js-google

Google JavaScript 最佳实践

这是一份全面的 JavaScript 风格与最佳实践指南，基于 Google 官方 JavaScript 风格指南编写，专为 AI Agent 和大模型设计。指南包含 8 个类别中的 47 条规则，并按影响程度排序，用于指导自动化重构和代码生成。

适用场景

在以下情况参考这些指南：

• 编写新的 JavaScript 或 ES6+ 代码
• 组织模块并管理导入/导出
• 添加 JSDoc 类型注解和文档
• 检查命名和风格一致性
• 重构现有 JavaScript 代码

按优先级划分的规则类别

优先级	类别	影响	前缀
1	模块系统与导入	关键	module-
2	语言特性	关键	lang-
3	类型安全与 JSDoc	高	type-
4	命名约定	高	naming-
5	控制流与错误处理	中高	control-
6	函数与参数	中	func-
7	对象与数组	中	data-
8	格式与风格	低	format-

快速参考

1. 模块系统与导入（关键）

• module-avoid-circular-dependencies - 避免循环导入导致加载失败
• module-file-extension-in-imports - 在导入路径中包含 .js 扩展名
• module-named-exports-over-default - 优先使用命名导出，以保持一致性
• module-no-duplicate-imports - 同一文件只导入一次
• module-no-import-aliasing - 保留原始导出名称
• module-source-file-structure - 遵循标准文件结构顺序

2. 语言特性（关键）

• lang-const-over-let-over-var - 默认使用 const，绝不使用 var
• lang-es6-classes-over-prototypes - 使用 class 语法，而非操作原型
• lang-explicit-semicolons - 始终明确使用分号
• lang-no-eval - 绝不使用 eval 或 Function 构造函数
• lang-no-modify-builtins - 绝不修改内置原型
• lang-no-non-standard-features - 仅使用标准 ECMAScript 特性
• lang-no-primitive-wrappers - 绝不使用原始类型包装对象
• lang-no-with-statement - 绝不使用 with 语句

3. 类型安全与 JSDoc（高）

• type-cast-with-parentheses - 类型转换使用括号
• type-enum-annotations - 使用静态字面量值注解枚举
• type-explicit-nullability - 使用明确的可空性修饰符
• type-jsdoc-required-for-exports - 导出的函数必须使用 JSDoc
• type-template-parameters - 始终指定模板参数
• type-typedef-for-complex-types - 复杂对象类型使用 typedef

4. 命名约定（高）

• naming-constant-case-for-constants - 不可变值使用 CONSTANT_CASE
• naming-descriptive-over-brief - 优先使用描述性名称，而非简短名称
• naming-file-naming-conventions - 文件名使用小写字母，并以连字符或下划线分隔
• naming-lowercamelcase-for-methods - 方法和变量使用 lowerCamelCase
• naming-no-dollar-prefix - 标识符避免使用美元符号前缀
• naming-uppercamelcase-for-classes - 类使用 UpperCamelCase

5. 控制流与错误处理（中高）

• control-comment-empty-catch - 为留空的 catch 块添加说明
• control-for-of-over-for-in - 优先使用 for-of，而非 for-in
• control-strict-equality - 除 null 检查外，使用严格相等
• control-switch-default-last - switch 中始终包含 default 分支
• control-throw-error-objects - 始终抛出 Error 对象

6. 函数与参数（中）

• func-arrow-functions-for-nested - 嵌套函数优先使用箭头函数
• func-arrow-parentheses - 箭头函数参数始终加括号
• func-default-parameters - 使用默认参数，而非条件判断
• func-rest-parameters-over-arguments - 使用 rest 参数，而非 arguments
• func-spread-over-apply - 使用展开运算符，而非 apply

7. 对象与数组（中）

• data-array-literals-over-constructor - 优先使用数组字面量，而非 Array 构造函数
• data-destructuring-for-multiple-values - 获取多个属性时使用解构
• data-no-mixing-quoted-unquoted-keys - 不要混用带引号和不带引号的键
• data-object-literals-over-constructor - 优先使用对象字面量，而非构造函数
• data-spread-over-concat-slice - 使用展开运算符，而非 concat 和 slice
• data-trailing-commas - 多行字面量中使用尾随逗号

8. 格式与风格（低）

• format-braces-required - 控制结构始终使用花括号
• format-column-limit - 每行限制为 80 个字符
• format-one-statement-per-line - 每行放置一条语句
• format-single-quotes - 字符串字面量使用单引号
• format-two-space-indent - 使用两个空格缩进

使用方法

阅读各参考文件，了解详细说明和代码示例：

• 章节定义 - 类别结构和影响级别
• 规则模板 - 添加新规则的模板

完整编译文档

如需查看包含所有规则的完整编译指南，请参阅 AGENTS.md。

参考文件

文件	描述
AGENTS.md	包含所有规则的完整指南
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息