FastAPI请求

路径参数

路径参数是URL路径中的占位符，用于捕获URL中的路径作为参数。路径参数会作为实参传入操作函数。

路径参数格式：{参数名}

from fastapi import FastAPI

app = FastAPI()

# 捕获单个路径参数
@app.get("/users/{user_id}")
async def read_user(user_id: int):
    return {"user_id": user_id}

# 捕获多个路径参数
@app.get("/events/{year}/{month}/{day}")
async def get_event(year: int, month: int, day: int):
    return {"date": f"{year}-{month:02d}-{day:02d}"}

例如访问 /users/2333 则会以user_id作为参数名，并将"2333"解析为参数声明的类型，然后将解析后的结果作为值。

如果参数无法解析为对应类型，则返回422报错。

路径参数约束

使用 fastapi.Path() 可以给路径参数添加额外的验证规则和文档说明。

接口设计与Pydantic的Field保持一致。

from fastapi import FastAPI, Path

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(
    item_id: int = Path(ge=1, le=1000, description="商品ID，范围1~1000")
):
    return {"item_id": item_id}

常用约束参数：

default：指定默认值。

min_length, max_length：字符串、列表的长度。

gt, ge, lt, le：数值范围。

pattern：正则匹配（如pattern=r'^Hello'）。

description：提供示例或描述，用于Swagger文档。

查询参数

查询参数是URL路径中 ? 后的可选键值对参数。查询参数也会作为实参传入操作函数。

查询参数格式：?key=value

多个参数用&分隔：?key=value&key=value

from fastapi import FastAPI

app = FastAPI()

@app.get("/query")
# 没有默认值则为必传的参数
async def get_users(q: str):
    return {"q": q}

例如访问 /query?q=hello 则会以q作为参数名，并将值解析为参数声明的类型，然后将解析后的结果作为参数最终的值。

查询参数约束

使用 fastapi.Query() 可以给查询参数添加额外的验证规则和文档说明。

接口设计与Pydantic的Field保持一致。

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(
    q: str | None = Query(
        default=None,
        min_length=3,
        max_length=50,
        pattern=r"^[a-zA-Z0-9_]+$",
        description="搜索关键词，仅支持字母、数字和下划线",
        alias="query"
    )
):
    return {"q": q}

常用约束参数：

default：指定默认值。

min_length, max_length：字符串、列表的长度。

gt, ge, lt, le：数值范围。

pattern：正则匹配（如pattern=r'^Hello'）。

description：提供示例或描述，用于Swagger文档。

alias ：使用别名接收参数(如?query=xxx)。

请求体

FastAPI中获取请求体需要定义一个Pydantic模型，并将其作为路径操作函数的参数类型声明。

FastAPI会自动解析JSON请求体，并将其转换为对应的Pydantic模型实例。

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

# 1. 定义请求体模型
class Item(BaseModel):
    name: str
    price: float
    is_offer: bool | None = None

@app.post("/items/")
async def create_item(item: Item):
    return {
        "message": f"Created item: {item.name}",
        "price": item.price,
        "full_data": item.model_dump()
    }

请求体字段约束

请求体字段约束使用的是Pydantic原生的Field实现。

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()

# 定义一个Pydantic模型，并在其中使用Field
class UserCreate(BaseModel):
    username: str = Field(
        min_length=3,
        max_length=20,
        pattern=r"^[a-zA-Z0-9_]+$",
        description="用户名，仅支持字母、数字和下划线",
        example="alice_2025"
    )
    email: str = Field(
        min_length=5,
        max_length=100,
        description="用户邮箱"
    )
    age: int = Field(ge=0, le=150, default=18)
    is_active: bool = Field(default=True, alias="isActive")  # 别名

# 在路径函数中使用该模型(作为请求体)
@app.post("/users/")
async def create_user(user: UserCreate):
    return {
        "message": f"User {user.username} created!",
        "user": user.model_dump(by_alias=True)  # 使用别名输出
    }

常用约束参数：

default：指定默认值。

min_length, max_length：字符串、列表的长度。

gt, ge, lt, le：数值范围。

pattern：正则匹配（如pattern=r'^Hello'）。

description：提供示例或描述，用于Swagger文档。

alias ：使用别名接收参数(如?query=xxx)。

Form表单

fastapi.Form() 是 FastAPI 中用于接收和验证 HTML 表单数据的工具，支持类型转换、字段约束、默认值和文档生成。配合 File() 可处理文件上传，是构建 Web 表单接口的标准方式。

Form() 依赖 python-multipart 库来解析 multipart/form-data。

安装依赖库：pip install python-multipart

from fastapi import FastAPI, Form, File, UploadFile

app = FastAPI()

@app.post("/upload/")
async def upload_profile(
    name: str = Form(min_length=1),
    bio: str = Form(default=""),          # 可选字段
    avatar: UploadFile = File()           # 文件字段
):
    return {
        "name": name,
        "bio": bio,
        "filename": avatar.filename,
        "content_type": avatar.content_type
    }

常用约束参数：

default：指定默认值。

min_length, max_length：字符串、列表的长度。

gt, ge, lt, le：数值范围。

pattern：正则匹配（如pattern=r'^Hello'）。

description：提供示例或描述，用于Swagger文档。

获取Cookie和Header

Cookie() 和 Header() 用于从请求报文的Cookies和Headers中获取信息。

两种方法都是根据字段名或别名读取Cookie或Header中的数据，而非直接获取请求中的所有Cookies或Headers。

from typing import Annotated
from fastapi import Cookie, Header

@app.get("/modern")
async def modern_way(
    # 读取Cookie中的session信息，无默认值所以必填
    session: Annotated[str, Cookie()],
    # 读取Header中的user_agent信息，有默认值可为空
    user_agent: Annotated[str | None, Header()] = None,
    # 读取Header中的X-Token信息，有默认值可为空
    x_token: Annotated[str | None, Header(alias="X-Token")] = None,
):
    return {
        "session": session,
        "user_agent": user_agent,
        "x_token": x_token
    }

常用约束参数：

default：指定默认值。

min_length, max_length：字符串、列表的长度。

gt, ge, lt, le：数值范围。

pattern：正则匹配（如pattern=r'^Hello'）。

description：提供示例或描述，用于Swagger文档。

alias ：使用别名接收参数(如?query=xxx)。

Request对象

在 FastAPI 中，Request 是一个非常强大且灵活的工具，它让你能够直接访问底层的 HTTP 请求对象，可用于获取原始请求信息（如：headers、cookies、客户端 IP、请求体原始内容等）。

只有当FastAPI框架的声明式能力不够用时，才需要使用底层 request 对象。

from fastapi import FastAPI, Request

app = FastAPI()

# 通过类型注解直接注入Request对象
@app.get("/info")
async def info(request: Request):
    return {
        "url": str(request.url),
        "method": request.method,
        "client_host": request.client.host,
        "headers": dict(request.headers)
    }

如果既要验证返回数据结构，又要操作 Response(如设置 Cookie)。

可以在路径操作函数再指定一个任意名称的参数(例如body)，但类型注解必须是Pydantic模型类，FastAPI会将该参数视为接收请求体模型的参数。

FastAPI会通过类型注解识别参数用途，所以名称和顺序都无所谓。

例如：user_login(response: Response, body: UserAuth)

常用属性和方法：

属性/方法	说明
request.url	完整 URL（URL 对象，可转为 str）
request.base_url	基础 URL（协议 + host + 端口）
request.method	HTTP 方法（"GET", "POST" 等）
request.headers	请求头（类似字典，不区分大小写）
request.query_params	查询参数（QueryParams 对象，类似字典）
request.path_params	路径参数（字典，如 {"user_id": "123"}）
request.client	客户端信息（.host, .port）
request.cookies	Cookies（字典）
request.session	会话数据（需配置 SessionMiddleware）
request.state	自定义状态（用于中间件传递数据）
request.body()	读取原始请求体，适用于处理非JSON数据。异步需要使用 await 异步读取，流式传输只能有效读取一次。
request.json()	读取并解析 JSON 请求体。异步需要使用 await 异步读取，流式传输只能有效读取一次。