JavaScript 开发标准
前端开发标准系列 · 广州一千河科技有限公司 · 2026 年 11 月
文档版本控制
| 版本号 | 修订时间 | 修订者 | 备注 |
|---|---|---|---|
| V1.0 | 2026/11/08 | 初稿 |
1. 文件信息
1.1. 编制依据
本标准以阿里巴巴前端规约《JavaScript 编码规约》为基础，用于公司前端项目的 JavaScript 编写和代码评审。
1.2. 适用范围和规则等级
适用于公司维护的 JavaScript 源码，包括浏览器脚本、Node.js 脚本和测试代码。默认面向 ES2015 及以上。
强制条款须满足。推荐条款默认采用，参考条款用于指导实现。
2. 编码风格
2.1. 缩进与标点
强制 每级缩进使用 2 个空格。语句需要终止符时显式写分号，例如变量声明、表达式语句和 return。
强制 逗号放在前一项末尾。目标语法允许时，多行数组、对象、导入导出列表及参数列表保留尾逗号。剩余参数后不可加逗号。
export const DEFAULT_OPTIONS = {
mode: 'standard',
retryLimit: 3,
timeoutMs: 1500,
};2.2. 代码块和空白
推荐 if、for、while 等控制语句即使只有一条语句，也用大括号。文件以换行符结束。
强制 非空块左大括号跟在语句头同行，右大括号另起一行。块首尾不留空行。避免空块，确需保留时在块内说明原因。
强制 控制关键字与左小括号之间留一个空格，函数名与参数括号相连。小括号、数组方括号内侧无空格，非空对象字面量的大括号内侧各留一个空格。二元运算符两侧留空格，属性冒号后留空格。
推荐 单行以 100 字符为目标，字符串、模板字符串和正则等不宜拆分时可例外。
参考 文件约 1000 行或函数约 80 行时，检查能否按职责拆分。
3. 变量和数据
3.1. 变量声明
强制 使用 const 或 let。不重新赋值的绑定使用 const，需要重新赋值时使用 let。每条声明只定义一个变量，解构声明按同一绑定模式处理。
强制 先声明再使用。删除未用声明，禁止重复声明、遮蔽外层变量及连续赋值。
参考 在首次使用附近声明变量，保持作用域尽可能小。
3.2. 原始类型和字符串
强制 字符串优先用单引号，去掉无效转义。在已有布尔语义的条件中省略多余转换。禁止用 new 创建原始类型包装对象。
推荐 显式转换可用 Number()、String() 或 !!。整数解析使用 parseInt() 并传入基数。变量插值优先用模板字符串。
3.3. 数组
强制 用数组字面量创建普通数组。对 map、filter、reduce 等依赖返回值的方法，回调的每条正常路径都返回预期值。
推荐 使用数组解构读取固定位置。可迭代值可用扩展语法展开，非可迭代的类数组用 Array.from() 转换。展开复制为浅复制。
export function getActiveIds(users) {
return users.filter((user) => user.active).map((user) => user.id);
}3.4. 对象
强制 普通对象使用字面量，并采用属性及方法简写。属性名仅在语法需要时加引号。已知且可用标识符表示的属性用点号访问，动态键使用方括号。
强制 检查自有属性时，目标环境支持可用 Object.hasOwn()。兼容旧环境时可用 Object.prototype.hasOwnProperty.call()。不得直接调用实例的 hasOwnProperty 等原型方法。
推荐 用解构读取所需字段，用扩展语法合并普通数据对象。合并前明确覆盖顺序，涉及嵌套对象时确认浅复制是否足够。
参考 同类简写属性集中书写，动态键优先在对象字面量中定义。
export function makeOptions(defaults, overrides, mode) {
return {
...defaults,
...overrides,
mode,
};
}4. 函数和类
4.1. 函数
强制 禁止用 Function 构造器创建函数。代码块内需要定义函数时使用绑定加函数表达式。匿名回调优先用箭头函数，依赖动态 this 的回调保留普通函数。
强制 参数禁止命名为 arguments。可变参数用剩余参数收集。立即执行函数表达式用小括号包裹。生成器函数体包含 yield。
推荐 箭头函数参数保留括号，单一返回表达式可省略函数体大括号。直接返回对象字面量时给对象加小括号。
推荐 默认参数放在普通必填参数之后，剩余参数保持末尾。避免修改参数绑定或入参对象。
参考 优先用合适的数组方法表达迭代意图。参数多时考虑参数对象，圈复杂度约 10 或认知复杂度约 15 时检查是否需拆分。
export function getLabels(items, prefix = 'item') {
return items.map(({ id }) => `${prefix}-${id}`);
}4.2. 类
推荐 使用 class 声明类，使用 extends 声明继承关系。
强制 省略无额外逻辑的构造函数。派生类显式编写构造函数时，在使用 this 前调用 super()。类成员不得重复定义。
5. 模块和控制流
5.1. 模块依赖
推荐 新代码优先使用 ESM。维护 CommonJS 模块时遵循现有边界。选择发布格式时以实际消费者、运行时和构建工具为依据。
强制 静态导入集中在模块顶部。同一来源的导入合并，禁止模块自引用及循环依赖。默认导入的本地名称不与源模块的其他命名导出混淆。
推荐 导入后留一空行。已作为命名导出的成员直接按名导入，避免从默认导出对象上读取同名成员。
参考 导入按内置模块、第三方依赖、项目内模块分组。保留有副作用导入的执行顺序。公开导出形式以模块职责和项目约定为准。
5.2. 操作符和分支
推荐 比较时使用 === 和 !==，需要转换时先显式转换类型。
强制 禁止使用 ++、--、void，以及嵌套或冗余的三元表达式。混合运算容易误读时用小括号明确分组。循环计数器方向须与退出条件一致。
强制 switch 中有执行逻辑的分支用 break、return 或 throw 明确退出。禁止意外贯穿到下一分支。
推荐 switch 提供 default，有意省略时说明原因。遍历对象自有键优先用 Object.keys()，使用 for...in 时先检查键是否自有。
参考 用提前返回减少嵌套。少量简单分支可用 if，同一值有多个离散分支时考虑 switch。
5.3. 调试和运行时安全
强制 禁止使用 eval，禁止提交 debugger，禁止覆盖原生对象和只读全局变量。
推荐 避免使用 alert 和遗留的调试 console。生产诊断日志使用项目约定的日志接口。
6. 注释和命名
6.1. 注释
强制 注释内容和分隔符之间留一个空格。
推荐 单行注释用 //，放在被说明代码上方。除块首或连续注释外，注释上方留一空行。多行说明使用块注释。
参考 解释约束、原因和边界条件。公开接口可使用 JSDoc，待办事项用清楚的标记，及时删除失效注释及注释掉的代码。
6.2. 命名
强制 类和构造函数使用大驼峰，例如 OrderService。
参考 变量、函数、实例及导出的函数用小驼峰。普通文件名使用小写，多个单词以短横线分隔，例如 order-service.js。
参考 全大写下划线命名用于对外导出的稳定常量。对象属性沿用普通命名，不因对象导出而统一大写。避免用前后下划线模拟私有性。