node.js 工程规范最佳实践

经过多个项目的实践和思考,总结出当前规范。不强求别人一定要遵守这个规范,首先自己要尽量遵守这个规范。

 

一. 模块引用规范

类似如下的形式:

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 处理。

猜你喜欢

转载自www.cnblogs.com/lswit/p/10641095.html