Node.js 编码规范
Node.js 编码规范
一、编码风格
1. 全局变量使用
直接使用 Node.js 内置的全局变量，无需通过 require 引入：
// 不推荐
const { Buffer } = require('buffer');
const b = Buffer.alloc(16);// 推荐
const b = Buffer.alloc(16);
适用于 Buffer、URL、URLSearchParams、TextEncoder、TextDecoder、process、console 等全局对象。
2. 优先使用 Promise API
推荐使用模块的 promises API 替代回调方式：
// 不推荐
const fs = require('fs');
fs.readFile(filePath, 'utf8', (error, content) => { ... });// 推荐
const { promises: fs } = require('fs');
async function readData(filePath) {const content = await fs.readFile(filePath, 'utf8');
}
3. 模块引用顺序
模块引用应遵循以下顺序：
- Node 内置模块
- npm 包
- 本地文件
同类引用按字典序排列，不同类别间空一行分隔：
// 推荐
const fs = require('fs');
const http = require('http');const { Bar, Foo } = require('tool');
const moment = require('moment');const Car = require('./models/car');
4. 异常处理规范
必须使用原生 Error 对象抛出异常：
// 不推荐
throw 'error';
throw 0;// 推荐
throw new Error('error');
const err = new Error('error');
throw err;
5. 避免同步方法
线上环境应避免使用同步方法：
// 不推荐
fs.readFileSync('./somefile', 'utf-8');// 推荐
const { promises: fs } = require('fs');
async function test() {await fs.readFile('./somefile', 'utf-8');
}
二、安全规范
- 隐藏错误详情：客户端错误提示不得包含敏感系统信息
- 隐藏技术栈标识：移除或伪造 X-Powered-By 响应头
- JSONP 安全：跨域接口需严格校验访问来源，配置域名白名单
- 用户标识安全：禁止使用参数或明文 cookie 中的用户标识查询敏感信息
- 防止 SQL 注入：使用预编译语句，对用户输入进行转义和过滤
- 依赖管理：定期检查并更新存在漏洞或过期的依赖
- 文件上传安全：用户上传文件应存储至 OSS 等专业服务
- URL 重定向安全：服务端重定向需设置白名单验证
- 接口入参校验：使用 jsonschema 或 joi 严格校验请求参数
三、最佳实践
- 无状态设计：应用应保持无状态，使用外部存储管理数据
- 静态文件托管：推荐使用 CDN 而非 Node.js 托管前端静态文件
- CPU 密集型任务：将 CPU 密集型任务委托给反向代理（如 nginx）
- 异步编程：优先使用 async/await 替代回调函数
- 回调函数处理：使用 util.promisify 将回调转为 Promise：
const util = require('util');
const fs = require('fs');
const stat = util.promisify(fs.stat);
- Promise 使用：优先使用原生 Promise 而非第三方库
- 链式调用：类方法返回 this 实现链式调用：
class Jedi {jump() {this.jumping = true;return this;}setHeight(height) {this.height = height;return this;}
}
本规范基于 eslint-config-egg 扩展，旨在提升 Node.js 业务开发的代码一致性、安全性和可维护性。