核心内容摘要
职场暗流涌动，凪光演绎的《职场应酬》让你洞悉一切
你是不是经常为API里该用路径参数还是查询参数而头疼又或者面对请求体、Cookie、Header一堆参数不知从何下手我见过太多项目接口参数设计得那叫一个随心所欲路径里塞过滤条件查询参数里传资源ID后期维护和联调简直就是大型甩锅现场。
今天咱就用一个餐厅点餐的比喻把FastAPI里这点参数事掰开了、揉碎了讲清楚。
保证你听完就能用用了就不想换。
先唠两句参数就像餐厅点单把API想象成一家餐厅的“后厨系统”。
️ 路径参数/* by
hk - online tools website :
hk/zh/useragent.html */ /dishes/{dish_id}- 好比你要点“宫保鸡丁”这道具体的菜它是菜单资源路径的一部分。
查询参数/* by
hk - online tools website :
hk/zh/useragent.html */ /dishes?spicytruetypeSichuan- 好比你说“我要川菜要辣的”。
这是对结果的筛选和描述不是特定资源。
请求体- 你递进去的详细订单包括要什么菜、口味、备注内容可以很复杂。
Cookie / Header- 像是你的会员卡自动带身份或者你给服务员的口头特殊要求如“快点上”。
搞清楚这个参数该放哪儿基本就对了一半。
另一半在于怎么让后厨你的代码准确无误地理解这些“订单”。
分基础必知——路径与查询参数好咱们先来聊聊最常用的两个兄弟。
路径参数锁定具体目标用来唯一标识一个资源。
想象一下你要获取ID为42的用户信息路径就是/users/42。
from fastapi import FastAPI app FastAPI() app.get(/items/{item_id}) async def read_item(item_id: int): # FastAPI自动将路径中的item_id转换为int return {item_id: item_id}关键点参数类型声明如int至关重要FastAPI会据此自动进行类型转换和验证。
如果你传个“abc”进来它会礼貌地返回一个错误而不是让你的代码崩溃。
这里千万别学我当初偷懒所有参数都定义成字符串到函数内部再转换。
结果就是错误处理代码散落一地调试起来想哭。
查询参数提供筛选与选项它不是路径的一部分跟在?后面用连接。
比如/items/?skip0limit10。
app.get(/items/) async def read_items(skip: int 0, limit: int
: return {skip: skip, limit: limit}注意到 0和 10了吗这给了它们默认值让它们变成了可选参数。
没有默认值的参数就是必选查询参数。
官方文档虽然把查询参数讲得很简单但根据我们的线上经验对于复杂的分页过滤接口强烈建议用Pydantic模型来封装查询参数而不是把一长串参数都列在函数定义里维护起来简直是灾难。
这个我们后面讲。
️
分进阶必备——参数验证与请求体接下来重点来了如何确保客人点的菜是合理的比如“宫保鸡丁”要求加“草莓”这得拦住。
用Query、Path、Body等工具精细控制Fastapi提供了这些“工具函数”让你能对参数进行更多描述。
from fastapi import Query, Path app.get(/items/{item_id}) async def read_items( item_id: int Path(..., title商品ID, ge
, # ...表示无默认值必填。
ge1表示大于等于1 q: str Query(None, min_length3, max_length
, # 可选参数None是默认值 size: float Query(
0, gt0, lt
# 可选必须大于0小于10 ): return {item_id: item_id, q: q, size: size}踩坑提醒当同一个参数既可能是路径参数又可能是查询参数时虽然设计上应避免FastAPI默认会认为是查询参数。
你必须显式使用Path来声明它是路径参数。
请求体Body处理复杂数据当数据复杂时比如创建一篇博客文章就用请求体通常是POST/PUT。
核心工具Pydantic模型。
这简直是FastAPI的“王牌搭档”数据验证和序列化的神器。
from pydantic import BaseModel class Item(BaseModel): name: str description: str | None None price: float tax: float | None None app.post(/items/) async def create_item(item: Item): # FastAPI会自动从请求体中识别item return item你可能会问多个参数混着来怎么办比如路径参数、查询参数和请求体模型一起放心FastAPI智能到令人发指。
它会自动识别1️⃣ 参数在路径中或Path()声明 -路径参数2️⃣ 单数类型int, str等且有/无默认值(必填/非必填)或Query()声明等不在路径中 -查询参数3️⃣ Pydantic模型类型 -请求体app.put(/items/{item_id}) async def update_item( item_id: int, # 路径参数 q: str | None None, # 可选查询参数 item: Item, # 请求体 user: User # 第二个请求体FastAPI会自动处理为多个请求体参数 ): return {item_id: item_id, q: q, item: item, user: user} 再说个容易翻车的点嵌套模型与复杂验证Pydantic模型可以嵌套用来描述复杂数据结构比如订单里有商品列表每个商品又有自己的属性。
class Image(BaseModel): url: str name: str class Item(BaseModel): name: str price: float tags: list[str] [] # 字符串列表 image: Image | None None # 嵌套模型 app.post(/items/) async def create_item(item: Item): return item这个工具的选择好比选螺丝刀不是最贵的就好而是最趁手的。
Pydantic就是FastAPI生态里最趁手的那把“瑞士军刀”字段类型、默认值、自定义验证器validator一套全齐。
分扩展知识——Cookie、Header与其他是不是以为这样就完了餐厅点单还有会员卡和特殊要求呢 Cookie 和 Header 参数它们通常用于元数据、身份认证等不直接作为业务参数。
在FastAPI中获取它们非常方便。
from fastapi import Cookie, Header app.get(/) async def read_header_cookie( user_agent: str | None Header(None), session_token: str | None Cookie(None) ): return {user_agent: user_agent, session_token: session_token}注意Header会自动将参数名中的下划线_转换为连字符-。
比如user_agent会读取User-Agent这个请求头且不区分大小写哦。
如果请求头本身就有连字符直接用Header(..., alias...)指定别名。
表单数据Form和文件上传File当需要接收HTML表单提交的数据或上传文件时使用。
from fastapi import Form, File, UploadFile app.post(/login/) async def login(username: str Form(...), password: str Form(...)): return {username: username} app.post(/upload/) async def upload_file(file: UploadFile File(...)): content await file.read() return {filename: file.filename, size: len(content)}最后啰嗦一句File和Form参数不能与纯JSON的Body模型混用它们是不同的编码格式。
接收文件记得用异步读写大文件更要流式处理别一股脑读到内存里。
✨
总结与一张速查表好了咱们今天把FastAPI的参数系统彻底捋了一遍。
最后送你一张我
总结的“参数安置决策表”下次设计接口时拿出来看一眼保准不迷糊 路径参数Path用于唯一指定资源。
如/users/{id} 查询参数Query用于过滤、排序、分页资源列表。
如/users?roleadminpage2 请求体Body用于创建或更新资源复杂数据。
用Pydantic模型。
Cookie用于自动携带的会话或身份信息。
Header用于元数据、内容协商、认证令牌等。
表单Form用于接收HTML表单提交的键值对数据。
文件File用于上传文件。
技术这东西底层原理就那些但经验和最佳实践才是让你少加班的关键。
希望这篇来自“踩坑前线”的
总结能让你在玩转FastAPI参数时更加得心应手。
我是【一名程序媛】喜欢用故事讲技术。
这篇近3000字的干货是我想了好久结合无数个线上真实case
总结出来的。
如果觉得对你有帮助别忘了点赞、收藏。
下次当你或同事再为参数放哪儿吵架时就把这篇文章甩过去能省下至少两杯咖啡的时间。
还有什么具体想了解的FastAPI骚操作评论区留言咱们下回接着聊