https://github.com/neoyeelf/koa2-rest-scaffold
Koa2 RESTful API 脚手架。
https://github.com/neoyeelf/koa2-rest-scaffold
koa koa2 node nodejs rest-api restful-api scaffold
Last synced: about 2 months ago
JSON representation
Koa2 RESTful API 脚手架。
- Host: GitHub
- URL: https://github.com/neoyeelf/koa2-rest-scaffold
- Owner: NeoyeElf
- Created: 2018-04-28T03:53:59.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2018-06-21T07:19:07.000Z (almost 7 years ago)
- Last Synced: 2025-03-21T13:53:09.191Z (2 months ago)
- Topics: koa, koa2, node, nodejs, rest-api, restful-api, scaffold
- Language: JavaScript
- Size: 21.5 KB
- Stars: 26
- Watchers: 1
- Forks: 7
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
## koa2 Restful API 脚手架
本项目旨在提供一个纯Restful API server脚手架。
本项目引入了一些koa2&node的常用库，集成了redis和mongo，包含路由、参数校验、单元测试、业务逻辑异常处理等特性
项目的由来：本人之前用Java写后台，习惯了throw Exception。使用node koa框架，也找了些网上的koa2脚手架，发现并没有
一个项目能提供优雅的异常处理，故产生了此项目⁄(⁄ ⁄•⁄ω⁄•⁄ ⁄)⁄
### 项目运行
- 直接运行 `npm start` 便可启动项目，访问 localhost:7100/api/hello，若看到数据正常返回则说明启动成功；若需要**热更新**，则运行`npm run dev`
- 运行 `npm run build` 会将项目编译至 app 目录下
- 运行 `npm run test` 会执行 test 目录下的测试用例
#### 生产环境运行
- node
首先编译：`npm run build`，然后运行`npm run pro`即可
- pm2
首先编译：`npm run build`，然后运行`pm2 start pm2.json`即可（若没安装pm2则需要先安装`npm install pm2@latest -g`）。pm2.json根据项目需要自行修改。
- docker
运行`./docker-build.sh`生成 docker 镜像，接着运行 `docker run --name koa2-rest-scaffold -d -p 8000:7100 koa2-rest-scaffold:latest`即可
其中，`docker run` 中的 `name` 和 `-p` 映射出来的端口都可以按需修改。也可以将镜像 push 到 docker 仓库在服务器上先 pull 拉取镜像再 run。
_tips: `docker run` 时可以通过 `-v somePath/production.json:/app/config/production.json` 将config/production.json挂载出来，配置项和代码分离，防止敏感信息提交到代码库。logs等文件夹也应该挂载出来，保持干净的container。_
### 开发使用说明
#### 配置项
引入 [config](https://github.com/lightbend/config) 库作配置项管理，配置项文件统一放在 config 文件夹下面
default.json为默认配置项，本地开发时，直接调整其中参数即可
- test.json 对应 NODE_ENV=test
- production.json 对应 对应 NODE_ENV=production
#### 生成文档
运行命令：
```bash
npm i apidoc -g
npm run docs
```
用浏览器打开./apidoc/index.html
#### 定义返回格式
在 utils/response.js 中定义了数据的返回格式，默认如下：
```json
{
"code": 0,
"msg": "ok",
"data": {}
}
```
#### 优雅地处理错误
在 utils/customError.js 中定义了 CustomError 和 HttpError，在 utils/errorCode.js 中定义了 code 和 msg 的对应关系
- 当你需要抛出业务逻辑错误时，只需`throw new CustomError(1001)`即可
- 若需要抛出 httpcode error，只需`throw new HttpError(401)`即可
可查看 helloController.js 中的示例
#### 主要插件介绍
1. **ioredis 和 mongoose**
由于 Node 项目中经常会用到 redis 和 mongo，所以在本项目中引入了 ioredis 和 mongoose
**如果不需要 ioredis**，那么则运行`npm remove ioredis -S`，然后删除`src/lib/redis.js`文件并移除相应配置项即可
**如果不需要 mongoose**，那么则运行`npm remove mongoose -S`，然后删除`src/models/mongo`目录并移除相应配置项即可
- redis 的使用方法，具体使用方式参考 [ioredis](https://github.com/luin/ioredis)
```javascript
import {
redis
} from '../lib/redis'
const getRedisData = async () => {
return await redis.set('a', 1)
}
```
- mongo 的使用方法，具体使用方式参考 [mongoose](https://github.com/Automattic/mongoose)
```javascript
import mongoose from 'mongoose'
const User = mongoose.model('User')
const saveMongoData = async () => {
const user = new User({
name: 'Tom',
age: 27
})
return await user.save()
}
```
tips: _如果 mongo schema 需要实现继承关系，则可以使用 [mongoose-schema-extend](https://github.com/briankircho/mongoose-schema-extend)_
2. **[koa-validate](https://github.com/RocksonZeta/koa-validate)**
用于请求的参数校验
3. **[lodash](https://github.com/lodash/lodash/)**
一个一致性、模块化、高性能的 JavaScript 实用工具库
4. **[moment](https://github.com/moment/moment/)**
一个优秀的 JavaScript 日期处理类库
### 接下来要做的
- [x] 开发模式下，热更新模式
- [x] docker build