API 契约守卫

技能文档

---
name: jarvis-api-contract-guard-01
description: 设计并验证 API 契约，确保接口向后兼容。当用户需要设计 API 接口契约、修改已有接口、评估接口变更的兼容性风险、制定接口版本策略或搭建接口质量门禁时触发。触发词：API契约、接口设计、向后兼容、接口变更、契约测试、接口评审、版本策略。
title: API 契约守卫
category: 开发工具
---

# API 契约守卫

为开发任务提供一套可复用的工作流，聚焦 API 契约的设计与验证，保证接口演进过程中的向后兼容性。

## 技能工作流

### 步骤1：明确输入

开始前确认以下信息齐备，缺失时向用户澄清：

- 期望结果与时间要求
- 约束条件（时间、可用工具、风险容忍度）
- 已有素材（代码、文档、截图、日志、现有接口定义）

### 步骤2：定义验收标准

以可度量的方式定义成功与失败标准：

- 兼容性边界：哪些调用方行为必须保持不变
- 破坏性变更清单：字段删除、类型变更、语义调整等
- 每条标准都要可验证（如「旧客户端不传新字段时响应结构不变」）

### 步骤3：构建最小可行路径

先打通最小可用的执行路径，再扩展投入：

- 先定义契约（请求/响应结构、错误码、状态码语义）
- 用最少字段跑通端到端调用
- 确认后再补充可选字段与扩展能力

### 步骤4：检查点执行与留证

分检查点推进，每个检查点记录证据：

1. 契约定义完成 → 验证：契约文档经评审确认
2. 兼容性验证完成 → 验证：旧版本调用样例全部通过
3. 变更评审完成 → 验证：破坏性变更有明确的版本迁移方案

### 步骤5：质量门禁

在给出最终结论前逐项自查：

- 只做有证据支撑的判断
- 显式列出假设与权衡
- 高风险操作优先选择可回滚方案
- 每个下一步都有明确负责人与截止时间
- 主方案失败时提供备选方案

### 步骤6：输出结论

按固定结构交付：

- 现状摘要（不超过 5 行）
- 关键发现（按影响排序）
- 行动计划（今日 / 本周）
- 风险与缓解措施
- 必要时附上确切的检查清单或命令

## 常用提示语

- 「帮我把这份零散的接口讨论整理成可落地的契约方案」
- 「按风险优先级给出接口变更的行动序列，附验收检查项」
- 「评估这次接口改动是否向后兼容，列出破坏性风险」

使用说明

# API 契约守卫

设计并验证 API 契约，确保接口在迭代过程中的向后兼容性。

## 能做什么

- 设计结构清晰的接口契约（请求/响应、错误码、状态码语义）
- 评估接口变更的兼容性风险，识别破坏性变更
- 制定接口版本策略与迁移方案
- 搭建接口质量门禁，输出可验收的行动计划

## 何时使用

- 新增或修改 API 接口时
- 接口评审、评估老接口能否安全下线时
- 多个调用方共享同一接口、需要保证旧客户端不受影响时

## 快速上手

把接口现状与变更需求发给 Agent，例如：

```text
我要给 /orders 接口增加一个可选字段 refundReason，
评估这次改动是否向后兼容，输出风险与验收清单。
```

Agent 会按「明确输入 → 定义验收标准 → 最小可行路径 → 检查点执行 → 质量门禁 → 输出结论」的流程给出结构化结论。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。