SuperAPI AI 工具集

typescript-functional-patterns

编程与开发

查看项目

更新于 10-16 07:08

技能介绍

用途

该技能面向需要构建可靠 TypeScript 系统的场景,通过函数式编程模式让类型系统承担正确性证明:将业务规则编码进类型,使非法状态无法构造,编译期捕获错误而非运行期。

主要能力

技能内容覆盖四类核心模式:

  1. 可辨识联合(Discriminated Unions / Sum Types):用 kind、type、_tag 等判别字段建模"多种变体之一",并在 switch 的 default 分支配合 assertNever 实现穷尽性检查,缺少分支时产生编译错误。示例包括支付方式(card/ach/wallet)、交易生命周期(pending/settled/failed/reversed)等状态机。

  2. Option 类型:显式处理"值可能缺失",定义为 { _tag: "None" } | { _tag: "Some"; value: T },并提供 isNone、isSome、getOrElse、map、flatMap 等工具函数。

  3. Result 类型:不使用异常处理可恢复错误,定义为 { _tag: "Ok"; value: T } | { _tag: "Err"; error: E },并提供 isOk、isErr、mapResult、flatMapResult 等工具函数。

  4. 品牌类型(Branded Types):通过 Brand<K, T> = K & { __brand: T } 与智能构造函数(smart constructor)实现名义类型与校验不变量,示例含 Cents、Dollars、Email、Millis、PositiveInt、UserId、OrderId、Seconds 等。

使用方式

技能给出可直接粘贴的 helper 代码(Option、Result、assertNever、Brand 及其构造函数),可按需复制到项目中使用。文中建议的实践包括:default 分支始终使用 assertNever;判别字段命名保持一致(如统一用 _tag);尽早收窄类型以启用类型安全;智能构造函数中完成校验;以及启用 TypeScript 严格模式标志(strictNullChecks、noImplicitReturns、strictFunctionTypes)。迁移策略为:新功能从第一天使用函数式模式;修改缺陷时把相关代码重构为可辨识联合;优先处理金融计算、状态机等高风险区域;团队内共享 helper 并结对完成首次实现。

适用场景

  • 可辨识联合:状态机建模(pending → settled → reconciled)、互斥变体(支付方式、用户角色)、带不同状态的领域模型、用显式状态替代布尔标志。
  • Option:值可能缺失且缺失是合法预期、替代 null/undefined 检查、串联可能找不到值的操作、在 API 中显式表达可空性。
  • Result:操作可能以可恢复错误失败、需要传递错误上下文、替代预期失败的 try/catch、把错误处理写进函数签名。
  • 品牌类型:防止单位混淆(分与元、毫秒与秒)、强制校验不变量(邮箱格式、正数)、类型安全的 ID(UserId 与 OrderId)、领域驱动设计中的值对象。

限制

资料未说明该技能的具体运行环境依赖、版本兼容范围、性能开销与已知缺陷;错误处理策略中建议用异常处理程序性错误(如 unreachable),资料未给出更多边界情况说明。

触发条件

讨论可辨识联合与 sum 类型、状态机建模、Result/Option 类型与错误处理、品牌类型与智能构造函数、类型安全领域模型、使非法状态不可表示、TypeScript 函数式编程时,该技能会自动加载。

参考来源说明

这些模式受 Rastrian 的文章《Why Reliability Demands Functional Programming, ADTs, Safety and Critical Infrastructure》启发;技能内提供 ADT、Option & Result、Branded Types 的详细参考与迁移指南链接(资料未列出具体 URL)。