在 FastAPI 开发中，路径参数、查询参数、请求体参数是处理客户端数据的三种核心方式，它们分别对应 HTTP 请求的不同位置，分工明确、各司其职。本文将从定义、语法、使用场景和实战示例出发，系统性拆解这三种参数，帮你彻底搞懂它们的区别与用法。

一、路径参数

1.定义

路径参数是直接嵌入在 URL 路径中的变量，用于标识资源的唯一标识，比如 /users/{user_id} 中的 user_id。

它的核心特点是：必须存在于 URL 中，是路由匹配的一部分，常用于定位单个资源（如查询指定 ID 的用户、商品）。

2.语法

FastAPI 会自动解析路径参数，并根据你声明的类型进行校验和转换，同时生成交互式文档。

2.1原生类型注解

语法格式：参数名: 基础类型；
仅使用 Python 内置类型：int、str、float、bool；
作用：告诉 FastAPI 这个参数是什么类型，自动做类型转换与校验。

代码示例

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/{user_id}")
async def read_user(user_id: int):
    return {"user_id": user_id}

2.2额外类型注解

语法格式：参数名: 类型 = Path(…)；
Path() ：专门用于路径参数的额外校验；
常用规则：gt(大于)、ge(大于等于)、lt(小于)、le(小于等于)、title、description。

代码示例

from fastapi import FastAPI, Path

app = FastAPI()

@app.get("/users/{user_id}")
async def read_user(
    user_id: int = Path(..., ge=1, description="用户ID必须大于等于1")
):
    return {"user_id": user_id}

3.适用场景

获取 / 修改 / 删除单个指定资源（如 /products/{product_id} 查询单个商品）。
资源的唯一标识必须在 URL 中体现（RESTful 风格的标准设计）。

二、查询参数

1. 核心定义

查询参数是附加在 URL 末尾的键值对，格式为
?key1=value1&key2=value2，比如 /items?limit=10&skip=0 中的 limit 和 skip。它的核心特点是：不影响路由匹配，是可选的筛选 / 分页参数，常用于过滤、分页、排序等场景。

2.语法

2.1原生类型注解

语法格式：参数名: 基础类型；
仅使用 ：int、str、float、bool；
作用：声明参数类型，FastAPI 自动解析并校验类型。

代码示例

from fastapi import FastAPI

app = FastAPI()

@app.get("/items")
async def read_items(skip: int, limit: int):
    return {"skip": skip, "limit": limit}

2.2额外类型注解

语法格式：参数名: 类型 = Query(…)
Query() ：专门用于查询参数的额外校验
常用规则：default(默认值)、min_length、max_length、ge、le。

代码示例

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items")
async def read_items(
    skip: int = Query(0, ge=0),
    limit: int = Query(10, ge=1, le=50)
):
    return {"skip": skip, "limit": limit}

3.适用场景

列表资源的分页、排序、筛选（如 /products?page=2&size=20）。
非核心、可选的请求条件（如搜索关键词、过滤条件）。

三、请求体参数

1. 核心定义

请求体参数是客户端通过 HTTP 请求体发送的数据，通常用于 POST、PUT、PATCH 等请求方法，格式多为 JSON。它的核心特点是：数据不在 URL 中传输，适合传递复杂、大量或敏感数据，常用于创建 / 修改资源。

2.语法

2.1原生类型注解

在 Pydantic 模型中使用：字段名: 基础类型；
仅使用 int、str、float、bool；
作用：定义 JSON 字段的类型，自动校验。

代码示例

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

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

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

2.2额外类型注解

语法格式：字段名: 类型 = Field(…)；
Field() ：专门用于模型字段的额外校验；
常用规则：gt、ge、min_length、max_length、default。

代码示例

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()

class Item(BaseModel):
    name: str = Field(..., min_length=2, max_length=50)
    price: float = Field(..., gt=0)

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

3.适用场景

创建 / 修改资源（如用户注册、商品新增，需要传递大量字段）。
传递复杂结构化数据（嵌套对象、列表等）。

四、语法总结

1.原生类型注解语法

统一格式：

参数名: 基础类型

常用基础类型：int、str、float、bool

2.额外类型注解语法

路径参数：参数名: 类型 = Path(…)
查询参数：参数名: 类型 = Query(…)
请求体字段：字段名: 类型 = Field(…)