Typed Service Contracts(Spec & Handler 模式)是一项用于构建健壮、类型安全 TypeScript 服务的架构标准。它定义了基于契约式设计(Design by Contract, DbC)原则的垂直切片架构,将应用逻辑视为严格定义的工作单元:输入需要被解析(parse)而非仅仅校验(validate),错误则作为值通过 Result 模式返回,而不是以异常形式抛出。
适用场景
该技能适用于以下情况:构建 CLI 或库,需要在用户输入与系统逻辑之间建立严格边界;输入需要先经过转换(解析)才能使用,例如确保字符串是有效文件路径;对可靠性要求高,不能承受未处理的运行时异常,需要穷尽的错误处理;希望将数据校验测试与业务逻辑测试分离的测试场景。
架构组成
-
Spec(spec.ts):即“契约”或“端口”,定义“做什么”。其中包含输入 Schema(Zod 模式,将原始输入解析为有效 DTO)、输出 Schema(定义成功数据结构)、错误 Schema(具体失败模式的可辨识联合,而非通用错误)、Result 类型(成功与失败的可辨识联合),以及接口(能力定义,如 interface ConfigureSpec)。
-
Handler(handler.ts):即“实现”或“适配器”,定义“怎么做”。它实现 Spec 中定义的接口,是处理副作用(文件系统、API 调用)的“非纯”类,且绝不抛出异常,必须捕获内部错误并映射为 Result 类型。
使用方式
第一步:在 spec.ts 中定义契约。可创建可复用的校验辅助模式(如 SafePathSchema),定义输入 Schema 并导出推断类型,定义穷尽的错误码枚举,定义成功与失败的 Result 模式及对应类型,最后声明能力接口(如 execute 方法返回 Promise)。
第二步:在 handler.ts 中实现处理器。实现 Spec 接口,在 execute 方法中编写业务逻辑;遇到预期错误时显式返回失败 Result(不抛出);成功时返回成功 Result;并通过 try/catch 作为安全网捕获未知运行时错误,映射为 UNKNOWN_ERROR。
第三步:测试策略。不要编写单体式测试,而应拆分为契约测试与逻辑测试。契约测试针对 Schema,确保无效数据在到达处理器前被拒绝,聚焦边界情况、校验规则与 Zod 精化,采用数据驱动(表驱动)风格。逻辑测试针对 Handler,模拟外部依赖(如 fs、网络)并断言 Result 对象,聚焦业务逻辑流程、错误映射与成功状态,采用模拟单元测试或场景运行器风格。
限制与注意事项
资料未提供该技能的安装方式、平台要求、收费信息或性能数据。使用该模式需要项目已采用 TypeScript 与 Zod;Handler 中需要自行处理所有副作用并确保异常被捕获映射为 Result,否则会破坏“不抛异常”的契约约定。