enthal-koa2-boilerplate

介绍

Nodejs 开发后台服务程序模板（脚手架），可以随意使用。

特色

• 基于 Koa2
• 支持 ES6
• 支持热更新、自启动
• 用户注册、登陆，用户、组织、角色三重管理
• api 访问路由的权限等级管理
• 支持 multipart 与 文件上传
• 可轻松实现 RESTful
• 不同环境自动读取对应的配置文件，同时提供默认项与本地才会有的保密项
• 灵活的日志与 tracer，可根据不同运行环境按级别打印日志
• 集中错误代码与统一响应返回结构.

功能

• 借助 koa-views，支持多种模板引擎, 默认 pug
• 可在 views 中渲染 markdown 文件

基本版

• 基于 Koa2
• 支持 ES6
• 支持热更新、自启动
• 支持 multipart 与 文件上传
• 可轻松实现 RESTful
• 灵活自由的配置
• 多级别日志

Mongo 版

• 基本版功能
• mongodb 数据库操作，支持众租模式，支持

鉴权版

• Mongo 版
• 用户注册、登陆，用户、组织、角色三重管理
• JWT 签发与自动校验

全能版

• 鉴权版功能

软件架构

目录结构

├── env              // 配置文件与启动文件
├── public           // 静态资源
│   ├── files
│   ├── js
│   └── stylesheets
│       └── fonts
├── src               // 主体源代码
│   ├── aux           // 辅助工具，如日志
│   ├── cnf           // 内部模块与功能配置
│   ├── controls      // 核心业务逻辑实现
│   ├── demo          // 部分功能测试代码
│   ├── midwares      // 自定义中间件，比如权限路由，错误处理等
│   ├── models        // 集中各种数据库操作，若无必要可以缩减一层
│   │   └── mongo     // mongodb数据库基本操作
│   └── routes        // 路由定义
└── views             // 页面模板

说明：由于需要 babel 支持，所以代码尽可能都集中在src目录中，能够集中编译

安装教程

• 第一步 git clone https://gitee.com/dr.wei/enthal-koa2-boilerplate.git

• 第二步 进项目根目录，执行 yarn or npm install 安装所需的各种依赖包

• 第三步 启动项目，分三类环境，开发dev、测试test与生产prod

  • 开发环境，运行 npm run dev 启动，支持热更新
  • 测试环境，先运行npm run build，再npm run test 启动，不支持热更新
  • 生产环境，先运行npm run build，再npm run prod 启动，不支持热更新

说明：

1. npm run build 或编译代码到 dist目录。
2. 对于运行环境，全项目以dev,test和prod贯穿，为process.env.NODE_ENV在运行期的取值。可自己增加，但建议不要删除或修改。
3. 生产模式基于pm2实现，如果要使用pm2管理生产运行，请先全局安装之。

使用说明

实现代码集中放置于src目录。

• main.js 为入口文件，负责启动服务，一般无需更改
• app.js 为主流程实现的人口，koa2 的主体流程与逻辑实现放在这里

其中涉及的 api 接口基本都需要 JWT 验证，为了方便，启动时会自动生成一个用预测测试的 Token，此后可使用 ApiPost 或 PostMan 进行测试。

配置管理

访问

项目中的配置使用dotEnv-flow进行管理，能够将指定文件中的变量加载解析并绑定到process.env上，并可在koa2的支持下，通过app.env同时进行访问。

但这些变量都为字符串，如果需要类型，则可通过import src/cnf目录后，通过其访问类型解析之后的同名变量。

New 通过global的控制, 添加了appCnf全局变量,能够在任意位置从中取得所有配置的变量,不再需要引入配置脚本. 另外,还有可以全局使用的eCode与logger

设置

配置文件全部放在 conf 目录中，文件名有以下几种(可以规则随意增减)：

• .env 全局默认配置文件，会被 git 进行版本管理，出现在代码库中；
• .env.local 全局默认配置文件，但在.gitignore中忽略，所以不会出现在代码库中，可用于保存安全要求的秘密等。
• .env.${NODE_DEV} 针对各运行环境的配置，优先级高于 .env，有版本管理
• .env.${NODE_ENV}.local 针对各运行环境的配置，不会出现在代码库中

说明：

1. 因为.前缀的文件在 linux 中隐藏文件，直接可能无法在conf中看到；
2. 其中${NODE_DEV}实际为所需要的运行环境值，如prod；
3. 使用时需注意不要覆盖 proccess.env 默认就存在的变量
4. 同名变量会按照优先级高低覆盖，未同时出现的则会融合；
5. 上述所列文件优先级从上到下依次增高；
6. .gitignore已经对local后缀的配置文件规避，对于安全要求的配置尽量放在 local 中，部署后需要，在服务器上单独添加或再复制过去。
7. 如果涉及到更复杂的类型解析，可考虑 dotenv-conversion。

鉴权

两种方式：JWT Token 与 Session，现支持 JWT 参考 https://www.cnblogs.com/yuanrw/p/10089796.html

• JWT 需要在请求时根据账号信息，添加头部 {'authorization': "Bearer " + token}
• 因为 koa-jwt 依赖 jsonwebtoken，所以需要 jsonwebtoken 时无需再额外安装

唯一标识/ID

可以考虑使用 uuid uid 包 或者 shortid。

参与贡献