api-versioning-patterns

@vibeeval · 收录于 1 周前 · 上游提交 1 个月前

API versioning strategies, breaking change detection, deprecation lifecycle, and migration guides

场景接口升级版本规划兼容性检查

适合你，如果你在维护对外 API 并需要规划版本演进。

/ 下载安装

api-versioning-patterns.skill双击,或拖进 Claude 桌面版 / Cowork,即完成安装↓ .skill ↓ .zip

用别的 agent?下载 .zip 解压,把文件夹放进它的技能目录

Claude Code~/.claude/skills/(项目级 .claude/skills/)

Codex CLI~/.codex/skills/

Cursor自动读取上面两处目录

其他工具见其文档的「skills」目录;两个下载是同一份文件,只是名字不同

/ 通过 npx 安装 校验哈希

npx oh-my-skill add vibeeval/vibecosystem/api-versioning-patterns

/ 通过 bash 安装

curl -fsSL https://oh-my-skill.com/install.sh | bash -s -- vibeeval/vibecosystem/api-versioning-patterns

/ 已经装过?验证本机副本,不用重装

npx oh-my-skill verify vibeeval/vibecosystem/api-versioning-patterns

安装目标可用 --agent / --scope 或 --to 明确指定;省略时只会在唯一已存在的 agent 目录上自动选择,零命中或多命中会停止并提示。content_hash 缺失或不一致均拒装。

515GitHub stars

~570上下文体积 · 单文件

镜像托管

怎么用

技能原文 SKILL.md作者撰写 · MIT · cea9462

API Versioning Patterns

Versioning Strategies

| Strateji | Örnek | Pros | Cons | |----------|-------|------|------| | URL Path | /v1/users | Açık, cache-friendly | URL kirliliği | | Header | Accept: application/vnd.api+json;v=2 | Clean URL | Debug zor | | Query Param | /users?version=2 | Basit | Cache sorunlu | | Content Negotiation | Accept: application/vnd.company.v2+json | RESTful | Karmaşık |

Öneri: URL Path (/v1/) — en yaygın, en anlaşılır.

Breaking Change Detection

// Breaking changes
const breakingChanges = [
  'Required field ekleme',
  'Field silme veya rename',
  'Type değiştirme (string → number)',
  'Enum value silme',
  'Response structure değiştirme',
  'Error code değiştirme',
  'Auth requirement ekleme'
]

// Non-breaking changes
const nonBreaking = [
  'Optional field ekleme',
  'Yeni endpoint ekleme',
  'Enum value ekleme',
  'Response'a optional field ekleme',
  'Performance improvement'
]

Deprecation Lifecycle

Phase 1: ANNOUNCE (3 ay önce)
  → Deprecation header: Sunset: Sat, 01 Jan 2027 00:00:00 GMT
  → API docs'ta uyarı
  → Consumer'lara email

Phase 2: WARN (2 ay önce)
  → Response header: Deprecation: true
  → Log: deprecated endpoint kullanımı
  → Dashboard: kullanım metrikleri

Phase 3: THROTTLE (1 ay önce)
  → Rate limit düşür
  → Warning response body'ye ekle

Phase 4: SUNSET
  → 410 Gone döndür
  → Migration guide link'i ile

Migration Guide Template

# Migration: v1 → v2

## Breaking Changes
1. `GET /v1/users` → `GET /v2/users`
   - Response: `{ data: User[] }` → `{ items: User[], meta: {...} }`
2. `POST /v1/orders`
   - New required field: `currency` (ISO 4217)

## Step-by-Step
1. Update client SDK to v2
2. Add `currency` field to order creation
3. Update response parsing for `items` + `meta`
4. Test against v2 staging
5. Switch production to v2

## Compatibility Period
v1 available until: 2027-06-01

Checklist

[ ] Versioning stratejisi seçilmiş
[ ] Breaking change policy documented
[ ] Deprecation lifecycle tanımlı
[ ] Sunset header ekleniyor
[ ] Migration guide var
[ ] Version usage metrikleri tracked
[ ] Consumer notification sistemi var
[ ] Minimum 6 ay backward compatibility

Anti-Patterns

Version'sız API (her değişiklik breaking)
Eski version'u ani kapatma (sunset lifecycle uygula)
Breaking change without version bump
Her küçük değişiklikte yeni version
Consumer'lara haber vermeden deprecate

按 MIT 许可原样转载,未经改动 · 在 GitHub 查看 →

登录即可评论;带「已验证安装」的,是发布者名下有本店的安装或持有记录。

…