用途
该指南是一套 TypeScript 类型安全政策,用于在编写或审查任何 TypeScript 代码时应用。其目标是编写最大程度类型安全的代码。
主要能力与规则
资料以规则加概要的形式列出以下内容:
- 禁用 as 类型断言:每一次 as 都是潜在的运行时崩溃。应在边界处做验证,只有在有充分依据时才断言。优先使用 Zod/Valibot 而非手工验证。
- 用 unknown 替代 any:any 会对其触及的一切关闭类型检查。外部数据始终是 unknown。
- 可辨识联合:用共享的字面量判别字段来建模变体。不要使用可选字段的集合。
- 类型收窄的优先级:优先使用 可辨识联合的 switch > in 运算符 > typeof/instanceof > 类型守卫 > as。
- 类型守卫:必须真正验证其断言。命名使用 isX 或 hasX。尽可能优先使用判别字段收窄。
- 穷尽性检查:对可辨识联合的 switch 始终添加 default: never 分支。可使用 absurd() 辅助函数减少样板代码。
- 用 satisfies 替代 as:在验证某个值匹配某类型而又不希望拓宽类型时,使用 satisfies 以保留字面量类型。
- 不可能状态:如果某个 bug 需要追问“这种组合会发生吗?”,说明类型过于宽松,应收紧它。
使用方式
在编写或审查 TypeScript 时应用上述规则。资料指出,可阅读 references/patterns.md 获取每条规则的代码示例。除此之外的具体安装命令、配置方式与集成方式暂未提供。
适用场景
适用于需要最大化类型安全的 TypeScript 代码编写与代码审查场景,尤其是涉及外部数据边界校验、变体状态建模、类型收窄与穷尽性检查的代码。
限制
资料未提供收费、价格、平台支持范围、运行环境要求或具体工具链集成信息。具体代码示例位于 references/patterns.md,本资料仅给出了规则概要。