Flask蓝图通过url_prefix显式绑定API版本路径，如/app.register_blueprint(user_bp, url_prefix='/api/v1')；版本号不可写入路由装饰器内，须隔离命名空间、模型与序列化层以避免冲突。
Flask 蓝图如何绑定特定 API 版本路径？
蓝图本身不内置版本控制能力，必须靠 url_prefix 显式声明版本段。比如 v1 接口统一走 /api/v1/users，就得在注册蓝图时写死前缀：
from flask import Flask from myapp.v1.users import user_bp app = Flask(__name__) app.register_blueprint(user_bp, url_prefix='/api/v1')
注意：不能把版本号写进蓝图内部的 @user_bp.route('/users')——那样会导致路径变成 /api/v1//users（双斜杠），Flask 会静默忽略或 404。
- 版本号必须是
url_prefix的一部分，不是路由装饰器里的内容 - 若用变量拼接（如
f'/api/{version}'），确保 version 是字符串且不含非法字符 - 多个版本共存时，每个蓝图必须独立实例化（不能复用同一个
Blueprint对象）
如何避免 v1 和 v2 蓝图之间函数名冲突？
常见错误是两个版本都定义了 get_user() 视图函数，结果 v2 注册后覆盖 v1 的同名函数——这不是蓝图机制问题，而是 Python 模块导入时的变量覆盖。根本解法是隔离命名空间：
- 每个版本放在独立包下：
myapp/v1/users.py和myapp/v2/users.py - 蓝图对象命名带版本标识：
user_v1_bp、user_v2_bp，而非都叫bp - 视图函数内部不要依赖全局变量（如共享的
db实例），改用蓝图内初始化或通过current_app获取
例如 v2 可能改用 SQLAlchemy 2.0 语法，若和 v1 共用同一 models.py，就容易因 ORM 行为差异导致隐性 bug。
立即学习“Python免费学习笔记（深入）”；
请求来了，怎么让 Flask 自动路由到对应版本蓝图？
Flask 不自动解析 URL 中的版本号并分发——它只做静态前缀匹配。所谓“自动”，其实是靠 Nginx 或客户端明确指定路径。如果你希望支持 /api/users?version=v2 这种查询参数方式，必须手动干预：
- 注册一个无前缀的通用蓝图，用
@bp.before_request解析request.args.get('version') - 再根据版本动态
redirect到对应/api/v2/users（不推荐，破坏 RESTful 原则） - 更合理的是用反向代理（如 Nginx）把
/api/v2/.*转发到不同 Flask 实例，或用dispatch_request在单应用内做分发（复杂度陡增）
绝大多数生产系统选择显式路径前缀，因为简单、可缓存、符合 OpenAPI 规范，也方便 CDN 和日志按版本切分。
为什么 /api/v1 和 /api/v2 不能共用同一个数据库模型？
版本升级常伴随字段增删、类型变更或权限逻辑调整。如果 v1 和 v2 蓝图共用同一套 User 模型类，v2 的新字段可能让 v1 的请求抛出 KeyError，或者 v1 的旧字段校验规则在 v2 请求中被绕过。
- v1 模型应冻结：字段、验证、序列化逻辑不再修改
- v2 模型可新建类（如
UserV2），或用继承（UserV2(User)）但重载关键方法 - 序列化层必须分离：v1 用
schema_v1.dump()，v2 用schema_v2.dump()，不能混用
最容易被忽略的是数据库迁移脚本——alembic 升级时若没区分版本影响范围，一次 upgrade 可能让 v1 接口突然无法读取旧数据格式。
