ts-google

Google TypeScript 最佳实践

基于 Google 内部标准制定的全面 TypeScript 风格指南，专为 AI Agent 和大模型设计。包含 8 个类别中的 45 条规则，并按影响优先级排序，以指导自动重构和代码生成。

适用场景

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

• 编写新的 TypeScript 代码
• 组织模块和导入
• 设计类型注解和接口
• 创建类和函数
• 检查代码风格是否一致
• 重构现有 TypeScript 代码

按优先级划分的规则类别

优先级	类别	影响	前缀
1	模块组织	CRITICAL	module-
2	类型安全	CRITICAL	types-
3	类设计	HIGH	class-
4	函数模式	HIGH	func-
5	控制流	MEDIUM-HIGH	control-
6	错误处理	MEDIUM	error-
7	命名与风格	MEDIUM	naming-
8	字面量与类型强制转换	LOW-MEDIUM	literal-

快速参考

1. 模块组织（CRITICAL）

• module-named-exports - 优先使用命名导出，而非默认导出
• module-no-mutable-exports - 避免可变导出
• module-es6-modules - 仅使用 ES6 模块
• module-no-namespaces - 避免使用 TypeScript 命名空间
• module-import-paths - 项目导入使用相对路径
• module-import-type - 仅导入类型时使用 import type
• module-export-api-surface - 尽量缩小导出的 API 范围

2. 类型安全（CRITICAL）

• types-no-any - 绝不使用 any 类型
• types-prefer-interfaces - 对象优先使用接口，而非类型别名
• types-explicit-structural - 显式标注结构类型
• types-nullable-patterns - 正确处理可空类型
• types-array-syntax - 使用一致的数组类型语法
• types-no-wrapper-types - 绝不使用包装对象类型
• types-prefer-map-set - 优先使用 Map 和 Set，而非索引签名
• types-no-empty-object - 避免使用空对象类型

3. 类设计（HIGH）

• class-parameter-properties - 构造函数赋值使用参数属性
• class-readonly-properties - 属性不再重新赋值时，将其标记为 readonly
• class-no-private-fields - 使用 TypeScript 的 private，而非私有字段
• class-no-static-containers - 避免创建仅包含静态成员的容器类
• class-constructor-parens - 调用构造函数时始终使用括号
• class-no-prototype-manipulation - 绝不直接操作原型

4. 函数模式（高）

• func-declarations-over-expressions - 优先使用函数声明，而非函数表达式
• func-arrow-concise-bodies - 适当地使用简洁的箭头函数体
• func-avoid-this-rebinding - 避免重新绑定 this
• func-rest-parameters - 使用剩余参数，而非 arguments
• func-generator-syntax - 使用正确的生成器函数语法
• func-default-parameters - 谨慎使用默认参数

5. 控制流（中高）

• control-always-use-braces - 控制结构始终使用花括号
• control-triple-equals - 始终使用三等号
• control-for-of-iteration - 遍历数组时优先使用 for-of，而非 for-in
• control-switch-default - switch 中始终包含 default 分支
• control-no-assignment-in-condition - 避免在条件表达式中赋值

6. 错误处理（中）

• error-throw-errors - 始终抛出 Error 实例
• error-catch-unknown - 将 catch 子句变量的类型设为 unknown
• error-empty-catch-comments - 为留空的 catch 块添加说明
• error-avoid-assertions - 避免类型断言和非空断言

7. 命名与风格（中）

• naming-identifier-styles - 使用正确的标识符命名风格
• naming-descriptive-names - 使用描述性名称
• naming-no-decorative-underscores - 避免使用装饰性下划线
• naming-no-interface-prefix - 接口名称不使用 I 前缀
• naming-constants - 真正常量使用 CONSTANT_CASE

8. 字面量与类型转换（低中）

• literal-single-quotes - 字符串使用单引号
• literal-number-formats - 使用正确的数字字面量格式
• literal-explicit-coercion - 使用显式类型转换
• literal-array-constructor - 避免使用 Array 构造函数

使用方法

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

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

参考文件

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