接口为什么要设计出v1和v2
接口设计出 v1、v2 这样的版本号，主要是为了 在系统升级或调整时，不影响已有用户或客户端的正常使用。
简单说，就是给接口一个“时间维度的名字”，方便未来平稳迭代。
1. 核心原因
① 向后兼容
- 老接口（v1）发布后，已有客户端可能依赖现有字段、参数和逻辑。
- 如果直接改动，可能会导致老版本客户端调用出错。
- 有版本号的话，老客户端继续调用 v1，新客户端调用 v2，互不影响。
② 可控升级
- 允许 API 平行存在多个版本，逐步引导用户升级，而不是一次性强制更新。
- 比如先开放 v2 一段时间，待用户都迁移完成后，再下线 v1。
③ 清晰的变更边界
-
在开发和文档中，版本号可以明确告知调用方：“这是哪一代接口”。
-
避免混淆，比如
/api/user到底返回什么格式，有 v1/v2 就很清楚：/api/v1/user：返回旧的字段格式/api/v2/user：返回新的字段结构、更多功能
④ 支持长期维护
- 在大规模系统中，不同业务方、合作方可能使用不同版本。
- 版本号方便维护团队并行维护多个版本，按计划淘汰旧版本。
2. 常见的 API 版本管理方式
| 方式 | 优点 | 缺点 |
|---|---|---|
URL 路径版本 /api/v1/user | 最直观，调用方一眼能看出版本 | URL 变更，迁移需要改路径 |
请求头版本 Accept: application/vnd.myapp.v1+json | URL 不变，版本信息集中管理 | 客户端需额外设置 Header |
查询参数 /api/user?version=1 | 简单好改 | 容易被忽略，不够标准 |
子域名 v1.api.xxx.com | 可以物理隔离版本 | 维护多个域名配置 |
3. 典型变化场景
在 API 升级时可能会引入：
- 字段变化：增加/删除/修改字段名
- 返回结构变化：比如分页格式变化
- 逻辑变化：权限校验、计算规则更新
- 性能优化：分页方式、缓存策略改变
- 协议升级：HTTP → HTTPS、JSON → Protobuf
如果不加版本，直接改动，老客户端就会直接“炸”掉。
4. 简单例子
# v1
GET /api/v1/user/123
{"id": 123,"name": "Liang"
}# v2
GET /api/v2/user/123
{"userId": 123,"fullName": "Liang","phone": "123456789"
}
这样新旧格式可以同时存在，调用方自己选择升级时间。
我建议如果是 内部系统，可以不强制每次都加版本号，但在 对外开放的 API（尤其是要长期维护的），版本号是必备的，否则一次改动就可能引发全网客户端适配危机。