FastAPI 请求参数完全攻略：从默认解析到深度定制 —— 详解 Path、Query、Form 等 8 种常用参数函数

玄同765

发布于 2026-01-14 14:15:14

600

【个人主页：】

大语言模型（LLM）开发工程师｜中国传媒大学·数字媒体技术（智能交互与游戏设计） 深耕领域：大语言模型开发 / RAG知识库 / AI Agent落地 / 模型微调 技术栈：Python / LangChain/RAG（Dify+Redis+Milvus）| SQL/NumPy | FastAPI+Docker ️ 工程能力：专注模型工程化部署、知识库构建与优化，擅长全流程解决方案 专栏传送门：LLM大模型开发项目实战指南、Python 从真零基础到纯文本 LLM 全栈实战、从零学 SQL + 大模型应用落地、大模型开发小白专属：从 0 入门 Linux&Shell 「让AI交互更智能，让技术落地更高效」 欢迎技术探讨/项目合作！关注我，解锁大模型与智能交互的无限可能！

摘要

你是不是用 FastAPI 写接口时只会用基础类型注解，遇到必填参数、默认值、长度范围、正则表达式、依赖注入这些需求就犯愁？这篇详解 Path、Query、Form、Body、Cookie、Header、File、Depends 等 8 种常用参数函数，配合代码示例和对比表格，帮你彻底搞懂 FastAPI 请求参数的解析和验证逻辑。

一、引言：为什么要学参数函数？

在 FastAPI 的入门阶段，很多开发者会用基础类型注解（如int、str、list[int]）来解析请求参数，FastAPI 会自动处理参数验证、类型转换、文档生成等工作。但随着项目的复杂程度提高，基础类型注解无法满足以下需求：

参数定制化验证：如要求用户名长度在 3-20 个字符之间，密码必须包含大小写字母和数字；
参数元数据设置：如设置参数的标题、描述、示例值；
参数位置指定：如明确区分路径参数、查询参数、请求体参数、Cookie 参数、Header 参数；
依赖注入：如获取当前用户信息、数据库会话。

这时候，我们需要使用 FastAPI 的参数函数（如 Path、Query、Form 等）来满足这些需求。

二、基础类型注解回顾

在详解参数函数之前，我们先回顾一下 FastAPI 的基础类型注解。

2.1 路径参数

路径参数是 URL 路径中的可变部分，用于定位资源。在 FastAPI 中，路径参数通过在 URL 路径中使用{}包裹变量名，并在函数参数中使用同名变量和类型注解来解析。

代码示例（学生管理系统）：

from fastapi import FastAPI

app = FastAPI(title="学生管理系统", version="1.0.0", description="一个基于FastAPI的学生管理系统")

@app.get("/students/{student_id}")
def get_student_info(student_id: int):
    """获取单个学生信息"""
    return {"student_id": student_id, "name": "张三", "gender": "男"}

测试：打开浏览器，访问 http://127.0.0.1:8000/docs，点击/students/{student_id}接口旁边的Try it out按钮，输入101，点击Execute，返回以下 JSON 响应：

{"student_id": 101, "name": "张三", "gender": "男"}

2.2 查询参数

查询参数是 URL 查询字符串中的可变部分，用于过滤、排序、分页资源。在 FastAPI 中，查询参数通过在函数参数中使用类型注解和默认值来解析。

代码示例（学生管理系统）：

@app.get("/students")
def get_students_info(page: int = 1, page_size: int = 10, name: str = None):
    """获取学生列表"""
    return {
        "page": page,
        "page_size": page_size,
        "name": name,
        "data": [
            {"student_id": 101, "name": "张三", "gender": "男"},
            {"student_id": 102, "name": "李四", "gender": "女"}
        ]
    }

测试：打开浏览器，访问 http://127.0.0.1:8000/docs，点击/students接口旁边的Try it out按钮，输入page=1、page_size=2、name=张，点击Execute，返回以下 JSON 响应：

{"page":1,"page_size":2,"name":"张","data":[{"student_id":101,"name":"张三","gender":"男"}]}

2.3 请求体

请求体是 HTTP 请求 Body 中的数据，用于提交、更新资源。在 FastAPI 中，请求体通过在函数参数中使用 Pydantic 数据验证模型来解析。

代码示例（学生管理系统）：

from pydantic import BaseModel, EmailStr, Field

class StudentCreate(BaseModel):
    student_no: str = Field(..., min_length=8, max_length=20, pattern=r"^[a-zA-Z0-9]+$")
    name: str = Field(..., min_length=2, max_length=50)
    gender: str = Field(..., pattern=r"^男|女$")
    birthdate: str = Field(None, pattern=r"^\d{4}-\d{2}-\d{2}$")
    phone: str = Field(None, pattern=r"^1[3-9]\d{9}$")
    email: EmailStr = None
    address: str = Field(None, max_length=200)

@app.post("/students")
def create_student_info(student: StudentCreate):
    """创建学生信息"""
    return {"message": "学生信息创建成功", "data": student}

测试：打开浏览器，访问 http://127.0.0.1:8000/docs，点击/students接口旁边的Try it out按钮，输入以下 JSON 数据：

{
  "student_no": "20250001",
  "name": "张三",
  "gender": "男",
  "birthdate": "2005-01-01",
  "phone": "13800138001",
  "email": "zhangsan@example.com",
  "address": "北京市海淀区"
}

点击Execute，返回以下 JSON 响应：

{"message":"学生信息创建成功","data":{"student_no":"20250001","name":"张三","gender":"男","birthdate":"2005-01-01","phone":"13800138001","email":"zhangsan@example.com","address":"北京市海淀区"}}

三、fastapi.param_functions.py 中的常用参数函数

fastapi.param_functions.py 是 FastAPI 的参数解析和验证模块，包含了多种常用参数函数。

3.1 Path 函数：路径参数定制化

Path 函数用于对路径参数进行定制化验证和元数据设置。

语法：

from fastapi import Path

def function_name(parameter_name: Type = Path(default, ..., **kwargs)):
    ...

常用参数：

参数名	类型	功能
default	Type	参数的默认值，必填参数需要设置为...
min_length	int	字符串类型参数的最小长度
max_length	int	字符串类型参数的最大长度
pattern	str	字符串类型参数的正则表达式
ge	int/float	数值类型参数的最小值（大于等于）
le	int/float	数值类型参数的最大值（小于等于）
gt	int/float	数值类型参数的最小值（大于）
lt	int/float	数值类型参数的最大值（小于）
title	str	参数的标题
description	str	参数的描述
example	Any	参数的示例值
deprecated	bool	参数是否已过时

代码示例（学生管理系统）：

@app.get("/students/{student_id}")
def get_student_info(
    student_id: int = Path(
        ...,
        title="学生ID",
        description="学生的唯一标识符",
        ge=101,
        le=999999999,
        example=101
    )
):
    """获取单个学生信息"""
    return {"student_id": student_id, "name": "张三", "gender": "男"}

测试：打开浏览器，访问 http://127.0.0.1:8000/docs，点击/students/{student_id}接口旁边的Try it out按钮，输入100，点击Execute，返回以下 JSON 响应：

{"detail":[{"loc":["path","student_id"],"msg":"Input should be greater than or equal to 101","type":"value_error.number.not_ge","ctx":{"limit_value":101}}]}

3.2 Query 函数：查询参数定制化

Query 函数用于对查询参数进行定制化验证和元数据设置。

语法：

from fastapi import Query

def function_name(parameter_name: Type = Query(default, ..., **kwargs)):
    ...

常用参数：与 Path 函数相同。

代码示例（学生管理系统）：

@app.get("/students")
def get_students_info(
    page: int = Query(
        1,
        title="当前页码",
        description="学生列表的当前页码",
        ge=1,
        le=1000,
        example=1
    ),
    page_size: int = Query(
        10,
        title="每页显示的数量",
        description="学生列表每页显示的数量",
        ge=1,
        le=100,
        example=10
    ),
    name: str = Query(
        None,
        title="学生姓名",
        description="学生姓名的模糊查询",
        min_length=2,
        max_length=50,
        example="张"
    )
):
    """获取学生列表"""
    return {
        "page": page,
        "page_size": page_size,
        "name": name,
        "data": [
            {"student_id": 101, "name": "张三", "gender": "男"},
            {"student_id": 102, "name": "李四", "gender": "女"}
        ]
    }

测试：打开浏览器，访问 http://127.0.0.1:8000/docs，点击/students接口旁边的Try it out按钮，输入page=1、page_size=101、name=张，点击Execute，返回以下 JSON 响应：

{"detail":[{"loc":["query","page_size"],"msg":"Input should be less than or equal to 100","type":"value_error.number.not_le","ctx":{"limit_value":100}}]}

3.3 Form 函数：表单参数解析

Form 函数用于解析 HTTP 请求 Body 中的表单数据。在使用 Form 函数之前，需要安装python-multipart依赖库：

pip install python-multipart

语法：

from fastapi import Form

def function_name(parameter_name: Type = Form(default, ..., **kwargs)):
    ...

常用参数：与 Path 函数相同。

代码示例（学生管理系统）：

@app.post("/login")
def login(
    username: str = Form(
        ...,
        title="用户名",
        description="用户的登录用户名",
        min_length=3,
        max_length=20,
        pattern=r"^[a-zA-Z0-9_]+$",
        example="testuser"
    ),
    password: str = Form(
        ...,
        title="密码",
        description="用户的登录密码",
        min_length=8,
        max_length=20,
        pattern=r"^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).*$",
        example="Test1234"
    )
):
    """用户登录"""
    return {"message": "用户登录成功", "username": username}

测试：打开浏览器，访问 http://127.0.0.1:8000/docs，点击/login接口旁边的Try it out按钮，输入username=testuser、password=Test1234，点击Execute，返回以下 JSON 响应：

{"message":"用户登录成功","username":"testuser"}

3.4 Body 函数：请求体定制化

Body 函数用于对 Pydantic 数据验证模型进行定制化，或者直接解析 HTTP 请求 Body 中的原始数据。

语法：

from fastapi import Body

def function_name(parameter_name: Type = Body(default, ..., **kwargs)):
    ...

常用参数：

参数名	类型	功能
default	Type	参数的默认值，必填参数需要设置为...
embed	bool	是否将参数嵌入到一个字段中，默认值为 False
title	str	参数的标题
description	str	参数的描述
example	Any	参数的示例值

代码示例（学生管理系统）：

@app.post("/students")
def create_student_info(
    student: StudentCreate = Body(
        ...,
        embed=True,
        title="学生信息",
        description="要创建的学生信息",
        example={
            "student": {
                "student_no": "20250001",
                "name": "张三",
                "gender": "男",
                "birthdate": "2005-01-01",
                "phone": "13800138001",
                "email": "zhangsan@example.com",
                "address": "北京市海淀区"
            }
        }
    )
):
    """创建学生信息"""
    return {"message": "学生信息创建成功", "data": student}

测试：打开浏览器，访问 http://127.0.0.1:8000/docs，点击/students接口旁边的Try it out按钮，输入以下 JSON 数据：

{
  "student": {
    "student_no": "20250001",
    "name": "张三",
    "gender": "男",
    "birthdate": "2005-01-01",
    "phone": "13800138001",
    "email": "zhangsan@example.com",
    "address": "北京市海淀区"
  }
}

点击Execute，返回以下 JSON 响应：

{"message":"学生信息创建成功","data":{"student_no":"20250001","name":"张三","gender":"男","birthdate":"2005-01-01","phone":"13800138001","email":"zhangsan@example.com","address":"北京市海淀区"}}

3.5 Cookie 函数：Cookie 参数解析

Cookie 函数用于解析 HTTP 请求 Header 中的 Cookie 参数。

语法：

from fastapi import Cookie

def function_name(parameter_name: Type = Cookie(default, ..., **kwargs)):
    ...

常用参数：与 Path 函数相同。

代码示例（学生管理系统）：

@app.get("/profile")
def get_profile_info(
    session_id: str = Cookie(
        None,
        title="Session ID",
        description="用户的会话ID",
        example="abc123"
    )
):
    """获取用户的个人信息"""
    return {"session_id": session_id, "username": "testuser", "email": "testuser@example.com"}

测试：打开浏览器的开发者工具，切换到Network标签，访问 http://127.0.0.1:8000/profile，然后在Request Headers中添加Cookie: session_id=abc123，返回以下 JSON 响应：

{"session_id":"abc123","username":"testuser","email":"testuser@example.com"}

3.6 Header 函数：Header 参数解析

Header 函数用于解析 HTTP 请求 Header 中的参数。

语法：

from fastapi import Header

def function_name(parameter_name: Type = Header(default, ..., **kwargs)):
    ...

常用参数：与 Path 函数相同。

代码示例（学生管理系统）：

@app.get("/profile")
def get_profile_info(
    user_agent: str = Header(
        None,
        title="User Agent",
        description="用户的浏览器信息",
        example="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
    )
):
    """获取用户的个人信息"""
    return {"user_agent": user_agent, "username": "testuser", "email": "testuser@example.com"}

测试：打开浏览器的开发者工具，切换到Network标签，访问 http://127.0.0.1:8000/profile，然后在Request Headers中添加User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36，返回以下 JSON 响应：

{"user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36","username":"testuser","email":"testuser@example.com"}

3.7 File 函数：文件参数解析

File 函数用于解析 HTTP 请求 Body 中的文件参数。在使用 File 函数之前，需要安装python-multipart依赖库：

pip install python-multipart

语法：

from fastapi import File

def function_name(parameter_name: Type = File(default, ..., **kwargs)):
    ...

常用参数：与 Path 函数相同。

代码示例（学生管理系统）：

from fastapi.responses import FileResponse
import os

@app.post("/upload-avatar")
def upload_avatar(
    avatar: bytes = File(
        ...,
        title="头像文件",
        description="用户的头像文件，支持JPG、PNG格式，大小不超过2MB",
        example="avatar.jpg"
    )
):
    """上传用户的头像"""
    # 保存文件到本地
    with open("static/avatar.jpg", "wb") as f:
        f.write(avatar)
    return {"message": "头像上传成功"}

@app.get("/download-avatar")
def download_avatar():
    """下载用户的头像"""
    if not os.path.exists("static/avatar.jpg"):
        return {"message": "头像文件不存在"}
    return FileResponse("static/avatar.jpg")

测试：打开浏览器，访问 http://127.0.0.1:8000/docs，点击/upload-avatar接口旁边的Try it out按钮，选择一张 JPG 或 PNG 格式的图片，点击Execute，返回以下 JSON 响应：

{"message":"头像上传成功"}

3.8 Depends 函数：依赖注入

Depends 函数用于依赖注入，将函数的返回值作为参数注入到另一个函数中。

语法：

from fastapi import Depends

def dependency_function():
    ...
    return value

def function_name(parameter_name: Type = Depends(dependency_function)):
    ...

代码示例（学生管理系统）：

from sqlalchemy.orm import Session
from app.core.database import get_db

@app.get("/profile")
def get_profile_info(
    db: Session = Depends(get_db),
    user_agent: str = Header(
        None,
        title="User Agent",
        description="用户的浏览器信息"
    )
):
    """获取用户的个人信息"""
    return {"user_agent": user_agent, "username": "testuser", "email": "testuser@example.com"}

四、常见问题与解决方案

4.1 参数位置指定错误

问题：FastAPI 会根据参数的位置和类型自动解析请求参数，但有时会出现参数位置指定错误的问题。

解决方案：

对于路径参数，必须在 URL 路径中使用{}包裹变量名；
对于查询参数，必须在函数参数中使用默认值；
对于请求体参数，必须使用 Pydantic 数据验证模型；
对于表单参数，必须使用 Form 函数；
对于 Cookie 参数，必须使用 Cookie 函数；
对于 Header 参数，必须使用 Header 函数；
对于文件参数，必须使用 File 函数。

4.2 参数验证失败

问题：FastAPI 会自动验证请求参数，但有时会出现参数验证失败的问题。

解决方案：

检查参数的类型是否正确；
检查参数的验证规则是否符合要求；
检查参数的默认值是否正确；
检查参数的示例值是否符合要求。

4.3 依赖注入失败

问题：FastAPI 会自动解析依赖注入函数的返回值，但有时会出现依赖注入失败的问题。

解决方案：

检查依赖注入函数的返回值类型是否正确；
检查依赖注入函数是否有参数；
检查依赖注入函数的参数是否能够被解析；
检查依赖注入函数是否有异常。

五、总结与展望

5.1 总结

通过以上步骤，我们详解了 FastAPI 的 8 种常用参数函数，包括 Path、Query、Form、Body、Cookie、Header、File、Depends。这些参数函数可以满足我们对请求参数的各种需求，包括参数定制化验证、参数元数据设置、参数位置指定、依赖注入。

5.2 展望

未来，我们可以对 FastAPI 的参数解析和验证进行以下优化：

使用自定义验证规则：通过继承 Pydantic 的 BaseModel 类，实现自定义的验证规则；
使用类型守卫：通过使用 Type Guard 类型注解，实现运行时的类型检查；
使用依赖注入链：通过使用 Depends 函数，实现依赖注入链；
使用缓存依赖注入：通过使用缓存装饰器，实现依赖注入的缓存。

本文参与腾讯云自媒体同步曝光计划，分享自作者个人站点/博客。

原始发表：2026-01-11，如有侵权请联系 cloudcommunity@tencent.com 删除

form

本文分享自作者个人站点/博客前往查看

如有侵权，请联系 cloudcommunity@tencent.com 删除。

本文参与腾讯云自媒体同步曝光计划，欢迎热爱写作的你一起参与！

登录后参与评论

0 条评论

热度