第 6 章:蓝图
蓝图不是"更小的心应用",它只是"一组路由 + 一组资源"的容器。理解这一点,端点名就不会写错。
学习目标
- 会把一个
views.py按业务拆成多个蓝图 - 记住端点名的规则,用
url_for时不再靠猜 - 会处理蓝图自己的模板与静态文件
- 知道什么时候该拆、什么时候拆早了
6.1 它到底是什么
| 是 | 不是 |
|---|---|
| 一组路由的集合 | 一个独立的应用 |
| 可以带 URL 前缀 | 可以单独启动 |
| 可以有自己的模板/静态目录 | 有独立的配置对象 |
一句话:蓝图必须注册到 app 上才生效。
python
# app/views/admin.py
from flask import Blueprint, render_template
admin_bp = Blueprint("admin", __name__, url_prefix="/admin")
@admin_bp.get("/")
def dashboard():
return render_template("admin/dashboard.html")python
# app/__init__.py
from .views.admin import admin_bp
app.register_blueprint(admin_bp)访问 /admin/,端点名是 admin.dashboard。
6.2 端点名的规则
python
url_for("admin.dashboard") # 蓝图名.视图函数名
url_for("main.index") # 另一个蓝图
url_for("index") # app 上直接注册的视图,没有前缀规则只有一条:注册到哪个命名空间,就用哪个前缀去找。
三个常见错误:
| 错误写法 | 后果 |
|---|---|
url_for("dashboard") | BuildError:找不到端点 |
| 蓝图名与视图名重名 | 端点冲突,后注册的覆盖前一个 |
| 蓝图名带点 | 命名空间层级混乱,别用 |
6.3 蓝图自己的模板与静态文件
python
admin_bp = Blueprint(
"admin", __name__,
url_prefix="/admin",
template_folder="templates", # 相对于本蓝图所属包
static_folder="static",
static_url_path="/static",
)现实中的坑:多蓝图同名模板会互相覆盖。Jinja2 的加载器按搜索顺序找,找到第一个就停。
两个规避办法:
- 模板文件加目录:
templates/admin/dashboard.html,模板名带前缀,天然不冲突; - 不依赖蓝图的
template_folder,统一放应用级templates/。
推荐第一种:目录名就是命名空间,比配置更可靠。
6.4 嵌套与拆分
python
# 一个蓝图挂到另一个蓝图(前缀会拼接)
api_bp = Blueprint("api", __name__, url_prefix="/api")
admin_bp.register_blueprint(api_bp) # 最终路径 /admin/api/...嵌套适合"子模块",但超过两层就别再嵌了——端点名会变成 a.b.c.view,很难维护。
6.5 注册顺序与冲突
app.url_map 是排查这类问题的唯一可靠手段:
Map([<Rule '/admin/' (GET, HEAD) -> admin.dashboard>,
<Rule '/' (GET, HEAD) -> main.index>])6.6 蓝图里能用什么、不能用什么
| 能用 | 说明 |
|---|---|
@bp.route / @bp.get | 路由 |
@bp.before_request / after_request | 只作用于该蓝图的路由 |
@bp.errorhandler | 蓝图内错误处理 |
@bp.app_context_processor | 只在该蓝图渲染的模板里生效 |
| 不能用 | 原因 |
|---|---|
在蓝图里 new Flask() | 那会变成两个应用 |
| 在蓝图里初始化扩展 | 应该用 init_app 绑到 app |
| 蓝图级配置 | 配置只能挂在 app 上 |
蓝图级钩子是它比"拆文件"更强的地方:/admin 下所有路由统一鉴权,写在 admin_bp.before_request 里一次搞定。
6.7 三个坑
| 坑 | 现象 | 修法 |
|---|---|---|
| 蓝图名与端点重名 | url_for 命中错的视图 | 蓝图名加业务前缀,如 admin、user |
| 模板路径写错 | TemplateNotFound: dashboard.html | 模板放 templates/admin/,调用时带目录 |
| 循环导入 | views 导入 extensions 又导入 app | 蓝图只导扩展,不导 app |
本章小结
| 要点 | 说明 |
|---|---|
| 本质 | 路由 + 资源的容器,必须注册到 app |
| 端点名 | 蓝图名.视图名 |
| 模板 | 用目录区分命名空间,别靠 template_folder 覆盖 |
| 嵌套 | 可嵌套,但别超过两层 |
| 钩子 | 蓝图级钩子只作用于自己的路由 |
| 拆分 | 一个业务一个蓝图,别按技术层拆 |
| 排查 | app.url_map |
下一章
数据库:Flask-SQLAlchemy 的模型与会话、迁移怎么做、以及"g 上的会话什么时候关"。