接口为什么要设计出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（尤其是要长期维护的），版本号是必备的，否则一次改动就可能引发全网客户端适配危机。