{"id":18324312,"url":"https://github.com/neoyeelf/koa2-rest-scaffold","last_synced_at":"2026-02-24T15:32:30.410Z","repository":{"id":85990764,"uuid":"131370670","full_name":"NeoyeElf/koa2-rest-scaffold","owner":"NeoyeElf","description":"Koa2 RESTful API 脚手架。","archived":false,"fork":false,"pushed_at":"2018-06-21T07:19:07.000Z","size":22,"stargazers_count":26,"open_issues_count":0,"forks_count":7,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-06T00:31:58.542Z","etag":null,"topics":["koa","koa2","node","nodejs","rest-api","restful-api","scaffold"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NeoyeElf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-28T03:53:59.000Z","updated_at":"2023-07-04T01:02:47.000Z","dependencies_parsed_at":"2023-03-13T07:47:50.431Z","dependency_job_id":null,"html_url":"https://github.com/NeoyeElf/koa2-rest-scaffold","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/NeoyeElf/koa2-rest-scaffold","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeoyeElf%2Fkoa2-rest-scaffold","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeoyeElf%2Fkoa2-rest-scaffold/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeoyeElf%2Fkoa2-rest-scaffold/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeoyeElf%2Fkoa2-rest-scaffold/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NeoyeElf","download_url":"https://codeload.github.com/NeoyeElf/koa2-rest-scaffold/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeoyeElf%2Fkoa2-rest-scaffold/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29787928,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-24T10:45:18.109Z","status":"ssl_error","status_checked_at":"2026-02-24T10:45:09.911Z","response_time":75,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["koa","koa2","node","nodejs","rest-api","restful-api","scaffold"],"created_at":"2024-11-05T18:33:43.279Z","updated_at":"2026-02-24T15:32:30.395Z","avatar_url":"https://github.com/NeoyeElf.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## koa2 Restful API 脚手架\n\n本项目旨在提供一个纯Restful API server脚手架。\n本项目引入了一些koa2\u0026node的常用库，集成了redis和mongo，包含路由、参数校验、单元测试、业务逻辑异常处理等特性\n\n项目的由来：本人之前用Java写后台，习惯了throw Exception。使用node koa框架，也找了些网上的koa2脚手架，发现并没有\n一个项目能提供优雅的异常处理，故产生了此项目⁄(⁄ ⁄•⁄ω⁄•⁄ ⁄)⁄\n\n### 项目运行\n\n- 直接运行 `npm start` 便可启动项目，访问 localhost:7100/api/hello，若看到数据正常返回则说明启动成功；若需要**热更新**，则运行`npm run dev`\n- 运行 `npm run build` 会将项目编译至 app 目录下\n- 运行 `npm run test` 会执行 test 目录下的测试用例\n\n#### 生产环境运行\n- node\n\n首先编译：`npm run build`，然后运行`npm run pro`即可\n\n- pm2\n\n首先编译：`npm run build`，然后运行`pm2 start pm2.json`即可（若没安装pm2则需要先安装`npm install pm2@latest -g`）。pm2.json根据项目需要自行修改。\n\n- docker\n\n运行`./docker-build.sh`生成 docker 镜像，接着运行 `docker run --name koa2-rest-scaffold -d -p 8000:7100 koa2-rest-scaffold:latest`即可\n\n其中，`docker run` 中的 `name` 和 `-p` 映射出来的端口都可以按需修改。也可以将镜像 push 到 docker 仓库在服务器上先 pull 拉取镜像再 run。\n\n_tips: `docker run` 时可以通过 `-v somePath/production.json:/app/config/production.json` 将config/production.json挂载出来，配置项和代码分离，防止敏感信息提交到代码库。logs等文件夹也应该挂载出来，保持干净的container。_\n\n### 开发使用说明\n\n#### 配置项\n引入 [config](https://github.com/lightbend/config) 库作配置项管理，配置项文件统一放在 config 文件夹下面\ndefault.json为默认配置项，本地开发时，直接调整其中参数即可\n- test.json 对应 NODE_ENV=test\n- production.json 对应 对应 NODE_ENV=production\n\n#### 生成文档\n\n运行命令：\n```bash\nnpm i apidoc -g\nnpm run docs\n```\n用浏览器打开./apidoc/index.html\n\n#### 定义返回格式\n\n在 utils/response.js 中定义了数据的返回格式，默认如下：\n\n```json\n{\n    \"code\": 0,\n    \"msg\": \"ok\",\n    \"data\": {}\n}\n```\n\n#### 优雅地处理错误\n\n在 utils/customError.js 中定义了 CustomError 和 HttpError，在 utils/errorCode.js 中定义了 code 和 msg 的对应关系\n\n- 当你需要抛出业务逻辑错误时，只需`throw new CustomError(1001)`即可\n- 若需要抛出 httpcode error，只需`throw new HttpError(401)`即可\n\n可查看 helloController.js 中的示例\n\n#### 主要插件介绍\n\n1. **ioredis 和 mongoose**\n\n由于 Node 项目中经常会用到 redis 和 mongo，所以在本项目中引入了 ioredis 和 mongoose\n\n**如果不需要 ioredis**，那么则运行`npm remove ioredis -S`，然后删除`src/lib/redis.js`文件并移除相应配置项即可\n\n**如果不需要 mongoose**，那么则运行`npm remove mongoose -S`，然后删除`src/models/mongo`目录并移除相应配置项即可\n\n- redis 的使用方法，具体使用方式参考 [ioredis](https://github.com/luin/ioredis)\n\n```javascript\nimport {\n  redis\n} from '../lib/redis'\n\nconst getRedisData = async () =\u003e {\n  return await redis.set('a', 1)\n}\n```\n\n- mongo 的使用方法，具体使用方式参考 [mongoose](https://github.com/Automattic/mongoose)\n\n```javascript\nimport mongoose from 'mongoose'\nconst User = mongoose.model('User')\n\nconst saveMongoData = async () =\u003e {\n  const user = new User({\n      name: 'Tom',\n      age: 27\n  })\n  return await user.save()\n}\n```\n\ntips: _如果 mongo schema 需要实现继承关系，则可以使用 [mongoose-schema-extend](https://github.com/briankircho/mongoose-schema-extend)_\n\n2. **[koa-validate](https://github.com/RocksonZeta/koa-validate)**\n\n用于请求的参数校验\n\n3. **[lodash](https://github.com/lodash/lodash/)**\n\n一个一致性、模块化、高性能的 JavaScript 实用工具库\n\n4. **[moment](https://github.com/moment/moment/)**\n\n一个优秀的 JavaScript 日期处理类库\n\n### 接下来要做的\n\n- [x] 开发模式下，热更新模式\n- [x] docker build\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneoyeelf%2Fkoa2-rest-scaffold","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneoyeelf%2Fkoa2-rest-scaffold","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneoyeelf%2Fkoa2-rest-scaffold/lists"}