7.4.4 变更日志
一句话破题
API 变更不只是代码改了就完了——需要记录下来、通知到人，这样用户才不会措手不及。
Changelog 格式
标准结构
markdown
# API Changelog
## [2.0.0] - 2024-06-01
### 破坏性变更 (Breaking Changes)
- `User` 对象的 `name` 字段拆分为 `firstName` 和 `lastName`
- 移除废弃的 `GET /api/users/:id/profile` 接口
### 新增 (Added)
- 新增 `PATCH /api/users/:id/avatar` 接口
- `User` 对象新增 `lastLoginAt` 字段
### 变更 (Changed)
- 分页默认每页数量从 20 改为 10
### 废弃 (Deprecated)
- `GET /api/users/:id/settings` 将在 v3.0.0 移除，请使用 `/api/settings/:userId`
### 修复 (Fixed)
- 修复用户搜索时特殊字符导致的 500 错误分类规则
| 分类 | 含义 | 示例 |
|---|---|---|
| Breaking | 不兼容变更 | 删除字段、改变类型 |
| Added | 新功能 | 新接口、新字段 |
| Changed | 功能变更 | 修改行为、优化性能 |
| Deprecated | 即将废弃 | 标记老接口 |
| Fixed | Bug 修复 | 修复问题 |
| Security | 安全更新 | 修复漏洞 |
Changelog 示例
markdown
# API Changelog
所有 API 变更都会记录在此文件。
## [未发布]
### 新增
- 用户批量导入接口 `POST /api/users/batch`
## [1.2.0] - 2024-03-15
### 新增
- 用户头像上传 `POST /api/users/:id/avatar`
- 文章收藏功能 `POST /api/posts/:id/favorite`
### 变更
- 提升文章列表接口性能，响应时间减少 50%
### 修复
- 修复分页参数 `page=0` 时返回空数据的问题
## [1.1.0] - 2024-02-01
### 新增
- `User` 对象新增 `avatar` 可选字段
- 新增用户设置接口 `GET /api/users/:id/settings`
### 废弃
- `User.nickname` 字段将在 v2.0.0 移除，请使用 `displayName`
## [1.0.0] - 2024-01-01
### 新增
- 用户 CRUD 接口
- 文章 CRUD 接口
- JWT 认证通知机制
响应头通知
typescript
// 在响应中添加废弃警告
function addDeprecationHeaders(response: NextResponse) {
response.headers.set('Deprecation', 'true')
response.headers.set('Sunset', 'Sat, 01 Jun 2024 00:00:00 GMT')
response.headers.set(
'Link',
'</api/v2/users>; rel="successor-version"'
)
return response
}响应体警告
json
{
"data": { ... },
"warnings": [
{
"code": "DEPRECATED_FIELD",
"message": "nickname 字段将在 2024-06-01 移除，请使用 displayName"
}
]
}邮件通知
markdown
## API 变更通知
尊敬的开发者，
我们将在 2024-06-01 发布 API v2.0.0，包含以下变更：
### 破坏性变更
- User.name 将拆分为 firstName 和 lastName
### 迁移指南
1. 更新客户端代码，使用 firstName + lastName
2. 测试新版本 API（已在 staging 环境可用）
3. 2024-06-01 前完成迁移
如有问题，请联系 api-support@example.com
Best regards,
API Team版本状态页
typescript
// app/api/status/route.ts
export async function GET() {
return NextResponse.json({
versions: [
{
version: 'v2',
status: 'current',
releaseDate: '2024-06-01',
},
{
version: 'v1',
status: 'deprecated',
sunsetDate: '2024-12-01',
successor: 'v2',
},
],
changelog: 'https://api.example.com/changelog',
documentation: 'https://docs.example.com',
})
}迁移指南
文档结构
markdown
# v1 到 v2 迁移指南
## 概述
本指南帮助你从 API v1 迁移到 v2。
## 主要变更
### 1. 用户名称字段变更
**v1:**
```json
{ "name": "张三" }v2:
json
{ "firstName": "三", "lastName": "张" }迁移方式:
typescript
// 旧代码
const displayName = user.name
// 新代码
const displayName = `${user.lastName}${user.firstName}`2. 认证方式变更
v1: 使用 API Key v2: 使用 JWT Token
详细迁移步骤请参考认证文档。
测试
v2 API 现已在 staging 环境可用： https://staging-api.example.com/v2
时间线
- 2024-04-01: v2 beta 发布
- 2024-06-01: v2 正式发布
- 2024-09-01: v1 停止更新
- 2024-12-01: v1 完全下线
## 自动化 Changelog
### 使用 Conventional Commits
```bash
# 提交格式
feat(api): add user avatar upload endpoint
fix(api): handle special characters in search
feat(api)!: split name into firstName and lastName
# ! 表示破坏性变更自动生成 Changelog
bash
# 使用 standard-version
npx standard-version
# 或使用 conventional-changelog
npx conventional-changelog -p angular -i CHANGELOG.md -s觉知：注意事项
1. 及时更新
❌ 发布后再写 Changelog
✅ 开发时同步更新2. 清晰具体
markdown
❌ 模糊
- 更新了用户接口
✅ 具体
- `GET /api/users` 新增 `status` 过滤参数
- 响应新增 `lastLoginAt` 字段3. 提供迁移指南
markdown
❌ 只说"字段改了"
✅ 提供迁移代码示例
```javascript
// 迁移前
const name = user.name
// 迁移后
const name = `${user.lastName}${user.firstName}`
## 本节小结
| 要点 | 说明 |
|------|------|
| **Changelog** | 记录所有变更 |
| **分类** | Breaking/Added/Changed/Deprecated/Fixed |
| **通知** | 响应头、邮件、文档 |
| **迁移指南** | 代码示例、时间线 |