NeoyeElf / koa2-rest-scaffold

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 库作配置项管理，配置项文件统一放在 config 文件夹下面 default.json为默认配置项，本地开发时，直接调整其中参数即可

• test.json 对应 NODE_ENV=test
• production.json 对应 对应 NODE_ENV=production

生成文档

运行命令：

npm i apidoc -g
npm run docs

用浏览器打开./apidoc/index.html

定义返回格式

在 utils/response.js 中定义了数据的返回格式，默认如下：

{
    "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

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 需要实现继承关系，则可以使用 mongoose-schema-extend

2. koa-validate

用于请求的参数校验

3. lodash

一个一致性、模块化、高性能的 JavaScript 实用工具库

4. moment

一个优秀的 JavaScript 日期处理类库

接下来要做的

• 开发模式下，热更新模式
• docker build