1. 从“Hello World”到真实业务：为什么参数处理是API的基石
刚接触FastAPI时，我们写的第一个接口往往是@app.get("/")返回一个{"message": "Hello World"}。这很酷，启动服务，访问http://127.0.0.1:8000/就能看到JSON响应。但现实中的API远不止于此。无论是用户登录、商品查询、订单提交还是数据筛选，几乎每一个业务接口都需要与客户端交换数据。这些数据从哪里来？如何安全、高效、准确地接收并验证它们？这就是GET和POST请求参数处理的全部意义。
如果说路由定义了API的“地址”，那么参数处理就定义了API的“交互规则”。一个设计良好的参数接收与验证机制，不仅能极大提升开发效率（减少大量胶水代码），更是API健壮性、安全性和开发者友好性的直接体现。FastAPI在这方面之所以备受推崇，正是因为它将Python的类型提示（Type Hints）和Pydantic模型的能力发挥到了极致，让参数声明即文档、声明即验证。在这篇文章里，我不会只给你看语法糖，而是要拆解在FastAPI中处理GET和POST参数时，你必然会遇到的几种场景、背后的原理，以及那些官方文档可能不会明说，但实际项目中一定会踩到的“坑”。我们会从最简单的查询参数开始，一路深入到复杂的请求体验证，目标是让你看完就能在项目中直接应用，并且理解每一个选择背后的“为什么”。
2. GET请求参数：不止是URL里的?key=value
GET请求通常用于获取数据，其参数直观地拼接在URL的问号之后，例如/users?name=john&age=30&active=true。在FastAPI中，处理这些参数简单得令人发指，但魔鬼藏在细节里。
2.1 基础查询参数：函数参数就是API参数
最直接的方式是将参数定义为路径操作函数的参数。FastAPI会自动识别那些不属于路径参数的函数参数，并将其视为查询参数。
from fastapi import FastAPI app = FastAPI() @app.get("/items/") async def read_items(skip: int = 0, limit: int = 10, q: str | None = None): """ 获取物品列表。 - skip: 跳过的记录数，用于分页。 - limit: 返回的记录数上限。 - q: 可选的搜索关键词。 """ # 模拟数据库查询 fake_items_db = [{"item_name": "Foo"}, {"item_name": "Bar"}, {"item_name": "Baz"}] end = skip + limit items = fake_items_db[skip:end] if q: items = [item for item in items if q.lower() in item["item_name"].lower()] return {"skip": skip, "limit": limit, "q": q, "items": items}访问/items/?skip=0&limit=2&q=bar，你会得到预期的过滤结果。这里有几个关键点：
- 类型声明：
skip: int和limit: int不仅用于Python类型检查，FastAPI会用它来进行请求参数的数据转换和验证。如果客户端传了skip=abc，FastAPI会自动返回一个422状态码的错误响应，告诉你skip的值不是合法的整数。这省去了你手动写try...except或者if not str.isdigit()的功夫。 - 默认值：
= 0和= 10设置了默认值。这意味着这两个参数是可选的。如果URL中不提供，函数内部就会使用这些默认值。这是定义可选参数的推荐方式。 - 可选参数与None：
q: str | None = None是Python 3.10+的语法（旧版本可用Optional[str] = None）。它明确表示q是一个可选的字符串参数，如果不提供，其值就是None。重要区别：q: str = ""（空字符串默认值）和q: str | None = None在业务逻辑上完全不同。前者表示客户端必须传这个参数（但可以为空字符串），而后者表示客户端可以不传这个参数。根据你的业务语义谨慎选择。
2.2 查询参数验证：用Query对象赋予更多控制力
当基础类型声明不够用时，就需要请出fastapi.Query。它不是一个数据库查询工具，而是一个用于装饰和验证查询参数的专用对象。
from fastapi import FastAPI, Query from typing import Annotated # Python 3.9+ 推荐方式 app = FastAPI() @app.get("/items/") async def read_items( q: Annotated[str | None, Query(max_length=50, description="搜索关键词，最多50个字符")] = None, tags: Annotated[list[str], Query(description="按标签过滤")] = [], ): # 函数体... return {"q": q, "tags": tags}这里使用了Python 3.9引入的Annotated类型。它允许你将类型（str | None）和元数据（Query(...)）绑定在一起，是更现代、更清晰的写法。Query对象提供了丰富的验证和元数据选项：
max_length=50,min_length=1: 验证字符串长度。regex=r"^[a-zA-Z0-9_]*$": 用正则表达式验证参数格式。gt=0,ge=1,lt=100,le=99: 对数字进行大于、大于等于、小于、小于等于的验证。description: 用于OpenAPI文档，让前端或测试人员一眼看懂参数用途。deprecated=True: 标记该参数已弃用，会在文档中显示为灰色。
一个实战中的大坑：列表类型查询参数。你可能想通过/items/?tags=python&tags=fastapi&tags=web来传递多个标签。在FastAPI中，你需要显式使用Query来声明一个列表参数，否则FastAPI会认为你只期望一个字符串值。上面的tags: Annotated[list[str], Query(...)] = []就是正确写法。如果你写成tags: list[str] = []，FastAPI会期望一个像?tags=python,fastapi,web的逗号分隔字符串，并将其拆分为列表，这与很多前端库（如axios）默认发送多值参数的方式不兼容。理解这个差异，能避免很多前后端联调时的困惑。
2.3 别名、隐藏参数与复杂场景
有时，前端传来的参数名不符合Python的命名规范（例如user-name），或者你想在内部使用一个不同的变量名。这时可以用alias。
async def read_item(item_id: Annotated[int, Query(alias="item-id", ge=1)]): # 函数内部使用 `item_id`，但API接收的参数名为 `item-id` return {"item_id": item_id}你还可以用Query(..., include_in_schema=False)将一个参数从OpenAPI文档中隐藏。这常用于一些内部调试参数或遗留参数，你不想在公开文档中暴露它们，但代码仍需支持。
3. POST请求体：处理复杂数据结构的艺术
当需要创建、更新资源或执行复杂操作时，我们会使用POST、PUT、PATCH等方法，并将数据放在请求体（Request Body）中发送，通常以JSON格式。FastAPI通过Pydantic模型来处理请求体，这是它最强大的特性之一。
3.1 初识Pydantic模型：声明即验证
首先，定义一个Pydantic模型来描述你期望接收的数据结构。
from pydantic import BaseModel, Field, EmailStr from typing import List class Item(BaseModel): name: str description: str | None = Field(default=None, max_length=300) price: float = Field(gt=0, description="价格必须大于0") tax: float | None = None tags: List[str] = [] class UserCreate(BaseModel): username: str = Field(min_length=3, max_length=20) email: EmailStr # Pydantic提供的特殊类型，验证邮箱格式 full_name: str | None = None disabled: bool = False然后，在路径操作函数中，将该模型的一个实例声明为参数。
from fastapi import FastAPI app = FastAPI() @app.post("/items/") async def create_item(item: Item): # 此时，`item` 已经是一个验证通过的 `Item` 类的实例。 # 你可以直接用 `item.name`, `item.price` 来访问数据。 item_dict = item.dict() if item.tax: price_with_tax = item.price + item.tax item_dict.update({"price_with_tax": price_with_tax}) return item_dict当客户端向/items/发送一个POST请求，Body为{"name": "Foo", "price": 50.5, "tags": ["a", "b"]}时，FastAPI会：
- 自动读取JSON请求体。
- 尝试用这个数据初始化
Item模型。 - 执行所有字段级别的验证（类型、范围、格式等）。
- 如果验证通过，将生成的
Item实例传递给create_item函数。 - 如果验证失败，自动返回包含详细错误信息的422响应。
为什么这比手动解析JSON好？手动处理你需要：request.json()获取数据，检查每个字段是否存在、类型是否正确，处理缺失值和默认值，转换数据类型（如字符串转数字）。而Pydantic模型一行声明就解决了所有问题，并且错误信息是结构化的，能明确指出是哪个字段、出了什么问题（如"loc": ["body", "price"], "msg": "ensure this value is greater than 0"），极大提升了开发调试效率。
3.2 请求体验证的进阶技巧
嵌套模型：现实中的数据很少是扁平的。Pydantic完美支持嵌套。
class Image(BaseModel): url: str name: str class Item(BaseModel): name: str description: str | None = None price: float tax: float | None = None tags: List[str] = [] images: List[Image] | None = None # 嵌套模型列表字段验证器：有时字段间的验证逻辑是关联的。例如，创建用户时，密码和确认密码必须一致。这需要用到Pydantic的validator（V1）或field_validator（V2）。
from pydantic import BaseModel, field_validator class UserCreate(BaseModel): password: str password_confirm: str @field_validator('password_confirm') def passwords_match(cls, v, info): if 'password' in info.data and v != info.data['password']: raise ValueError('两次输入的密码不一致') return v区分None与字段缺失：这是API设计中的一个常见难题。假设你有一个更新用户的接口，允许部分更新（PATCH）。前端可能传{"full_name": null}表示要清空这个字段，也可能根本不传full_name表示不更新这个字段。为了区分，Pydantic V2提供了Field(..., default=PydanticUndefined)来表示字段“未提供”，但这在接收请求体时比较棘手。更常见的实践是，对于更新操作，将所有字段都设为可选（Optional[str]），并在业务逻辑层判断：如果字段值是None，且它存在于请求的JSON中，则清空；如果字段根本不存在于JSON中，则跳过更新。这需要前后端约定一致。
3.3 同时使用路径参数、查询参数和请求体
一个接口完全可以混合使用多种参数来源。
@app.put("/items/{item_id}") async def update_item( item_id: int, # 路径参数 q: str | None = None, # 查询参数 item: Item | None = None, # 请求体（可选） ): results = {"item_id": item_id} if q: results.update({"q": q}) if item: results.update({"item": item}) return resultsFastAPI能智能地区分它们：
- 路径参数：是URL路径的一部分（
/items/123）。 - 查询参数：是函数参数，但提供了默认值或使用了
Query，且不是Pydantic模型。 - 请求体参数：函数参数被声明为Pydantic模型（
Item）。
4. 表单数据与文件上传：当Content-Type不是application/json
并非所有POST请求都发送JSON。在网页表单提交或文件上传时，数据通常以multipart/form-data或application/x-www-form-urlencoded格式编码。FastAPI通过Form和UploadFile来处理。
4.1 接收普通表单数据
首先需要安装python-multipart：pip install python-multipart。然后使用fastapi.Form。
from fastapi import FastAPI, Form app = FastAPI() @app.post("/login/") async def login(username: str = Form(...), password: str = Form(...)): # `Form(...)` 表示该字段是必需的。`Form(default=None)` 表示可选。 return {"username": username}Form的用法和Query非常相似，可以设置默认值、描述等。关键区别：你不能同时使用Body（或隐式的Pydantic模型）和Form字段来接收同一个请求体的混合数据（JSON部分和表单部分）。如果需要混合，通常意味着API设计可能需要重新考虑，或者使用更底层的Request对象手动解析。
4.2 处理文件上传
文件上传是multipart/form-data的典型应用。FastAPI的UploadFile提供了异步、高效的处理方式。
from fastapi import FastAPI, File, UploadFile from fastapi.responses import HTMLResponse app = FastAPI() @app.post("/files/") async def create_file(file: bytes = File(...)): # 使用 `bytes`，FastAPI会将整个文件内容读入内存。适用于小文件。 contents = file.decode("utf-8") # 假设是文本文件 return {"file_size": len(file)} @app.post("/uploadfile/") async def create_upload_file(file: UploadFile = File(...)): # 使用 `UploadFile`，适用于大文件。它使用spooled文件，内存和磁盘混合存储。 contents = await file.read() # 处理文件内容... # 记得如果读取了，可能需要 seek(0) 或重新获取文件 return {"filename": file.filename, "content_type": file.content_type}UploadFile的优势：
- 异步读写：支持
await file.read()和await file.write()。 - 文件属性：可以直接访问
filename,content_type。 - Spooled文件：小文件存在内存，大文件自动写入临时磁盘文件，避免内存耗尽。
- 可用作上下文管理器：
async with file:语法确保文件被正确关闭。
上传多个文件：files: list[UploadFile] = File(...)。客户端需要以相同的字段名（如files）上传多个文件。
混合表单与文件：这是完全允许的。
@app.post("/profile/") async def create_profile( name: str = Form(...), avatar: UploadFile = File(None), # 可选的头像文件 ): profile_data = {"name": name} if avatar: avatar_url = await save_upload_file(avatar) # 自定义保存函数 profile_data["avatar_url"] = avatar_url return profile_data5. 参数接收的底层原理与高级定制
理解了基本用法，我们深入一层，看看FastAPI是如何做到这些的，以及当默认行为不满足需求时，我们如何定制。
5.1 依赖注入系统：参数处理的引擎
FastAPI强大的参数处理能力，建立在它的依赖注入（Dependency Injection）系统之上。当你定义一个路径操作函数时，FastAPI会分析它的参数：
- 检查参数是否被声明为依赖项（使用
Depends）。 - 如果不是，检查它是否是路径参数（在路径中声明）。
- 如果不是，检查它是否是Pydantic模型（视为请求体）。
- 如果还不是，且参数有默认值或使用了
Query/Form/File/Cookie/Header等特殊类，则视为对应的请求参数。 - 如果以上都不是，FastAPI会报错。
这个过程是递归的，依赖项本身也可以有依赖项。这个系统使得你可以将通用的逻辑（如身份验证、数据库会话获取）抽象为依赖项，然后在多个路径操作中复用，保持代码的整洁和可测试性。
5.2 使用Body进行精细控制
大多数时候，声明一个Pydantic模型参数就足够了。但有些复杂场景需要fastapi.Body。
- 单个非模型请求体字段：如果你只需要接收一个JSON字段（如一个字符串或数字），而不是一个对象。
from fastapi import Body @app.put("/items/{item_id}") async def update_item(item_id: int, importance: int = Body(...)): # 期望请求体是 `{"importance": 5}`，而不是 `{"item": {...}}` return {"item_id": item_id, "importance": importance}- 多个请求体参数：一个操作需要接收多个JSON对象。
class Item(BaseModel): name: str price: float class User(BaseModel): username: str @app.put("/items/{item_id}") async def update_item( item_id: int, item: Item, user: User, priority: int = Body(ge=1, le=5) # 额外的单一体字段 ): # 期望请求体是：`{"item": {...}, "user": {...}, "priority": 3}` return {"item_id": item_id, "item": item, "user": user, "priority": priority}- 嵌入单个请求体字段：使用
Body(..., embed=True)可以强制让一个字段被包裹在一个键中，即使它是唯一的请求体参数。这在某些特定的API规范中可能有用。
5.3 错误处理与自定义验证响应
当参数验证失败时，FastAPI会自动抛出RequestValidationError异常，并返回一个包含错误详情的422响应。这个默认行为在大多数情况下是合适的。但有时你可能需要：
- 全局自定义错误响应格式：通过添加一个自定义的异常处理器。
from fastapi import FastAPI, Request from fastapi.responses import JSONResponse from fastapi.exceptions import RequestValidationError from pydantic import ValidationError app = FastAPI() @app.exception_handler(RequestValidationError) async def validation_exception_handler(request: Request, exc: RequestValidationError): # 简化错误信息，或转换为公司统一的错误码格式 errors = [] for error in exc.errors(): field = ".".join([str(loc) for loc in error["loc"]]) errors.append({ "field": field, "message": error["msg"], "type": error["type"] }) return JSONResponse( status_code=422, content={"code": 1001, "message": "参数验证失败", "errors": errors}, )在模型内部进行更复杂的业务验证：如前所述，使用Pydantic的验证器（
@field_validator或@model_validator）。这些验证器抛出的ValueError也会被FastAPI捕获，并转化为422响应。在依赖项或路径操作函数内部进行验证：有时验证逻辑需要查数据库或调用外部服务，无法在Pydantic模型层面完成。这时可以在依赖项或函数内部进行，如果验证失败，直接抛出
HTTPException。
from fastapi import Depends, HTTPException async def verify_item_exists(item_id: int): # 模拟数据库查询 if item_id not in existing_item_ids: raise HTTPException(status_code=404, detail="Item not found") return item_id @app.get("/items/{item_id}") async def read_item(item_id: int = Depends(verify_item_exists)): # 只有当 `verify_item_exists` 成功返回后，才会执行到这里 return {"item_id": item_id}这种模式将参数验证、资源存在性检查等横切关注点与核心业务逻辑分离，是构建清晰、可维护API架构的关键。
