typescript-best-practices

TypeScript 最佳实践

以粗体或反引号标出的技能名称，或以 /<name> 形式运行的技能，指的是本技能目录旁的 ../<name>/SKILL.md 文件；不带前缀的原则名称指的是 ../principle-<name>/SKILL.md。阅读该文件并遵循其中的要求。大多数 pstack 技能仅供用户使用，因此你的技能工具无法加载它们。

首先应用 type-system-discipline 原则技能。

规则	摘要
可辨识联合	使用 kind 字面量判别字段对不同变体建模，确保无法表示不可能的状态。不要使用包含可选字段的对象。
品牌类型	用 & { readonly __brand: "X" } 为原始类型添加品牌，避免它们被混淆。只在边界处验证一次。品牌应来自验证型类型守卫（input is AgentId），而不是 as。
构造式建模	设计数据结构，使非法值无法构造。非空用 [T, ...T[]]，偶数长度用 [T, T][]，范围用 start 加 duration。这不是运行时守卫，也不是对细化类型的期待。
最简单的全函数类型	只要对 T[] 的所有操作都保持全定义，就继续使用 T[]。只有当宽松类型迫使你使用 !、类型断言或“理论上不应发生”的抛错时，才强化为 NonEmpty<T>。
优先使用 unknown，而非 any	外部数据的类型是 unknown。
先用模式，再写守卫	在手写逐属性类型守卫之前，先使用仓库的运行时模式库，并从模式推导类型，例如使用 z.infer。
不用 as 类型断言	每个 as 都可能导致运行时崩溃。仅在验证之后才使用类型断言。
缩窄优先级	判别字段 switch > in 运算符 > typeof/instanceof > 用户定义的类型守卫 > as。
类型守卫	必须验证其所声称的内容。说谎的守卫比 as 更糟，因为错误藏在一个看似安全的名称背后。将其命名为 isX 或 hasX。
穷尽性检查	在 default 分支中内联 const _exhaustive: never = x;，以便添加新变体时编译器报错。
优先使用 satisfies，而非 as	验证值，同时不扩大字面量类型。
边界验证	在数据进入系统的边界处解析为具名领域类型。Record<string, unknown>（无论具体写法如何）都应止步于该解析处。内部应信任类型。参见 boundary-discipline 原则技能。
从模式推导类型	声明新接口之前，优先考虑 Pick/Omit/Parameters/ReturnType/Awaited/typeof。
对象参数	传递对象而非位置参数，让参数顺序一目了然。热路径（逐帧渲染、分词器、解析器）除外。
真实测试	能实际运行的就不要模拟。优先使用框架真实的测试原语，检查泄漏和可释放资源，并在运行中的构建中验证 UI。只模拟无法在本地运行的内容。
结构化遥测	优先使用带有充分上下文的结构化日志诊断，以便根据 ID 进行调试。已发布的代码中不要使用 console.log。

示例：references/patterns.md。