FastAPI参数大全：从路径查询到请求体，一篇搞定所有传参方式

你是不是经常为API里该用路径参数还是查询参数而头疼？又或者面对请求体、Cookie、Header一堆参数不知从何下手？

我见过太多项目，接口参数设计得那叫一个随心所欲，路径里塞过滤条件，查询参数里传资源ID，后期维护和联调简直就是大型甩锅现场。今天，咱就用一个餐厅点餐的比喻，把FastAPI里这点参数事，掰开了、揉碎了讲清楚。保证你听完就能用，用了就不想换。🎯

📖 先唠两句：参数就像餐厅点单

把API想象成一家餐厅的“后厨系统”。

搞清楚这个，参数该放哪儿，基本就对了一半。另一半，在于怎么让后厨（你的代码）准确无误地理解这些“订单”。

🚀 第一部分：基础必知——路径与查询参数

好，咱们先来聊聊最常用的两个兄弟。

🎯 路径参数：锁定具体目标

用来唯一标识一个资源。想象一下，你要获取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/?skip=0&limit=10。

@app.get("/items/") async def read_items(skip: int = 0, limit: int = 10): 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=1), # ...表示无默认值，必填。ge=1表示大于等于1 q: str = Query(None, min_length=3, max_length=50), # 可选参数，None是默认值 size: float = Query(1.0, gt=0, lt=10) # 可选，必须大于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智能到令人发指。它会自动识别：

@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的参数系统彻底捋了一遍。最后送你一张我总结的“参数安置决策表”，下次设计接口时，拿出来看一眼，保准不迷糊：

技术这东西，底层原理就那些，但经验和最佳实践才是让你少加班的关键。希望这篇来自“踩坑前线”的总结，能让你在玩转FastAPI参数时，更加得心应手。

我是【一名程序媛】，喜欢用故事讲技术。这篇近3000字的干货，是我想了好久，结合无数个线上真实case总结出来的。如果觉得对你有帮助，别忘了点赞、收藏。下次当你或同事再为参数放哪儿吵架时，就把这篇文章甩过去，能省下至少两杯咖啡的时间。

还有什么具体想了解的FastAPI骚操作？评论区留言，咱们下回接着聊！