FastAPI 三大核心参数实战：路径、查询与请求体详解在 FastAPI 开发中，参数的正确使用是接口高效、规范的关键

在 FastAPI 开发中，参数的正确使用是接口高效、规范的关键。FastAPI 内置了对路径参数、查询参数和请求体参数的完美支持，无需额外配置就能实现参数校验、类型转换和接口文档自动生成，极大提升开发效率。本文将聚焦这三类核心参数，通过可直接运行的代码示例，讲解其用法和校验规则，帮助开发者快速掌握接口参数的核心技巧。

一、路径参数：定位唯一资源的核心

路径参数是 URL 路径的组成部分，格式为 /资源名称/{参数名}，其核心作用是精准定位唯一的特定资源，通常用于查询单个资源详情，仅支持 GET 请求方法。

基础用法：简单参数定义

只需在路由路径中声明参数，配合 Python 原生类型注解，FastAPI 就能自动完成参数类型校验和转换，无需手动处理。

from fastapi import FastAPI

# 初始化FastAPI应用
app = FastAPI()

# 以用户id为路径参数，查询单个用户信息
@app.get("/user/{id}")
async def get_single_user(id: int):
    # 响应结果包含用户id和按规则生成的用户名
    return {"id": id, "name": f"普通用户{id}"}

启动应用后，访问 /user/456，会直接返回 {"id":456,"name":"普通用户456"}；若传入非整数（如 /user/abc），FastAPI 会自动返回类型错误提示，无需额外编写校验逻辑。

高级用法：Path 注解实现参数校验

当需要对路径参数进行更精细的限制（如数值范围、字符串长度）时，可使用 FastAPI 提供的 Path 函数，通过参数传递校验规则，让接口更健壮。

from fastapi import FastAPI, Path

app = FastAPI()

# 接口1：员工部门id查询，id范围1~20（必填）
@app.get("/employee/department/{dept_id}")
async def get_employee_department(
    dept_id: int = Path(..., gt=0, lt=21, description="员工部门ID，仅支持1-20之间的整数")
):
    return {"department_id": dept_id, "department_name": f"部门{dept_id}"}

# 接口2：员工姓名查询，姓名长度2~6（必填）
@app.get("/employee/name/{emp_name}")
async def get_employee_name(
    emp_name: str = Path(..., min_length=2, max_length=6, description="员工姓名，长度2-6个字符")
):
    return {"employee_name": emp_name, "department": "未分配"}

上述代码中，... 表示参数为必填项，gt/lt 用于限制整数范围，min_length/max_length 用于限制字符串长度，description 用于添加参数说明，方便生成接口文档。

二、查询参数：筛选资源集合的工具

查询参数位于 URL 的 ? 之后，格式为 参数1=值1&参数2=值2，核心作用是对资源集合进行过滤、分页、排序等操作，同样仅支持 GET 请求方法。

基础用法：默认参数与可选参数

查询参数无需在路由路径中声明，直接在接口函数中定义即可，可通过赋值设置默认值，未赋值则为必填参数。

from fastapi import FastAPI

app = FastAPI()

# 基础用法：默认参数与可选参数结合
@app.get("/course/list")
async def get_course_list(
    # 默认值为"初级"，可选参数，用于筛选课程等级
    level: str = "初级",
    # 无默认值，必填参数，用于筛选课程所属专业
    major: str
):
    return {
        "filter_condition": {"level": level, "major": major},
        "course_list": []
    }

访问示例：/course/list?major=计算机，接口会使用默认的 level 值（初级）进行筛选；若不传入 major 参数，会提示参数缺失。

高级用法：Query 注解实现精准校验

与 Path 注解用法类似，Query 函数用于对查询参数进行校验，支持默认值、数值范围、长度限制等规则，适用于复杂的资源筛选场景。

from fastapi import FastAPI, Query

app = FastAPI()

# 商品查询接口，携带分类和库存两个查询参数
@app.get("/goods/query")
async def query_goods_list(
    # 商品分类：默认值为电子产品，长度5~20个字符
    goods_type: str = Query("电子产品", min_length=5, max_length=20, description="商品分类"),
    # 商品库存：必填，范围1~1000
    stock: int = Query(..., gt=0, lt=1001, description="商品库存，1-1000之间")
):
    return {
        "query_condition": {
            "goods_type": goods_type,
            "stock": stock
        },
        "result": []
    }

访问示例：/goods/query?goods_type=智能设备&stock=500，接口会根据传入的查询参数返回对应筛选结果；若库存超出1~1000的范围，会自动返回校验失败提示。

三、请求体参数：创建/更新资源的载体

请求体参数位于 HTTP 请求的消息体（body）中，主要用于传输大量数据（如 JSON 格式），核心作用是创建、更新资源，支持 POST、PUT 等请求方法。FastAPI 结合 Pydantic 模块，可快速定义请求体参数并实现校验。

基础用法：BaseModel 定义请求体结构

通过继承 Pydantic 的 BaseModel 类，可定义请求体的结构和字段类型，FastAPI 会自动解析请求体数据，并进行类型校验。

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

# 定义商品请求体模型
class GoodsCreate(BaseModel):
    # 商品名称：字符串类型
    name: str
    # 商品价格：浮点型
    price: float
    # 商品库存：整数类型
    stock: int

# 新增商品接口，接收请求体参数
@app.post("/goods/add")
async def add_new_goods(goods: GoodsCreate):
    goods_info = goods.dict()
    goods_info["goods_id"] = 1001  # 模拟生成唯一商品ID
    return {
        "msg": "商品新增成功",
        "goods_info": goods_info
    }

调用该接口时，需在请求体中传入 JSON 格式数据（如 {"name":"无线耳机","price":199.9,"stock":200}），FastAPI 会自动校验字段类型，校验通过后返回成功信息。

高级用法：Field 注解完善参数校验

Field 函数用于对请求体中的单个字段进行校验，支持必填项、长度限制、数值范围等规则，与 Path、Query 注解的用法保持一致，让请求体参数更规范。

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()

# 定义员工请求体模型
class EmployeeCreate(BaseModel):
    # 员工姓名：必填，长度2~6个字符
    name: str = Field(..., min_length=2, max_length=6, description="员工姓名，不能为空")
    # 员工年龄：必填，范围18~60
    age: int = Field(..., ge=18, le=60, description="员工年龄，18-60之间")
    # 员工岗位：默认值为职员
    position: str = Field("职员", description="员工岗位，默认值为职员")
    # 月薪：必填，大于3000元
    salary: float = Field(..., gt=3000, description="员工月薪，必须大于3000元")

# 新增员工接口，接收请求体参数
@app.post("/employee/add")
async def add_new_employee(employee: EmployeeCreate):
    # 将请求体数据转换为字典，模拟数据入库操作
    emp_info = employee.dict()
    emp_info["emp_id"] = 5001  # 模拟生成唯一员工ID
    return {
        "msg": "员工新增成功",
        "employee_info": emp_info
    }

调用该接口时，需在请求体中传入 JSON 格式数据（如 {"name":"张三","age":25,"salary":5000}），FastAPI 会自动校验所有字段规则，校验通过后返回成功信息。

四、HTTP 请求结构与参数对应关系

一个完整的 HTTP 请求由三部分组成，三类核心参数分别对应不同的请求部分，明确其对应关系能更好地理解参数用法：

请求行：包含请求方法、URL、协议版本，路径参数和查询参数均包含在 URL 中；
请求头：存储 Content-Type、Authorization 等元数据，用于描述请求的附加信息；
请求体：存储请求体参数，用于传输创建、更新资源所需的核心业务数据。

总结

FastAPI 的三类核心参数各有其适用场景，精准使用能让接口开发更高效、规范：

路径参数：用于定位唯一资源，通过 Path 注解实现校验，拼接在 URL 路径中；
查询参数：用于筛选资源集合，通过 Query 注解实现校验，位于 URL 的 ? 之后；
请求体参数：用于创建、更新资源，通过 BaseModel+Field 定义，存储在请求体中。

掌握这三类参数的基础用法和校验规则，就能完成 FastAPI 基础接口的开发，让接口具备自动校验、自动生成文档的能力，提升开发效率和接口健壮性。