002 - 【FastAPI 入门教程】请求体与数据校验

丑过三八线2026-08-19 14:37

请求体与数据校验

核心概念

FastAPI 用 Pydantic 模型 定义请求体的结构，自动完成：

JSON 解析
类型校验（int/str/float 等）
必填/可选字段
默认值
复杂嵌套结构

定义模型

继承 BaseModel，用类型提示定义字段：

python 复制代码

from pydantic import BaseModel

class User(BaseModel):
    name: str          # 必填，字符串
    age: int           # 必填，整数
    email: str = None  # 可选，默认 None

接收请求体

用 POST + 模型类型作为参数：

python 复制代码

@app.post("/users")
def create_user(user: User):
    # user 已经是解析好的 Python 对象，直接用
    return {"message": f"你好 {user.name}"}

FastAPI 自动从请求体 JSON 中提取并校验字段。

字段校验

用 Field() 添加约束：

python 复制代码

from pydantic import Field

class Item(BaseModel):
    name: str
    price: float = Field(gt=0, description="价格必须大于0")
    stock: int = Field(ge=0, le=1000, description="库存0~1000")

常用约束：

gt / ge / lt / le --- 大于/大于等于/小于/小于等于
min_length / max_length --- 字符串长度
regex --- 正则匹配
description --- 文档说明

运行示例

文件：01_request_body.py

bash 复制代码

uvicorn 01_request_body:app --reload

用 Swagger 测试

访问 http://127.0.0.1:8000/docs ，可以：

点开 POST /users
点 Try it out
输入：

json 复制代码

{
  "name": "张三",
  "age": 25
}

点 Execute，看返回结果

校验失败的处理

发一个错误请求试试：

bash 复制代码

curl -X POST http://127.0.0.1:8000/users \
  -H "Content-Type: application/json" \
  -d '{"name": "张三"}'

缺少 age 字段，FastAPI 自动返回 422 错误：

json 复制代码

{
  "detail": [
    {
      "loc": ["body", "age"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

不需要写任何校验代码，Pydantic 全自动处理。