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
    6
    from 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
    7
    version('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
    2
    WARNING: 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
    9
    name: 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
      12
      downloading 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_DIR
    UV_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
    2
    uv 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 123ms
    1
    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 能改激活时显示的目录名。
  • 项目化流程(推荐用法,比 requirements.txt 强在锁文件):

    1
    2
    3
    uv 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__)

    # 配置路由
    @app.route('/')
    def index():
    return 'Hello World'

    if __name__=='__main__':
    # 启动
    app.run()

三种启动方式

Flask 项目里没有 manage.py,python manage runserver 是 Django 的启动命令。在 Flask 目录里照抄,Python 会把 manage 当成要执行的脚本文件名,找不到就直接退出:

1
2
$ python manage runserver
python.exe: can't open file '...\manage': [Errno 2] No such file or directory

本机 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 后退出码 0
    1
    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
2
3
4
$ flask run
* Serving Flask app 'app.py'
* Debug mode: off
以一种访问权限不允许的方式做了一个访问套接字的尝试。

这句中文对应 OSError: [WinError 10013],不是 Flask 的 bug。装了 Hyper-V / WSL2 的 Windows 开机时会划走一整段 TCP 端口,5000 正好落在里面:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
$ netsh interface ipv4 show excludedportrange protocol=tcp
协议 tcp 端口排除范围

开始端口 结束端口
---------- --------
1048 1147
1348 1447
1464 1563
4902 5001
5172 5271
5284 5383
5384 5483
5484 5583
7409 7508
7569 7668
12168 12267
12373 12472
13508 13508
50000 50059 *
  • 换端口(推荐):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
2
3
4
5
* Debug mode: on
* Running on http://127.0.0.1:5003
* Restarting with stat
* Debugger is active!
* Debugger PIN: 914-890-930
  • 代码里写 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),默认就是多线程
app.py
1
2
if __name__ == '__main__':
app.run(debug=True, threaded=True, port=5002, host='0.0.0.0')
  • 实测 host='0.0.0.0' 启动时会多打两行,第二行就是本机在局域网里的地址,手机连同一个 WiFi 能直接打开:
1
2
3
* Running on all addresses (0.0.0.0)
* Running on http://127.0.0.1:5004
* Running on http://192.168.1.39:5004
  • 脚本后面多写的参数会被忽略:实测 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
    2
    request.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
    2
    GET /hook/ok -> 200 OK
    before_request -> view -> after_request 200 -> teardown_request exc=None
  • 视图里抛异常时的顺序,这一条最能说明 after_request 和 teardown_request 的区别:

    1
    2
    GET /hook/boom
    before_request -> view -> teardown_request exc=ZeroDivisionError('division by zero')

    after_request 那一步没有出现,异常对象交给了 teardown_request。

  • 「钩子函数就是框架给用户预留的后门」这句理解是对的,官方叫法是 callbacks 和 signals。

  • before_request 里只要 return 了东西,请求就被截住,视图函数不再执行。实测同一个 /guard:

    1
    2
    GET /guard          -> 403 | '没带 token'
    GET /guard?token=ok -> 200 | '放行'

视图函数

最小路由

app.py
1
2
3
@app.route('/test/')
def test():
return 'for test'
  • 决定 URL 的是装饰器里的路径,不是函数名;函数名是 endpoint,url_for() 用的就是它。

带参数的路由与转换器

app.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@app.route('/welcome/<name>')              # 不写类型就是 string
def welcome(name):
return 'Hello %s!' % name

@app.route('/user/<int:uid>') # 类型写在参数名前面,用 : 分隔
def user(uid):
return '%d 号,你好!' % uid

@app.route('/file/<path:rest>') # path 允许值里带 /
def file(rest):
return rest

@app.route('/username/<name>/uid/<uid>') # 多个参数
def userinfo(name, uid):
return name + uid
  • 各转换器的匹配与类型都是本机实测的,404 表示规则压根没匹配上,不是页面出错:

    规则 请求 实测结果
    <name> /t/plain/xiaoming 200,name='xiaoming',str
    <name> /t/plain/123 200,name='123',仍是 str
    <int:uid> /t/int/42 200,uid=42,int
    <int:uid> /t/int/abc 404
    <float:ratio> /t/float/3.14 200,ratio=3.14,float
    <float:ratio> /t/float/3 404,float 不接整数写法
    <path:rest> /t/path/a/b/c 200,rest='a/b/c'
    <path:rest> /t/path/a%2Fb 200,rest='a/b',转义斜杠也算进值
    <uuid:key> /t/uuid/12345678-1234-1234-1234-123456789012 200,UUID(...)
    <uuid:key> /t/uuid/not-uuid 404
    <any(a,b,c):letter> /t/any/b 200,letter='b'
    <any(a,b,c):letter> /t/any/z 404
    两个 string 参数 /t/two/xiaoming/uid/250 200,name='xiaoming' uid='250'
  • 最后一行是老笔记那句 return name + uid 的真相:两个参数都是字符串,250 也是 '250',所以拼出 xiaoming250 而不是报错。想要数字必须写 <int:uid>。

  • string 转换器不匹配 /,所以 path 是唯一能吃下多级路径的那个。

尾斜杠、方法、endpoint

  • 尾斜杠是有讲究的:规则带斜杠、访问不带,Werkzeug 会 308 重定向到规范地址;规则不带斜杠、访问带了,直接 404。实测:

    1
    2
    3
    4
    GET /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
    3
    GET /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.url http://localhost/req?name=xiaoming&name=aaa&passwd=123
    request.base_url http://localhost/req
    request.root_url http://localhost/
    request.host_url http://localhost/
    request.host localhost
    request.path /req
    request.full_path /req?name=xiaoming&name=aaa&passwd=123
    request.query_string b'name=xiaoming&name=aaa&passwd=123'
    request.method GET
    request.remote_addr 127.0.0.1
    request.scheme / is_secure http / False
    request.endpoint / view_args req / {}
    request.content_type / content_length None / None,GET 没有正文
  • 老笔记注释里那几行「只有装饰器中的路由地址」对应的是 request.path,「不包含 get 参数的请求地址」对应 request.base_url,这两句描述是对的。

取查询参数

app.py
1
2
3
4
5
request.args['name']              # 同名多个时取第一个
request.args.get('passwd') # 取不到返回 None
request.args.get('nope', '默认值') # 取不到给默认值
request.args.getlist('name') # 同名全部取回
'name' in request.args # 只判断存在,最安全
  • 实测这五行分别得到 'xiaoming'、'123'、'默认值'、['xiaoming', 'aaa']、True。

  • 用 [] 取不存在的键会抛异常,而且抛的不是普通 KeyError:实测 args、form、cookies 三个都是 BadRequestKeyError(HTTP 400),只有 headers 是普通 KeyError。

    1
    2
    3
    4
    request.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 判断。

取正文

app.py
1
2
3
4
5
6
request.form           # x-www-form-urlencoded 表单
request.values # args 和 form 合并后的查询
request.get_json() # JSON 正文
request.get_data() # 原始字节 / 文本
request.files # multipart 上传的文件
request.cookies # 请求带来的 cookie
  • 表单实测(name=xiaoming&tag=a&tag=b):

    1
    2
    3
    4
    content_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
    2
    files -> {'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 原样
    '文字', 404 404 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
    2
    TypeError: 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,两个通常一起用。
app.py
1
2
3
4
5
6
7
@app.route('/old')
def old():
return redirect(url_for('new'))

@app.route('/new')
def new():
return '新内容'
  • 实测 GET /old -> 302 Location='/new',redirect() 默认就是 302;要永久重定向写 redirect('/new', code=301),实测得到 301。

  • url_for() 的实测行为,这张表比说明文字靠谱:

    写法 实测结果
    url_for('new') /new
    url_for('welcome', name='xiaoming') /welcome/xiaoming
    url_for('welcome', name='x', uid=250) /welcome/x?uid=250
    url_for('new', q=1) /new?q=1
    url_for('new', _external=True) http://localhost/new
    url_for('static', filename='css/a.css') /static/css/a.css
    url_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
    3
    abort(404)                                    # 最常见
    abort(404, description='带描述的 abort') # 换掉默认错误页里的说明
    abort(make_response('这段文字', 418)) # 直接给一个响应对象
    1
    2
    3
    GET /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
    @app.errorhandler(404)
    def page_not_found(e):
    return '大哥,是不是搞错了?', 404

    @app.errorhandler(Exception)
    def any_error(e):
    return '兜底页面', 500
    1
    2
    3
    GET /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
    7
    from werkzeug.exceptions import HTTPException

    @app.errorhandler(Exception)
    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-基本入门。

参考