关于 typescript-best-practices
为 TypeScript 提供类型系统与实现规范，帮助编写更安全、清晰的代码。内容涵盖变体建模、在边界验证外部数据，以及使用真实测试原语验证行为。
主要功能
- 01用可辨识联合建模变体
- 02在边界验证外部数据
- 03优先使用 unknown 和模式派生类型
- 04进行穷尽性检查
- 05使用真实测试原语
- 06输出结构化诊断信息
适用场景
- 01设计领域类型与模式
- 02审查类型守卫和类型断言
- 03测试应用行为
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/typescript-best-practices确认已加载。
附带文件references/patterns.md
详细介绍
TypeScript 最佳实践
首先应用 type-system-discipline 原则技能。
| 规则 | 摘要 |
|---|---|
| 可辨识联合 | 使用 kind 字面量判别字段对变体建模，使不可能的状态无法表示。不要使用装满可选字段的对象。 |
| 品牌类型 | 使用 & { readonly __brand: "X" } 为原始类型添加品牌，避免它们混淆。只在边界处验证一次。 |
| 构造式建模 | 设计类型结构，使非法值无法构造。非空使用 [T, ...T[]]，偶数长度使用 [T, T][]，范围使用 start 加 duration。不要依赖运行时检查，也不要寄希望于细化类型。 |
| 最简单的全定义类型 | 只要对 T[] 的每项操作都保持全定义，就使用 T[]。只有在宽松类型迫使你使用 !、类型断言或“本不该发生”的抛错时，才加强为 NonEmpty<T>。 |
优先使用 unknown 而非 any | 外部数据类型为 unknown。 |
| 先定义 Schema，再写守卫 | 在手写逐属性类型守卫之前，先使用仓库的运行时 Schema 库，并从 Schema 推导类型，例如 z.infer。 |
不使用 as 类型断言 | 每个 as 都可能导致运行时崩溃。仅在验证后使用类型断言。 |
| 缩窄优先级 | 判别字段 switch > in 运算符 > typeof/instanceof > 用户定义的类型守卫 > as。 |
| 类型守卫 | 必须验证其声称的内容。会撒谎的守卫比 as 更糟，因为错误会藏在一个声称安全的名称后面。将其命名为 isX 或 hasX。 |
| 穷尽性检查 | 在 default 分支中内联 const _exhaustive: never = x;，这样添加新变体时编译器会报错。 |
优先使用 satisfies 而非 as | 验证值，同时避免字面量类型扩大。 |
| 边界验证 | 在数据进入系统时，将其解析为有名称的领域类型。Record<string, unknown>（无论如何拼写）只应存在于解析之前。内部应信任类型。请参阅 boundary-discipline 原则技能。 |
| 从 Schema 推导类型 | 声明新接口之前，优先考虑 Pick/Omit/Parameters/ReturnType/Awaited/typeof。 |
| 对象参数 | 传递对象而非位置参数，让参数顺序一目了然。高频路径（逐帧渲染、分词器、解析器）除外。 |
| 真实测试 | 能实际运行的内容就不要模拟。优先使用框架真实的测试原语，并检查资源泄漏和可释放对象；在运行中的构建中验证 UI。只模拟无法在本地运行的内容。 |
| 结构化遥测 | 优先使用包含足够上下文、可通过 ID 调试的结构化日志诊断。已发布的代码中不要使用 console.log。 |
示例：references/patterns.md。
评论
支持 Markdown