技能介绍

先处理接口腐化问题

随着服务拆分和团队协作加深，API 会从‘小脚本’变成跨端契约。常见问题是：同一类错误在不同端点返回 { error }、null 或直接抛异常；内部函数到处重复校验；第三方响应未经检查就进入业务逻辑；字段命名忽大忽小。更隐蔽的是，用户总会依赖未文档化的行为，例如错误文案、响应顺序或字段类型，这就是 Hyrum's Law。一旦这些行为成为事实上的契约，再想安全移除就很困难。另一个问题是多版本并行：同一份依赖被不同消费者锁定在不同版本，会带来 diamond dependency 和长期维护成本。

技能如何组织设计过程

这个技能把接口设计拆成可检查的决策，而不是只给名词解释：

Contract First：先定义输入输出类型或 schema，再实现。契约不是写完后补文档，而是类型本身就是文档。
一致错误语义：全站选定一种错误格式，例如统一返回 { error: ... }，避免部分端点抛错、部分返回 null、部分返回错误对象。
边界校验：在 API route handler、表单提交、环境变量加载和第三方响应解析处校验；内部函数之间、已校验数据上不要重复校验。
优先扩展：新增字段应可选且向后兼容；用 PATCH 做局部更新，而不是强迫客户端每次提交完整对象。
命名可预测：REST 资源用复数名词，如 GET /api/tasks；查询参数和响应字段用 camelCase；布尔字段用 is、has、can 前缀；枚举值用 UPPER_SNAKE。
TypeScript 表达变体：用 discriminated union 描述输入变体，用 branded type 区分字符串 ID，并把输入类型和输出类型分开。

设计完成后，可以按清单自查：每个端点有类型化 schema；错误格式一致；校验只在边界；列表接口支持分页；新字段可选；命名统一；文档或类型与实现一起提交。

适用边界与注意点

它适用于 REST API、GraphQL schema、模块边界、组件 props 等代码交接面，但不替代鉴权、限流、可观测性、性能优化等专项设计。第三方接口返回的数据应始终视为不可信输入，即使对方是合作伙伴。若外部输入、环境变量或跨服务响应已经存在，重点不是补一层内部防御，而是把校验放在系统入口。