API版本管理
版本管理策略对比
| 策略 | 示例 | 优点 | 缺点 |
|---|---|---|---|
| URL路径 | /api/v1/users | 简单、可缓存、可见 | URL随版本变化 |
| 查询参数 | /api/users?v=1 | 可选，便于测试 | 缓存复杂 |
| 自定义Header | API-Version: 1 | URL整洁 | 默认不可缓存 |
| Accept Header | Accept: application/vnd.api.v2+json | 符合REST规范 | 冗长，难测试 |
语义化版本（SemVer）
MAJOR.MINOR.PATCH → 2.1.4 MAJOR: Breaking changes (2.x.x → 3.0.0) MINOR: New features, backward compatible (2.1.x → 2.2.0) PATCH: Bug fixes, backward compatible (2.1.4 → 2.1.5) Pre-release: 2.0.0-beta.1 Build meta: 2.0.0+build.123
API弃用策略
// Response headers for deprecated endpoints HTTP/1.1 200 OK Deprecation: Sat, 01 Jan 2025 00:00:00 GMT Sunset: Mon, 01 Jul 2025 00:00:00 GMT Link: <https://api.example.com/v2/users>; rel="successor-version"
破坏性 vs 非破坏性变更
| 破坏性（主版本） | 非破坏性（次版本/补丁） |
|---|---|
| 删除字段 | 添加新可选字段 |
| 重命名字段 | 添加新端点 |
| 更改字段类型 | 扩展允许值范围 |
| 更改认证方式 | Bug修复 |
| 删除端点 | 性能改进 |