版本路由必须用独立蓝图分离，如Blueprint("api_v1", __name__, url_prefix="/api/v1")，禁止在视图中用if判断版本；各版本需隔离Schema、错误处理器，并确保Nginx路径与蓝图url_prefix完全一致。
版本路由必须用蓝图分离，不能靠 if 判断拼接
Flask 本身不提供原生版本控制机制，硬要在同一个视图函数里用 if version == "v1" 分支处理不同逻辑，会导致路由耦合、测试困难、文档混乱。真实项目中，每个 API 版本应视为独立模块——这意味着 v1 和 v2 必须是两个隔离的蓝图，各自注册自己的 URL 前缀和错误处理器。
常见错误现象：在 @app.route("/api/users") 中读取请求头或 query 参数判断版本，结果 Swagger 文档无法区分接口、OpenAPI 规范失效、前端调用时缓存错乱。
- 每个版本蓝图需独立定义
url_prefix，如Blueprint("api_v1", __name__, url_prefix="/api/v1") - 蓝图内所有路由自动继承前缀，无需重复写
/v1 - 避免在蓝图外用
app.register_blueprint(blueprint, url_prefix="/api/v1")二次指定前缀（易与蓝图自身冲突）
如何让 v1 和 v2 共享模型但隔离序列化逻辑
版本升级常伴随字段增删或类型变更（比如 v1 返回 user_id 字符串，v2 改为整数 ID），此时模型层可复用 SQLAlchemy 类，但序列化必须分版本实现。直接复用 marshmallow Schema 或 pydantic Model 会引发兼容性断裂。
使用场景：用户资料接口在 v2 新增 preferred_language 字段，但 v1 客户端解析失败。
立即学习“Python免费学习笔记（深入）”；
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
- 为每个蓝图单独定义 Schema，如
v1/schemas.py中的UserSchemaV1，v2/schemas.py中的UserSchemaV2 - 不要在蓝图间 import 对方的 Schema，可通过包级
__init__.py暴露统一入口，但保持实现隔离 - 若用
pydantic，注意BaseModel的Config.extra = "forbid"在 v2 中可能拒绝 v1 请求体，需按版本实例化不同模型
404 和 406 错误要按版本拦截，不能全局兜底
当用户访问 /api/v3/users 但 v3 蓝图未注册时，Flask 默认返回 404 —— 这看似合理，实则掩盖了版本管理漏洞。更危险的是，若 v2 接口要求 Accept: application/vnd.myapp.v2+json，但客户端传了 v1 的 media type，应返回 406 Not Acceptable，而非 404 或 200。
错误现象：前端调试时发现“接口不存在”，实际是 Accept 头不匹配，却因没做版本协商而静默降级到 v1，导致数据格式错乱。
- 在每个蓝图的
errorhandler中定义@blueprint.errorhandler(406)，返回明确提示如{"error": "Unsupported API version"} - 禁用全局
@app.errorhandler(404)捕获版本路径缺失，改用蓝图级@blueprint.errorhandler(404)区分“路径不存在”和“版本未启用” - 注册蓝图时检查
url_prefix是否已存在，避免/api/v1被重复注册覆盖（可用app.extensions.get("registered_versions", set())记录）
部署时蓝图书名和路径别名必须对齐 Nginx 配置
开发时用 flask run 可能一切正常，但上线后 Nginx 把 /api/v2/ 反向代理到 Flask 应用，若蓝图注册时用了 url_prefix="/v2"，就会变成 /api/v2/v2/ —— 多出一层前缀。
性能影响：每次请求多一次字符串匹配；兼容性影响：前端 SDK 生成的 URL 与服务端实际路由不一致，导致批量调用失败。
- 蓝图定义时
url_prefix必须与 Nginxlocation块路径完全一致（例如 Nginx 写location /api/v2/，蓝图就用url_prefix="/api/v2"） - 禁止在 Nginx 中用
rewrite裁剪路径，应由 Flask 蓝图承担路由语义 - 用
app.url_map在启动时打印所有端点，验证api_v2.users_list是否映射到GET /api/v2/users
最易被忽略的是版本生命周期管理：v1 不是“永久保留”，而是要有明确的 deprecation 时间戳和 Deprecated 响应头；一旦移除 v1 蓝图，必须同步清理数据库迁移脚本、CI 测试用例、文档链接——否则残留的 import 会让新版本构建失败。
