URL前缀硬隔离最稳，即/v1/和/v2/分别挂载独立路由实例，避免行为静默变更。FastAPI用APIRouter(prefix)、Django用include、Flask用Blueprint实现；序列化与参数解析层按版本建模；包结构按版本分模块并强制初始化指定version；Accept头不可靠，不能作为唯一版本路由依据。
Python API 怎么让 v1 和 v2 路由共存不冲突
靠 URL 前缀硬隔离最稳，别信“自动版本路由”这种模糊设计。Django 或 FastAPI 都得手动把 /api/v1/ 和 /api/v2/ 挂到不同 router 实例上，否则版本一升级，GET /users 的行为就可能悄无声息地变。
常见错误是只改了文档或响应字段，但没拆路由——结果前端调 /api/users 时，后端其实已悄悄切到新逻辑，而老客户端崩在 KeyError: 'updated_at' 上。
- FastAPI：用
APIRouter(prefix="/api/v1")和APIRouter(prefix="/api/v2")分开挂载，别共用一个 router - Django：在
urls.py里用path("api/v1/", include("v1_urls"))显式分发，别靠中间件动态解析 path - Flask：必须用 Blueprint，
v1_bp = Blueprint("v1", __name__, url_prefix="/api/v1")，别在同一个 app.route 里 if-else 判版本
如何让同一函数支持多版本输入输出格式
别在视图函数里写 if version == "v2": ... else: ...。分支越多，越难测、越易漏兼容逻辑。应该把差异收拢到序列化层和参数解析层。
比如 FastAPI 的 Pydantic 模型，v1 用 UserV1Schema，v2 用 UserV2Schema，视图里只做类型标注：def get_user() -> UserV2Schema: —— 这样 OpenAPI 文档、校验、序列化全跟着走，不会漏。
立即学习“Python免费学习笔记（深入）”；
- 请求体解析：用不同
BaseModel子类，v1 接受is_active: bool，v2 改成status: Literal["active", "inactive"] - 响应体：返回值注解直接写版本化模型，不要 return dict 后再手动 dump
- 路径/查询参数：也该有对应版本 schema，避免
request.query_params.get("include_deleted")这种弱类型判断
Python 包里怎么声明 API 版本并防止误用
光靠文档说“v2 已上线”没用。得让 import 或初始化阶段就报错，逼开发者面对版本选择。
典型坑是把 from myapi import Client 当成通用入口，结果它默认连 v1；或者 Client() 不传 version 就静默用最新版，导致测试环境跑着 v1，上线却用 v2。
- 包结构按版本分：
myapi.v1.Client、myapi.v2.Client，顶层myapi.Client不要存在 - 初始化强制指定：
Client(version="v2", base_url="...")，不设默认值；设了默认就等于鼓励不声明版本 - HTTP 客户端加请求头：自动带
Accept: application/vnd.myapi.v2+json，后端据此拒绝非匹配版本请求，而不是降级处理
为什么不能靠 Accept 头做唯一版本路由
Accept 头本质是内容协商机制，不是版本控制协议。现实里 Nginx、CDN、某些 HTTP 客户端库会丢、改、缓存它，而且前端 JS fetch 默认不发这个头，全靠它等于埋雷。
你看到 406 Not Acceptable 错误，大概率不是因为客户端没申明版本，而是中间某层把 Accept 给吞了，或者后端没配好 content negotiation 逻辑。
- Accept 头适合配合同一路由返回不同格式（如 JSON/XML），不适合区分语义差异大的 v1/v2
- 如果真要用，必须在所有反向代理、网关、负载均衡器上显式透传
Accept，且每个服务都要做 fallback 处理，成本远高于前缀路由 - 移动端 SDK、curl 调试、Postman 测试都容易漏设 Accept，导致“本地能过，线上报错”
版本管理最不可妥协的点：路由路径必须显式、稳定、可预测。其他都是锦上添花，唯独这个错了，整个协作链路就断在第一跳。
