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。强行下线只会催生客户端绕过网关直连旧服务的“影子调用”，反而更难监控。
立即学习“Python免费学习笔记（深入）”；
向后兼容最常被忽略的细节
开发者容易盯着字段增减，却漏掉这些隐性破坏点：
-
HTTP 状态码变更：v1 对无效 ID 返回404，v2 改成400+ JSON 错误体？客户端可能只处理 404，其余全当成功； -
分页参数默认值不同：v1 的limit=20是硬编码，v2 改成limit=50，前端未显式传参就会突然多拉数据，触发内存溢出； -
时间格式不统一：v1 用ISO 8601 字符串（"2024-03-15T10:30:00Z"），v2 悄悄换成 Unix timestamp 整数，iOSDate()解析直接失败； -
空值处理差异：v1 返回"field": null，v2 因 ORM 配置省略该字段，JSON Schema 校验器认为缺失字段非法。
真正棘手的从来不是加字段，而是改默认行为——它不会报错，但会让客户端在某个周二凌晨三点开始静默丢数据。
