HoRain云小助手个人主页 个人专栏: 《Linux 系列教程》《c语言教程》⛺️生活的理想就是为了理想的生活!⛳️ 推荐前些天发现了一个超棒的服务器购买网站性价比超高大内存超划算忍不住分享一下给大家。点击跳转到网站。专栏介绍专栏名称专栏介绍《C语言》本专栏主要撰写C干货内容和编程技巧让大家从底层了解C把更多的知识由抽象到简单通俗易懂。《网络协议》本专栏主要是注重从底层来给大家一步步剖析网络协议的奥秘一起解密网络协议在运行中协议的基本运行机制《docker容器精解篇》全面深入解析 docker 容器从基础到进阶涵盖原理、操作、实践案例助您精通 docker。《linux系列》本专栏主要撰写Linux干货内容从基础到进阶知识由抽象到简单通俗易懂帮你从新手小白到扫地僧。《python 系列》本专栏着重撰写Python相关的干货内容与编程技巧助力大家从底层去认识Python将更多复杂的知识由抽象转化为简单易懂的内容。《试题库》本专栏主要是发布一些考试和练习题库涵盖软考、HCIE、HRCE、CCNA等目录⛳️ 推荐专栏介绍1. 基础玩法声明与类型转换2. 可选与必选掌握参数的主动权3. 进阶绝招使用 Query添加强力校验 避坑指南与总结在 FastAPI 中查询参数Query Parameters 是构建灵活 API 的基石。它们通常用于过滤、分页、排序或执行搜索等操作。一句话概括所有在 URL 路径Path中没有被匹配的变量都会自动被 FastAPI 当作查询参数来处理。下面我们通过几个循序渐进的场景带你彻底玩转 FastAPI 的查询参数。1. 基础玩法声明与类型转换在 FastAPI 中你不需要学习任何新的魔法只需要利用标准的 Python 类型注解框架就能自动帮你做类型校验和转换。示例代码from fastapi import FastAPI app FastAPI() # 模拟一个数据库 fake_items_db [{item_id: Foo}, {item_id: Bar}, {item_id: Baz}] app.get(/items/) async def read_item(skip: int 0, limit: int 10): 访问 http://127.0.0.1:8000/items/?skip0limit2 FastAPI 会自动把 URL 中的字符串 0 和 2 转换成 int 类型 return fake_items_db[skip : skip limit]核心要点来源识别因为skip和limit没有在路径/items/中定义所以它们被自动识别为查询参数。类型转换URL 本质上只传输字符串但 FastAPI 会根据你声明的int自动将10转换成整数10。如果用户输入了无法转换的字符比如limitabcFastAPI 会自动返回一个非常清晰的 422 校验错误。2. 可选与必选掌握参数的主动权在实际开发中有些参数是用户必须传的有些则是可选的。在 FastAPI 中这完全由默认值决定。可选参数赋予一个默认值通常是None。必选参数不赋予默认值。示例代码from typing import Union from fastapi import FastAPI app FastAPI() app.get(/users/{user_id}) async def get_user( user_id: int, needy: str, optional_param: Union[str, None] None ): user_id: 路径参数 (必填因为在路径中) needy: 查询参数 (必填因为没有默认值) optional_param: 查询参数 (可选因为有默认值 None) return { user_id: user_id, needy: needy, optional_param: optional_param }测试效果访问/users/1?needyhello✅ 成功返回。访问/users/1❌ 报错提示missing - query - needy非常智能。3. 进阶绝招使用Query添加强力校验如果你需要对查询参数进行更高级的限制比如限制字符串长度、使用正则表达式、添加中文描述等就需要请出我们的主角Query类。FastAPI 官方强烈推荐配合Annotated一起使用让代码既优雅又强大。示例代码from typing import Annotated, Union from fastapi import FastAPI, Query app FastAPI() app.get(/items/) async def read_items( q: Annotated[ Union[str, None], Query( title查询关键词, description用于搜索商品的关键词长度必须在 3 到 50 个字符之间, min_length3, max_length50, pattern^search_ # 必须以 search_ 开头 ) ] None, category: Annotated[str, Query(min_length1)] default # 带默认值的必填校验 ): results [{item_id: F00}, {item_id: Baz}] if q: results.append({q: q}) return results核心要点Annotated[..., Query(...)]这是 FastAPI 推荐的现代写法。Query里的参数不会影响代码运行逻辑只负责给 FastAPI 提供校验规则和 API 文档的元数据。常用校验参数min_length/max_length: 限制字符串长度。pattern: 传入正则表达式进行格式匹配比如强制要求某种订单号格式。alias: 如果前端传的参数名带有连字符如item-queryPython 变量无法接收可以用aliasitem-query进行映射。 避坑指南与总结区分路径参数与查询参数路径参数是 URL 路径的一部分如/items/{item_id}而查询参数是 URL 中?后面的键值对如/items/?skip0。优先级路径参数必须定义在查询参数之前在函数签名中。善用类型提示无论是基础的str、int、bool还是复杂的Union和Annotated写好类型提示不仅能让 FastAPI 自动生成完美的 API 文档Swagger UI还能让你在开发阶段就规避 80% 的低级 bug。❤️❤️❤️本人水平有限如有纰漏欢迎各位大佬评论批评指正如果觉得这篇文对你有帮助的话也请给个点赞、收藏下吧非常感谢! Stay Hungry Stay Foolish 道阻且长,行则将至,让我们一起加油吧
HoRain云--FastAPI查询参数终极指南
HoRain云小助手个人主页 个人专栏: 《Linux 系列教程》《c语言教程》⛺️生活的理想就是为了理想的生活!⛳️ 推荐前些天发现了一个超棒的服务器购买网站性价比超高大内存超划算忍不住分享一下给大家。点击跳转到网站。专栏介绍专栏名称专栏介绍《C语言》本专栏主要撰写C干货内容和编程技巧让大家从底层了解C把更多的知识由抽象到简单通俗易懂。《网络协议》本专栏主要是注重从底层来给大家一步步剖析网络协议的奥秘一起解密网络协议在运行中协议的基本运行机制《docker容器精解篇》全面深入解析 docker 容器从基础到进阶涵盖原理、操作、实践案例助您精通 docker。《linux系列》本专栏主要撰写Linux干货内容从基础到进阶知识由抽象到简单通俗易懂帮你从新手小白到扫地僧。《python 系列》本专栏着重撰写Python相关的干货内容与编程技巧助力大家从底层去认识Python将更多复杂的知识由抽象转化为简单易懂的内容。《试题库》本专栏主要是发布一些考试和练习题库涵盖软考、HCIE、HRCE、CCNA等目录⛳️ 推荐专栏介绍1. 基础玩法声明与类型转换2. 可选与必选掌握参数的主动权3. 进阶绝招使用 Query添加强力校验 避坑指南与总结在 FastAPI 中查询参数Query Parameters 是构建灵活 API 的基石。它们通常用于过滤、分页、排序或执行搜索等操作。一句话概括所有在 URL 路径Path中没有被匹配的变量都会自动被 FastAPI 当作查询参数来处理。下面我们通过几个循序渐进的场景带你彻底玩转 FastAPI 的查询参数。1. 基础玩法声明与类型转换在 FastAPI 中你不需要学习任何新的魔法只需要利用标准的 Python 类型注解框架就能自动帮你做类型校验和转换。示例代码from fastapi import FastAPI app FastAPI() # 模拟一个数据库 fake_items_db [{item_id: Foo}, {item_id: Bar}, {item_id: Baz}] app.get(/items/) async def read_item(skip: int 0, limit: int 10): 访问 http://127.0.0.1:8000/items/?skip0limit2 FastAPI 会自动把 URL 中的字符串 0 和 2 转换成 int 类型 return fake_items_db[skip : skip limit]核心要点来源识别因为skip和limit没有在路径/items/中定义所以它们被自动识别为查询参数。类型转换URL 本质上只传输字符串但 FastAPI 会根据你声明的int自动将10转换成整数10。如果用户输入了无法转换的字符比如limitabcFastAPI 会自动返回一个非常清晰的 422 校验错误。2. 可选与必选掌握参数的主动权在实际开发中有些参数是用户必须传的有些则是可选的。在 FastAPI 中这完全由默认值决定。可选参数赋予一个默认值通常是None。必选参数不赋予默认值。示例代码from typing import Union from fastapi import FastAPI app FastAPI() app.get(/users/{user_id}) async def get_user( user_id: int, needy: str, optional_param: Union[str, None] None ): user_id: 路径参数 (必填因为在路径中) needy: 查询参数 (必填因为没有默认值) optional_param: 查询参数 (可选因为有默认值 None) return { user_id: user_id, needy: needy, optional_param: optional_param }测试效果访问/users/1?needyhello✅ 成功返回。访问/users/1❌ 报错提示missing - query - needy非常智能。3. 进阶绝招使用Query添加强力校验如果你需要对查询参数进行更高级的限制比如限制字符串长度、使用正则表达式、添加中文描述等就需要请出我们的主角Query类。FastAPI 官方强烈推荐配合Annotated一起使用让代码既优雅又强大。示例代码from typing import Annotated, Union from fastapi import FastAPI, Query app FastAPI() app.get(/items/) async def read_items( q: Annotated[ Union[str, None], Query( title查询关键词, description用于搜索商品的关键词长度必须在 3 到 50 个字符之间, min_length3, max_length50, pattern^search_ # 必须以 search_ 开头 ) ] None, category: Annotated[str, Query(min_length1)] default # 带默认值的必填校验 ): results [{item_id: F00}, {item_id: Baz}] if q: results.append({q: q}) return results核心要点Annotated[..., Query(...)]这是 FastAPI 推荐的现代写法。Query里的参数不会影响代码运行逻辑只负责给 FastAPI 提供校验规则和 API 文档的元数据。常用校验参数min_length/max_length: 限制字符串长度。pattern: 传入正则表达式进行格式匹配比如强制要求某种订单号格式。alias: 如果前端传的参数名带有连字符如item-queryPython 变量无法接收可以用aliasitem-query进行映射。 避坑指南与总结区分路径参数与查询参数路径参数是 URL 路径的一部分如/items/{item_id}而查询参数是 URL 中?后面的键值对如/items/?skip0。优先级路径参数必须定义在查询参数之前在函数签名中。善用类型提示无论是基础的str、int、bool还是复杂的Union和Annotated写好类型提示不仅能让 FastAPI 自动生成完美的 API 文档Swagger UI还能让你在开发阶段就规避 80% 的低级 bug。❤️❤️❤️本人水平有限如有纰漏欢迎各位大佬评论批评指正如果觉得这篇文对你有帮助的话也请给个点赞、收藏下吧非常感谢! Stay Hungry Stay Foolish 道阻且长,行则将至,让我们一起加油吧
