用途
TypeScript Best Practices 是一个面向 AI 智能体的技能，用于指导 AI 编写高质量的 TypeScript 代码。它提供编码标准、架构模式，以及用于分析和脚手架的工具。
何时使用
适用场景：
- 生成新的 TypeScript 代码
- 审查 TypeScript 文件的质量问题
- 创建新的模块、服务或组件
- 将 JavaScript 重构为 TypeScript
- 回答关于 TypeScript 模式或类型的问题
- 设计 API 或接口
不适用场景：
- 处理纯 JavaScript（无 TypeScript）
- 调试运行时错误（应使用调试工具）
- 框架特定模式（React、Vue 等，应使用框架技能）
核心原则
1. 类型安全优先
最大化编译期错误检测：对未知类型优先使用 unknown 而非 any；为公共 API 显式标注返回类型；使用 const 断言生成字面量类型。
2. 默认不可变
防止意外修改：对象属性使用 readonly；集合使用 ReadonlyArray；优先使用展开而非修改。
3. 带类型的错误处理
使用类型系统处理错误：为可恢复错误使用 Result 类型；使用类型化错误类；函数可返回 Result 返回类型。
4. 代码组织
为可维护性组织代码：一个文件一个概念；显式导出（不使用 barrel 文件通配符）。
快速参考
| 类别 | 推荐 | 避免 |
|---|---|---|
| 未知类型 | unknown | any |
| 集合 | ReadonlyArray<T> | 输入使用 T[] |
| 对象 | Readonly<T> | 默认可变 |
| 空值检查 | 可选链 ?. | != null |
| 类型收窄 | 类型守卫 | as 断言 |
| 返回类型 | 导出时显式 | 导出时推断 |
| 枚举 | 字符串字面量联合 | 数字枚举 |
| 导入 | 具名导入 | 默认导入 |
| 错误 | Result 类型 | 用抛出控制流程 |
| 循环 | for...of、.map() | 对数组用 for...in |
代码生成指南
生成 TypeScript 代码时遵循以下模式：
模块结构：包含模块描述注释、类型定义（导出接口）、常量（默认选项）、实现（导出函数）。
函数设计：优先纯函数；显式参数类型；复杂签名使用函数重载。
接口设计：对象形状优先使用 interface；联合与交叉使用 type；使用 JSDoc 文档。
常见反模式
生成代码时避免以下模式：
| 反模式 | 问题 | 解决方案 |
|---|---|---|
| any 类型 | 禁用类型检查 | 使用 unknown 并收窄 |
| as 断言 | 运行时错误 | 使用类型守卫 |
| 非空 ! | 空指针错误 | 可选链 ?. |
| 可变参数 | 意外修改 | Readonly<T> |
| 魔法字符串 | 拼写错误、无自动补全 | 字符串字面量类型 |
| 上帝类 | 难以测试/维护 | 单一职责 |
| 循环依赖 | 构建/运行时问题 | 依赖倒置 |
| 索引签名 | 丢失类型信息 | 显式属性 |
详细示例见 references/anti-patterns/common-mistakes.md。
脚本参考
analyze.ts
分析 TypeScript 代码的质量问题：
deno run --allow-read scripts/analyze.ts <path> [options]
选项：--strict（启用所有检查）、--json（输出 JSON 供程序化使用）、--fix-hints（显示建议修复）。
generate-types.ts
从 JSON 数据生成 TypeScript 类型：
deno run --allow-read --allow-write scripts/generate-types.ts <input> [options]
选项：--name <name>（根类型名，默认推断）、--output <path>（输出文件路径）、--readonly（生成 readonly 类型）、--interface（使用 interface 而非 type）。
scaffold-module.ts
创建结构正确的 TypeScript 模块：
deno run --allow-read --allow-write scripts/scaffold-module.ts [options]
选项：--name <name>（模块名，必填）、--path <path>（目标目录，默认 ./src）、--type <type>（类型：service、util、component）、--with-tests（包含测试文件）。
附加资源
类型系统深入：references/type-system/advanced-types.md（泛型、条件类型、映射类型）、references/type-system/type-guards.md（类型收窄技术）、references/type-system/utility-types.md（内置工具类型）。
模式指南：references/patterns/error-handling.md（Result 类型、类型化错误）、references/patterns/async-patterns.md（async/await 最佳实践）、references/patterns/functional-patterns.md（不可变性、组合）、references/patterns/module-patterns.md（导出、依赖注入）。
架构：references/architecture/project-structure.md（目录组织）、references/architecture/api-design.md（接口设计、版本控制）。
模板：assets/templates/module-template.ts.md（模块起始模板）、assets/templates/service-template.ts.md（服务类模板）、assets/tsconfig-presets/strict.json（最大严格度配置）、assets/tsconfig-presets/recommended.json（平衡默认值）。