经过多个项目的实践和思考,总结出当前规范。不强求别人一定要遵守这个规范,首先自己要尽量遵守这个规范。
一. 模块引用规范
类似如下的形式:
const fs = require('fs');
const koa = require('koa');
const utils = require('../utils');
const SECONT = 1000;
const MINUTE = SECOND * 60;
规则如下:
1. 模块顺序按照 内置模块、第三方模块、自身文件模块 的顺序引用,并且每个块之间要用空行分开;
2. 模块引用要用 const 定义;
3. 有关联关系的变量要定义在一个块里。
二、模块导出规范
位置需要紧邻在顶部的所有常量定义之下,与最下面的常量之间有一行空格。
模块导出对象时,导出语句需如下格式:
const A = 100;
exports = module.exports = {
module1,
module2
};
除此之外,无特殊情况,不可再有其它地方有导出属性的声明。
特殊情况说明:有时候可能需要在运行时动态导出属性,这时可以在其它地方声明。但是最好避免动态导出。
模块导出函数时,不可使用匿名函数,必须有命名,如下所示:
exports = module.exports = function util() {
// func body
};
三. 注释规范
0. 一定要写注释
1. 函数注释要用多行注释的形式,写在函数外面
2. 块级别比如一个 if 块或者一个 for 循环块的注释,要用单行注释的形式写在块的上方,如果注释复杂的话用块注释,不要用多行单行注释
3. 行级别的注释写在代码行后面,与代码间隔两个空格,注释内容与注释标识(//)之间间隔一个空格
四. 接口定义规范
0. 所有接口都要定义在一个文件中
1. 每个接口都要有注释: 接口作用 开发人员
2. 同一业务范畴的接口放在一个块里,跟其它业务范畴的接口用空行隔离开,块的上下添加注释,如下所示:
/***************** 业务1 *****************/
router1, // 功能1 王大锤
router2, // 功能2 王大锤
/***************** 业务1 *****************/
/***************** 业务2 *****************/
router3, // 功能3 赵铁柱
router4, // 功能4 张全蛋
/***************** 业务2 *****************/
如果一个业务可以分为多个小业务,这些业务也可以互相之间用空行分开,如下所示:
/***************** 业务3 *****************/
router5, // 功能5 赵铁柱
router6, // 功能6 赵铁柱
router7, // 功能7 赵铁柱
router8, // 功能8 张全蛋
router9, // 功能9 赵铁柱
router0, // 功能0 张全蛋
/***************** 业务3 *****************/
五. 业务规范
0. 涉及到数据库的业务,要做完整的增删改查接口,不能因为暂时没有用就少了哪个。因为以为不会用的总是会突然要被用到!
六. 接口返回值规范
0. 接口返回值全都要遵循以下格式:
ctx.body = { code: 0, data: data, msg: '' };
有且只能有三个字段: code、data、msg
其中 code 为返回值代码,0 为成功,其它数字为失败
data 为返回值的数据部分,没有的话可以为空
msg 为处理结果信息,成功可以不填,失败时需要填写失败信息
七. 日志规范
0. 日志开头需要是当时的时间,年月日时分秒,最好毫秒也加上
1. http 日志最好在每一条日志中都有 flowId 或者 sessionId
2. http 日志要包含的元素有: flowId, ip, method, originalUrl, referer, status, responseTime, responseLength, userAgent
3. 日志要分级别,错误及以上级别的日志最好存放在单独的文件中
4. 日志要考虑归档,防止撑爆硬盘
八. 配置规范
0. 配置要有三个层次:文件、内存、数据库
1. 文件配置中要体现所有的配置,最好不要有遗漏
2. 运行过程中使用的配置需要是内存配置(复制的文件配置),不可使用文件配置,否则无法动态修改配置
3. 使用统一的数据库配置用来动态更新内存配置,否则无法使用分布式架构
九. 代码风格规范
0. koa 的 await next() 后面如果还有代码的话, await next() 这一行要和上下的代码块各有一行空行分割开
1. else 或者 else if 要另起一行,不要放在 } 后面
十. 异常处理规范
0. 预计可能出现不可控的 Exception 的地方,比如 JSON.parse、JSON.stringify、 decodeURI、encodeURI 等处理过程,一定要用 try catch 来捕获异常。
1. 要在程序主体启动前,加上 process.on('uncaughtException', cb) 和 process.on('unhandleRejction', cb) 两个进程级的异常捕获和未处理的否决态 promise 处理。