项目结构及开发规范

WARNING

阅读本小节前，请确保你已经完成了上一节的内容，当然你非常熟悉 koa 的开发也可直接阅读本小节

项目结构

koa 是一个优美的微框架。这既是一件好事——你可以按照自己的习惯和想法来组织你的项目，不过对于团队来说这可能是一件坏事——团队每个人都有自己的喜好，这会使整体项目的结构很混乱。因此我们提供了 starter 模板项目，它是我们团队从诸多项目开发中提炼而来的一种规范，它不仅仅是结构，风格还有诸多细节，你会在后续逐渐了解到。

  1. app
  2. ├── api // api层
  3. │   ├── cms // 关于cms的api
  4. │   │   ├── admin.js
  5. │   │   ├── log.js
  6. │   │   ├── test.js
  7. │   │   └── user.js
  8. │   └── v1 // 普通api
  9. │       └── book.js
  10. ├── app.js // 创建koa实例及应用扩展
  11. ├── config // 配置文件目录
  12. │   ├── secure.js // 安全性配置文件
  13. │   └── setting.js // 普通配置文件
  14. ├── libs // 其它类库
  15. │   ├── errCode.js // 异常类库
  16. │   └── util.js // 助手函数
  17. ├── models // 模型层
  18. │   ├── book.js
  19. ├── dao // 数据库操作
  20. │   ├── admin.js
  21. │   ├── log.js
  22. │   └── user.js
  23. ├── plugins // 插件目录
  24. ├── starter.js  // 程序的启动文件
  25. └── validators // 校验层
  26.     ├── admin.js // 校验器模块
  27.     ├── book.js
  28.     ├── common.js
  29.     ├── log.js
  30.     └── user.js

上面是 starter 项目的整体结构，开发时我们强烈建议你遵循如下规范开发，在前期你肯定会不适应，但慢慢地你会爱上它。

  • 在 app/api 文件夹中开发 API，并将不同版本，不同类型的 API 分开，如：v1 代表第一版本的 API，v2 代表第二版本，cms 代表属于 cms 的 API。
  • 将程序的配置文件放在 app/config 文件夹下，并着重区分 secure（安全性配置）和 setting（普通性配置）。配置更详细内容参考配置
  • 将可重用的类库放在 app/libs 文件夹下。
  • 将数据模型放在 app/models 文件夹下。
  • 将开发的插件放在 app/plugins 文件夹下。
  • 将校验类放在 app/validators 文件夹下。

TIP

在你自己的实际开发中你可能不需要dao这一层，对于简单的模型操作，我们建议你直接在视图函数中操作，而对于复杂的操作，我们建议你为每一类的 router 封装一个 dao。

dao 全称 data access object，主要是负责数据对对象的操作，实际上它也属于模型层，属于 MVC 中的 M 层。

开发规范

API 规范

koa 的 API 开发规范是一个很棘手的问题，目前社区中知名的基于 koa 二次的开发的think.js 与 egg.js 都为 API 的开发引入了 Controller 这个概念。但 koa 官方以及它的生态大多都是以匿名函数的形式来进行 API 的开发的。koa-router 是目前很流行的路由管理库，它也遵循了匿名函数这一方式。所以 Lin 仍然是选择了与 koa 官方文档一致的做法，通过匿名函数来进行 API 的开发，从而降低学习成本。

Lin 是一套高可用的 CMS 系统，因为权限的控制是必须的，但是 koa-router 本身并不能满足我们的需求，因此我们在 koa-router 的基础上扩展除了 LinRouter 这一概念，它100%兼容了 koa-router 的开发，并且也提供了相应的方式进行权限的配置与管理。

一般的，我们推荐你在一类 API 中新建一个 router(如 Book 这一类，它负责与图书相关的 API)。如下：

  1. const { LinRouter } = require("lin-mizar");
  3. const bookApi = new LinRouter({
  4.   prefix: "/v1/book"
  5. });
  7. bookApi.get("/:id", async ctx => {
  8.   ctx.json({
  9.     msg: "hello, I am a book"
  10.   });
  11. });

如果你熟悉 koa 和 koa-router，你会发现这几乎与 koa 的标准开发方式一样。新建router 时，你需传入红图的前缀prefix，如/v1/book，而后红图会自己在访问的 url中加入/v1/book前缀。当然你可以查看 koa-router的文档项目结构及开发规范 - 图1，获得更多的初始化参数。

数据库模型规范

koa 本身并非对数据库做出支持，Lin 通过集成sequelize这个 orm 库来进行数据访问，如果你不熟悉，请先阅读官方文档项目结构及开发规范 - 图2。

由于 Lin 在核心库中便已经依赖于数据库的操作，因此我们将初始化的Sequelize实例置放在了核心库中，你可以通过如下方式拿到这个实例：

  1. const { db } = require("lin-mizar/lin/db");
  2. // 使用Sequelize实例
  3. await db.query(...)

异常处理规范

提起异常，大多时候我们都并不想碰见，因为它经常会与程序 crash 一起出现。但它确实又是程序中不可或缺的一部分，在 Lin 中我们默认集成了全局异常处理机制。因此不论你程序出现何种异常，都将会返回固定格式的提示信息给前端。对于前端来说，这是非常友好的一种交互。

在项目开发中我们强力推荐，甚至可以说是要求你在开发的过程中，关于某一类的异常一定要通过继承HttpException的方式来自定义，这会让前后端的交互更加友好。

当然，当你每自定义一个异常后，别忘记在根目录下的code.md中记录相关异常的error_code 和 msg，方便前端查阅和团队协作。

数据校验规范

我们强烈建议你为每个有数据校验的接口定义一个相应的校验类。Lin 整合了validator.js这个好用的校验库，并提供了一个基础的校验类LinValidator来方便参数的校验。 validator.js 包含了很多的校验函数，你可以查看官方文档项目结构及开发规范 - 图3。

  1. class BookSearchValidator extends LinValidator {
  2.   constructor() {
  3.     super();
  4.     this.q = new Rule("isNotEmpty", "必须传入搜索关键字");
  5.   }
  6. }

如上，我们定义了一个图书搜索的校验类，在BookSearchValidator类中定义了一个字段q，并且传入了 q 的校验规则为 isNotEmpty，表示 q 不可为空。该字段会对前端传入的数据做出校验，若传入的数据中不存在q字段，则会返回前端一个错误信息，错误信息为必须传入搜索关键字。

到这里，你或许未发现校验类的可取之处，因为这个简单的校验直接在视图函数中实现，或许更为直接和简单。

但是，一旦我们的数据变多，且校验规则变得复杂，如下：

  1. class RegisterValidator extends LinValidator {
  2.   constructor() {
  3.     super();
  4.     this.nickname = [
  5.       new Rule("isNotEmpty", "昵称不可为空"),
  6.       new Rule("isLength", "昵称长度必须在2~10之间", 2, 10)
  7.     ];
  8.     this.group_id = new Rule("isInt", "分组id必须是整数，且大于0", {
  9.       min: 1
  10.     });
  11.     this.email = [
  12.       new Rule("isOptional"),
  13.       new Rule("isEmail", "电子邮箱不符合规范，请输入正确的邮箱")
  14.     ];
  15.     this.password = [
  16.       new Rule(
  17.         "matches",
  18.         "密码长度必须在6~22位之间，包含字符、数字和 _ ",
  19.         /^[A-Za-z0-9_*&$#@]{6,22}$/
  20.       )
  21.     ];
  22.     this.confirm_password = new Rule("isNotEmpty", "确认密码不可为空");
  23.   }
  25.   validateConfirmPassword(data) {
  26.     if (!data.body.password || !data.body.confirm_password) {
  27.       return [false, "两次输入的密码不一致，请重新输入"];
  28.     }
  29.     let ok = data.body.password === data.body.confirm_password;
  30.     if (ok) {
  31.       return ok;
  32.     } else {
  33.       return [false, "两次输入的密码不一致，请重新输入"];
  34.     }
  35.   }
  36. }

可以发现，当我们需要校验的参数变得复杂时，一个专注于校验的类可以让我们的代码变得更易维护，提升代码整体的可读性。

Lin 的校验器十分灵活，详细内容的请参考校验器这一节。

配置规范

在我们的 starter 项目中，统一把项目的配置文件放在了app/config文件夹下。当然，我们也强烈建议你如此做。不仅如此，由于 Node.js 的特点你必须导出每一个配置项。

  1. "use strict";
  3. module.exports = {
  4.   apiDir: "app/api"
  5. };

如上我们导出了 apiDir 这个配置项，Lin 会自动将配置加载到 config 中，如果你需要扩展配置，请直接在module.exports中添加其他的配置项，详细内容的请参考配置这一节。

小结

到此，我们介绍了项目的结构和开发规范。本小节注重的不是项目的开发实现与细节，而是项目的整体与规范，对于很多人来说，去适应一个规范会觉得不舒服，但对于团队来说，这是一件必须的事。最后，送大家一句话——越规矩，越自由。