编码规范-后端.md

代码风格

后端代码风格 必须 严格遵循 Standard JavaScript Style 规范。

路由器

路由闭包

绝不 在路由配置文件里书写『闭包路由』或者其他业务逻辑代码，

路由器要保持干净整洁，绝不 放置除路由配置以外的其他程序逻辑。

路由定义一般使用二级路径，如/a/b。不应该 超过这个层级

路由 必须 填写完整的信息:

• 路径
• 描述
• 请求方式
• 控制器
• 请求参数
• 响应数据
• 权限

单数 or 复数？

资源路由路由 URI 必须 使用单数形式，如：

• /photo/create
• /photo/{photo}

错误的例子如：

• /photos/create
• /photos/{photo}

路由命名

除了 resource 资源路由以外，其他所有路由都 必须 使用 name 方法进行命名。

必须 使用『资源前缀』作为命名规范，如下的 user.follow，资源前缀的值是 user.：

/user/follow

数据模型

放置位置

所有的数据模型文件，都 必须 存放在：models 文件夹中。

使用基类

所有的 数据模型 都 必须 继承统一的基类 BaseModel，此基类存放位置为 models/BaseModel.js

以 Photo 数据模型作为例子继承 Model 基类：

const BaseModel = require('./BaseModel')
class Photo extends BaseModel {
  constructor (conn) {
    super(conn)

    this._table = 'photo'
    this._dFlag = 'd_flag'
    this._cTime = 'c_time'
    this._mTime = 'm_time'
  }
  .
  .
  .
}

命名规范

数据模型相关的命名规范：

• 数据模型类名 必须 为「单数」, 如：models/Photo
• 类文件名 必须 为「单数」，如：models/Photo.js
• 数据库表名字 必须 为「单数」，多个单词情况下使用「Snake Case」 如：photo, my_photo
• 数据库表迁移名字 必须 为「单数」，如：2014_08_08_234417_create_photo_table.js
• 数据填充文件名 必须 为「单数」，如：PhotoTableSeeder.js
• 数据库字段名 必须 为「Snake Case」，如：view_count, is_vip
• 数据库表主键 必须 为「id」
• 数据库表外键 必须 为「resource_id」，如：user_id, post_id

Repository

绝不 使用 Repository，因为我们不是在写 JAVA 代码，太多封装就成了「过度设计（Over Designed）」，极大降低了编码愉悦感，使用 MVC 够傻够简单。

代码的可读性，维护和开发的便捷性，直接关系到程序员开发时的愉悦感，直接影响到项目推进效率和程序 Debug 的速度。

关于 SQL 文件

• 绝不 使用命令行或者 Mysql管理工具 直接创建索引或表。必须 使用 数据库迁移 去创建表结构，并提交版本控制器中；
• 绝不 为了共享对数据库更改就直接导出 SQL，所有修改都 必须 使用 数据库迁移 ，并提交版本控制器中；
• 绝不 直接向数据库手动写入伪造的测试数据。必须 使用 数据填充 来插入假数据，并提交版本控制器中。

控制器

单数 or 复数？

必须 使用资源的单数形式，如：

• 类名：PhotoController
• 文件名：PhotoController.js

错误的例子：

• 类名：PhotosController
• 文件名：PhotosController.js

保持短小精炼

必须 保持控制器文件代码行数最小化，还有可读性。

• 不应该 为「方法」书写注释，这要求方法取名要足够合理，不需要过多注释；
• 应该 为一些复杂的逻辑代码块书写注释，主要介绍产品逻辑 - 为什么要这么做。；
• 不应该 在控制器中书写「私有方法」，控制器里 应该 只存放「路由动作方法」；
• 绝不 遗留「死方法」，就是没有用到的方法，控制器里的所有方法，都应该被使用到，否则应该删除；
• 绝不 在控制器里批量注释掉代码，无用的逻辑代码就必须清除掉。

数据填充

运行效率

开发数据填充时，必须 特别注意 npm run db:seed 的运行效率，否则随着项目的代码量越来越大，db:seed 的运行时间会变得越来越长，有些项目多达几分钟甚至几十分钟。

原则是：

Keep it lighting speed.

只有当 db:seed 运行起来很快的时候，才能完全利用数据填充工具带来的便利，而不是累赘。

批量入库

所有假数据入库操作，都 必须 是批量操作，配合 factory 使用以下方法：

const users = factory(User)
                .times(1000)
                .make();
User.insert(users.toArray());

以上只执行一条数据库语句

自定义命令

所有的自定义命令，都 必须 有项目的命名空间。

如：

$ npm run db:update
$ npm run db:seed
...

错误的例子为：

$ npm run clear-token
$ npm run send-status-email
...

日期和时间

必须 使用 moment 来处理日期和时间相关的操作。