接口契约助手
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,安装 @user_b4da0893/interface-contract-cn。
技能介绍
要解决什么问题
跨团队或跨服务对接时,常见痛点不是「有没有 OpenAPI」,而是消费者无法预测:成功体里字段算不算状态、重复 POST 会不会多扣款、并发 PATCH 谁覆盖谁、新增枚举会不会把旧 App 打崩。展示文案当错误码、路由先上再补语义,都会把集成成本推到线上事故里。
技能如何协助你
本技能把契约定义为双方可观察且可依赖的行为全集,而不只是路径清单。标准流从识别生产者/消费者与信任边界开始,固定资源与状态机,再分别写输入、成功输出、错误目录(含是否可重试)、幂等键与并发语义、列表分页规则,以及安全与可观察面。
产出按固定骨架组织:操作清单(QUERY / COMMAND / EVENT)、兼容性标注(COMPATIBLE / CONDITIONAL / BREAKING)、迁移与契约测试门禁。还内置反模式对照(先写控制器再补契约、错误只有自然语言等)和场景化深度说明(支付幂等、弱网客户端、开放平台弃用周期等)。
适用边界与注意点
它不替你选框架、调真实生产接口或自动发版;在未知消费者存在时也不应直接删字段或错误码。类型定义不能替代契约——权限、副作用、排序与时序仍需显式写明。变更前应结合真实客户端版本分布,并按需引用兼容性矩阵与契约测试清单做验收。
使用场景
- 前后端对同一字段含义不一致,需要先统一资源术语、输入输出和状态变化再改实现
- 上线带副作用的创建/支付接口前,要定义幂等键、重复请求响应和可重试错误码
- 列表接口被客户端依赖默认排序,需要写清游标/页码、上限和过滤组合的稳定语义
- 准备破坏性变更枚举或删字段,要标 BREAKING、迁移动线和回滚阈值
适合人员
- 负责对外 REST/GRPC 的后端工程师,要在实现前把错误码与并发写入规则写进评审材料
- 维护多端 SDK 或 BFF 的工程师,需要把第三方不稳定响应在信任边界上验 schema 与大小限制
- 技术负责人推进跨团队接口改版,要评估旧客户端版本分布并制定双写读与弃用门禁
- QA/测试开发编写生产者与消费者契约测试,覆盖失败、重试与演进场景