FastAPI教程：深入理解路径操作与参数声明-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00518/article/details/148419604

FastAPI教程：深入理解路径操作与参数声明

Tutorial-Codebase-Knowledge Turns Codebase into Easy Tutorial with AI 项目地址: https://gitcode.com/gh_mirrors/tu/Tutorial-Codebase-Knowledge

前言

在构建现代Web API时，灵活处理各种请求参数是核心能力之一。FastAPI通过巧妙利用Python类型提示(Type Hints)和Pydantic模型，为我们提供了一套优雅而强大的参数处理机制。本文将深入探讨FastAPI中的路径操作和参数声明，帮助开发者掌握API设计的精髓。

路径操作基础

HTTP方法概述

FastAPI支持所有标准HTTP方法，每种方法对应不同的操作语义：

from fastapi import FastAPI

app = FastAPI()

# 获取资源
@app.get("/items/")
async def read_items():
    return [{"name": "Item 1"}]

# 创建资源
@app.post("/items/")
async def create_item():
    return {"message": "Item created"}

# 完整更新资源
@app.put("/items/{item_id}")
async def update_item(item_id: int):
    return {"item_id": item_id}

# 部分更新资源
@app.patch("/items/{item_id}")
async def partial_update(item_id: int):
    return {"item_id": item_id}

# 删除资源
@app.delete("/items/{item_id}")
async def delete_item(item_id: int):
    return {"item_id": item_id}

每种HTTP方法都有其特定的语义，遵循RESTful设计原则可以让API更加清晰和可预测。

参数类型详解

路径参数(Path Parameters)

路径参数是URL路径中的变量部分，用于标识特定资源：

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

关键特点：

必需参数，缺少会导致404错误
通过类型提示自动转换和验证
支持高级验证规则

查询参数(Query Parameters)

查询参数是URL中?后的键值对，用于过滤、分页等：

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

关键特点：

可选参数，通过默认值声明
同样支持类型转换和验证
可以设置为必需参数(不提供默认值)

请求体(Request Body)

用于接收复杂数据，通常用于POST、PUT等操作：

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None

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

关键特点：

使用Pydantic模型定义数据结构
自动JSON解析和验证
支持嵌套复杂结构

高级参数验证

FastAPI提供了精细的参数控制能力：

from typing import Annotated
from fastapi import Path, Query

@app.get("/items/{item_id}")
async def read_item(
    item_id: Annotated[int, Path(title="商品ID", gt=0, le=1000)],
    q: Annotated[str | None, Query(max_length=50)] = None
):
    return {"item_id": item_id, "q": q}

验证选项包括：