FastAPI 查询参数Query Parameters完全指南自动解析、类型转换与必填校验【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi导读本文基于 FastAPI 官方文档的韩文教程 docs/ko/docs/tutorial/query-params.md与 docs/en/docs/tutorial/query-params.md 同源展开系统讲解 FastAPI 中查询参数的自动解析机制如何在路径操作函数中声明skip、limit等查询参数如何利用默认值、None与类型注解实现「可选参数」与「必填参数」的精确控制以及int、bool、str等类型如何在 URL 字符串与 Python 数据之间自动转换与校验。读完本文你将能够熟练设计 RESTful 查询接口理解缺失必填参数时 422 错误响应的结构与来源并能结合仓库源码与测试用例独立验证 FastAPI 的底层行为。查询参数的本质不在路径里的函数参数在 FastAPI 中只要在路径操作函数里声明一个不属于路径path部分的参数它就会被自动识别为查询参数query parameter。这是声明式 API 框架的核心便利之一你不需要手动解析 URL框架会根据函数签名自动完成分发。以下代码来自 docs_src/query_params/tutorial001_py310.py是查询参数最基础的用法from fastapi import FastAPI app FastAPI() fake_items_db [{item_name: Foo}, {item_name: Bar}, {item_name: Baz}] app.get(/items/) async def read_item(skip: int 0, limit: int 10): return fake_items_db[skip : skip limit]这里的skip: int 0与limit: int 10都没有出现在路由路径/items/中因此 FastAPI 会自动把它们当作查询参数处理。URL 中查询参数的语法查询参数位于 URL 中?之后多个参数之间用分隔本质是一组键值对。例如访问下面的 URLhttp://127.0.0.1:8000/items/?skip0limit10对应的查询参数为skip值为0limit值为10。由于查询参数是 URL 的一部分它天然以字符串形式传输。但当你用 Python 类型注解如上面的int声明后FastAPI 会将其转换parse并校验为对应类型——这与路径参数的处理流程完全一致共同构成了 FastAPI 的「编辑器支持 数据解析 数据校验 自动文档化」四条能力链编辑器支持IDE 能根据函数签名提示参数类型与默认值数据解析parsing把 HTTP 请求中携带的字符串转换为 Python 数据数据校验validation类型不符或缺少必填项时返回 422 校验错误自动文档化OpenAPI 模式与/docs交互式文档自动生成。默认值让查询参数可省略查询参数不是 URL 路径中的固定组成部分因此它可以完全省略——只要为它提供默认值即可。在上面的例子中skip0和limit10就是默认值。访问下面的 URL不带任何查询参数http://127.0.0.1:8000/items/等价于访问http://127.0.0.1:8000/items/?skip0limit10而如果只指定了部分参数例如访问http://127.0.0.1:8000/items/?skip20函数收到的参数值将是skip 20因为它在 URL 中被显式给出limit 10因为未给出时使用默认值。仓库中的测试 tests/test_tutorial/test_query_params/test_tutorial001.py 验证了这种切片行为pytest.mark.parametrize( (path, expected_json), [ (/items/, [{item_name: Foo}, {item_name: Bar}, {item_name: Baz}]), (/items/?skip1, [{item_name: Bar}, {item_name: Baz}]), (/items/?skip1limit1, [{item_name: Bar}]), ], )可以看到不带参数返回全部 3 条数据?skip1时limit仍取默认值10因此返回从索引 1 开始的所有数据?skip1limit1则精确返回 1 条。同时该测试还对/openapi.json做了快照断言确认生成的 OpenAPI 中skip、limit均被标记为required: False、in: query且带上了default字段——这正是「默认值 自动文档化」的直接证据。可选参数用 None 声明「可有可无」与提供具体默认值不同如果希望某个查询参数可以不被提供但又不希望给它一个「业务默认值」可以把默认值设置为None。此时该参数类型通常声明为「该类型或 None」的联合类型。参考 docs_src/query_params/tutorial002_py310.pyfrom fastapi import FastAPI app FastAPI() app.get(/items/{item_id}) async def read_item(item_id: str, q: str | None None): if q: return {item_id: item_id, q: q} return {item_id: item_id}在这个例子里函数参数q是可选的未提供时值为None。注意这里同时出现了item_id路径参数和q查询参数item_id因为出现在路径模板/items/{item_id}中被识别为路径参数q不在路径中被识别为查询参数。提示FastAPI 足够「聪明」能通过路径模板与函数参数的匹配关系自动区分二者无需额外声明。这种区分同样适用于后续的可选/必填逻辑。str | None是 Python 3.10 的联合类型写法示例文件名以_py310结尾即为此意。在更早的 Python 版本中可以使用typing.Optional[str]达到同等效果。布尔类型转换short1 与 shorttrue 都是 True查询参数同样支持声明为bool类型FastAPI 会执行相应的类型转换。参考 docs_src/query_params/tutorial003_py310.pyfrom fastapi import FastAPI app FastAPI() app.get(/items/{item_id}) async def read_item(item_id: str, q: str | None None, short: bool False): item {item_id: item_id} if q: item.update({q: q}) if not short: item.update( {description: This is an amazing item that has a long description} ) return item这里short: bool False是一个默认为False的布尔查询参数。当访问下面任意一个 URL 时http://127.0.0.1:8000/items/foo?short1 http://127.0.0.1:8000/items/foo?shortTrue http://127.0.0.1:8000/items/foo?shorttrue http://127.0.0.1:8000/items/foo?shorton http://127.0.0.1:8000/items/foo?shortyes函数中的short都会被转换为布尔值True而其他任何无法解析为真值的输入如short0、shortfalse或完全省略则得到False。FastAPI 在布尔转换时是大小写不敏感的True、true、TRUE、True等各种大小写变体以及1、on、yes等「真值词」都会被识别。这种宽容的转换规则让 URL 参数对前端调用方更加友好。业务含义上这个示例实现了「短描述开关」当shortTrue时不附加长描述字段反之则附加完整描述方便调用方按需获取精简响应。混合声明多个路径参数与查询参数共存你可以在同一个函数中同时声明多个路径参数与多个查询参数FastAPI 会依据参数名自动识别各自归属不需要按照任何特定顺序排列参数——参数是靠名字而不是位置被识别并赋值的。参考 docs_src/query_params/tutorial004_py310.pyfrom fastapi import FastAPI app FastAPI() app.get(/users/{user_id}/items/{item_id}) async def read_user_item( user_id: int, item_id: str, q: str | None None, short: bool False ): item {item_id: item_id, owner_id: user_id} if q: item.update({q: q}) if not short: item.update( {description: This is an amazing item that has a long description} ) return item在这个接口中user_id: int与item_id: str是路径参数对应/users/{user_id}/items/{item_id}q: str | None None与short: bool False是查询参数。一个完整的调用示例http://127.0.0.1:8000/users/42/items/foo?qhelloshort1即便把q参数写在short后面、把user_id声明在item_id之后FastAPI 也总能正确地按名称绑定每个值——这与 Python 普通函数按关键字传参的直觉完全一致也保证了「参数顺序」永远不会成为 bug 的来源。必填查询参数不给默认值即可到目前为止我们看到的查询参数都不是必填的因为要么提供了具体的默认值如skip: int 0要么把默认值设为None使其可选。那么如果希望某个查询参数必须由调用方提供该怎么做答案非常简单不要为它声明默认值。参考 docs_src/query_params/tutorial005_py310.pyfrom fastapi import FastAPI app FastAPI() app.get(/items/{item_id}) async def read_user_item(item_id: str, needy: str): item {item_id: item_id, needy: needy} return item这里needy: str没有默认值因此它是一个必填的str类型查询参数。缺少必填参数时的 422 响应如果直接在浏览器中打开下面的 URL没有携带needyhttp://127.0.0.1:8000/items/foo-itemFastAPI 会返回 HTTP422 Unprocessable Entity响应体如下{ detail: [ { type: missing, loc: [ query, needy ], msg: Field required, input: null } ] }这个错误结构非常值得解读type: missing表示错误类型是「字段缺失」而非类型错误loc: [query, needy]定位出错的来源是query查询参数区域中的needy字段配合路径参数出错时的path位置可以精确区分参数来源msg: Field required人类可读的错误消息input: null当前输入值。上面这段错误格式并非随意书写——仓库测试 tests/test_tutorial/test_query_params/test_tutorial005.py 精确断言了GET /items/foo会得到 422 且响应体逐字段等于上述结构同时也断言了携带参数时的成功响应def test_foo_needy_very(): response client.get(/items/foo?needyvery) assert response.status_code 200 assert response.json() {item_id: foo, needy: very} def test_foo_no_needy(): response client.get(/items/foo) assert response.status_code 422同一测试还验证了 OpenAPI 快照中needy被标记为required: True、in: query——也就是说必填语义不仅作用于运行时的校验也会如实反映到自动生成的 OpenAPI 文档中供前端与 API 客户端在调用前自查。补上必填参数即可正常返回needy是必填的因此请求必须显式携带它例如访问http://127.0.0.1:8000/items/foo-item?needysooooneedy这时接口正常工作返回{ item_id: foo-item, needy: sooooneedy }混合必填、可选与默认值参数真实项目中接口常常同时包含必填参数、带默认值的参数与可选参数。FastAPI 完全支持这种混合声明参考 docs_src/query_params/tutorial006_py310.pyfrom fastapi import FastAPI app FastAPI() app.get(/items/{item_id}) async def read_user_item( item_id: str, needy: str, skip: int 0, limit: int | None None ): item {item_id: item_id, needy: needy, skip: skip, limit: limit} return item这个接口包含 3 个查询参数语义各不相同参数类型声明方式语义needystr无默认值必填调用方必须提供skipint 0可选未提供时默认为0limitint \| None None可选未提供时为None可据此实现「不限制条数」等逻辑一个完整调用示例http://127.0.0.1:8000/items/foo-item?needyyesskip20limit5值得提醒的是 Python 语言本身的一条规则带默认值的参数必须排在无默认值参数之后。因此在函数签名里必填的needy必须写在skip、limit之前这与 FastAPI 无关是 Python 语法约束FastAPI 则负责在满足该约束的前提下为每个查询参数建立独立的默认/必填语义并在 OpenAPI 中逐一体现required与default字段随声明自动变化。与路径参数联动还可以用 Enum与路径参数一样查询参数同样可以结合Enum使用将取值限制在预定义的枚举集合内。关于这一点可以进一步参考 docs/ko/docs/tutorial/path-params.md 中的「预定义值」一节对应英文教程 docs/en/docs/tutorial/path-params.md那里展示了如何用str枚举限定路径参数的可选值该技巧可直接迁移到查询参数上。源码视角FastAPI 如何解析与校验查询参数了解了全部使用方式后我们再从仓库源码层面理解其底层原理。FastAPI 依赖注入系统在 fastapi/dependencies/utils.py 中负责把请求参数绑定到函数签名上其关键逻辑如下在约 171~195 行框架会收集依赖项上积累的各类字段其中显式维护了query_params: list[ModelField]列表最终与路径参数、请求头参数、Cookie 参数合并排序供后续统一求解在约 556 行当解析到带查询参数语义Query的字段时会通过dependant.query_params.append(field)把该字段归入「查询参数」集合在约 685 行求解器将request.query_paramsStarlette 从 URL query string 解析出的键值对作为该集合的原始输入随后交给 Pydantic 完成类型转换、默认值填充与校验。也就是说一次查询参数的完整处理链路是路由分发请求命中路径操作函数字段分类FastAPI 根据函数签名将参数划分为 path / query / header / cookie 四类依据是否出现在路径模板、是否被Path、Query、Header、Cookie显式标注取值解析查询参数从request.query_params中按名取值字符串形式转换与校验由 Pydantic 按类型注解执行str → int/bool/...转换、默认值兜底与必填检查错误响应校验失败时构造detail数组的 422 响应type、loc、msg、input四字段结构自动文档同一份函数签名同时驱动 OpenAPI 参数定义生成。从测试目录 tests/test_tutorial/test_query_params/ 中可以找到覆盖本教程全部 6 个示例的用例test_tutorial001.py到test_tutorial006.py它们通过TestClient模拟真实 HTTP 请求并配合inline_snapshot对/openapi.json响应做逐字段快照对比是验证上述行为最直接的权威参照。小结查询参数是 FastAPI 构建灵活 HTTP 接口的基本功。通过本文的 6 个递进示例你可以掌握以下规则位置即语义不位于路径模板中的函数参数自动成为查询参数默认值即可选给定默认值 0、 False、 None的参数可以省略其中None表达「可空」语义无默认值即必填不写默认值的查询参数如needy: str必须由调用方提供否则返回 422类型注解驱动一切int、bool、str、str | None乃至Enum都自动获得转换、校验与文档化能力顺序无关、名字绑定多个路径/查询参数混用时无需考虑声明顺序。如果想对查询参数做更细粒度的长度限制、正则匹配、别名与多重取值校验下一步可以阅读 docs/en/docs/tutorial/query-params-str-validations.md介绍Query类与字符串校验参数并对照 docs_src/query_params/ 与 tests/test_tutorial/test_query_params/ 中的示例边读边验证。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考