Flask-基本入门
这篇讲什么
- Flask 官方给自己的定位是「轻量的 WSGI Web 应用框架」:一个
app.route加一个函数就能跑起来,这篇从建虚拟环境、起服务一路走到请求、响应、重定向和错误处理。 - 覆盖虚拟环境四条路(venv / conda / uv / virtualenv)、
flask run与app.run()的区别(含本机 5000 端口被 Windows 占用的实测)、视图函数、上下文对象与请求钩子、路由转换器、url_for、errorhandler。 - 结论都在 Flask 3.1.3 + Werkzeug 3.1.9 上实测,老笔记里
flask_script那套启动写法已按现状订正。
简介
-
Flask 官方给自己的定义是一句话:lightweight WSGI web application framework(轻量的 WSGI Web 应用框架),上手快,也能长成大项目。
-
「微型框架」里的 micro 指的是核心保持简单、其余靠外挂,不是「只能写 demo」,也不是「功能残缺」。官方 design 章把这条讲得很清楚:
- Flask 不替你决定用哪个数据库;它替你做的决定(模板引擎用 Jinja)也很容易换掉。
- 默认不带数据库抽象层、不带表单校验,因为这些领域已经有成熟的库,Flask 把它们留给扩展。
- 原话是 “Flask will never have a database layer. It will not have a form library”,数据库层和表单库永远不会进核心。
-
micro 也不等于「没有依赖」。官方首页点名三个依赖:Werkzeug(WSGI 工具包)、Jinja(模板引擎)、Click(命令行工具包)。
-
本机 conda
flask环境实际装的是六个包,版本用importlib.metadata.version()取:包 本机版本 管什么 Flask 3.1.3 路由注册、上下文、配置、扩展接口 Werkzeug 3.1.9 WSGI、URL 匹配、request/response 对象、开发服务器 Jinja2 3.1.6 模板渲染与自动转义 click 8.5.0 flask命令和自定义命令itsdangerous 2.2.0 给 session cookie 签名 blinker 1.9.0 信号, signals_available的来源 -
版本号别用
模块.__version__取,官方口径是importlib.metadata.version()。本机实测:1
2
3
4
5
6from importlib.metadata import version
import click, flask, werkzeug
version('flask'), version('werkzeug'), version('click')
flask.__version__ # 触发 DeprecationWarning
werkzeug.__version__ # 干脆没有这个属性1
2
3
4
5
6
7version('flask') -> '3.1.3' version('werkzeug') -> '3.1.9'
version('jinja2') -> '3.1.6' version('click') -> '8.5.0'
flask.__version__ -> '3.1.3' 警告: The '__version__' attribute is deprecated and will be removed in Flask 3.2. Use feature detection or 'importlib.metadata.version("flask")' instead.
click.__version__ -> '8.5.0' 警告: 同上,Click 9.1 起移除
itsdangerous.__version__ -> '2.2.0' 警告: 同上,ItsDangerous 2.3 起移除
jinja2.__version__ -> '3.1.6' 无警告
werkzeug / blinker -> AttributeError: module ... has no attribute '__version__' -
顺带一条:
MySQLdb这类 C 扩展包也没有__version__,要版本用MySQLdb.version_info或importlib.metadata.version('mysqlclient')。 -
这一篇讲最小可用的一圈:怎么起服务、路由怎么写、请求怎么读、响应怎么给、怎么重定向、怎么中止。数据库、表单、模板、部署各自单独成篇:Flask-模板引擎、Flask-表单使用、Flask-文件上传、Flask-数据模型操作、Flask-项目部署。
WEB工作原理
-
C/S 与 B/S:C/S 每台客户端都要装程序,B/S 的客户端就是浏览器,升级只发生在服务端,这是 Web 应用取代大量桌面软件的原因。
-
一次请求经过的层次,本机部署形态是这样:
1
浏览器 -> HTTP 服务器(nginx) -> WSGI 服务器(gunicorn / waitress) -> Flask 应用 -> 数据库
-
WSGI 不是 Flask 的东西:它是 Python 侧「服务器」与「Web 应用」之间的调用约定。服务器把请求整理成一个
environ字典来调用你的应用,应用返回(状态行, 响应头, 正文迭代器)。Flask 的app对象本身就是那个可调用对象,所以官方反复强调「Flask 是一个 WSGI application」,用哪个服务器是别人的事。 -
自带服务器只用于开发:
flask run起的是 Werkzeug 的开发服务器,启动时那行英文警告是原文:1
2WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
* Running on http://127.0.0.1:5002官方部署章还把这层意思写成了加粗的一句:Do not use the development server when deploying to production。
-
老笔记那条链路要改:
客户端<=>nginx<=>uWSGI<=>flask<=>数据路(MySQL)把 uWSGI 写成了唯一选项。官方自托管清单其实是六项:Gunicorn、Waitress、mod_wsgi、uWSGI、gevent、ASGI。- Linux 上默认选 Gunicorn;它依赖 POSIX,Windows 上跑不了。
- Windows 上官方列的是 Waitress,本机 waitress 3.0.2 实测可用。
- 启动参数和 nginx 反向代理的配置见 Flask-项目部署,这里不重复。
配置虚拟环境
老笔记这一节写的是 2019 年 Linux 上的 virtualenv + virtualenvwrapper(source venv/bin/activate、改 ~/.bashrc),在 Windows 上照抄第一步就卡住。现在常用的四条路是 conda(Anaconda / Miniconda / Miniforge)、uv、标准库 venv、virtualenv,下面每条都在本机跑过。
四条路的分工
| 方案 | 本机版本 | 建环境 | 装包 | 适合谁 |
|---|---|---|---|---|
| conda(Anaconda) | conda 26.9.4 | conda create -n 名字 python=3.12 |
环境内 pip install … |
要同时管多版本 Python,还要装非 Python 依赖(CUDA、MKL、数据库客户端) |
| Miniconda / Miniforge | 同一个 conda | 同上 | 同上 | 只想要 conda 本身,不要 Anaconda 预装的那一大堆科学计算包 |
| uv | uv 0.13.7 | uv venv --python 3.12 |
uv pip install … 或 uv add … |
新项目、要锁文件、嫌 pip 慢 |
标准库 venv |
Python 3.14.10 自带 | python -m venv .venv |
python -m pip install … |
只想跟着官方文档走,不装任何额外工具 |
| virtualenv | 21.15.5 | python -m virtualenv 目录 |
环境内 pip |
老脚本里已经在用它 |
conda:Anaconda、Miniconda、Miniforge
-
本机装的是 Anaconda(
D:\ProgramData\anaconda3,conda 26.9.4)。conda env list实测:1
2
3
4
5
6# conda environments:
#
base D:\ProgramData\anaconda3
django D:\ProgramData\anaconda3\envs\django
flask D:\ProgramData\anaconda3\envs\flask
shop D:\ProgramData\anaconda3\envs\shop -
日常就四条:
conda create -n flask python=3.12、conda activate flask、conda deactivate、conda remove -n flask --all。想先看它会装什么再决定,加--dry-run(实测节选):1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17$ conda create -n uv-demo --dry-run python=3.12
Channels:
- defaults
Platform: win-64
Solving environment: ...working... done
environment location: D:\ProgramData\anaconda3\envs\uv-demo
added / updated specs:
- python=3.12
The following NEW packages will be INSTALLED:
ca-certificates anaconda/pkgs/main/noarch::ca-certificates-2026.10.20-h382c6e5_1
pip anaconda/pkgs/main/noarch::pip-26.2.2-pyhc872135_0
python anaconda/pkgs/main/win-64::python-3.12.16-hd7b1df3_0
setuptools anaconda/pkgs/main/win-64::setuptools-84.2.1-py312haa95532_0
sqlite anaconda/pkgs/main/win-64::sqlite-3.53.4-hee5a0db_0
tzdata anaconda/pkgs/main/noarch::tzdata-2026c-he532380_0 -
复现环境用
conda env export,它会把 conda 层和 pip 层分开列(本机flask环境的实测开头):environment.yml 1
2
3
4
5
6
7
8
9name: flask
channels:
- defaults
dependencies:
- python=3.14.10=h7ce57fb_100_cp314
- pip=26.2.2=pyh0d26453_0
- pip:
- flask==3.1.3
- alembic==1.20.1换机器时
conda env create -f environment.yml就能重建;只想要 Python 层的依赖,用pip freeze > requirements.txt更轻。 -
Anaconda 与 Miniconda / Miniforge 的区别只在安装器:官方文档说 Miniconda 是 conda 的「minimal installer」(只带 conda 和 Python),Anaconda 则额外预装了上千个科学计算包;Miniforge 是社区版,默认走 conda-forge 频道。命令完全一致。
-
Windows 上的坑:裸 PowerShell 里直接
conda activate实测报:1
CondaError: Run 'conda init' before 'conda activate'
官方建议是开「Anaconda Prompt / Miniforge Command Prompt」(已经初始化好)。要在自己的 PowerShell 里用,跑一次
conda init powershell,它改的是 PowerShell 配置文件,之后还要允许脚本执行:Set-ExecutionPolicy -Scope CurrentUser RemoteSigned。
uv:新项目首选
-
安装用官方脚本(Windows PowerShell):
1
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
实测装完落在
C:\Users\<用户名>\.local\bin,安装器会提示把这个目录加进PATH(或者重开终端)。版本uv 0.13.7 (2026-11-03)。
装到指定目录
-
默认装到
$HOME\.local\bin(也就是C:\Users\<用户名>\.local\bin),而且安装器会直接改「用户 PATH」注册表——实测这台机器装完后用户 PATH 里确实多了一条C:\Users\Loong\.local\bin,所以只需重开终端,不用自己手动加。想换个盘装、或者不想让它动 PATH,用环境变量:1
2
3$env:UV_INSTALL_DIR = "D:\Tools\uv" # 指定安装目录
$env:UV_NO_MODIFY_PATH = "1" # 不让它改 PATH
irm https://astral.sh/uv/install.ps1 | iex-
实测(装到一个空目录再核对):
1
2
3
4
5
6
7
8
9
10
11
12downloading uv 0.13.7 (x86_64-pc-windows-msvc)
installing to E:\Desktop\Test\uv-dir-probe\bin
uv.exe
uvx.exe
uvw.exe
everything's installed!
--- 安装目录内容 ---
\uv.exe \uvw.exe \uvx.exe # flat 布局:三个 exe 直接放在该目录,没有子目录
--- 装完之后 PATH 有没有被改 ---
PATH 是否变化: False
--- 这个目录里的 uv 能不能跑 ---
uv 0.13.7 (316c827e0 2026-11-03 x86_64-pc-windows-msvc) -
也就是说设了
UV_INSTALL_DIR就真的装到那里,设了UV_NO_MODIFY_PATH=1就不动 PATH;这种情况下要自己把目录加进 PATH,或者直接用全路径调用D:\Tools\uv\uv.exe。
-
-
脚本里还有几个相关开关(读
install.ps1源码确认,实测过前两条):变量 / 参数 作用 备注 UV_INSTALL_DIR指定安装目录 优先级最高,布局是 flat UV_UNMANAGED_INSTALL指定目录 + 同时关掉 PATH 修改和自动更新 给包管理器、CI、公司统一分发用 CARGO_DIST_FORCE_INSTALL_DIR通用(cargo-dist)的安装目录变量 uv 只是兼容它,新项目用 UV_INSTALL_DIRUV_NO_MODIFY_PATH=1不改 PATH 单独用,不指定目录 -NoModifyPath参数同上 脚本里已标注 deprecated,会提示改用环境变量 都不设时,安装器按
XDG_BIN_HOME→XDG_DATA_HOME\..\bin→$HOME\.local\bin的顺序找默认目录(这段写在install.ps1的头部注释里)。 -
缓存也要一起挪。装到 D 盘只是挪了 exe,uv 的下载缓存默认还在 C 盘(实测
uv cache dir输出C:\Users\<用户名>\AppData\Local\uv\cache)。要挪走就固定设一个环境变量:1
[Environment]::SetEnvironmentVariable("UV_CACHE_DIR", "D:\Tools\uv-cache", "User")
之后
uv cache dir就会指向新位置;uv cache clean可以清缓存,uv self是管理 uv 自身(升级/卸载)的命令组。 -
卸载:删掉那个安装目录里的
uv.exe、uvx.exe、uvw.exe,再把 PATH 里那条删掉即可;缓存目录另算(uv cache clean或直接删)。 -
建环境并装包,两条命令,实测耗时都记下来了:
1
2uv venv .venv --python 3.12 # 7.2 s(本机没有 3.12,它顺手把解释器下了)
uv pip install flask # 4.0 s:Resolved 7 packages in 2.26s,Installed 7 packages in 123ms1
2
3
4
5$ uv venv venv-uv --python 3.12
Downloading cpython-3.12.16-windows-x86_64-none (download) (21.0MiB)
Using CPython 3.12.16
Creating virtual environment at: venv-uv
Activate with: venv-uv\Scripts\activate- 也就是说 uv 不仅能建虚拟环境,还能自己管 Python 版本:
uv python list实测能列出cpython-3.14.10 -> D:\ProgramData\anaconda3\python.exe(它会认出 conda 的解释器)和<download available>的 3.15/3.16 预览版。 - 想要
pip这个种子包,加--seed;--prompt能改激活时显示的目录名。
- 也就是说 uv 不仅能建虚拟环境,还能自己管 Python 版本:
-
项目化流程(推荐用法,比
requirements.txt强在锁文件):1
2
3uv init --name demo-proj --python 3.12 # 生成 pyproject.toml
uv add flask # 0.9 s:写依赖 + 生成 uv.lock + 建 .venv + 装好
uv tree # 看依赖树1
2
3
4
5
6
7
8
9
10
11$ uv tree
demo-proj v0.1.0
└── flask v3.1.3
├── blinker v1.9.0
├── click v8.5.0
├── itsdangerous v2.2.0
├── jinja2 v3.1.6
│ └── markupsafe v3.0.4
├── markupsafe v3.0.4
└── werkzeug v3.1.9
└── markupsafe v3.0.4换机器只要
uv sync,它按uv.lock精确复现,不用pip freeze。 -
只想临时跑一次、不想留环境:
uv run --with flask python -c "import flask; print(flask.__version__)"实测 2.3 s(Installed 7 packages in 27ms)。 -
两个实测的小坑:
1
2
3$ uv python list --installed
error: unexpected argument '--installed' found
tip: a similar argument exists: '--isolated'- 想看已装的解释器就直接
uv python list,没有--installed这个参数。 - 缓存目录和项目在不同盘时会警告
Failed to hardlink files; falling back to full copy(本机就报了),想消掉设UV_LINK_MODE=copy。
- 想看已装的解释器就直接
标准库 venv 与 virtualenv
-
标准库这条最省事,Python 3.3+ 自带,实测建环境 5.1 s:
1
python -m venv .venv
1
.venv\Scripts\Activate.ps1 # PowerShell
1
.venv\Scripts\activate # cmd
1
source .venv/bin/activate # Linux / macOS
- 老笔记那句
source venv/bin/activate在 Windows 上必然失败:Windows 的目录是venv\Scripts\,不是venv/bin/,而且激活脚本按 shell 分.ps1/.bat。 - 退出都是
deactivate。
- 老笔记那句
-
virtualenv 现在也还在维护(实测 21.15.5),比标准库快在能缓存种子包、能指定任意解释器:
1
2
3
4
5
6$ python -m virtualenv venv-virtualenv
created virtual environment CPython3.12.16.final.0-64-x86_64 in 3430ms
creator CPython3Windows(dest=..., clear=False, no_vcs_ignore=False, ...)
seeder FromAppData(download=False, pip=bundle, via=copy, app_data_dir=C:\Users\...\pypa\virtualenv\Cache)
added seed packages: pip==26.3
activators BashActivator,BatchActivator,FishActivator,NushellActivator,PowerShellActivator,PythonActivator,XonshActivator注意 activators 里已经有 PowerShell、Nushell、Xonsh,不再只有 bash。
-
virtualenvwrapper可以不学了:它的价值是「所有环境放一个目录、用workon来回切」,而 conda 有conda activate、uv 有项目级.venv,两家都自带这套;它还是 bash 时代的产物,Windows 上从来不好用。老笔记里那 30 行~/.bashrc配置直接作废。
该用哪个
- 这台机器:已经装了 Anaconda,本批 Flask 笔记的实测一律用 conda 环境
flask(conda activate flask),Python 3.14.10 + Flask 3.1.3。 - 新开项目:
uv init+uv add,锁文件进仓库,requirements.txt那套可以退休了。 - 跟着官方教程做、不想装任何东西:
python -m venv .venv。 - 只有还在跑的老脚本才继续用 virtualenv /
requirements.txt,别在新项目里引入。
使用测试
- 示例:
app.py 1
2
3
4
5
6
7
8
9
10
11
12
13
14# 导入类库
from flask import Flask
# 创建对象
app = Flask(__name__)
# 配置路由
def index():
return 'Hello World'
if __name__=='__main__':
# 启动
app.run()
三种启动方式
Flask 项目里没有 manage.py,python manage runserver 是 Django 的启动命令。在 Flask 目录里照抄,Python 会把 manage 当成要执行的脚本文件名,找不到就直接退出:
1 | $ python manage runserver |
本机 Flask 3.1.3 实测,能用的启动写法只有下面三种:
| 写法 | 实测结果 |
|---|---|
python app.py |
正常起服务,端口等参数由脚本里的 app.run() 决定 |
flask run |
默认端口 5000,本机直接报错,见下一节 |
flask run -p 5002 |
起服务,http://127.0.0.1:5002/ 返回 Hello World! |
-
flask run不执行app.run():脚本里写的port、debug对它无效,它只认命令行参数和环境变量。两套参数各说各话,是「改了代码端口却没变」的常见原因。 -
入口文件是自动找的:没设
FLASK_APP时,flask命令按wsgi.py、app.py找实例。本机每个用例起一个独立子进程跑flask routes(只打印路由表,不占端口):目录里有什么 不设 FLASK_APP 设 FLASK_APP app.py退出码 0,路由表正常打印 不用设 wsgi.py退出码 0,路由表正常打印 不用设 main.py/blog.py退出码 2,报下面那句 FLASK_APP=blog后退出码 01
Error: Could not locate a Flask application. Use the 'flask --app' option, 'FLASK_APP' environment variable, or a 'wsgi.py' or 'app.py' file in the current directory.
这句报错把规则说全了:要么
--app传参,要么设FLASK_APP,要么把文件命名成wsgi.py/app.py。 -
命令行开关(摘自
flask run --help):-p, --port指定端口,-h, --host指定主机。注意这里的-h是 host 而不是 help,看帮助要写--help。
5000 端口被 Windows 占用
flask run 和 app.run() 的默认端口都是 5000,本机一启动就退出:
1 | $ flask run |
这句中文对应 OSError: [WinError 10013],不是 Flask 的 bug。装了 Hyper-V / WSL2 的 Windows 开机时会划走一整段 TCP 端口,5000 正好落在里面:
1 | $ netsh interface ipv4 show excludedportrange protocol=tcp |
- 换端口(推荐):
flask run -p 5002,或代码里app.run(port=5002)。实测 5001 同样报 10013,5002 / 5004 / 5050 / 8000 都能正常起;挑端口前先跑一次上面那条netsh,对着区间找空档。 - 腾出区间:
net stop winnat再net start winnat能临时释放,但重启后大概率又被划走,还会中断 WSL 的网络,这条本机没有实测。 - 同类坑:PostgreSQL 的默认端口 5432 落在 5384–5483 这一段里,所以那篇笔记连的是 5600。
开 debug 的写法
- 老笔记里的
FLASK_ENV=development从 Flask 2.3 起已经删除,实测设成什么都不影响,flask run依旧打印Debug mode: off。 - 现在开 debug 有两条路:命令行
flask run --debug,或环境变量FLASK_DEBUG=1。实测两者都得到下面这段输出:
1 | * Debug mode: on |
- 代码里写
app.run(debug=True)效果相同;app.run()不带参数时,实测FLASK_DEBUG=1也能把它变成Debug mode: on——环境变量只在没显式传debug时才生效。 debug=True会同时打开代码自动重载和在线调试器,调试器允许浏览器里执行任意 Python 代码,所以只在本机开着用。
app.run 的参数
| 参数 | 默认值 | 说明 |
|---|---|---|
| host | 127.0.0.1 |
写 0.0.0.0 时局域网其它设备能访问 |
| port | 5000 |
本机被 Windows 预留,见上一节 |
| debug | False |
打开后自动重载 + 在线调试器 |
| threaded | True |
Flask 源码里 options.setdefault("threaded", True),默认就是多线程 |
1 | if __name__ == '__main__': |
- 实测
host='0.0.0.0'启动时会多打两行,第二行就是本机在局域网里的地址,手机连同一个 WiFi 能直接打开:
1 | * Running on all addresses (0.0.0.0) |
- 脚本后面多写的参数会被忽略:实测
python app.py runserver照样正常起服务,runserver只是留在sys.argv里没人读它。
请求与响应
四个上下文对象
-
current_app、g、request、session都不是真身,而是代理对象:实测type(g).__name__、type(request).__name__、type(session).__name__全是LocalProxy。它们只在上下文里才有值。名称 属于哪个上下文 是什么 本机实测 current_app应用上下文 当前运行的应用实例 <Flask 'probe_basic'>g应用上下文 一次请求内临时存数据的地方 g.tmp = 42随取随用request请求上下文 本次 HTTP 请求 见下一节 session请求上下文 签名 cookie 会话 存的是 cookie,不是服务端 -
在请求外面读它们会直接报错,实测是两个不同的错误:
1
2request.url -> RuntimeError: Working outside of request context.
current_app.name -> RuntimeError: Working outside of application context.前者要用
app.test_request_context(),后者要用app.app_context()。脚本、定时任务里想读current_app就得先压一个上下文。
请求钩子的正确清单
老笔记的钩子表里 before_first_request 已经不存在了,实测 hasattr(app, 'before_first_request') 在 Flask 3.1.3 上是 False(2.3 起废弃,后续版本删除),照抄会得到 AttributeError。
| 钩子 | 什么时候跑 | 本机实测有没有 |
|---|---|---|
before_request |
每次请求前,视图函数之前 | 有 |
after_request |
每次请求后,且没有未捕获异常时;参数是 response,必须 return 它 | 有 |
teardown_request |
每次请求后,无论有没有异常;参数是异常对象,无异常为 None |
有 |
teardown_appcontext |
应用上下文弹出时 | 有 |
context_processor |
往模板上下文里塞变量 | 有 |
errorhandler |
出错时接管 | 有 |
before_first_request |
—— | 已删除 |
-
正常请求的调用顺序,实测:
1
2GET /hook/ok -> 200 OK
before_request -> view -> after_request 200 -> teardown_request exc=None -
视图里抛异常时的顺序,这一条最能说明
after_request和teardown_request的区别:1
2GET /hook/boom
before_request -> view -> teardown_request exc=ZeroDivisionError('division by zero')after_request那一步没有出现,异常对象交给了teardown_request。 -
「钩子函数就是框架给用户预留的后门」这句理解是对的,官方叫法是 callbacks 和 signals。
-
before_request里只要 return 了东西,请求就被截住,视图函数不再执行。实测同一个/guard:1
2GET /guard -> 403 | '没带 token'
GET /guard?token=ok -> 200 | '放行'
视图函数
最小路由
1 |
|
- 决定 URL 的是装饰器里的路径,不是函数名;函数名是
endpoint,url_for()用的就是它。
带参数的路由与转换器
1 | # 不写类型就是 string |
-
各转换器的匹配与类型都是本机实测的,404 表示规则压根没匹配上,不是页面出错:
规则 请求 实测结果 <name>/t/plain/xiaoming200, name='xiaoming',str<name>/t/plain/123200, name='123',仍是 str<int:uid>/t/int/42200, uid=42,int<int:uid>/t/int/abc404 <float:ratio>/t/float/3.14200, ratio=3.14,float<float:ratio>/t/float/3404,float 不接整数写法 <path:rest>/t/path/a/b/c200, rest='a/b/c'<path:rest>/t/path/a%2Fb200, rest='a/b',转义斜杠也算进值<uuid:key>/t/uuid/12345678-1234-1234-1234-123456789012200, UUID(...)<uuid:key>/t/uuid/not-uuid404 <any(a,b,c):letter>/t/any/b200, letter='b'<any(a,b,c):letter>/t/any/z404 两个 string 参数 /t/two/xiaoming/uid/250200, name='xiaoming' uid='250' -
最后一行是老笔记那句
return name + uid的真相:两个参数都是字符串,250也是'250',所以拼出xiaoming250而不是报错。想要数字必须写<int:uid>。 -
string转换器不匹配/,所以path是唯一能吃下多级路径的那个。
尾斜杠、方法、endpoint
-
尾斜杠是有讲究的:规则带斜杠、访问不带,Werkzeug 会 308 重定向到规范地址;规则不带斜杠、访问带了,直接 404。实测:
1
2
3
4GET /slash -> 200
GET /slash/ -> 404
GET /with-slash -> 308 Location='http://localhost/with-slash/'
GET /with-slash/ -> 200 -
不想让斜杠参与匹配,就在装饰器上写
strict_slashes=False,实测带与不带都能命中同一个视图。 -
默认只接受 GET:要收 POST 得写
methods=['GET', 'POST'],用没声明的方法访问得到 405。实测PUT /multi -> 405 Method Not Allowed,GET 打到只收 POST 的/form同样 405。 -
endpoint 默认是函数名,可以用
endpoint=改名,url_for()按这个名字找:1
GET /ep -> url_for('my_ep')=/ep
-
一个函数可以叠多个
@app.route,配合defaults能给缺省参数兜底,实测:1
2
3GET /defaults/xiaoming -> name='xiaoming' page=1
GET /defaults/xiaoming/page/3 -> name='xiaoming' page=3
GET /defaults/xiaoming/page/abc -> 404
路由要一次注册完
-
Flask 3 之后,处理过第一个请求就不能再注册路由或错误处理,实测
@app.route和@app.errorhandler迟注册都抛:1
AssertionError: The setup method 'route' can no longer be called on the application.
所以别想在运行时动态加路由;确实需要分模块注册时,用 Blueprint 在启动阶段挂上去。
请求(request)
-
客户端带来的信息全在
request对象里,最常用的是url、method、args、headers。 -
下表的取值来自同一次实测请求:
GET /req?name=xiaoming&name=aaa&passwd=123,请求头User-Agent: probe-ua/1.0,用测试客户端发出(主机名固定是localhost)。属性 实测值 request.urlhttp://localhost/req?name=xiaoming&name=aaa&passwd=123request.base_urlhttp://localhost/reqrequest.root_urlhttp://localhost/request.host_urlhttp://localhost/request.hostlocalhostrequest.path/reqrequest.full_path/req?name=xiaoming&name=aaa&passwd=123request.query_stringb'name=xiaoming&name=aaa&passwd=123'request.methodGETrequest.remote_addr127.0.0.1request.scheme/is_securehttp/Falserequest.endpoint/view_argsreq/{}request.content_type/content_lengthNone/None,GET 没有正文 -
老笔记注释里那几行「只有装饰器中的路由地址」对应的是
request.path,「不包含 get 参数的请求地址」对应request.base_url,这两句描述是对的。
取查询参数
1 | request.args['name'] # 同名多个时取第一个 |
-
实测这五行分别得到
'xiaoming'、'123'、'默认值'、['xiaoming', 'aaa']、True。 -
用
[]取不存在的键会抛异常,而且抛的不是普通KeyError:实测args、form、cookies三个都是BadRequestKeyError(HTTP 400),只有headers是普通KeyError。1
2
3
4request.args['nope'] -> BadRequestKeyError: 400 Bad Request
request.form['nope'] -> BadRequestKeyError: 400 Bad Request
request.cookies['nope'] -> BadRequestKeyError: 400 Bad Request
request.headers['nope'] -> KeyError: 'HTTP_NOPE'所以老代码里
request.form['xxx']少传一个字段就是整条 400,改用.get()或先in判断。
取正文
1 | request.form # x-www-form-urlencoded 表单 |
-
表单实测(
name=xiaoming&tag=a&tag=b):1
2
3
4content_type application/x-www-form-urlencoded
dict(request.form) {'name': 'xiaoming', 'tag': 'a'}
form.getlist('tag') ['a', 'b']
dict(request.values) {'name': 'xiaoming', 'tag': 'a'}dict(form)对重复键只留最后一个,要全拿必须用getlist()。 -
文件实测(两个文件字段加一个普通字段):
1
2files -> {'up': ['note.txt', 'text/plain', 11], 'pic': ['a.png', 'image/png', 23]}
form -> {'title': 'note'}request.files[name]拿到的是FileStorage,有.filename、.content_type、.read();普通字段仍然进form,不会混进files。 -
get_json()现在是严格的:Content-Type 不是application/json就抛UnsupportedMediaType(HTTP 415),不会静默返回None。实测把表单 POST 打到只调get_json()的视图,整个请求直接 415 失败。- 想让它安静一点就写
get_json(silent=True),实测返回None。 - Content-Type 写对但正文为空,实测是 400 Bad Request,同样不是
None。
- 想让它安静一点就写
响应(response)
-
视图的返回值就是响应,Flask 负责把它包成 response 对象。七种写法实测如下:
视图返回 状态码 Content-Type 正文 '纯字符串'200 text/html; charset=utf-8原样 '文字', 404404 text/html; charset=utf-8原样 '文字', 201, {'X-Mine': '1', 'Content-Type': 'text/plain'}201 text/plain原样 make_response('文字', 404)404 text/html; charset=utf-8原样 Response('文字', status=202, mimetype='text/plain')202 text/plain; charset=utf-8原样 {'name': 'xiaoming', 'age': 25}200 application/json{"age":25,"name":"xiaoming"}'<h1>标题</h1>'200 text/html; charset=utf-8原样 -
返回字符串默认 200 是对的,但 Content-Type 默认是
text/html而不是text/plain:老笔记「直接返回一个字符串即可」这句没错,只是它会被当 HTML 解析,把用户输入拼进返回值就是 XSS。 -
元组的第二项是状态码,第三项是响应头字典,实测三元组两种都生效。
-
直接返回 dict 会自动转 JSON(Flask 2.0 起),实测 Content-Type 变成
application/json,这是写接口最省事的返回方式。 -
make_response()用来在返回前改响应头和 cookie,实测:1
GET /r/make -> 404 | X-From=make_response | Set-Cookie=visited=yes; Expires=Fri, 06 Nov 2026 ...
返回非法值会怎样
-
视图返回
123或四元素元组这种非法值,实测在没有自定义处理时都是 500 页面,日志里是那句原文:1
2TypeError: The view function did not return a valid response tuple.
The tuple must have the form (body, status, headers), (body, status), or (body, headers). -
更坑的是注册了
errorhandler(500)却只 return 字符串的情况,实测状态码变成 200:1
GET /r/bad4 -> 200 | '自定义 500 页面'
错误页返回 200,前端和搜索引擎都识别不出这是出错,下一节专门说这条。
重定向(redirect)
- 用途有两个:URL 换了又想让老地址还能用,以及登录、提交成功后跳到目标页。
redirect()造一个重定向响应,url_for()按 endpoint 反查 URL,两个通常一起用。
1 |
|
-
实测
GET /old -> 302 Location='/new',redirect()默认就是 302;要永久重定向写redirect('/new', code=301),实测得到 301。 -
url_for()的实测行为,这张表比说明文字靠谱:写法 实测结果 url_for('new')/newurl_for('welcome', name='xiaoming')/welcome/xiaomingurl_for('welcome', name='x', uid=250)/welcome/x?uid=250url_for('new', q=1)/new?q=1url_for('new', _external=True)http://localhost/newurl_for('static', filename='css/a.css')/static/css/a.cssurl_for('nope')BuildError: Could not build url for endpoint 'nope'. Did you mean 'new' instead? -
老笔记那句「可以构造带参的路由:
url_for('welcome', name='xiaoming', uid=250')」有误导:uid不在路由规则里,实测它被拼成了查询串?uid=250,而不是路径的一部分。要进路径,规则里就得写<int:uid>。 -
静态文件一律走
url_for('static', filename=...),别手写/static/,这样以后改STATIC_URL不会漏。 -
_external=True才会带上协议和主机名,用在邮件正文、第三方回调地址这种「浏览器不知道自己在哪」的场合。
终止(abort)
-
abort()的作用是在视图里中断请求、交给错误处理机制;它内部是raise,所以后面的代码不会执行。 -
三种可用写法实测:
app.py 1
2
3abort(404) # 最常见
abort(404, description='带描述的 abort') # 换掉默认错误页里的说明
abort(make_response('这段文字', 418)) # 直接给一个响应对象1
2
3GET /a/404 -> 404 | <title>404 Not Found</title> ...
GET /a/desc -> 404 | <p>带描述的 abort</p>
GET /a/resp -> 418 | '用 abort 中止并返回这段文字' -
abort(Forbidden())这种写法在 Werkzeug 3.1 里已经不能用了:abort()只接受状态码或 response,传异常对象实测得到 500,日志里是LookupError: no exception for <Forbidden '403: Forbidden'>。要么直接raise Forbidden()(实测正常返回 403),要么abort(make_response(...))。 -
定制错误页用
@app.errorhandler,实测匹配顺序是具体状态码优先,Exception兜底:app.py 1
2
3
4
5
6
7
def page_not_found(e):
return '大哥,是不是搞错了?', 404
def any_error(e):
return '兜底页面', 5001
2
3GET /e404 -> 404 | '404 专属'
GET /nothing -> 404 | '404 专属'
GET /e500 -> 500 | 'Exception 兜底:ZeroDivisionError'第二行说明 404 不会被
Exception兜底抢走,具体码的处理器优先。 -
处理函数必须自己带上状态码:实测
return '自定义 500 页面'的状态码是 200,return '自定义 500 页面', 500才是 500。这条最容易漏,也最坑监控。 -
@app.errorhandler(500)能不能接住未捕获的异常?实测能接住——Flask 会把ZeroDivisionError包成InternalServerError再找处理器;但它接不住 400 这类其它状态码,实测request.form['nope']抛的BadRequestKeyError仍然是 400 页面。 -
errorhandler(Exception)会把 404 也一并接走,这是官方文档专门警告过的一条。实测只注册 Exception 处理器时:1
GET /nope -> 500 | 'Exception 兜底:NotFound'
一个不存在的地址被报成 500。所以兜底处理器里要先放行 HTTP 异常:
app.py 1
2
3
4
5
6
7from werkzeug.exceptions import HTTPException
def any_error(e):
if isinstance(e, HTTPException):
return e # 404、405 这类交回默认处理
return '服务器错误', 500
拓展
MVC 与 MTV
- MVC:Model 数据模型、View 视图(显示逻辑)、Controller 控制器(业务逻辑),目的是把三者解耦。
- MTV:Model、Template(显示)、View(业务逻辑),是 Django 的叫法。两个名字里的 V 位置换了,分工其实一回事:Template 对应 MVC 的 View,Django 的 View 对应 MVC 的 Controller。
- Flask 不给自己贴 MTV 标签:它连 Model 层都没有(官方原话 “Flask will never have a database layer”),M 完全靠扩展,本系列用的是 Flask-SQLAlchemy;V 是视图函数加 Jinja 模板;C 也就是视图函数本身。
- 想对比 Django 的写法,看 Django-基本入门。
参考
- Welcome to Flask — 官方对 Flask 的定义与三个依赖
- Design Decisions in Flask — What does “micro” mean? 与 What Flask is, What Flask is Not
- Deploying to Production — 官方自托管服务器清单与开发服务器警告
- Quickstart — Routing、About Responses、Sessions
- Handling Application Errors — errorhandler 与自定义错误页
- werkzeug.exceptions.abort — abort 只接受状态码或 Response