FastAPI自学教程（5）- 请求体

1. 基础用法

from fastapi import FastAPI
from pydantic import BaseModel

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

app = FastAPI()

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

• 通过继承 BaseModel 定义请求体模型
• 模型字段会自动转换为请求体参数
• 支持自动请求解析和类型验证

2. 可选参数

from typing import Optional

class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: Optional[float] = None

• 使用 Optional[...] = None 声明可选字段
• 未提供的可选字段会设为默认值

3. 多数据类型支持

from pydantic import Field

class User(BaseModel):
    username: str = Field(..., min_length=3)
    age: int = Field(ge=0, le=100)
    email: str = Field(regex=r"^[\w\.-]+@[\w\.-]+\.\w+$")

• 支持多种数据约束：
  • 数值范围（ge/le）
  • 字符串正则匹配
  • 最小/最大长度

4. 必填字段

class Item(BaseModel):
    name: str  # 必填字段
    price: float = Field(...)  # 显式声明必填

• 未设置默认值的字段自动成为必填项
• 缺少必填字段会返回 422 验证错误

5. 混合参数

@app.put("/items/{item_id}")
async def update_item(
    item_id: int = Path(..., ge=1),
    q: str | None = None,
    item: Item = Body(...)
):

• 支持同时使用：
  • 路径参数（Path）
  • 查询参数（Query）
  • 请求体参数（Body）

6. 校验与元数据

from fastapi import Body

@app.post("/items/")
async def create_item(
    item: Item = Body(
        ...,
        example={
            "name": "Foo",
            "price": 35.4,
            "description": "A test item"
        }
    )
):

• Body 参数支持：
  • 字段示例（examples）
  • 文档嵌入（embed=True）
  • 媒体类型声明（media_type）

7. 自动文档支持

• 交互式文档 /docs 自动显示：
  • 请求体字段结构
  • 类型约束说明
  • 示例值展示
  • 错误响应示例

提示：所有请求体验证错误会自动生成结构化错误响应。可通过访问 /docs 查看完整的请求体文档说明，支持直接测试API端点。使用 Field 和 Body 可以增强文档的可读性和测试便利性。