API 契约与接口设计

设计服务间通信协议、明确请求与响应规范、固化输入输出校验并统一错误返回结构。本 skill 关注系统对外与模块间的通信契约；内部业务逻辑由领域模块负责。

本 skill 保持技术栈无关，不预设具体网络框架或校验库，只提供协议权衡维度、结构化决策清单与防御性工程标准。

何时主动介入

在实现过程中遇到以下情况时，停下来先把契约定下来，而不是先写实现再回头补：

• 新增一个对外或跨模块调用的接口，但还没有结构化契约定义：先确认字段、类型与校验规则，再写路由处理逻辑。口头约定或"看实现代码猜字段"都不算契约。
• 错误响应的字段结构和已有接口不一致：指出偏差，要求统一到同一个错误外壳，而不是让新接口另起一套。
• 要给已上线接口删字段、改字段类型或收紧校验：这是破坏性变更，先确认是否有存量调用方，并给出弃用窗口，不要直接改。
• 响应体直接序列化 ORM 实体或数据库查询结果：立即指出潜在的字段泄露风险，要求换成显式的响应结构投影。

日常增量开发中新增字段、调整可选参数等不破坏兼容性的小改动，不必每次都重新过一遍完整决策清单。

决策清单