在使用 FastAPI 开发项目时，虽然有非常简单的接口函数（路由函数）可以快速地定义接口，但是针对路由函数中的参数，也就是希望从前端请求中解析的参数，到底应该怎么写呢？不同写法分别代表什么含义？今天就来全面讲解路由函数中的参数的用法，看完之后，你就能轻松使用 FastAPI 搭建接口。

有时候我们看到别人写的接口，有的参数用了 Query，有的直接写了 request: Request，还有的用了 Depends。如果不系统梳理，很容易糊涂。这篇文章将带你全面梳理 FastAPI 路由函数的参数类型，并通过实际项目的组合示例，帮助你快速掌握这些写法的使用场景。

一、参数类型全景图

在 FastAPI 中，路由函数的参数大致可以分为三大类：

1. 数据型参数 —— 从 HTTP 请求中提取的数据（Query、Path、Header、Cookie、Body 等）
2. 上下文型参数 —— 框架本身提供的上下文对象（Request、Response、WebSocket、BackgroundTasks 等）
3. 逻辑注入型参数 —— 依赖注入机制（Depends），用于复用逻辑、资源管理、认证鉴权

下面是一个对照表：

关系图：

接下来详细盘点这些类型的参数。

1.1 请求参数相关（Query, Path, Header, Cookie）

这些是 来自 HTTP 请求的数据，FastAPI 会自动解析：

• Query 参数（URL 中的 ?key=value）

from fastapi import Query

@app.get("/items/")
def read_items(page: int = Query(1, ge=1), size: int = Query(10, le=100)):
    return {"page": page, "size": size}

默认取自 query string，如果不用 Query()，FastAPI 也会按名字匹配 URL 参数。

• Path 参数（路径里的 /items/{item_id}）

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id}

• Header 参数

from fastapi import Header

@app.get("/agent/")
def read_agent(user_agent: str = Header(...)):
    return {"User-Agent": user_agent}

• Cookie 参数

from fastapi import Cookie

@app.get("/cookies/")
def read_cookies(session_id: str = Cookie(None)):
    return {"session_id": session_id}

1.2 请求体参数（Pydantic模型 / Body）

适用于 JSON 请求体、表单、文件上传：

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float

@app.post("/items/")
def create_item(item: Item):
    return item

如果是文件、表单：

from fastapi import File, Form

@app.post("/upload/")
def upload_file(file: bytes = File(...), username: str = Form(...)):
    return {"username": username, "file_size": len(file)}

1.3 特殊对象注入（Request / Response / WebSocket）

FastAPI 可以直接把 框架级别对象 注入进来：

from fastapi import Request, Response

@app.get("/meta/")
def read_meta(request: Request, response: Response):
    client_host = request.client.host
    response.headers["X-My-Header"] = "Value"
    return {"client_host": client_host}

这些对象不是请求参数，而是 Starlette 提供的上下文对象。框架会自动解析参数并传入到路由函数中。

1.4依赖注入（Depends）

用来实现 逻辑复用 / 权限校验 / 数据库 session 获取：

from fastapi import Depends

def get_db():
    db = "模拟数据库session"
    try:
        yield db
    finally:
        pass  # 关闭连接

@app.get("/users/")
def read_users(db=Depends(get_db)):
    return {"db": db}

依赖函数还可以返回别的类型，比如用户对象、权限信息等等。

二、常见组合写法示例

2.1 分页 + 搜索 + 排序

常见于后台管理系统的列表接口：

@app.get("/items/")
def list_items(
    q: str | None = Query(None, min_length=2, max_length=50, description="搜索关键词"),
    page: int = Query(1, ge=1, description="页码"),
    size: int = Query(10, ge=1, le=100, description="每页数量"),
    sort_by: str = Query("created_at", description="排序字段"),
    order: str = Query("desc", regex="^(asc|desc)#34;, description="排序方向")
):
    return {"query": q, "page": page, "size": size, "sort_by": sort_by, "order": order}

Query 参数约束可以直接写在函数参数中，非常方便。

不过，如果Query部分太长，试着用一下Annotated。

2.2 路径参数 + 请求体

常见于更新接口：

class ItemUpdate(BaseModel):
    name: str
    price: float
    available: bool

@app.put("/items/{item_id}")
def update_item(item_id: int, payload: ItemUpdate):
    return {"item_id": item_id, "data": payload.dict()}

路径参数和请求体 JSON 可以同时使用，分别对应资源定位和更新数据。item_id 从请求的url路径中拿到，而 payload 框架会解析后从请求体中拿。

2.3 Header + Cookie + Query

常见于需要会话和客户端信息的接口：

@app.get("/profile/")
def get_profile(
    token: str = Header(..., description="认证 Token"),
    session_id: str | None = Cookie(None),
    lang: str = Query("zh", description="语言设置")
):
    return {"token": token, "session_id": session_id, "lang": lang}

一个接口可以同时从 Header、Cookie、Query 中提取参数。

2.4 数据库依赖 + 用户认证依赖

这个在实际项目的业务接口中非常常用：

def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

def get_current_user(token: str = Header(...)):
    if token != "valid-token":
        raise HTTPException(status_code=401, detail="Unauthorized")
    return {"username": "jack"}

@app.get("/users/me")
def read_current_user(
    db: Session = Depends(get_db),
    current_user: dict = Depends(get_current_user),
    page: int = Query(1, ge=1),
    size: int = Query(10, ge=1, le=50),
):
    return {"user": current_user, "page": page, "size": size}

Depends 是核心机制：数据库连接、认证校验都能优雅复用。

2.5 后台任务 + 请求体

常见于发邮件、日志等异步任务。这个是进阶的用法，需要配合from fastapi import BackgroundTasks：

from fastapi import BackgroundTasks

def send_email(email: str, content: str):
    print(f"发送邮件给 {email}: {content}")

class EmailRequest(BaseModel):
    email: str
    message: str

@app.post("/send-email/")
def send_email_task(payload: EmailRequest, background_tasks: BackgroundTasks):
    background_tasks.add_task(send_email, payload.email, payload.message)
    return {"status": "邮件已加入发送队列"}

后台任务能让接口快速响应，把耗时逻辑放到后台执行，BackgroundTasks 异步执行任务。

三、最佳实践建议

路径参数 (Path)

• 用于标识资源 ID（如 /users/{user_id}）。
• 不要滥用路径参数存放可选参数。

查询参数 (Query)

• 适合做过滤、分页、搜索等可选条件。
• 参数较多时，最好定义一个 Pydantic 模型，避免函数参数过长。

请求体 (Body)

• 用于提交核心业务数据（新增/更新）。
• 复杂数据结构一定要定义 Pydantic 模型，保证可维护性。

Header / Cookie

• 一般用于认证信息（如 Token、Session ID）。
• 建议统一在依赖中解析，避免到处写重复逻辑。

Request / Response

• 只在需要访问上下文（如客户端 IP、自定义响应头）时使用。
• 不要把业务逻辑混进 Request 里，保持单一职责。

Depends (依赖注入)

• 强烈推荐用来管理数据库连接、权限校验、公共逻辑。
• 复杂依赖可以模块化，避免接口函数过于臃肿。

BackgroundTasks

• 适合轻量异步任务（日志、通知）。
• 耗时较长的任务应交给 Celery、RQ 等专业任务队列。

四、总结

FastAPI 的参数系统非常灵活：

• 数据类参数：Path、Query、Header、Cookie、Body (JSON / Form / File)
• 上下文参数：Request、Response、WebSocket、BackgroundTasks
• 依赖注入参数：Depends（数据库、权限、逻辑复用）

在实际项目中：

• 分页搜索接口 → Query
• 编辑资源接口 → Path + Body
• 用户接口 → Header + Cookie + Depends
• 任务接口 → Body + BackgroundTasks

总的建议是：用 Path 定位资源，用 Query 过滤数据，用 Body 提交业务信息，用 Depends 抽取公共逻辑，用 BackgroundTasks 处理耗时操作。

掌握这些套路后，你就能写出既简洁又健壮的 API。

长篇技术文章编写不易，如果您想了解更多关于Python Web框架FastAPI的知识，可以点点赞和关注，后续将继续分享。

#编程# #Python# #后端开发# #Web系统开发# #敏捷开发# #restful api#