Agent Skills
返回列表
接口契约助手

接口契约助手

开发编程 更新于 2026.08.29

将以下提示词粘贴到你的 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/测试开发编写生产者与消费者契约测试,覆盖失败、重试与演进场景