3. 动作模型
动作需要浏览器发送的信息:URL 的参数([?name=martin&age=42])、表单字段、JSON 请求正文,有时还有一个 HTTP 请求头。原课程把所有这些信息称为 动作模型。本章展示动作如何获取这些信息、将其转换为正确的类型并进行验证。这一过程称为数据绑定。
[Flask] 在这方面比其他框架极简得多:它提供对请求信息的访问,以字符串的形式,仅此而已。将 ["42"] 转换为整数 42、验证名称至少有两个字符、把各字段组装成对象——这一切都由应用程序负责。我们将先手工完成这些工作(示例 07),然后使用 [Pydantic] 库(示例 08–12),它用一个类来描述模型,类中的每个字段都指定其类型和约束。在下一章中,HTML 表单将由另一个专为它们设计的库 [WTForms] 来处理;[Pydantic] 仍然是处理 URL 参数和 API 的 JSON 正文的自然工具。
术语说明:在下一章中,“模型”一词将主要指动作传递给其 视图的数据。本章中所说的动作的模型,则是它所 接收的数据。
示例 07 至 12 的运行方式与上一章的示例相同:在示例目录中打开终端,并激活虚拟环境([python app.py]);[Ctrl-C] 可停止服务器。它们的 [app.py] 文件都很相似:一个工厂 [create_app] 负责创建应用程序,配置 JSON 提供者(保留重音符号,键保持原有顺序;参见示例 03),并注册一个蓝图。只有当它们引入新内容时,我们才会加以评注。
3.1. 示例 07:URL 的参数
所谓URL 的参数 是跟在 [?] 之后的部分:[?name=martin&age=42]。这部分称为查询字符串(*query string*)。每个参数都是一个 [name=value] 对;各对之间用 [&] 分隔。[controllers/parameters.py] 文件:
| # controllers/parameters.py:URL 的参数("查询字符串")
from flask import Blueprint, abort, request
parameters = Blueprint("parameters", __name__, url_prefix="/parameters")
# /parameters/action01?name=martin:request.args 包含 URL 的参数;
# get 返回参数的值,参数缺失时返回 None
@parameters.get("/action01")
def action01():
name = request.args.get("name")
return f"name = [{name}], of type {type(name).__name__}"
# /parameters/action02?age=42:type=int 将值(字符串)转换为
# 整数;参数缺失或不是整数时,结果为 None
@parameters.get("/action02")
def action02():
age = request.args.get("age", type=int)
return f"age = [{age}], of type {type(age).__name__}"
# /parameters/action03?age=42:必需的参数;参数缺失,或
# 值不是整数时,动作以 400 响应(Bad Request)终止
@parameters.get("/action03")
def action03():
text = request.args.get("age")
if text is None:
# abort 抛出一个异常,Flask 将其转换为错误响应
abort(400, "the [age] parameter is required")
# 转换由我们自己负责
try:
age = int(text)
except ValueError:
abort(400, f"[{text}] is not an integer")
return f"age = [{age}], of type {type(age).__name__}"
# /parameters/action04?page=2:参数缺失时使用默认值
@parameters.get("/action04")
def action04():
page = request.args.get("page", default=1, type=int)
return f"page = [{page}]"
# /parameters/action05?q=flask:URL 参数的名称不一定
# 与 Python 变量的名称相同
@parameters.get("/action05")
def action05():
search = request.args.get("q")
return f"search = [{search}]"
# /parameters/action06?name=martin&age=42:以字典形式一次获取所有参数
@parameters.get("/action06")
def action06():
return request.args.to_dict()
|
- 第 11 行:[request.args] 包含 URL 的参数,这些参数已经由 [Werkzeug] 解码。它是一个特殊的 字典,即 [MultiDict],正如我们将在示例 10 中看到的,它的每个键可以接受多个值。它的方法 [get] 返回参数的值,如果参数不存在则返回 [None] 。与 [request.args["name"]] 不同,后者在参数缺失时会抛出异常,[get] 永远不会引发错误;
- 第 12 行:动作显示该值及其类型:[type(x)] 是 [x] 的类,而 [__name__] 是 该类的名称。从 URL 获取的值始终是字符串([str]);
- 第 19 行:参数 [type] 属于 [get] ,它指定一个应用于字符串的转换函数:这里是 [int],即整数类,调用 [int("42")] 会返回 42。如果转换失败([int("abc")] 会引发 [ValueError]),[get] 返回 [None],就像参数缺失时一样:动作无法区分这两种情况,输入错误就这样被忽略了;
- 第 26–35 行:一个 必需参数,以及一种能够区分两种可能错误的手动转换。[abort(400, message)] 以 400 响应(*Bad Request*——请求无效)终止动作,并附带该消息(参见示例 03)。语句 [try] / [except ValueError] 捕获 [int] 抛出的异常;
- 第 42 行:一个 默认值,在参数缺失(或其转换失败)时使用。这是列表页码的典型用法;
- 第 50 行:不必让 [Python] 变量与 URL 参数同名。搜索引擎常用简短的参数 [q] (*query*);
- 第 57 行:[to_dict()] 将 [MultiDict] 转换为标准的 [Python] 字典(只保留每个参数的第一个值),动作直接返回它:[Flask] 会把它转换为 JSON(参见示例 03)。
我们用 [curl] 测试每个动作。先是参数存在,然后是参数缺失:
| curl -i "http://localhost:5000/parameters/action01?name=martin"
curl http://localhost:5000/parameters/action01
|
| HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 28
name = [martin], of type str
name = [None], of type NoneType
|
在终端中,URL 两侧的引号是必需的:没有引号的话,shell 会解释 [&] (在 [Linux] 下它会在后台运行命令)和 [?]。包含空格或特殊字符的值必须在 URL 中 编码 :空格变成 [%20],而 [&] 变成 [%26] (否则它会分隔两个参数)。浏览器会自动处理这一点;而使用 [curl] 时,你必须自己写出来。[Werkzeug] 会先对值解码,再把它存入 [request.args]:
| curl "http://localhost:5000/parameters/action01?name=jean%20dupont%20%26%20sons"
|
| name = [jean dupont & sons], of type str
|
使用 [type=int] 的转换,先成功,随后失败:
| curl "http://localhost:5000/parameters/action02?age=42"
curl "http://localhost:5000/parameters/action02?age=abc"
|
| age = [42], of type int
age = [None], of type NoneType
|
动作 03 的必需参数,先缺失,然后无效:
| curl -i http://localhost:5000/parameters/action03
curl "http://localhost:5000/parameters/action03?age=abc"
|
| HTTP/1.1 400 BAD REQUEST
Content-Type: text/html; charset=utf-8
Content-Length: 122
<!doctype html>
<html lang=en>
<title>400 Bad Request</title>
<h1>Bad Request</h1>
<p>the [age] parameter is required</p>
<!doctype html>
<html lang=en>
<title>400 Bad Request</title>
<h1>Bad Request</h1>
<p>[abc] is not an integer</p>
|
默认值和重命名后的参数:
| curl http://localhost:5000/parameters/action04
curl "http://localhost:5000/parameters/action04?page=3"
curl "http://localhost:5000/parameters/action05?q=flask"
|
| page = [1]
page = [3]
search = [flask]
|
最后,一次传入所有参数。参数 [name] 出现了两次:[to_dict()] 只保留第一个值。
| curl "http://localhost:5000/parameters/action06?name=martin&age=42&name=durand"
|
| {
"name": "martin",
"age": "42"
}
|
年龄仍然是字符串(["42"],在 JSON 中带引号):因为没有请求转换。在浏览器中(这里是 [Chromium]),JSON 显示在一行中:[Flask] 只在调试模式下才缩进 JSON,而截图是在没有调试模式的情况下截取的;勾选“Pretty-print”复选框就会以缩进形式显示。顺便说一下,地址栏显示了 URL 中带重音字符的编码([é] 变成 [%C3%A9],其两个字节采用 [UTF-8]):

第一个示例说明了手动方式的局限:对每个参数,你都必须编写读取、转换以及处理缺失值和错误的代码。有十个参数时,动作的代码会被这些检查淹没。更好的办法是描述所期望的内容,并让库来处理验证。这正是下一个示例的目的。
3.2. 示例 08:用类描述的动作模型
[Pydantic] 是 [Python] 中使用最广泛的数据验证库(它是 [FastAPI] 框架的核心)。它用一个类来描述所期望的数据:每个属性都有一个类型,还可以有约束。[Pydantic] 负责把接收到的数据转换为这些类型,并验证约束。它安装在示例的虚拟环境中(文件 [requirements.txt])。
3.2.1. 模型:models/person.py
| # models/person.py:动作的模型,一个 Pydantic 类,其中每个
# 字段都带有自己的类型和约束
from typing import Annotated, Literal
from pydantic import BaseModel, ConfigDict, EmailStr, Field
class PersonModel(BaseModel):
# 接收到的字符串会去除两端的空格
model_config = ConfigDict(str_strip_whitespace=True)
# 必填(无默认值),长度 2 到 20 个字符
name: Annotated[str, Field(min_length=2, max_length=20)]
# 整数("42" 会被转换为 42),范围 0 到 150
age: Annotated[int, Field(ge=0, le=150)]
# 仅限这三个值之一
title: Literal["Mr", "Mme", "Melle"]
# 可选(默认为 None);如果提供,必须是有效的电子邮件地址
email: EmailStr | None = None
|
- 第 8 行:一个 [Pydantic] 模型是一个继承自 [BaseModel] 的类。它的属性在类级别声明,并带有类型,就像 [dataclass] (示例 06)中一样;
- 第 10 行:模型的配置。[str_strip_whitespace=True] 会去掉接收到的字符串两侧的空格:输入为 [" martin "] 的名字在验证之前会变成 ["martin"] 。属性 [model_config] 不是模型中的字段:[Pydantic] 能识别这个保留名称;
- 第 13 行:字段 [name]。[Annotated[str, Field(...)]] 读作“类型 [str],由 [Field(...)] 注解”。[Annotated],来自标准模块 [typing],它允许给类型附加额外信息——这些信息会被 [Python] 忽略,但会被各个库读取:这里是 [Pydantic] 的约束,长度为 2 到 20 个字符([min_length],[max_length])。该字段没有默认值:它是 必需的;
- 第 15 行:类型 [int]:[Pydantic] 把字符串 ["42"] 转换为整数 42,并拒绝 ["abc"]。约束 [ge] (*greater or equal*,大于或等于)和 [le] (*less or equal*,小于或等于)限制取值范围。另外还有用于严格不等式的 [gt] 和 [lt] ;
- 第 17 行:[Literal["Mr", "Mme", "Melle"]] 是所列三个值(且只有这三个值)的类型;
- 第 19 行:[EmailStr] 是电子邮件地址的类型;[Pydantic] 使用 [email-validator] 库(它也由 [requirements.txt] 安装)验证其语法。[EmailStr | None]:一个地址,或者 [None]。默认值 [= None] 使该字段成为 可选的。
该模型描述所期望的数据;它不包含任何验证指令。这被称为声明式风格。
3.2.2. 动作:controllers/persons.py
| # controllers/persons.py:以 Pydantic 类为模型的动作
from flask import Blueprint, request
from models.person import PersonModel
persons = Blueprint("persons", __name__, url_prefix="/persons")
# /persons/action01?name=martin&age=42&title=Mr
# model_validate:Pydantic 根据参数字典创建对象
# (绑定:将字符串转换为每个字段的类型),然后检查
# 约束(验证)。无效的模型会抛出 ValidationError,
# 由 app.py 转换为 400 响应:动作到此终止
@persons.get("/action01")
def action01():
person = PersonModel.model_validate(request.args.to_dict())
return {
# model_dump:以字典形式表示的对象(可序列化为 JSON)
"person": person.model_dump(),
"ageType": type(person.age).__name__,
}
|
- 第 16 行:[model_validate] 类方法根据一个字典创建 [PersonModel] 对象——这里是包含 URL 参数的那个字典。它按以下顺序执行两个操作: - 绑定:字典中的每个值在转换为字段的类型之后,被赋给同名字段(["42"] → 42); - 验证:检查每个字段的约束(长度、范围、允许的值等)。
- 如果其中任一步骤失败,[model_validate] 就会抛出 [ValidationError] 异常,其中包含 所有 错误的列表(而不只是第一个)。动作不处理它:动作就此停止;我们稍后会看到由谁来处理;
- 第 19 行:[model_dump()] 以字典形式返回该对象,[Flask] 可以把它转换为 JSON;
- 第 20 行:年龄的类型,用来表明转换确实发生了。
3.2.3. 错误处理:app.py
| # app.py:示例 08 的应用
from flask import Flask
from pydantic import ValidationError
from controllers.persons import persons
def create_app():
app = Flask(__name__)
# JSON:保留重音,键保持原来的顺序(见示例 03)
app.json.ensure_ascii = False
app.json.sort_keys = False
app.register_blueprint(persons)
# 无效的模型:Pydantic 的 ValidationError 异常会在
# 整个应用范围内变成 400 响应,并详细列出各项错误
@app.errorhandler(ValidationError)
def invalid_model(e: ValidationError):
errors = [{"field": ".".join(str(x) for x in err["loc"]), "message": err["msg"]}
for err in e.errors()]
return {"status": 400, "errors": errors}, 400
return app
if __name__ == "__main__":
create_app().run(port=5000, debug=True)
|
- 第 17–21 行:装饰器 [@app.errorhandler(ValidationError)] 注册了一个 异常处理程序:当某个动作抛出 [ValidationError] (或其派生类的异常)时,[Flask] 会调用这个函数,把该异常作为参数传给它,并把它的返回值作为响应返回。处理程序声明在应用程序级别,因此适用于 所有 动作:每个验证模型的动作都能从中受益,而无需编写任何一行错误处理代码;
- 第 19 行:[e.errors()] 返回错误列表。每个错误都是一个字典;我们保留两项信息:[loc] (*location*,位置),即出错的字段,形式为元组([("name",)];更长的元组见示例 10),以及 [msg],即消息。表达式 [[... for err in e.errors()]] 是一个 列表推导式:它把左边的表达式应用于每个元素来构造列表;
- 第 21 行:一个元组 [(body, code)] (参见示例 03):一个被转换为 JSON 的字典,以及代码 400。
3.2.4. 执行
有效数据:
| curl -i "http://localhost:5000/persons/action01?name=martin&age=42&title=Mr"
|
| HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 116
{
"person": {
"name": "martin",
"age": 42,
"title": "Mr",
"email": null
},
"ageType": "int"
}
|
年龄确实变成了整数(在 JSON 中没有引号),缺失的地址是 [None] (在 JSON 中为 [null] )。名字两侧带有空格([%20]),并且提供了地址:
| curl "http://localhost:5000/persons/action01?name=%20%20martin%20&age=42&title=Mme&email=martin@example.com"
|
| {
"person": {
"name": "martin",
"age": 42,
"title": "Mme",
"email": "martin@example.com"
},
"ageType": "int"
}
|
没有参数:三个必需字段都缺失。
| curl -i http://localhost:5000/persons/action01
|
| HTTP/1.1 400 BAD REQUEST
Content-Type: application/json
Content-Length: 248
{
"status": 400,
"errors": [
{
"field": "name",
"message": "Field required"
},
{
"field": "age",
"message": "Field required"
},
{
"field": "title",
"message": "Field required"
}
]
}
|
四个字段同时无效:
| curl "http://localhost:5000/persons/action01?name=m&age=abc&title=Mlle&email=xx"
|
| {
"status": 400,
"errors": [
{
"field": "name",
"message": "String should have at least 2 characters"
},
{
"field": "age",
"message": "Input should be a valid integer, unable to parse string as an integer"
},
{
"field": "title",
"message": "Input should be 'Mr', 'Mme' or 'Melle'"
},
{
"field": "email",
"message": "value is not a valid email address: An email address must have an @-sign."
}
]
}
|
所有错误一次性报告,使用户可以一次改正所有问题。消息是英文的:[Pydantic] 不提供翻译。下一个示例用自己的消息取代它们。
3.3. 示例 09:由动作执行的验证
在示例 08 中,无效数据会中断动作,由应用程序级处理程序来响应。这对 API 很方便,因为它的客户端是期望得到标准化错误响应的程序。然而,Web 页面往往更希望重新显示带有错误消息的表单:在这种情况下,动作必须自行决定如何处理无效的模型。[models/person.py] 模型与示例 08 中的相同。
3.3.1. 自定义消息:models/messages.py
| # models/messages.py:验证错误的消息,英文。
# 每个 Pydantic 错误都是一个字典:它的类型("missing"、
# "string_too_short"……)、涉及的字段(loc)、英文消息(msg),
# 以及上下文(ctx):约束的值({"min_length": 2}……)
MESSAGES = {
"missing": "the field is required",
"string_too_short": "{min_length} character(s) at least",
"string_too_long": "{max_length} character(s) at most",
"int_parsing": "an integer is expected",
"greater_than_equal": "the value must be greater than or equal to {ge}",
"less_than_equal": "the value must be less than or equal to {le}",
"literal_error": "unknown value",
"value_error": "invalid value",
"too_short": "{min_length} item(s) at least",
}
# 字段名:loc 是一个元组,如 ("name",),或 ("color", 1) 表示列表的
# 第 2 项
def field(error: dict) -> str:
return ".".join(str(x) for x in error["loc"])
# 我们自己的消息;未知的错误类型保留 Pydantic 的消息
def message_en(error: dict) -> str:
template = MESSAGES.get(error["type"])
if template is None:
return error["msg"]
# format 用上下文中的值替换 {min_length}……
return template.format(**error.get("ctx", {}))
|
- 第 5–14 行:[Pydantic] 中的每个错误都有一个 类型 和唯一标识符(["missing"] 表示缺失字段,["string_too_short"] 表示过短的字符串,等等),与英文消息无关。[MESSAGES] 字典为每种类型关联了我们自己的消息。其中一些包含诸如 [{min_length}]、[{ge}]……之类的标记:[Pydantic] 的文档为每种错误类型提供了其 上下文的值;
- 第 20–21 行:引发错误的字段名称,取自元组 [loc]。[".".join(...)] 把元组的元素(已转换为字符串)用句点连接起来;
- 第 25–30 行:我们自己的错误消息。[MESSAGES.get(...)] 对于字典中找不到的错误类型,返回 [None] ;此时使用来自 [Pydantic] 的英文消息。否则,[format] 会把消息中每一处 [{name}] 替换为上下文中同名的值:["{min_length} character(s) at least".format(min_length=2)] 得到 ["2 character(s) at least"]。记法 [**dictionary] 把字典的各项作为命名参数传入;[error.get("ctx", {})] 对于没有上下文的错误会返回一个空字典。
这种技术(根据错误类型进行翻译)正是案例研究中使用的方法:那里的消息由 键标识,这些键会被翻译成用户的语言。
3.3.2. 动作:controllers/persons.py
| # controllers/persons.py:由动作决定如何处理无效的模型
from flask import Blueprint, request
from markupsafe import escape
from pydantic import ValidationError
from models.messages import field, message_en
from models.person import PersonModel
persons = Blueprint("persons", __name__, url_prefix="/persons")
@persons.get("/action01")
def action01():
try:
person = PersonModel.model_validate(request.args.to_dict())
except ValidationError as e:
# 按字段列出的错误:e.errors() 给出它们的列表
items = "".join(f"<li>{field(error)}: {message_en(error)}</li>" for error in e.errors())
return f"<p>The form contains errors:</p><ul>{items}</ul>"
# escape:输入的姓名会被插入 HTML;其中的字符 < > & " '
# 会被替换为 < >……(否则,输入内容可能注入 HTML)
return f"<p>Welcome {person.title} {escape(person.name)} ({person.age} years old)</p>"
|
- 第 14–19 行:动作本身在 [try] / [except] 块中拦截 [ValidationError]。如果发生错误,它会构造一个 HTML 错误列表([<ul>],每个错误对应一个 [<li>] 标签);
- 第 22 行:如果成功,则返回欢迎消息。名字要经过 [escape] 函数处理,该函数来自 [markupsafe] 库(随 [Flask] 一起安装)。[escape] 会把在 HTML 中有特殊含义的字符([<]、[>]、[&]、["]、['])替换为它们的 实体 ([<]、[>]……):它们将被原样显示,而不会被解释。如果没有这一防范措施,用户就可以输入包含 HTML 甚至 [JavaScript] 的“名字”,这些代码会在任何查看该页面的人的浏览器中执行。这是 Web 上最常见的安全漏洞:脚本注入 (*XSS*,*cross-site scripting*)。标题和年龄不需要这种保护:它们的值已经由模型验证过(三个允许值之一,或一个整数)。在下一章中,[Jinja2] 视图引擎会对插入页面的任何值 自动 执行这种转义。
一个有效的输入,随后是一个包含四个错误的输入:


对第二个请求的原始响应,以及包含 HTML 的名字所对应的响应:
| curl "http://localhost:5000/persons/action01?name=m&age=abc&title=Mx&email=xx"
curl "http://localhost:5000/persons/action01?name=%3Cb%3Emartin%3C/b%3E&age=42&title=Mr"
|
| <p>The form contains errors:</p><ul><li>name: 2 character(s) at least</li><li>age: an integer is expected</li><li>title: unknown value</li><li>email: invalid value</li></ul>
<p>Welcome Mr <b>martin</b> (42 years old)</p>
|
名字 [<b>martin</b>] (在 URL 中编码为 [%3Cb%3E...] )被原样显示,没有被加粗:它的标签已被中和。请注意,这一次响应是 200 状态码:这是因为动作选择了返回包含错误的普通页面。
3.4. 示例 10:多值参数
同一个参数可以在 URL 中出现多次:[?color=red&color=green]。浏览器对于一组同名复选框或多选列表(见下一章)就会发送这样的内容。[controllers/arrays.py] 文件:
| # controllers/arrays.py:在 URL 中多次出现的参数
from flask import Blueprint, request
from pydantic import ValidationError
from models.choice import ChoiceModel
from models.messages import field, message_en
arrays = Blueprint("arrays", __name__, url_prefix="/arrays")
# /arrays/action01?color=red&color=green:get 只返回第一个值
@arrays.get("/action01")
def action01():
return {"color": request.args.get("color")}
# /arrays/action02?color=red&color=green:getlist 返回所有
# 值,放在列表中(参数缺失时为空列表)
@arrays.get("/action02")
def action02():
colors = request.args.getlist("color")
return {"color": colors, "count": len(colors)}
# /arrays/action03?color=red:由 ChoiceModel 验证的列表
@arrays.get("/action03")
def action03():
colors = request.args.getlist("color")
try:
ChoiceModel(color=colors)
errors = []
except ValidationError as e:
errors = [f"{field(error)}: {message_en(error)}" for error in e.errors()]
return {"colors": colors, "valid": not errors, "errors": errors}
|
- 第 14 行:[get] 只返回参数的 第一个 值;
- 第 21 行:[getlist] 以列表形式返回 全部 值,如果参数缺失则列表为空。这正是 [MultiDict] 的特色:它为每个键保留值的列表;
- 第 27–34 行:使用 [Pydantic] 模型对列表进行验证。这一次,模型通过普通调用 [ChoiceModel(color=colors)] 来构造,各字段作为命名参数传入:这等价于对字典调用 [model_validate] 。创建出来的对象除了验证之外没有别的用途:它不会被保留。对于空列表,表达式 [not errors] 等价于 [True] 。
模型 [models/choice.py]:
| # models/choice.py:一个列表,以及对列表中每一项的约束
from typing import Annotated, Literal
from pydantic import BaseModel, Field
class ChoiceModel(BaseModel):
# list[Literal[...]]:每一项必须是 "red"、"green" 或 "blue";
# min_length=1:列表至少包含一项
color: Annotated[list[Literal["red", "green", "blue"]], Field(min_length=1)]
|
- 第 10 行:类型 [list[Literal["red", "green", "blue"]]] 表示这样一个列表,其中 每个元素 都是三种颜色之一。约束 [min_length=1] 用在列表上时,针对的是元素个数:至少要有一个。
文件 [models/messages.py] 与示例 09 中的相同。结果如下:
| curl "http://localhost:5000/arrays/action01?color=red&color=green"
curl "http://localhost:5000/arrays/action02?color=red&color=green"
curl http://localhost:5000/arrays/action02
|
| {
"color": "red"
}
{
"color": [
"red",
"green"
],
"count": 2
}
{
"color": [],
"count": 0
}
|
验证起初成功,随后因为未知颜色而失败,再后来因为列表为空而失败:
| curl "http://localhost:5000/arrays/action03?color=red&color=blue"
curl "http://localhost:5000/arrays/action03?color=red&color=yellow"
curl http://localhost:5000/arrays/action03
|
| {
"colors": [
"red",
"blue"
],
"valid": true,
"errors": []
}
{
"colors": [
"red",
"yellow"
],
"valid": false,
"errors": [
"color.1: unknown value"
]
}
{
"colors": [],
"valid": false,
"errors": [
"color: 1 item(s) at least"
]
}
|
错误 "unknown value" 指向 [color.1]:错误元组 [loc] 为 [("color", 1)],即字段,以及列表中有问题元素的索引(第二个元素,索引从 0 开始)。
3.5. 示例 11:POST 请求的参数
前面的示例使用的是 GET 请求,其参数包含在 URL 中。POST 请求把数据放在它的 正文中,主要有两种形式:
- HTML 表单的字段:正文的语法与查询字符串相同([name=martin&age=42]),其类型(头 [Content-Type])为 [application/x-www-form-urlencoded];
- 由程序发送的 JSON 文档(页面上的 [JavaScript] 、API 的客户端等):其类型为 [application/json]。
文件 [controllers/post.py]:
| # controllers/post.py:POST 请求的参数
from flask import Blueprint, request
from pydantic import ValidationError
from models.messages import field, message_en
from models.person import PersonModel
post = Blueprint("post", __name__, url_prefix="/post")
# HTML 表单的字段(application/x-www-form-urlencoded 正文):
# request.form,一个 "多值" 字典(MultiDict),与 request.args 类似
@post.post("/action01")
def action01():
return {
"receivedType": request.content_type,
# flat=False:每个字段 -> 其值的列表
"fields": request.form.to_dict(flat=False),
}
# JSON 正文:get_json 将其反序列化(字典、列表等);
# 非 JSON 的正文 -> 错误 415(不支持的类型)或 400(JSON 格式错误)
@post.post("/action02")
def action02():
return {"receivedType": request.content_type, "body": request.get_json()}
# 表单中的单个字段
@post.post("/action03")
def action03():
name = request.form.get("name")
return f"name = [{name}]"
# 表单的各字段,由 PersonModel 类绑定并验证
@post.post("/action04")
def action04():
try:
person = PersonModel.model_validate(request.form.to_dict()).model_dump()
errors = []
except ValidationError as e:
person = None
errors = sorted(f"{field(error)}: {message_en(error)}" for error in e.errors())
return {"person": person, "valid": not errors, "errors": errors}
|
- 第 13 行:[post.post(...)]:第一个 [post] 是蓝图,第二个是为 HTTP 方法 POST 声明路由的方法(参见示例 02);
- 第 16 行:[request.content_type] 是请求的 [Content-Type] 头;
- 第 18 行:[request.form] 包含以 POST 发送的表单字段。与 [request.args] 一样,它是一个 [MultiDict]。[to_dict(flat=False)] 实际上创建一个字典,其中每个值都是该字段所有值的列表;
- 第 26 行:[request.get_json()] 对 JSON 正文进行反序列化:JSON 文本变成一个 [Python] 对象(JSON 对象变成字典,JSON 数组变成列表等)。如果正文未声明为 JSON,[get_json] 会引发 415 错误(*Unsupported Media Type*);如果已声明,但文本格式有误,则会发生 400 错误;
- 第 32 行:一个字段,被当作 URL 参数来解释;
- 第 38–45 行:示例 08 中的 [PersonModel] 模型,这一次与表单字段关联。代码与 URL 参数的情形相同:只是字典的来源不同。[sorted] 对消息排序,以确保响应一致。
使用 [curl] 时,[-d] (*data*)选项会发送一个正文;此时请求变成 POST 请求,类型为 [application/x-www-form-urlencoded],除非 [-H] (*header*)选项指定了其他类型。选项 [-X POST] 显式设置方法(这里可有可无)。表单的字段,包括一个重复出现的字段:
| curl -i -X POST -d "name=martin&age=42&hobby=tennis&hobby=piano" http://localhost:5000/post/action01
|
| HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 195
{
"receivedType": "application/x-www-form-urlencoded",
"fields": {
"name": [
"martin"
],
"age": [
"42"
],
"hobby": [
"tennis",
"piano"
]
}
}
|
一个包含整数和数组的 JSON 正文:
| curl -H "Content-Type: application/json" -d "{\"name\": \"martin\", \"age\": 42, \"children\": [\"léa\", \"tom\"]}" http://localhost:5000/post/action02
|
| {
"receivedType": "application/json",
"body": {
"name": "martin",
"age": 42,
"children": [
"léa",
"tom"
]
}
}
|
JSON 中的引号前面加了 [\] ,以防命令字符串提前结束;在 [Linux] 和 [macOS] 下,也可以用撇号把 JSON 括起来:[-d '{"name": "martin"}']。与表单字段不同,JSON 携带数据类型:年龄已经是整数。一个不是 JSON 的正文,以及随后一个格式有误的 JSON:
| curl -i -d "name=martin" http://localhost:5000/post/action02
curl -i -H "Content-Type: application/json" -d "{\"name\": " http://localhost:5000/post/action02
|
| HTTP/1.1 415 UNSUPPORTED MEDIA TYPE
Content-Type: text/html; charset=utf-8
Content-Length: 215
<!doctype html>
<html lang=en>
<title>415 Unsupported Media Type</title>
<h1>Unsupported Media Type</h1>
<p>Did not attempt to load JSON data because the request Content-Type was not 'application/json'.</p>
HTTP/1.1 400 BAD REQUEST
Content-Type: text/html; charset=utf-8
Content-Length: 163
<!doctype html>
<html lang=en>
<title>400 Bad Request</title>
<h1>Bad Request</h1>
<p>Failed to decode JSON object: Expecting value: line 1 column 10 (char 9)</p>
|
单个字段,然后用 GET 请求同一个 URL:
| curl -d "name=jean%20dupont" http://localhost:5000/post/action03
curl -i "http://localhost:5000/post/action03?name=martin"
|
| name = [jean dupont]
HTTP/1.1 405 METHOD NOT ALLOWED
Content-Type: text/html; charset=utf-8
Allow: POST, OPTIONS
Content-Length: 153
<!doctype html>
<html lang=en>
<title>405 Method Not Allowed</title>
<h1>Method Not Allowed</h1>
<p>The method is not allowed for the requested URL.</p>
|
URL 存在,但不支持 GET 方法:[Flask] 返回 405(*Method Not Allowed*),其头 [Allow] 列出了接受的方法([OPTIONS] 由 [Flask] 自动为任何路由处理)。最后,是与表单字段关联的模型,先有效后无效:
| curl -d "name=martin&age=42&title=Mr" http://localhost:5000/post/action04
curl -d "name=m&age=200" http://localhost:5000/post/action04
|
| {
"person": {
"name": "martin",
"age": 42,
"title": "Mr",
"email": null
},
"valid": true,
"errors": []
}
{
"person": null,
"valid": false,
"errors": [
"age: the value must be less than or equal to 150",
"name: 2 character(s) at least",
"title: the field is required"
]
}
|
3.6. 示例 12:自定义绑定与验证
标准类型并不总是够用。本示例展示了扩展绑定和验证的三种方式:
- 一个 路径转换器:在 URL 的路径中使用法语格式的日期 [23-09-2026];
- 一个 装饰器 ,它为动作提供一个并非来自 URL、而是来自 HTTP 头的参数;
- “自定义”类型 ,用于 [Pydantic]:一个约束(不含空格)和一个转换([dd/mm/yyyy] 格式的日期)。
| 12-custom-binding/
├── app.py
├── binding/
│ ├── date_fr.py
│ ├── language.py
│ └── types.py
└── controllers/
└── examples.py
|
3.6.1. 路径转换器:binding/date_fr.py
在示例 02 中,我们遇到了 [Werkzeug] 的转换器:[<int:id>] 只接受整数并对其进行转换。你可以编写新的转换器。
| # binding/date_fr.py:URL 路径中的法式日期 "23-09-2026"
from datetime import date, datetime
from werkzeug.routing import BaseConverter, ValidationError
# 一个 Werkzeug 转换器(Flask 所基于的库):
# 它判断路径的某一段是否合适,并将其转换为 Python 对象
class DateFrConverter(BaseConverter):
# 路径片段的正则表达式:dd-mm-yyyy
regex = r"\d{2}-\d{2}-\d{4}"
# 路径文本 -> date 对象
def to_python(self, value: str) -> date:
try:
# strptime 检查该日期是否存在:"31-02-2026" 会被拒绝
return datetime.strptime(value, "%d-%m-%Y").date()
except ValueError:
# 路由不匹配:Flask 会查找另一条路由,然后返回 404
raise ValidationError()
# date 对象 -> 路径文本(由 url_for 使用)
def to_url(self, value: date) -> str:
return value.strftime("%d-%m-%Y")
|
- 第 9 行:转换器是继承自 [BaseConverter] 的类;
- 第 11 行:属性 [regex] 是一个 正则表达式 ,描述被接受的路径段的格式:[\d] 表示一个数字,[{2}] 表示前一个元素重复——这里是两位数字。字符串前的前缀 [r] (*raw string*,原始字符串)可防止 [Python] 解释 [\]。路由只会尝试对这种形式的路径段使用该转换器;
- 第 14–20 行:[to_python] 把路径文本转换为 [Python] 对象,这里是 [date]。[datetime.strptime] (*string parse time*)按照特定格式解析字符串:[%d] 表示日,[%m] 表示月,[%Y] 表示四位数的年份;[.date()] 只保留日期而不含时间。[strptime] 会验证该日期是否存在:[31-02-2026] 格式正确,但会引发 [ValueError]。随后,转换器会引发 来自 [Werkzeug] 的 [ValidationError] 异常 (不要与 [Pydantic] 中的同名异常混淆):对于路由而言,该路由与 URL 不匹配,因此如果没有其他路由匹配,就会导致 404 错误;
- 第 23–24 行:反向操作,由 [url_for] 用来根据日期构造 URL。[strftime] (*string format time*)用于格式化日期。
转换器在 [app.py] 中注册:
| # app.py:示例 12 的应用
from flask import Flask
from controllers.examples import examples
from binding.date_fr import DateFrConverter
def create_app():
app = Flask(__name__)
# 路径变量转换器,名称为 [datefr]:路由
# 现在可以写 <datefr:day>,就像 <int:id> 一样
app.url_map.converters["datefr"] = DateFrConverter
app.register_blueprint(examples)
return app
if __name__ == "__main__":
create_app().run(port=5000, debug=True)
|
- 第 12 行:[app.url_map] 是应用程序的路由表;它的字典 [converters] 为每个转换器关联一个名称([int]、[path]……)。我们把自己的转换器加入其中,名称为 [datefr]。这一条目必须出现在使用它的蓝图的注册之前。
3.6.2. 由装饰器提供的参数:binding/language.py
一个 [Flask] 动作只接收路径变量作为参数,别无其他。要为它提供额外的信息,我们可以装饰 该动作:装饰器用一个函数取代该动作,这个函数先计算出这些信息,然后把信息传给动作并调用它。
| # binding/language.py:一个为动作提供参数的装饰器
from functools import wraps
from flask import request
# 放在动作上的 @with_language 会向它传入 [language] 参数,该参数读取自
# 头部 "Accept-Language: fr-FR,fr;q=0.9,en;q=0.8" -> "fr"
def with_language(action):
# wraps:生成的函数保留动作的名称(Flask 用它
# 来命名路由)
@wraps(action)
def action_with_language(*args, **kwargs):
# request.accept_languages:Werkzeug 已解析好的头部;
# best_match:在提供的语言中,浏览器最偏好的语言
kwargs["language"] = request.accept_languages.best_match(["fr", "en"], default="fr")
return action(*args, **kwargs)
return action_with_language
|
- 第 9 行:装饰器是一个函数,它接受一个函数(这里是动作)并返回另一个函数(参见示例 01)。在 [def hello(...)] 上方写 [@with_language] ,等价于在定义之后写 [hello = with_language(hello)];
- 第 13 行:将取代该动作的函数。[*args] 以元组形式接收位置参数,而 [**kwargs] (*keyword arguments*)以字典形式接收命名参数。[Flask] 就是这样传递路径变量的([id=3]):该函数无需事先知道它们就能接收到它们;
- 第 16 行:增加了一个命名参数 [language]。[request.accept_languages] 是请求头 [Accept-Language],它已由 [Werkzeug] 解析。浏览器在这里按偏好顺序给出用户的语言:[fr-FR,fr;q=0.9,en;q=0.8] (系数 [q] 表示偏好程度,取值范围为 0 到 1)。[best_match] 从应用程序提供的语言中选出用户最偏好的那一种;如果没有合适的语言,则返回值 [default] ;
- 第 17 行:以收到的参数和新增的参数调用原始动作。这一次,记法 [*args] 和 [**kwargs] 用于把元组和字典解包为参数;
- 第 12 行:函数 [action_with_language] 获取动作的名称([__name__])和文档。这在这里至关重要:[Flask] 以每个路由所对应函数的名称来命名该路由(即 [url_for("examples.hello")] 中的 [hello]),如果有两个动作使用了该装饰器,它将拒绝注册两个同名的路由 [action_with_language]。
我们在整个课程中都会用到这种方法:身份验证一章中的 [@login_required] 和 [@role_required] 装饰器也是以同样的方式构建的。
3.6.3. Pydantic 的“自定义”类型:binding/types.py
| # binding/types.py:用于 Pydantic 模型的 "自制" 类型
from datetime import date, datetime
from typing import Annotated
from pydantic import AfterValidator, BeforeValidator
# 一个 "自制" 约束:字符串不得包含空格。
# 函数接收已经转换为 str 的值;它返回该值,或抛出
# ValueError,其消息即为验证错误的消息
def no_space(value: str) -> str:
if " " in value:
raise ValueError("the field must not contain a space")
return value
# Annotated:str 类型,外加一个在转换之后执行的
# 检查。NoSpace 随后像普通类型一样使用
NoSpace = Annotated[str, AfterValidator(no_space)]
# 一个 "自制" 转换:"23/09/2026" -> date(2026, 9, 23),在
# date 类型的验证之前执行
def date_fr(value):
if isinstance(value, str):
try:
return datetime.strptime(value, "%d/%m/%Y").date()
except ValueError:
raise ValueError(f"[{value}] is not a valid dd/mm/yyyy date")
return value
DateFr = Annotated[date, BeforeValidator(date_fr)]
|
- 第 11–14 行:一个验证函数:它接收字段的值,如果有效则原样返回,否则抛出 [ValueError] 。异常消息就是验证错误消息;
- 第 19 行:类型 [NoSpace] 就是类型 [str],并以 [AfterValidator(no_space)] 进行注解:[Pydantic] 会在验证(必要时转换)该值为 [str] 之后调用该函数。这样,我们只需定义一次,就可以像普通类型一样在所有模型中重复使用这个类型;
- 第 24–30 行:一个转换函数。
***[date] 类型在 *[Pydantic] 中接受国际格式的字符串,如 ***[2026-09-23];而我们想要法式格式,如 ***[23/09/2026]。该函数接收原始值:如果它是字符串,就把它转换为 [date];任何其他值(例如已构造好的 [date]**)则原样返回;
- 第 33 行:[BeforeValidator]:该函数在 [date] 类型验证之前被调用,因此验证时收到的是已构造好的 [date]。
3.6.4. 控制器:controllers/examples.py
| # controllers/examples.py:自定义绑定和验证
from datetime import date
from flask import Blueprint, request, url_for
from pydantic import BaseModel, ValidationError
from binding.language import with_language
from binding.types import DateFr, NoSpace
examples = Blueprint("examples", __name__, url_prefix="/examples")
# /examples/schedule/23-09-2026:自定义路径转换器(见 app.py)
@examples.get("/schedule/<datefr:day>")
def schedule(day: date):
# url_for 使用转换器的 to_url 方法:date -> "23-09-2026"
return f"schedule for the day [{day}], of type {type(day).__name__}, " \
f"URL: {url_for('examples.schedule', day=day)}"
# /examples/hello:一个并非来自 URL 而是来自头部的参数,
# 由 @with_language 装饰器提供
@examples.get("/hello")
@with_language
def hello(language: str):
return "Hello!" if language == "en" else "Bonjour !"
# 搜索的模型:两个 "自制" 类型
class SearchModel(BaseModel):
keyword: NoSpace | None = None
since: DateFr | None = None
# /examples/search?keyword=flask&since=01/09/2026
@examples.get("/search")
def search():
model = SearchModel.model_validate(request.args.to_dict())
return f"search for [{model.keyword}] since [{model.since}]"
# 错误处理
# 蓝图的 errorhandler:将其某个动作抛出的异常转换为
# 响应(应用上的同一装饰器则适用于所有动作)
@examples.errorhandler(ValidationError)
def validation(e: ValidationError):
# 第一个错误的消息,不带 Pydantic 的 "Value error, " 前缀
message = e.errors()[0]["msg"].removeprefix("Value error, ")
return message, 400, {"Content-Type": "text/plain; charset=utf-8"}
|
- 第 14–18 行:路径变量 [day] 使用转换器 [datefr]:动作接收到的是一个 [date]。[url_for] 借助转换器的 [to_url] 方法,根据该日期为这同一个动作构造 URL。行尾的 [\] 分隔符表示指令在下一行继续;两个相邻的字面字符串会被拼接;
- 第 23–25 行:装饰器的顺序很重要。它们自下而上依次应用:[@with_language] 先转换动作,然后 [@examples.get] 将转换后的函数注册到蓝图中。如果顺序相反,蓝图注册的将是原始动作,参数 [language] 也就永远不会被提供;
- 第 30–32 行:一个模型,它把这两个“自定义”类型当作普通类型来使用。两个字段都是可选的;
- 第 45–49 行:一个异常处理器,这次声明在蓝图上:它只处理由该蓝图的动作抛出的异常。[removeprefix] 从消息中移除前缀 ["Value error, "],该前缀是 [Pydantic] 添加到 [ValueError] 消息中的。响应是一个由三个元素组成的元组:响应体、状态码和一个头部字典(见示例 03),这里用于纯文本响应。
3.6.5. 执行
路径转换器:
| curl "http://localhost:5000/examples/schedule/23-09-2026"
curl -i "http://localhost:5000/examples/schedule/31-02-2026"
|
| schedule for the day [2026-09-23], of type date, URL: /examples/schedule/23-09-2026
HTTP/1.1 404 NOT FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 207
...
|
日期由 [Python] 以国际格式显示(这是把 [date] 转换为字符串的结果),但由 [url_for] 构造的 URL 又恢复为法式格式。2 月 31 日并不存在:返回 404。国际格式的日期 [2026-09-23] 与正则表达式描述的模式不匹配:同样返回 404。
装饰器。[curl] 的 [-H] 选项用于设置头部 [Accept-Language]:
| curl -H "Accept-Language: en-US,en;q=0.9,fr;q=0.8" http://localhost:5000/examples/hello
curl -H "Accept-Language: fr-FR,fr;q=0.9" http://localhost:5000/examples/hello
curl http://localhost:5000/examples/hello
|
| Hello!
Bonjour !
Bonjour !
|
没有 [Accept-Language] 头部时([curl] 不会发送该头部),使用默认语言。国际化一章将再次讨论这个问题,由用户来选择语言。
“自定义”类型:
| curl "http://localhost:5000/examples/search?keyword=flask&since=01/09/2026"
curl "http://localhost:5000/examples/search"
curl -i "http://localhost:5000/examples/search?keyword=flask%20mvc"
curl "http://localhost:5000/examples/search?since=2026-09-01"
curl "http://localhost:5000/examples/search?since=31/02/2026"
|
| search for [flask] since [2026-09-01]
search for [None] since [None]
HTTP/1.1 400 BAD REQUEST
Content-Type: text/plain; charset=utf-8
Content-Length: 34
the field must not contain a space
[2026-09-01] is not a valid dd/mm/yyyy date
[31/02/2026] is not a valid dd/mm/yyyy date
|
3.6.6. 结论
让我们总结一下动作获取其模型所能使用的方法:
来源 | 方法 |
路径变量 | 动作的参数,由转换器指定类型([<int:id>]、[<datefr:day>]) |
URL 参数 | [request.args]:[get] (连同 [type] 和 [default])、[getlist]、[to_dict] |
POST 表单中的字段 | [request.form],一个 [MultiDict],与 [request.args] 类似 |
JSON 请求体 | [request.get_json()] |
头部 | [request.headers],以及已经解析好的对象,例如 [request.accept_languages] |
转换与验证 | 一个 [Pydantic] 模型:[model_validate]、[ValidationError]、[e.errors()] |
常见错误 | [@app.errorhandler] (整个应用程序)或 [@blueprint.errorhandler] (某个蓝图) |
计算得到的参数 | 一个为动作添加命名参数的装饰器 |
另一方面,HTML 表单需要的不仅仅是验证:它们必须被显示出来,带着用户的输入和可能的错误重新显示,并受到保护以防伪造请求。这将是 [WTForms] 的职责,待引入视图之后,在下一章中讲解。