17370845950

URL路径嵌入版本号更可靠，因Header方式导致日志聚合难、OpenAPI生成难、CDN缓存失效；v1/v2共存应解耦数据模型与序列化契约，用独立ResponseModel映射；废弃v1需同时满足调用量

接口版本号该放在 URL 还是 Header？

绝大多数场景下，URL 路径中嵌入版本号（如 /api/v1/users）更可靠、更易调试、更利于 CDN 缓存与日志归类。用 Accept 或自定义 X-API-Version Header 的方式虽“语义干净”，但实际会带来三类问题：Nginx 日志无法按版本聚合、OpenAPI 文档生成困难、客户端缓存策略失效（同一 URL 不同 Header 返回不同结构，CDN 可能混存）。除非你已用 GraphQL 或完全服务端驱动的前端，否则别碰 Header 版本路由。

如何让 v1 和 v2 共存且不重复写业务逻辑？

核心是把「数据模型」和「序列化契约」解耦。不要为每个版本复制一整套 Pydantic 模型或 SQLAlchemy ORM 类。推荐做法：

• 底层数据库表和 ORM Model 保持稳定，只增不删字段；
• 每个 API 版本定义独立的 ResponseModel（如 UserV1Response、UserV2Response），只描述该版本对外暴露的字段及类型；
• 在路由函数里做轻量映射：

  def get_user_v1(user: User) -> UserV1Response:
      return UserV1Response(
          id=user.id,
          name=user.name,
          created_at=user.created_at.isoformat()
      )

  ；
• 避免在 v2 中直接继承 v1 模型——字段语义变化（如 status 从字符串变成枚举）会导致继承链断裂。

什么时候必须废弃 v1？

不是“有 v2 就该关 v1”，而是看三个硬指标是否同时满足：

• v1 接口调用量连续 90 天低于总流量 0.5%；
• 所有内部服务、移动端 SDK、第三方集成方均已确认完成 v2 迁移，并提供书面回执；
• v1 存在无法绕过的安全缺陷（如硬编码字段导致越权读取），且无法通过中间层兼容补丁修复。

只要有一条不满足，就继续维护 v1。强行下线只会催生客户端绕过网关直连旧服务的“影子调用”，反而更难监控。

向后兼容最常被忽略的细节

开发者容易盯着字段增减，却漏掉这些隐性破坏点：

• HTTP 状态码变更：v1 对无效 ID 返回 404，v2 改成 400 + JSON 错误体？客户端可能只处理 404，其余全当成功；
• 分页参数默认值不同：v1 的 limit=20 是硬编码，v2 改成 limit=50，前端未显式传参就会突然多拉数据，触发内存溢出；
• 时间格式不统一：v1 用 ISO 8601 字符串（"2025-03-15T10:30:00Z"），v2 悄悄换成 Unix timestamp 整数，iOS Date() 解析直接失败；
• 空值处理差异：v1 返回 "field": null，v2 因 ORM 配置省略该字段，JSON Schema 校验器认为缺失字段非法。

真正棘手的从来不是加字段，而是改默认行为——它不会报错，但会让客户端在某个周二凌晨三点开始静默丢数据。