# API 版本策略

## 版本号规范

- URL 路径版本：`/api/v1/users`, `/api/v2/users`
- 仅在 Breaking Change 时升级主版本

## 向后兼容规则

### 兼容变更（无需升版本）
- 新增可选请求字段
- 新增响应字段
- 新增 API 端点
- 新增枚举值（消费者需忽略未知值）

### Breaking Change（必须升版本）
- 删除/重命名字段
- 修改字段类型
- 修改字段语义
- 删除 API 端点
- 修改 URL 路径
- 修改认证方式

## 版本过渡期

1. 新版本发布时，旧版本继续可用
2. 旧版本标记 `Deprecated` 响应头
3. 过渡期建议：2-4 周
4. 过渡期结束前通知所有消费者
5. 下线旧版本

## 示例

```go
// v1 路由组
v1 := router.Group("/api/v1")
{
    v1.GET("/users", handler.ListUsersV1)
}

// v2 路由组（Breaking Change 后）
v2 := router.Group("/api/v2")
{
    v2.GET("/users", handler.ListUsersV2)
}
```
