技能介绍

你要解决什么问题

接口写出来才发现问题：有的端点直接 throw，有的返回 null，有的包一层 { error }，调用方写不出统一的处理逻辑。更隐蔽的是隐式契约——某条错误文案被前端拿去做了判断，一次「无害」的文案调整就变成线上故障；没写进文档的字段顺序，也在某个客户的解析脚本里悄悄生效。Hyrum 定律说这是必然：只要行为可被观察，就一定有人依赖它。

这个技能做什么

核心是一套从契约到落地的设计流程：

契约先行：先定义接口类型和 schema，再写实现；TypeScript 的类型本身就是文档，应与实现一起提交
单一版本策略：用扩展代替复制（fork），避免多版本并存引发的钻石依赖问题
统一错误语义：全局选定一种错误策略，禁止在同一套接口里混用 throw、null、error 对象三种姿势
边界校验：只在系统入口——路由处理器、表单提交、外部服务响应、环境变量——做校验；内部函数之间信任类型契约
渐进式演进：新增字段一律可选且向后兼容，旧的先废弃再移除
命名约定：REST 路径用复数名词，查询参数与响应字段用 camelCase，布尔字段加 is/has/can 前缀，枚举用 UPPER_SNAKE

适用边界与注意点

这套规范适用于 REST API、GraphQL schema、模块边界、组件 props 等任何「两段代码对话」的表面。两点注意：其一，契约测试挡不住 Hyrum 定律，依赖未文档化行为的用户仍可能被看似安全的变更打断，改动前要盘点所有可观察行为；其二，第三方 API 的响应永远按不可信输入处理，先校验形状再进入逻辑。文末的验证清单（类型化 schema、单一错误格式、仅边界校验、分页、字段向后兼容）可直接用作 review 检查表。