API Changelog & Versioning

概览

创建全面的API变更日志，记录更改、弃用、重大更改，并为API消费者提供迁移指南。

何时使用

API版本变更日志
重大更改文档
版本间迁移指南
弃用通知
API升级指南
向后兼容性说明
版本比较

API变更日志模板

# API Changelog

## 版本 3.0.0 - 2025-01-15

### 🚨 重大更改

#### 认证方法更改

**之前 (v2):**
```http
GET /api/users
Authorization: Token abc123

当前 (v3):

GET /api/v3/users
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

影响: 所有API消费者必须从API令牌切换到JWT Bearer令牌

迁移步骤:

从 /api/v3/auth/login 端点获取JWT令牌
将 Authorization: Token 替换为 Authorization: Bearer
更新令牌刷新逻辑（JWT令牌在1小时后过期）

迁移截止日期: 2025年6月1日（v2认证将被弃用）

迁移指南: JWT认证指南

响应格式更改

之前 (v2):

{
  "id": "123",
  "name": "John Doe",
  "email": "john@example.com"
}

当前 (v3):

{
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }
}

影响: 所有API响应现在遵循JSON:API规范

迁移:

// 之前 (v2)
const user = await response.json();
console.log(user.name);

// 之后 (v3)
const { data } = await response.json();
console.log(data.attributes.name);

// 或使用我们的SDK，它会自动处理这个
import { ApiClient } from '@company/api-sdk';
const user = await client.users.get('123');
console.log(user.name); // SDK解包响应

移除端点

移除端点	替代	注释
`GET /api/users/list`	`GET /api/v3/users`	使用分页参数
`POST /api/users/create`	`POST /api/v3/users`	RESTful约定
`GET /api/search`	`GET /api/v3/search`	现在支持高级过滤器

✨ 新功能

Webhook支持

订阅实时事件：

POST /api/v3/webhooks
Content-Type: application/json

{
  "url": "https://your-app.com/webhook",
  "events": ["user.created", "user.updated", "user.deleted"],
  "secret": "your-webhook-secret"
}

Webhook有效载荷:

{
  "event": "user.created",
  "timestamp": "2025-01-15T14:30:00Z",
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }
}

文档: Webhook指南

批量操作

在单个请求中处理多个记录：

POST /api/v3/users/batch
Content-Type: application/json

{
  "operations": [
    {
      "method": "POST",
      "path": "/users",
      "body": { "name": "User 1", "email": "user1@example.com" }
    },
    {
      "method": "PATCH",
      "path": "/users/123",
      "body": { "name": "Updated Name" }
    },
    {
      "method": "DELETE",
      "path": "/users/456"
    }
  ]
}

响应:

{
  "results": [
    { "status": 201, "data": { "id": "789", ... } },
    { "status": 200, "data": { "id": "123", ... } },
    { "status": 204 }
  ]
}

限制: 每个批量请求最多100个操作

字段过滤

只请求你需要的字段：

GET /api/v3/users/123?fields=id,name,email

之前（完整响应）:

{
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "+1234567890",
      "address": { "street": "123 Main St", "city": "NYC" },
      "preferences": { /* ... */ },
      "metadata": { /* ... */ }
      // ...更多字段
    }
  }
}

之后（过滤响应）:

{
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }
}

好处:

减少响应大小（最多小80%）
更快的响应时间
降低带宽使用

🔧 改进

性能增强

列表端点响应时间提高50%
数据库查询优化，平均查询时间从150ms降低到50ms
添加缓存层，用于频繁访问的资源
CDN集成，用于静态资产

基准比较：

端点	v2 (avg)	v3 (avg)	提高
GET /users	320ms	140ms	提高56%
GET /users/{id}	180ms	60ms	提高67%
POST /users	250ms	120ms	提高52%

更好的错误消息

之前 (v2):

{
  "error": "Validation failed"
}

之后 (v3):

{
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "email",
      "message": "Email format is invalid",
      "suggestion": "Use format: user@example.com"
    },
    {
      "code": "VALIDATION_ERROR",
      "field": "password",
      "message": "Password too weak",
      "suggestion": "Password must be at least 8 characters with uppercase, lowercase, and numbers"
    }
  ]
}

增强的速率限制

每个响应中的新速率限制头：

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1642694400
X-RateLimit-Window: 3600
Retry-After: 3600

按计划的速率限制：

计划	请求/小时	突发	重置
免费	100	10/min	1小时
Pro	1,000	50/min	1小时
企业	10,000	200/min	1小时

🔒 安全

需要TLS 1.3: 弃用TLS 1.2支持
JWT过期: 令牌现在在1小时后过期（之前是24小时）
速率限制: 对认证端点实施更严格的限制
CORS: 更新允许的来源（见安全政策）
输入验证: 增强所有端点的验证

🗑️ 弃用

弃用时间表

功能	弃用	移除日期	替代
API令牌认证	v3.0.0	2025-06-01	JWT Bearer令牌
XML响应格式	v3.0.0	2025-04-01	仅JSON
`/api/v1/*` 端点	v3.0.0	2025-03-01	`/api/v3/*`
查询参数 `filter`	v3.0.0	2025-05-01	使用 `filters[field]=value`

弃用警告：

所有弃用的功能返回一个警告头：

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 01 Jun 2025 00:00:00 GMT
Link: <https://docs.example.com/migration/v2-to-v3>; rel="deprecation"

📊 版本支持政策

版本	状态	发布日期	支持结束
v3.x	当前	2025-01-15	TBD
v2.x	维护	2024-01-01	2025-07-01
v1.x	生命周期结束	2023-01-01	2024-12-31

支持级别：

当前: 全面支持，新功能
维护: 仅修复漏洞和安全补丁
生命周期结束: 不再支持，需要升级

迁移指南：v2 → v3

第1步：更新基础URL

// 之前
const API_BASE = 'https://api.example.com/api';

// 之后
const API_BASE = 'https://api.example.com/api/v3';

第2步：迁移认证

// 之前 (v2) - API令牌
const response = await fetch(`${API_BASE}/users`, {
  headers: {
    'Authorization': `Token ${apiToken}`
  }
});

// 之后 (v3) - JWT Bearer
const tokenResponse = await fetch(`${API_BASE}/auth/login`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email, password })
});
const { token } = await tokenResponse.json();

const response = await fetch(`${API_BASE}/users`, {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

第3步：更新响应解析

// 之前 (v2)
const user = await response.json();
console.log(user.name);

// 之后 (v3) - 解包数据对象
const { data } = await response.json();
console.log(data.attributes.name);

// 或使用SDK
import { ApiClient } from '@company/api-sdk';
const client = new ApiClient(token);
const user = await client.users.get('123');
console.log(user.name); // SDK处理解包

第4步：更新错误处理

// 之前 (v2)
try {
  const response = await fetch(`${API_BASE}/users`);
  if (!response.ok) {
    const error = await response.json();
    console.error(error.error);
  }
} catch (error) {
  console.error(error);
}

// 之后 (v3) - 处理多个错误
try {
  const response = await fetch(`${API_BASE}/users`);
  if (!response.ok) {
    const { errors } = await response.json();
    errors.forEach(err => {
      console.error(`${err.field}: ${err.message}`);
      console.log(`建议: ${err.suggestion}`);
    });
  }
} catch (error) {
  console.error(error);
}

第5步：更新分页

// 之前 (v2)
const response = await fetch(`${API_BASE}/users?page=1&per_page=20`);

// 之后 (v3)
const response = await fetch(`${API_BASE}/users?page[number]=1&page[size]=20`);

// 响应结构
{
  "data": [...],
  "meta": {
    "page": {
      "current": 1,
      "size": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "links": {
    "first": "/api/v3/users?page[number]=1",
    "last": "/api/v3/users?page[number]=8",
    "next": "/api/v3/users?page[number]=2",
    "prev": null
  }
}

第6步：测试

// 针对v3 API运行测试
npm run test:api -- --api-version=v3

// 逐步测试迁移
const USE_V3 = process.env.USE_API_V3 === 'true';
const API_BASE = USE_V3
  ? 'https://api.example.com/api/v3'
  : 'https://api.example.com/api/v2';

版本比较

功能矩阵

功能	v1	v2	v3
REST API	✅	✅	✅
GraphQL	❌	❌	✅
Webhooks	❌	❌	✅
批量操作	❌	❌	✅
字段过滤	❌	✅	✅
JSON:API格式	❌	❌	✅
JWT认证	❌	✅	✅
API令牌认证	✅	✅	⚠️ 弃用
XML响应	✅	⚠️ 弃用	❌

图例：✅ 支持 | ❌ 不可用 | ⚠️ 弃用

SDK更新

更新到最新的SDK版本：

# JavaScript/TypeScript
npm install @company/api-sdk@^3.0.0

# Python
pip install company-api-sdk>=3.0.0

# Ruby
gem install company-api-sdk -v '~> 3.0'

# Go
go get github.com/company/api-sdk/v3

SDK变更日志： SDK发布

支持与资源

迁移支持: migration@example.com
文档: https://docs.example.com/v3
API状态: https://status.example.com
社区论坛: https://community.example.com
GitHub问题: https://github.com/company/api/issues