FastAPI传参类型

越甲八千2026-01-20 11:21

FastAPI 作为现代化的 Python Web 框架，提供了7种核心的参数传递方式，覆盖了 HTTP 请求的所有常见场景，且每种方式都有明确的使用场景和自动校验能力。

核心参数传递方式（按使用频率排序）

1. 路径参数（Path Parameters）
  • 核心作用 ：从 URL 路径中提取参数（比如 /users/123 中的 123）；
  • 适用场景：标识资源的唯一ID、分类、版本等（如用户ID、商品ID）；
  • 自动特性：支持类型注解（int/str/enum），自动校验类型，不匹配则返回 422 错误。
python 复制代码 
from fastapi import FastAPI

app = FastAPI()

# 路径参数：user_id 是路径中的参数
@app.get("/users/{user_id}")
def get_user(user_id: int):  # 限定为int类型，传字符串会报错
    return {"user_id": user_id, "message": "获取用户信息"}

# 枚举类型的路径参数（限定可选值）
from enum import Enum
class ItemType(str, Enum):
    book = "book"
    electronic = "electronic"

@app.get("/items/{item_type}")
def get_items(item_type: ItemType):
    return {"item_type": item_type}
2. 查询参数（Query Parameters）
  • 核心作用 ：从 URL 后的 ?key=value 中提取参数（比如 /items?page=1&size=10）；
  • 适用场景：分页、筛选、排序、搜索等（如页码、每页条数、搜索关键词）；
  • 自动特性：支持默认值、可选参数、数值校验（如最小值/最大值）。
python 复制代码 
from fastapi import FastAPI, Query

app = FastAPI()

# 查询参数：page和size是查询参数，有默认值
@app.get("/items/")
def get_items(
    page: int = 1,  # 默认值1，可选参数
    size: int = Query(10, ge=1, le=100)  # 限定size≥1且≤100
):
    return {"page": page, "size": size}

# 可选的查询参数（None表示可选）
@app.get("/search/")
def search(keyword: str | None = None):
    if keyword:
        return {"message": f"搜索关键词：{keyword}"}
    return {"message": "无搜索关键词"}
3. 请求体（Request Body）
  • 核心作用：从 HTTP 请求体中获取数据（POST/PUT/PATCH 请求的核心参数）；
  • 适用场景：提交/修改资源（如创建用户、提交表单、上传JSON数据）；
  • 自动特性：基于 Pydantic 模型校验数据，自动生成 JSON 校验规则，支持嵌套模型。
python 复制代码 
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

# 定义请求体模型（Pydantic）
class User(BaseModel):
    name: str
    age: int
    email: str | None = None  # 可选字段

# POST请求的请求体参数
@app.post("/users/")
def create_user(user: User):  # user 是请求体数据，自动解析JSON
    return {"message": "创建用户成功", "user": user}

# 多个请求体参数（自动合并为一个JSON）
@app.put("/users/{user_id}")
def update_user(user_id: int, user: User, is_active: bool = True):
    return {"user_id": user_id, "user": user, "is_active": is_active}
4. 请求头参数（Header Parameters）
  • 核心作用 ：从 HTTP 请求头中提取参数（如 Token、Content-Type）；
  • 适用场景：身份认证、传递非业务的元数据（如令牌、设备类型、语言）；
  • 注意点 ：请求头名称自动忽略大小写，下划线 _ 会转为 -（如 user_agent 对应 User-Agent）。
python 复制代码 
from fastapi import FastAPI, Header

app = FastAPI()

# 请求头参数：token和user_agent是请求头中的参数
@app.get("/auth/")
def auth(
    token: str = Header(...),  # ... 表示必填参数
    user_agent: str | None = Header(None)  # 可选的User-Agent
):
    return {"token": token, "user_agent": user_agent}
  • 核心作用：从 HTTP 请求的 Cookie 中提取参数；
  • 适用场景：读取客户端存储的 Cookie（如会话ID、用户标识）。
python 复制代码 
from fastapi import FastAPI, Cookie

app = FastAPI()

# Cookie参数：session_id 是Cookie中的参数
@app.get("/session/")
def get_session(session_id: str | None = Cookie(None)):
    if session_id:
        return {"session_id": session_id}
    return {"message": "未检测到会话ID"}
6. 表单参数（Form Parameters）
  • 核心作用 ：从 application/x-www-form-urlencoded 格式的表单中提取参数；
  • 适用场景：传统表单提交（如登录、注册的账号密码）；
  • 前置依赖 ：需要安装 python-multipart（pip install python-multipart）。
python 复制代码 
from fastapi import FastAPI, Form

app = FastAPI()

# 表单参数：username和password是表单字段
@app.post("/login/")
def login(
    username: str = Form(...),  # 必填表单字段
    password: str = Form(...)
):
    return {"message": f"登录成功，用户名：{username}"}
7. 文件上传（File Parameters）
  • 核心作用：接收客户端上传的文件（单文件/多文件）；
  • 适用场景：图片、文档、视频等文件上传；
  • 前置依赖 ：同样需要 python-multipart。
python 复制代码 
from fastapi import FastAPI, File, UploadFile

app = FastAPI()

# 单文件上传：file 是上传的文件
@app.post("/upload/")
def upload_file(file: UploadFile = File(...)):  # UploadFile比File更易用（支持文件名/内容类型）
    return {
        "filename": file.filename,
        "content_type": file.content_type,
        "message": "文件上传成功"
    }

# 多文件上传
@app.post("/upload-multiple/")
def upload_multiple_files(files: list[UploadFile] = File(...)):
    return {"filenames": [file.filename for file in files]}

进阶：混合参数传递

实际开发中，常混合使用多种参数方式，FastAPI 会自动识别：

python 复制代码 
from fastapi import FastAPI, Query, Header
from pydantic import BaseModel

app = FastAPI()

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

# 混合：路径参数 + 查询参数 + 请求头 + 请求体
@app.put("/items/{item_id}")
def update_item(
    item_id: int,  # 路径参数
    is_urgent: bool = Query(False),  # 查询参数
    token: str = Header(...),  # 请求头参数
    item: Item  # 请求体参数
):
    return {
        "item_id": item_id,
        "is_urgent": is_urgent,
        "token": token,
        "item": item
    }

总结

  1. 核心参数方式：路径参数（URL路径）、查询参数（URL后缀）、请求体（POST/PUT数据）是最常用的3种，覆盖80%以上场景；
  2. 辅助参数方式：请求头、Cookie（身份认证）、表单、文件上传（特殊场景）；
  3. 核心优势 ：所有参数都支持类型注解+自动校验，不合法参数自动返回422错误，且自动生成OpenAPI文档（访问 /docs 可查看）。
cpp 复制代码 
from fastapi import FastAPI, Query,Path
from pydantic import BaseModel, Field
import uvicorn

# 初始化FastAPI应用
app = FastAPI(
    title="参数传递示例",
    description="演示路径参数、查询参数、请求体参数的使用",
    version="1.0.0"
)

# ==================== 1. 路径参数（Path Parameters） ====================
# 场景1：基础路径参数（提取URL路径中的唯一标识）
# 接口：/users/{user_id} → 提取user_id作为参数
@app.get("/users/{user_id}", summary="获取单个用户信息")
def get_user(
    user_id: int  # 类型注解：限定为int，FastAPI会自动校验
):
    """
    路径参数详解：
    - user_id: 从URL路径 /users/123 中提取的用户ID，限定为整数
    - 如果传入非整数（如 /users/abc），FastAPI会自动返回422错误（参数校验失败）
    """
    return {
        "code": 200,
        "msg": "success",
        "data": {"user_id": user_id, "username": f"user_{user_id}"}
    }

# 场景2：带校验的路径参数（枚举值限定）
# 先定义枚举类，限定路径参数的可选值
from enum import Enum
class ItemCategory(str, Enum):
    ELECTRONIC = "electronic"  # 电子产品
    BOOK = "book"              # 图书
    CLOTHING = "clothing"      # 服装

@app.get("/items/{category}/{item_id}", summary="按分类和ID获取商品")
def get_item(
    category: ItemCategory,  # 限定为枚举值，只能传 electronic/book/clothing
    item_id: int = Path(..., ge=1, le=1000)  # 进阶：Path类增强校验（ge=≥1，le=≤1000）
):
    """
    进阶路径参数：
    - category: 枚举类型，只能传指定的3个值，否则返回422
    - item_id: 用Path类增强校验，限定1≤item_id≤1000
    """
    return {
        "code": 200,
        "msg": "success",
        "data": {"category": category, "item_id": item_id}
    }

# ==================== 2. 查询参数（Query Parameters） ====================
# 场景1：基础查询参数（URL后缀 ?key=value）
# 接口：/products/ → 支持 ?page=1&size=10&keyword=手机
@app.get("/products/", summary="分页查询商品列表")
def get_products(
    page: int = Query(1, ge=1),  # 默认值1，校验：≥1
    size: int = Query(10, ge=1, le=50),  # 默认值10，校验：1≤size≤50
    keyword: str | None = None  # 可选参数，默认None
):
    """
    查询参数详解：
    - page: 页码，默认1，必须≥1
    - size: 每页条数，默认10，1≤size≤50
    - keyword: 搜索关键词，可选（不传则返回全部）
    - Query类用于增强校验：默认值、范围、描述等
    """
    # 模拟返回数据
    data = {
        "page": page,
        "size": size,
        "keyword": keyword,
        "items": [{"id": i, "name": f"商品{i}"} for i in range((page-1)*size+1, page*size+1)]
    }
    return {"code": 200, "msg": "success", "data": data}

# ==================== 3. 请求体参数（Request Body） ====================
# 第一步：定义Pydantic模型（请求体的结构和校验规则）
class UserCreate(BaseModel):
    """创建用户的请求体模型"""
    username: str = Field(..., min_length=3, max_length=20, description="用户名，3-20个字符")
    email: str = Field(..., pattern=r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$", description="邮箱格式")
    age: int = Field(None, ge=18, le=100, description="年龄，18-100岁，可选")
    is_vip: bool = Field(False, description="是否VIP，默认False")

# 场景1：基础请求体（POST请求的核心数据）
# 接口：/users/ → POST请求，请求体为JSON格式
@app.post("/users/", summary="创建新用户")
def create_user(
    user: UserCreate  # 自动解析请求体的JSON为UserCreate对象，并校验
):
    """
    请求体参数详解：
    - user: 接收POST请求体的JSON数据，自动映射到UserCreate模型
    - Pydantic会自动校验：用户名长度、邮箱格式、年龄范围等
    - 校验失败则返回422错误，包含具体的错误信息
    """
    # 模拟创建用户（实际项目中可写入数据库）
    return {
        "code": 200,
        "msg": "用户创建成功",
        "data": {
            "username": user.username,
            "email": user.email,
            "age": user.age,
            "is_vip": user.is_vip
        }
    }

# 场景2：混合参数（路径+查询+请求体）
@app.put("/users/{user_id}/update", summary="更新用户信息（混合参数）")
def update_user(
    user_id: int,  # 路径参数
        user: UserCreate,  # 请求体参数
    is_admin: bool = Query(False),  # 查询参数

):
    """
    混合参数示例：
    - 路径参数：user_id（用户ID）
    - 查询参数：is_admin（是否管理员操作）
    - 请求体参数：user（更新的用户信息）
    FastAPI会自动区分不同类型的参数，无需额外配置
    """
    return {
        "code": 200,
        "msg": "用户更新成功",
        "data": {
            "user_id": user_id,
            "is_admin": is_admin,
            "user_info": user.dict()
        }
    }

# 启动服务（直接运行该文件时生效）
if __name__ == "__main__":
    # 启动uvicorn服务器：host=0.0.0.0（允许外部访问），port=8000，reload=True（热重载）
    uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)
相关推荐
南山乐只1 小时前
Java并发原生工具：原子类 (Atomic Classes)
java·开发语言·后端
惜.己1 小时前
单个图片转化工具分享（源码+工具）
python
一颗青果1 小时前
C++下的atomic | atmoic_flag | 内存顺序
java·开发语言·c++
大数据002 小时前
基于Ollama大模型学习
python·flask·大模型·alibaba·ollama·springai·deepseek
YHLG2 小时前
LangChain v1.0+ 入门详解：概念、架构、组件、模板与实战
python·langchain
Sylvia-girl2 小时前
Java之异常
java·开发语言
pen-ai2 小时前
PyTorch 张量维度处理详解
人工智能·pytorch·python
郝学胜-神的一滴2 小时前
Python对象的自省机制：深入探索对象的内心世界
开发语言·python·程序人生·算法
tjjucheng2 小时前
小程序定制开发哪家有数据支持
python
热门推荐
01GitHub 镜像站点022025 Telegram 最新免费社工库机器人（LetsTG可[特殊字符]）搭建指南（含 Python 脚本）03OpenCode 入门教程：介绍 · 安装 · 配置第三方 API (如 Claude)04Linux下V2Ray安装配置指南05安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）06UV安装并设置国内源07Claude Code Skills 实用使用手册08AI 规范驱动开发“三剑客”深度对比：Spec-Kit、Kiro 与 OpenSpec 实战指南09BongoCat - 跨平台键盘猫动画工具10网站改了域名，如何查找？