最稳妥的API版本控制是URL路径版本（如/api/v1/users），因其兼容CDN、缓存、日志及Nginx重写，避免查询参数或Accept头带来的缓存混乱、调试困难与文档失效问题。
用 URL 路径做版本控制最稳妥
路径版本（如 /api/v1/users）是实际项目中最易维护、最兼容的方案。它不依赖请求头或查询参数，能被 CDN、浏览器历史、日志系统、Nginx 重写规则直接识别，也避免了缓存混淆问题。
常见错误是把版本号塞进查询参数（/api/users?v=2），这会导致同一 URL 对应多个语义不同的响应，违反 HTTP 缓存语义，且 Swagger/OpenAPI 文档难以准确描述多版本资源。
- FastAPI 示例：
app.include_router(users_router, prefix="/api/v1")和app.include_router(users_router_v2, prefix="/api/v2") - Flask 中可用蓝图 +
url_prefix分离路由逻辑，不同版本的Blueprint各自管理序列化器、校验逻辑和数据库适配层 - 避免在路径中使用
v1.2或2024-01这类格式——语义模糊，且破坏了“主版本号变更即不兼容”的约定
Accept 头版本控制只适合内部服务间调用
用 Accept: application/vnd.myapi.v2+json 做版本控制，对前端 Web 或移动端几乎不可行：axios/fetch 默认不设该头，iOS/Android 原生网络库也不默认支持；更关键的是，浏览器地址栏无法体现版本，调试时极易误发错版本请求。
它唯一合理的场景是后端服务之间通过 HTTP 调用，且双方都严格遵循 API 规范、共用 SDK 封装了 Accept 头。
立即学习“Python免费学习笔记（深入）”；
安全 Python 代码沙箱：在隔离的沙箱中执行任意 Python 代码，预装 requests、NumPy、pandas 库。返回 stdout、stderr。
- FastAPI 中可通过
Request.headers.get("accept")手动解析，但需自行实现路由分发，失去框架级路由能力 - 若强行用于 Web 前端，必须在每个请求拦截器里统一注入
Accept头，一旦漏掉一个，就触发 v1 回退逻辑，埋下隐性兼容性故障 - Swagger UI 默认不支持切换
Accept值，文档测试功能基本失效
如何让 v1 和 v2 共享部分模型但隔离字段变更
版本升级常伴随字段增删、类型变化（如 price 从 int 改为 Decimal）、嵌套结构扁平化等。硬编码两套 Pydantic 模型容易失控，推荐按“协议契约”思路组织：
- v1 的
UserResponse和 v2 的UserResponseV2必须完全独立定义，禁止继承或BaseModel.copy()—— 字段默认值、Field(exclude=True)、alias等行为在不同版本中可能有差异 - 共享逻辑（如权限检查、DB 查询）可抽到 service 层函数，但返回数据必须经对应版本的模型
.model_dump()输出，不能直接return db_obj.__dict__ - 数据库字段变更时，v1 接口仍要兼容旧字段名，哪怕 DB 已加新列；可通过
model_config = ConfigDict(from_attributes=True, alias_generator=lambda x: x.replace("_", ""))控制别名，但仅限 v1 内部使用
不要在响应头里暴露当前 API 版本
像 X-API-Version: v2 这类响应头看似友好，实则增加客户端解析负担，且无实际价值。客户端本应明确知道自己调用的是哪个路径版本，响应头重复声明反而可能掩盖路径与实际逻辑不匹配的问题（比如 v1 路径误返回 v2 数据）。
真正需要的是错误提示的精准性：当用户访问 /api/v3/users 但该版本未上线时，返回 404 Not Found，而不是 400 Bad Request 加一段 JSON 提示 “v3 is not supported”。HTTP 状态码本身已是标准兼容信号。
容易被忽略的一点：Nginx 或 API 网关如果做了路径重写（如把 /v2/ 代理到后端 /api/v2/），务必确保重写规则不意外吞掉版本前缀，否则所有请求都会降级到默认版本，而日志里还显示着 /v2/ —— 这种错位极难排查。
