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免费学习笔记（深入）”；
睿拓智能网站系统-网上商城1.0免费版软件大小:5M运行环境：asp+access本版本是永州睿拓信息专为电子商务入门级用户开发的网上电子商城系统，拥有产品发布，新闻发布，在线下单等全部功能，并且正式商用用户可在线提供多个模板更换，可实现一般网店交易所有功能，是中小企业和个人开展个人独立电子商务商城最佳的选择，以下为详细功能介绍：1.最新产品-提供最新产品发布管理修改，和最新产品订单查看2.推荐产
- 请求体解析：用不同
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，导致“本地能过，线上报错”
版本管理最不可妥协的点：路由路径必须显式、稳定、可预测。其他都是锦上添花，唯独这个错了，整个协作链路就断在第一跳。
