koa2-rest-scaffoldKoa2 RESTful API 腳手架。
koa2 Restful API 腳手架
本項目旨在提供一個純Restful API server腳手架。 本項目引入了一些koa2&node的常用庫，集成了redis和mongo，包含路由、參數(shù)校驗、單元測試、業(yè)務(wù)邏輯異常處理等特性
項目的由來：本人之前用Java寫后臺，習慣了throw Exception。使用node koa框架，也找了些網(wǎng)上的koa2腳手架，發(fā)現(xiàn)并沒有 一個項目能提供優(yōu)雅的異常處理，故產(chǎn)生了此項目?(? ???ω??? ?)?
項目運行
- 直接運行
npm start便可啟動項目，訪問 localhost:7100/api/hello，若看到數(shù)據(jù)正常返回則說明啟動成功；若需要熱更新，則運行npm run dev - 運行
npm run build會將項目編譯至 app 目錄下 - 運行
npm run test會執(zhí)行 test 目錄下的測試用例
生產(chǎn)環(huán)境運行
- node
首先編譯：npm run build，然后運行npm run pro即可
- pm2
首先編譯：npm run build，然后運行pm2 start pm2.json即可（若沒安裝pm2則需要先安裝npm install pm2@latest -g）。pm2.json根據(jù)項目需要自行修改。
- 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 倉庫在服務(wù)器上先 pull 拉取鏡像再 run。
tips: docker run 時可以通過 -v somePath/production.json:/app/config/production.json 將config/production.json掛載出來，配置項和代碼分離，防止敏感信息提交到代碼庫。logs等文件夾也應(yīng)該掛載出來，保持干凈的container。
開發(fā)使用說明
配置項
引入 config 庫作配置項管理，配置項文件統(tǒng)一放在 config 文件夾下面 default.json為默認配置項，本地開發(fā)時，直接調(diào)整其中參數(shù)即可
- test.json 對應(yīng) NODE_ENV=test
- production.json 對應(yīng) 對應(yīng) NODE_ENV=production
生成文檔
運行命令：
npm i apidoc -g
npm run docs
用瀏覽器打開./apidoc/index.html
定義返回格式
在 utils/response.js 中定義了數(shù)據(jù)的返回格式，默認如下：
{
"code": 0,
"msg": "ok",
"data": {}
}
優(yōu)雅地處理錯誤
在 utils/customError.js 中定義了 CustomError 和 HttpError，在 utils/errorCode.js 中定義了 code 和 msg 的對應(yīng)關(guān)系
- 當你需要拋出業(yè)務(wù)邏輯錯誤時，只需
throw new CustomError(1001)即可 - 若需要拋出 httpcode error，只需
throw new HttpError(401)即可
可查看 helloController.js 中的示例
主要插件介紹
- ioredis 和 mongoose
由于 Node 項目中經(jīng)常會用到 redis 和 mongo，所以在本項目中引入了 ioredis 和 mongoose
如果不需要 ioredis，那么則運行npm remove ioredis -S，然后刪除src/lib/redis.js文件并移除相應(yīng)配置項即可
如果不需要 mongoose，那么則運行npm remove mongoose -S，然后刪除src/models/mongo目錄并移除相應(yīng)配置項即可
- redis 的使用方法，具體使用方式參考 ioredis
import {
redis
} from '../lib/redis'
const getRedisData = async () => {
return await redis.set('a', 1)
}
- mongo 的使用方法，具體使用方式參考 mongoose
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 需要實現(xiàn)繼承關(guān)系，則可以使用 mongoose-schema-extend
用于請求的參數(shù)校驗
一個一致性、模塊化、高性能的 JavaScript 實用工具庫
一個優(yōu)秀的 JavaScript 日期處理類庫
接下來要做的
- 開發(fā)模式下，熱更新模式
- docker build