FastAPI传参类型

关注

原创 2026-01-19 23:33:16 678 阅读 AI 写同款· GEO 优化 ›

Power Automate实战：用SharePoint REST API批量处理列表数据（附JSON解析技巧）本文深入探讨了如何利用Power Automate调用SharePoint REST API实现列表数据的批量自动化处理。文章详细解析了API的协同工作原理、高效的数据获取与筛选技巧，并重点分享了JSON数据解析的核心难点与实战解决方案，旨在帮助企业用户构建稳定可靠的数据处理流程，提升运营效率。阅读详情

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

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

1. 路径参数（Path Parameters）

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

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）；
适用场景：分页、筛选、排序、搜索等（如页码、每页条数、搜索关键词）；
自动特性：支持默认值、可选参数、数值校验（如最小值/最大值）。

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 校验规则，支持嵌套模型。

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）。

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}

5. Cookie 参数（Cookie Parameters）

核心作用：从 HTTP 请求的 Cookie 中提取参数；
适用场景：读取客户端存储的 Cookie（如会话ID、用户标识）。

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）。

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。

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 会自动识别：

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
    }

总结

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

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)