FastAPI 中的 Pydantic 模型是什么？

Question

Accepted Answer

**Pydantic 模型**是类（继承 `BaseModel`），它们定义数据的**结构、类型和验证规则**。FastAPI 在各个地方都使用它们——用于请求体、响应形状和设置——这使它们成为 FastAPI 类型驱动设计的核心。

## 定义模型

```python
from pydantic import BaseModel, EmailStr, Field

class User(BaseModel):
    name: str
    email: EmailStr                          # validates email format
    age: int = Field(ge=0, le=120)            # constraint: 0 <= age <= 120
    is_active: bool = True                    # default value
    tags: list[str] = []                      # typed list with a default
```

每个字段声明一个类型和可选的约束/默认值。Pydantic 根据此定义验证数据，并在合理的地方进行类型转换。

## 自动验证和解析

```python
@app.post("/users")
def create_user(user: User):                  # FastAPI builds & validates a User from the body
    return user                               # already validated here
# valid JSON → a typed User object; invalid → automatic 422 with field-level errors
```

当用作参数类型时，FastAPI 将 JSON 请求体解析为模型，**验证**每个字段，并返回一个结构化的 422 错误，确切说明出了什么问题——完全自动。

## Pydantic 提供的功能

```text
✓ Validation — type checks + constraints (lengths, ranges, formats), clear errors
✓ Parsing/coercion — "5" → 5, ISO string → datetime, etc.
✓ Serialization — model.model_dump() / model_dump_json() → dict/JSON
✓ Editor support — full autocomplete & type checking on model attributes
✓ Self-documenting — the model defines the schema used in the auto-generated docs
```

## 单一真实来源

```text
One Pydantic model drives: request validation, the response schema, the OpenAPI docs,
and typed access in your code → define the data shape ONCE.
```

## 为什么这很重要

Pydantic 模型是 FastAPI 的基石——它们是定义和验证 API 接受和返回的数据的方式，几乎所有 FastAPI 功能都通过它们实现。

理解它们至关重要，因为它们提供自动**验证**（对安全性和稳健性至关重要——永远不要相信原始输入）、解析/强制转换、序列化和编辑器支持，这些都来自单个声明式类。

它们充当**单一真实来源**：一个模型驱动请求验证、响应形状和自动生成的文档。

这种类型驱动、默认验证的方法——本质上免费地获得强大的输入验证和清晰的错误消息——是 FastAPI 如此高效和安全的主要原因，使 Pydantic 模型成为必须掌握的基础知识。