接口契约设计
给出一条接口边界的双方需求,产出唯一的契约工件、生成的类型和双方对接验证流程。
功能与用途
前后端并行开发时字段名、可空性、枚举和错误结构总是对不上,mock 和生产响应的形状还不一致,这时用它。它要求为每条边界只保留一份权威的契约文件(OpenAPI、AsyncAPI、Protobuf 或 JSON Schema),从消费方真正要完成的任务出发定义最小字段集,再由契约生成类型和 mock 让前端先动手,后端则要证明真实响应符合同一份契约。契约变更也有固定流程:先提兼容性影响、改工件、评审 diff、再重新生成和改实现,不允许先改代码后补契约。
适用场景
- 前后端要并行开工,但接口字段还没定,怕两边各写一套最后对不上:前后端要并行开工,但接口字段还没定,怕两边各写一套最后对不上
- 多个服务交换事件和命令,枚举值和错误结构总在悄悄漂移,谁都说:多个服务交换事件和命令,枚举值和错误结构总在悄悄漂移,谁都说不清哪份定义算准
- 想改一个接口字段名,但不确定会打断哪些下游消费者,需要先评估:想改一个接口字段名,但不确定会打断哪些下游消费者,需要先评估兼容性再动手
适用人群
- 后端 API 开发工程师
- 前端架构师
- 微服务技术负责人
使用步骤
- 先记录这条边界的消费者、提供方、可批准变更的人和哪份工件是权威版本。
- 从每个消费者要渲染或完成的任务出发,逐条确认必填字段、空值语义、枚举和错误分支。
- 选定工件格式写出最小契约,并用固定的生成器产出消费者类型和 mock。
- 要求提供方用真实响应逐条校验同一份契约,覆盖沙箱、错误、空集合和可空字段。
- 涉及字段变更时按先提影响、再改工件、评审 diff、重新生成、最后改实现的顺序推进。
开始使用
将需求和 Skill 名称发送给已连接 SkillPX MCP 的 AI 助手,核对适用工具和安装要求。
技术信息
- 分类
- 编程
- 适用工具
- 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.
使用前准备
- 需要一个使用版本控制的代码仓库,并已有可固定的契约生成器脚本
依赖与权限
- 读取用户主动提供的内容