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

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

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

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

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

🍽️ 路径参数 /dishes/{dish_id} -> 好比你要点“宫保鸡丁”这道具体的菜，它是菜单（资源路径）的一部分。

🔍 查询参数 /dishes?spicy=true&type=Sichuan -> 好比你说“我要川菜，要辣的”。这是对结果的筛选和描述，不是特定资源。

📦 请求体 -> 你递进去的详细订单，包括要什么菜、口味、备注，内容可以很复杂。

🍪 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/?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智能到令人发指。它会自动识别：

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?role=admin&page=2

📦 请求体（Body）：用于创建或更新资源（复杂数据）。用Pydantic模型。

🍪 Cookie：用于自动携带的会话或身份信息。

📋 Header：用于元数据、内容协商、认证令牌等。

📝 表单（Form）：用于接收HTML表单提交的键值对数据。

📎 文件（File）：用于上传文件。

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

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

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

posted @ 2026-01-30 09:38 一名程序媛呀阅读(0) 评论(0) 收藏举报

刷新页面返回顶部