API版本管理
diegosouzapw2026-10-27查看 1125复制 278
设计和管理 API 版本管理策略，以实现向后兼容的演进
📘如何使用这个技能
- 1复制技能内容·点击上方「Copy SKILL.md」复制全部内容，或 Download 下载到本地
- 2打开你的 AI 客户端·支持 Claude Code、Trae、Cursor、ChatGPT、DeepSeek、Kimi 等任意 AI 助手
- 3粘贴为系统提示/知识文件·Claude Code：放入 .claude/skills/ 目录；普通对话：作为首条消息发送并说「请严格按这份技能文档执行」
- 4直接提出你的需求·AI 会按技能定义的工作流、格式和约束来处理，无需再解释背景
💡 提示：技能生效后，每次对话只需一句需求，AI 会按 SKILL.md 的流程执行。
SKILL.md2396 chars
---
name: API Versioning
description: Design and manage API versioning strategies for backward-compatible evolution
category: api
version: 1.0.0
triggers:
- api-breaking-change
- deprecation-needed
- version-bump
globs: "**/api/**,**/openapi/**,**/routes/**"
---
# API Versioning Skill
Design and manage API versioning strategies for backward-compatible evolution.
## Trigger Conditions
- Breaking API change is proposed
- New API endpoint is created
- User invokes with "version API" or "API deprecation plan"
## Input Contract
- **Required:** Current API spec and proposed change
- **Required:** Consumer list (who calls this endpoint)
- **Optional:** Sunset timeline, migration support level
## Output Contract
- Versioning recommendation (strategy + implementation)
- Breaking change analysis with consumer impact
- Migration guide for consumers
- Deprecation timeline with Sunset headers
## Tool Permissions
- **Read:** API specs, route definitions, consumer registry
- **Write:** API specs, migration guides, deprecation notices
- **Search:** Codebase for endpoint usage
## Execution Steps
1. Analyze proposed change for breaking vs. non-breaking
2. If breaking: determine versioning strategy (URL path, header, content negotiation)
3. Assess consumer impact using consumer registry
4. Draft migration guide for affected consumers
5. Configure Sunset and Warning headers on deprecated endpoints
6. Set deprecation timeline (minimum 3 months)
7. Create monitoring for deprecated endpoint usage
## Success Criteria
- Breaking changes identified and versioned correctly
- All affected consumers notified with migration guide
- Sunset headers configured on deprecated endpoints
- Monitoring in place to track deprecated endpoint usage
## Escalation Rules
- Escalate if >10 consumers are affected by breaking change
- Escalate if deprecation timeline conflicts with consumer contracts
- Escalate if no versioning strategy exists yet
## Example Invocations
**Input:** "We need to change the /users response from {name: string} to {first_name: string, last_name: string}"
**Output:** Breaking change: field removal (name) + field addition (first_name, last_name). Strategy: v2 endpoint at /api/v2/users. v1 maintained with computed 'name' field for 6 months. Migration guide: update client SDK, map first_name+last_name. Sunset header on v1: 2026-08-01. Monitor v1 usage weekly.