Python 数据验证库：Pydantic -马育民老师

# 介绍

Pydantic 是一个非常流行的 Python 数据验证和设置管理库，它基于 Python 类型注解（Type Hints）工作，能自动校验数据类型和值的合法性，广泛用于 API 开发（如 FastAPI）、数据解析、配置管理等场景。

### 优点

- **类型校验**：基于类型注解自动校验输入数据的类型（如 int、str、list 等）；
- **数据转换**：自动将合法的输入转换为目标类型（如字符串 "123" 转为 int 123）；
- **错误提示**：校验失败时返回清晰的错误信息，便于调试；
- **易集成**：与 FastAPI、Django、SQLAlchemy 等框架无缝配合。

# 安装 Pydantic

首先需要安装 Pydantic（推荐安装最新的 v2 版本，性能和功能更优）：
```bash
# 安装基础版本
pip install pydantic

# 若需要兼容旧版（v1）特性，可安装兼容包
pip install pydantic[compat]
```

# 基础用法

Pydantic 的核心是 `BaseModel` 类，所有数据模型都需要继承它。下面是最基础的示例：

```python
from pydantic import BaseModel, ValidationError

# 定义数据模型（基于类型注解）
class User(BaseModel):
    name: str          # 必选字段，字符串类型
    age: int           # 必选字段，整数类型
    email: str | None  # 可选字段，字符串或 None（Python 3.10+ 写法）
    is_active: bool = True  # 有默认值的字段，可选

# 1. 正确的数据示例（自动校验+转换）
user_data = {
    "name": "张三",
    "age": "25",  # 字符串会自动转为 int
    "email": "zhangsan@example.com"
}
user = User(**user_data)
print(user.name)  # 输出：张三
print(user.age)   # 输出：25（int 类型）
# 转为字典/JSON
print(user.model_dump())  # 转为字典
print(user.model_dump_json())  # 转为 JSON 字符串

# 2. 错误的数据示例（校验失败）
bad_user_data = {
    "name": 123,  # 类型错误（应为 str）
    "age": "二十五"  # 无法转为 int
}
try:
    User(**bad_user_data)
except ValidationError as e:
    print(e.json())  # 输出清晰的错误信息
```

# 进阶用法

Pydantic 支持更精细的校验规则，比如字段长度、数值范围、正则匹配等，需要用到 `Field` 函数：

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

class User(BaseModel):
    # 姓名：字符串，长度 2-10
    name: str = Field(min_length=2, max_length=10)
    # 年龄：整数，18-100 之间
    age: int = Field(ge=18, le=100, description="用户年龄（18-100）")
    # 邮箱：自动校验邮箱格式（需安装 email-validator：pip install email-validator）
    email: EmailStr
    # 手机号：正则匹配（中国大陆手机号）
    phone: str = Field(pattern=r"^1[3-9]\d{9}$")

# 正确示例
valid_user = User(
    name="李四",
    age=30,
    email="lisi@example.com",
    phone="13812345678"
)
print(valid_user)

# 错误示例（手机号格式错误）
try:
    User(
        name="李四",
        age=30,
        email="lisi@example.com",
        phone="12345678901"
    )
except ValidationError as e:
    print(e)
```

# 应用场景
1. **API 数据校验（FastAPI 核心依赖）**：
   FastAPI 内置 Pydantic，定义请求体/响应体时直接用 Pydantic 模型，自动完成数据校验和接口文档生成。
2. **配置管理**：
   解析配置文件（如 JSON/YAML）时，用 Pydantic 模型校验配置项的类型和值，避免配置错误。
3. **数据解析**：
   处理外部数据（如 CSV、数据库返回值）时，用 Pydantic 校验数据格式，确保数据合规。

# 总结

1. Pydantic 是基于 Python 类型注解的**数据验证库**，核心是 `BaseModel` 类，能自动校验数据类型和值的合法性；
2. 核心优势是**类型校验、自动转换、清晰的错误提示**，是 FastAPI 等框架的核心依赖；
3. 进阶用法可通过 `Field` 函数定义精细的校验规则（长度、范围、正则等），满足复杂场景需求。

原文出处：http://www.malaoshi.top/show_1GW2qlZA2a1y.html