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. 模块引用顺序

模块引用应遵循以下顺序：

1. Node 内置模块
2. npm 包
3. 本地文件

同类引用按字典序排列，不同类别间空一行分隔：

// 推荐
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');
}

二、安全规范

1. 隐藏错误详情：客户端错误提示不得包含敏感系统信息
2. 隐藏技术栈标识：移除或伪造 X-Powered-By 响应头
3. JSONP 安全：跨域接口需严格校验访问来源，配置域名白名单
4. 用户标识安全：禁止使用参数或明文 cookie 中的用户标识查询敏感信息
5. 防止 SQL 注入：使用预编译语句，对用户输入进行转义和过滤
6. 依赖管理：定期检查并更新存在漏洞或过期的依赖
7. 文件上传安全：用户上传文件应存储至 OSS 等专业服务
8. URL 重定向安全：服务端重定向需设置白名单验证
9. 接口入参校验：使用 jsonschema 或 joi 严格校验请求参数

三、最佳实践

1. 无状态设计：应用应保持无状态，使用外部存储管理数据
2. 静态文件托管：推荐使用 CDN 而非 Node.js 托管前端静态文件
3. CPU 密集型任务：将 CPU 密集型任务委托给反向代理（如 nginx）
4. 异步编程：优先使用 async/await 替代回调函数
5. 回调函数处理：使用 util.promisify 将回调转为 Promise：

const util = require('util');
const fs = require('fs');
const stat = util.promisify(fs.stat);

6. Promise 使用：优先使用原生 Promise 而非第三方库
7. 链式调用：类方法返回 this 实现链式调用：

class Jedi {
  jump() {
    this.jumping = true;
    return this;
  }
  
  setHeight(height) {
    this.height = height;
    return this;
  }
}

本规范基于 eslint-config-egg 扩展，旨在提升 Node.js 业务开发的代码一致性、安全性和可维护性。