AI Skill 大全

接口契约设计

给出一条接口边界的双方需求,产出唯一的契约工件、生成的类型和双方对接验证流程。

功能与用途

前后端并行开发时字段名、可空性、枚举和错误结构总是对不上,mock 和生产响应的形状还不一致,这时用它。它要求为每条边界只保留一份权威的契约文件(OpenAPI、AsyncAPI、Protobuf 或 JSON Schema),从消费方真正要完成的任务出发定义最小字段集,再由契约生成类型和 mock 让前端先动手,后端则要证明真实响应符合同一份契约。契约变更也有固定流程:先提兼容性影响、改工件、评审 diff、再重新生成和改实现,不允许先改代码后补契约。

适用场景

  • 前后端要并行开工,但接口字段还没定,怕两边各写一套最后对不上:前后端要并行开工,但接口字段还没定,怕两边各写一套最后对不上
  • 多个服务交换事件和命令,枚举值和错误结构总在悄悄漂移,谁都说:多个服务交换事件和命令,枚举值和错误结构总在悄悄漂移,谁都说不清哪份定义算准
  • 想改一个接口字段名,但不确定会打断哪些下游消费者,需要先评估:想改一个接口字段名,但不确定会打断哪些下游消费者,需要先评估兼容性再动手

适用人群

  • 后端 API 开发工程师
  • 前端架构师
  • 微服务技术负责人

使用步骤

  1. 先记录这条边界的消费者、提供方、可批准变更的人和哪份工件是权威版本。
  2. 从每个消费者要渲染或完成的任务出发,逐条确认必填字段、空值语义、枚举和错误分支。
  3. 选定工件格式写出最小契约,并用固定的生成器产出消费者类型和 mock。
  4. 要求提供方用真实响应逐条校验同一份契约,覆盖沙箱、错误、空集合和可空字段。
  5. 涉及字段变更时按先提影响、再改工件、评审 diff、重新生成、最后改实现的顺序推进。

开始使用

将需求和 Skill 名称发送给已连接 SkillPX MCP 的 AI 助手,核对适用工具和安装要求。

查看 MCP 接入说明

技术信息

分类
编程
适用工具
Codex、Claude Code、OpenClaw、Hermes、国内 Agent
使用难度
专业
版本
main
最近更新
2026-09-13
文件数
3
安装包大小
自动生成 ZIP
安全检查
基础检查通过

Use when multiple consumers and providers must evolve an API or event schema without field drift, integration surprises, or one side silently redefining the interface.

使用前准备

  • 需要一个使用版本控制的代码仓库,并已有可固定的契约生成器脚本

依赖与权限

  • 读取用户主动提供的内容

同类 Skill