Flask 如何使用 Blueprint 蓝图模块化组织大型项目结构

Flask 使用 Blueprint 蓝图将视图函数拆分到独立模块，适合路由数量较多或团队协同开发的大型项目。主要风险边界是模块间循环导入会导致应用无法启动。

先说结论：Flask 蓝图是官方推荐的模块化方案，能将视图、模板和静态文件隔离到独立包中。

适合：多模块协作、功能边界清晰的中大型 Web 应用
先看：应用工厂模式 factory function 与蓝图注册顺序
建议：按功能域划分蓝图，避免按技术层级划分

快速处理思路

project/
├── app/
│   ├── __init__.py
│   ├── main.py
│   └── auth.py
├── templates/
├── static/
└── run.py

为什么会这样

蓝图本质是未实例化的应用组件，允许在不创建完整 app 对象的情况下定义路由。蓝图机制解耦了视图逻辑与核心配置，便于多人并行开发不同功能模块。

分步处理

步骤 1：创建应用工厂

在 app/__init__.py 中定义 create_app 函数，实例化 Flask 对象。

from flask import Flask
def create_app():
    app = Flask(__name__)
    from .main import main as main_blueprint
    app.register_blueprint(main_blueprint)
    return app

步骤 2：定义蓝图

在 app/main.py 中创建 Blueprint 对象并绑定视图。

from flask import Blueprint
main = Blueprint('main', __name__)
@main.route('/')
def index():
    return 'Hello'

步骤 3：注册蓝图

在 create_app 函数内部导入并注册蓝图，避免循环导入。

适用场景：新增功能模块。操作动作：新建蓝图文件并在 __init__.py 注册。验证结果：访问新路由返回预期内容。风险边界：导入语句必须放在函数内部。

怎么验证是否生效

启动服务后使用 curl 命令检查路由响应。

flask run
curl http://127.0.0.1:5000/

检查点：日志无 ImportError，HTTP 状态码为 200。

常见坑

循环导入：在模块顶层导入 app 对象会导致启动失败，必须在函数内导入。
静态文件路径：蓝图默认静态文件夹为 static，多蓝图共存时需指定 url_prefix 区分。
模板命名冲突：不同蓝图使用同名模板文件时，需放在子文件夹中并通过蓝图名/模板名调用。

常见问题

蓝图和 Flask 应用对象有什么区别？

蓝图是功能组件集合，不能独立运行；Flask 应用对象是完整实例，负责处理请求和注册蓝图。

如何在蓝图中设置 URL 前缀？

在 register_blueprint 方法中传入 url_prefix 参数，例如 app.register_blueprint(api, url_prefix='/api')。

参考来源

Flask Official Documentation, Modular Applications with Blueprints, https://flask.palletsprojects.com/en/latest/blueprints/