Pydantic

1. 什么是 Pydantic？

1.1 简单理解

Pydantic 是一个 Python 库，它的主要作用是验证数据是否正确 。想象一下，你有一个表单，用户需要填写姓名、年龄、邮箱等信息。Pydantic 就像一个严格的检查员，确保用户输入的数据符合要求：

• 年龄必须是数字，不能是文字
• 邮箱必须包含 @ 符号
• 姓名不能为空

如果数据不符合要求，Pydantic 会立即告诉你哪里出错了。

1.2 核心特点

1. 基于类型注解 ：使用 Python 的类型提示来定义数据应该是什么样子
2. 自动验证 ：创建对象时自动检查数据是否正确
3. 类型转换 ：如果可能，会自动将数据转换为正确的类型（比如把字符串 "123" 转换为数字 123）
4. 易于使用 ：代码简洁，容易理解

1.3 类比理解

把 Pydantic 想象成一个智能的表格模板 ：

• 你定义好表格的格式（哪些列是必需的，哪些列是什么类型）
• 当有人填写表格时，Pydantic 自动检查：
  • 必填项是否都填了？
  • 数字列填的是数字吗？
  • 邮箱格式正确吗？
• 如果填写错误，立即提示问题在哪里

2. 为什么需要 Pydantic？

2.1 传统方式的问题

在 Python 中，如果不使用 Pydantic，验证数据通常需要写很多 if-else 判断：

# 传统方式：手动验证数据
def create_user(user_data):
    # 检查 id 是否存在
    if 'id' not in user_data:
        raise ValueError("缺少 id")

    # 检查 id 是否是整数
    if not isinstance(user_data['id'], int):
        raise ValueError("id 必须是整数")

    # 检查 name 是否存在
    if 'name' not in user_data:
        raise ValueError("缺少 name")

    # 检查 name 是否是字符串
    if not isinstance(user_data['name'], str):
        raise ValueError("name 必须是字符串")

    # ... 还有很多检查 ...

    return user_data

这种方式的问题：

• 代码冗长 ：需要写很多重复的检查代码
• 容易出错 ：可能忘记检查某些字段
• 难以维护 ：当数据结构改变时，需要修改很多地方

2.2 Pydantic 的优势

使用 Pydantic，同样的功能只需要几行代码：

from pydantic import BaseModel

# 定义数据模型
class User(BaseModel):
    id: int
    name: str

# 自动验证
user = User(id=1, name="张三")  # 自动检查类型

优势：

• 代码简洁 ：定义一次，自动验证
• 自动类型检查 ：不需要手动写 if-else
• 清晰的错误信息 ：如果数据错误，会告诉你具体哪里错了
• 易于维护 ：修改模型定义即可

3. 前置知识

在学习 Pydantic 之前，你需要了解一些 Python 基础知识。如果你已经熟悉这些内容，可以跳过。

3.1 Python 类型注解（Type Hints）

类型注解是 Python 3.5+ 引入的功能，用来标注变量、函数参数和返回值的类型。

3.1.1 基本类型注解

# 标注变量的类型
name: str = "张三"        # name 是字符串类型
age: int = 25            # age 是整数类型
price: float = 99.99     # price 是浮点数类型
is_active: bool = True   # is_active 是布尔类型

# 标注函数参数和返回值的类型
def add(a: int, b: int) -> int:
    """
    函数 add 接收两个整数参数 a 和 b，返回一个整数
    """
    return a + b

result = add(3, 5)  # result 是 8

3.1.2 复杂类型注解

from typing import List, Dict, Optional

# List[str] 表示字符串列表
names: List[str] = ["张三", "李四", "王五"]

# Dict[str, int] 表示字典，键是字符串，值是整数
scores: Dict[str, int] = {"张三": 90, "李四": 85}

# Optional[str] 表示可以是字符串，也可以是 None
email: Optional[str] = None  # 可以是字符串，也可以是 None
email = "zhangsan@example.com"  # 也可以赋值字符串

注意 ：类型注解不会影响程序运行，只是给开发者和工具（如 Pydantic）提供信息。

3.2 Python 类的基础知识

3.2.1 定义类

# 定义一个简单的类
class Person:
    # __init__ 是构造函数，创建对象时自动调用
    def __init__(self, name: str, age: int):
        # self 表示对象本身
        self.name = name  # 设置对象的 name 属性
        self.age = age    # 设置对象的 age 属性

    # 定义方法
    def introduce(self):
        return f"我是{self.name}，今年{self.age}岁"

# 创建对象
person = Person("张三", 25)
print(person.introduce())  # 输出: 我是张三，今年25岁

3.2.2 类的继承

# 父类（基类）
class Animal:
    def __init__(self, name: str):
        self.name = name

    def speak(self):
        return "动物在叫"

# 子类（派生类），继承自 Animal
class Dog(Animal):
    def speak(self):
        return f"{self.name}在汪汪叫"

# 创建子类对象
dog = Dog("旺财")
print(dog.speak())  # 输出: 旺财在汪汪叫

Pydantic 中的 BaseModel 就是一个基类，我们定义的模型类继承自它，就自动获得了数据验证等功能。

3.3 字典解包（**kwargs）

在 Python 中，** 用于解包字典。

# 定义一个字典
user_data = {"id": 1, "name": "张三", "age": 25}

# 传统方式：逐个传递参数
def create_user(id, name, age):
    return {"id": id, "name": name, "age": age}

user1 = create_user(user_data["id"], user_data["name"], user_data["age"])

# 使用 ** 解包字典，自动传递所有键值对
user2 = create_user(**user_data)  # 等同于 create_user(id=1, name="张三", age=25)

在 Pydantic 中，我们经常用 ** 从字典创建对象：

user = User(**user_data)  # 从字典创建 User 对象

3.4 装饰器（Decorator）

装饰器是 Python 的高级特性，用于修改函数或类的行为。

# 定义一个装饰器
def my_decorator(func):
    def wrapper(*args, **kwargs):
        print("函数执行前")
        result = func(*args, **kwargs)
        print("函数执行后")
        return result
    return wrapper

# 使用装饰器
@my_decorator
def say_hello():
    print("Hello!")

say_hello()
# 输出:
# 函数执行前
# Hello!
# 函数执行后

在 Pydantic 中，@validator 是一个装饰器，用于定义字段验证函数。

4. 安装 Pydantic

4.1 使用 pip 安装

4.1.1 Windows 系统

打开命令提示符（CMD）或 PowerShell：

# 安装 Pydantic
pip install pydantic

如果使用 Python 3，可能需要使用 pip3：

pip3 install pydantic

4.1.2 Mac 系统

打开终端（Terminal）：

# 安装 Pydantic
pip3 install pydantic

4.2 验证安装

创建一个测试文件 test_pydantic.py：

# 导入 pydantic，检查是否安装成功
try:
    from pydantic import BaseModel
    print("Pydantic 安装成功！")
except ImportError:
    print("Pydantic 未安装，请运行: pip install pydantic")

运行测试：

Windows:

python test_pydantic.py

Mac:

python3 test_pydantic.py

如果看到 "Pydantic 安装成功！"，说明安装正确。

5. 快速开始

让我们通过一个简单的例子快速了解 Pydantic 的基本用法。

5.1 用户信息验证

创建一个文件 example_01_basic.py：

# ============================================
# 第一个 Pydantic 例子：用户信息验证
# ============================================

# 导入 BaseModel，这是 Pydantic 的基础类
from pydantic import BaseModel

# 定义一个用户模型
# 继承 BaseModel 后，这个类就自动具有数据验证功能
class User(BaseModel):
    # id 字段必须是整数类型
    id: int
    # name 字段必须是字符串类型
    name: str
    # email 字段必须是字符串类型
    email: str
    # age 字段是整数类型，默认值是 18
    # 如果创建对象时不提供 age，会自动使用默认值
    age: int = 18

# 示例1：创建用户对象（所有数据都正确）
print("=" * 50)
print("示例1：创建用户对象（数据正确）")
print("=" * 50)
user1 = User(id=1, name="张三", email="zhangsan@example.com", age=25)
print(f"用户对象: {user1}")
print(f"用户姓名: {user1.name}")
print(f"用户年龄: {user1.age}")

# 示例2：使用默认值（不提供 age）
print("\n" + "=" * 50)
print("示例2：使用默认值")
print("=" * 50)
user2 = User(id=2, name="李四", email="lisi@example.com")
print(f"用户对象: {user2}")
print(f"用户年龄（使用默认值）: {user2.age}")

# 示例3：从字典创建对象
print("\n" + "=" * 50)
print("示例3：从字典创建对象")
print("=" * 50)
user_data = {
    "id": 3,
    "name": "王五",
    "email": "wangwu@example.com",
    "age": 30
}
# 使用 ** 解包字典，将字典的键值对作为参数传递
user3 = User(**user_data)
print(f"用户对象: {user3}")

# 示例4：数据验证（错误的数据）
print("\n" + "=" * 50)
print("示例4：数据验证（错误的数据）")
print("=" * 50)
try:
    # 尝试用字符串作为 id（应该是整数）
    user4 = User(id="不是数字", name="赵六", email="zhaoliu@example.com")
except Exception as e:
    # 捕获异常并打印错误信息
    print(f"验证错误: {e}")
    print("\nPydantic 自动检测到 id 应该是整数，但提供了字符串！")

# 示例5：缺少必需字段
print("\n" + "=" * 50)
print("示例5：缺少必需字段")
print("=" * 50)
try:
    # 缺少必需的 email 字段
    user5 = User(id=5, name="孙七")
except Exception as e:
    print(f"验证错误: {e}")
    print("\nPydantic 检测到缺少必需的 email 字段！")

5.2 运行代码

Windows:

python example_01_basic.py

Mac:

python3 example_01_basic.py

5.3 运行结果

==================================================
示例1：创建用户对象（数据正确）
==================================================
用户对象: id=1 name='张三' email='zhangsan@example.com' age=25
用户姓名: 张三
用户年龄: 25

==================================================
示例2：使用默认值
==================================================
用户对象: id=2 name='李四' email='lisi@example.com' age=18
用户年龄（使用默认值）: 18

==================================================
示例3：从字典创建对象
==================================================
用户对象: id=3 name='王五' email='wangwu@example.com' age=30

==================================================
示例4：数据验证（错误的数据）
==================================================
验证错误: 1 validation error for User
id
  value is not a valid integer (type=type_error.integer)

Pydantic 自动检测到 id 应该是整数，但提供了字符串！

==================================================
示例5：缺少必需字段
==================================================
验证错误: 1 validation error for User
email
  field required (type=value_error.missing)

Pydantic 检测到缺少必需的 email 字段！

5.4 关键点理解

1. 定义模型 ：继承 BaseModel 并定义字段类型
2. 自动验证 ：创建对象时自动检查数据类型
3. 默认值 ：可以为字段设置默认值
4. 错误提示 ：数据错误时，Pydantic 会给出清晰的错误信息

6. 核心功能

6.1 数据验证

Pydantic 的核心功能是自动验证数据。让我们详细看看它是如何工作的。

6.1.1 类型验证

创建文件 example_02_validation.py：

# ============================================
# 数据验证
# ============================================

from pydantic import BaseModel, ValidationError

# 定义一个产品模型
class Product(BaseModel):
    # 产品名称必须是字符串
    name: str
    # 价格必须是浮点数
    price: float
    # 库存数量必须是整数
    stock: int

# 示例1：正确的数据
print("=" * 50)
print("示例1：正确的数据")
print("=" * 50)
product1 = Product(name="笔记本电脑", price=5999.99, stock=10)
print(f"产品: {product1}")
print(f"产品名称类型: {type(product1.name)}")
print(f"产品价格类型: {type(product1.price)}")

# 示例2：自动类型转换
print("\n" + "=" * 50)
print("示例2：自动类型转换")
print("=" * 50)
# 注意：price 传入的是字符串 "5999.99"，但 Pydantic 会自动转换为浮点数
# stock 传入的是字符串 "10"，但 Pydantic 会自动转换为整数
product2 = Product(name="鼠标", price="29.99", stock="5")
print(f"产品: {product2}")
print(f"价格类型（已自动转换）: {type(product2.price)}")
print(f"库存类型（已自动转换）: {type(product2.stock)}")

# 示例3：无法转换的类型错误
print("\n" + "=" * 50)
print("示例3：无法转换的类型错误")
print("=" * 50)
try:
    # 尝试将 "不是数字" 转换为整数，会失败
    product3 = Product(name="键盘", price=99.99, stock="不是数字")
except ValidationError as e:
    # ValidationError 是 Pydantic 的验证错误类型
    print("验证失败！")
    print(f"错误详情: {e}")
    # 可以获取更详细的错误信息
    print("\n详细错误列表:")
    for error in e.errors():
        print(f"  字段: {error['loc']}")
        print(f"  错误类型: {error['type']}")
        print(f"  错误信息: {error['msg']}")

# 示例4：缺少必需字段
print("\n" + "=" * 50)
print("示例4：缺少必需字段")
print("=" * 50)
try:
    # 缺少必需的 stock 字段
    product4 = Product(name="显示器", price=1999.99)
except ValidationError as e:
    print("验证失败！缺少必需字段")
    print(f"错误: {e}")

# 示例5：使用 Optional 定义可选字段
print("\n" + "=" * 50)
print("示例5：可选字段")
print("=" * 50)
from typing import Optional

# 定义一个新模型，description 是可选的
class ProductWithDescription(BaseModel):
    name: str
    price: float
    # Optional[str] 表示可以是字符串，也可以是 None
    # = None 表示默认值是 None
    description: Optional[str] = None

# 不提供 description（使用默认值 None）
product5 = ProductWithDescription(name="耳机", price=299.99)
print(f"产品（无描述）: {product5}")

# 提供 description
product6 = ProductWithDescription(name="音响", price=599.99, description="高品质蓝牙音响")
print(f"产品（有描述）: {product6}")

6.1.2 运行结果

运行 python example_02_validation.py（Windows）或 python3 example_02_validation.py（Mac），你会看到详细的验证过程。

6.2 数据序列化

序列化是将对象转换为可以存储或传输的格式（如字典、JSON）。反序列化是相反的过程。

创建文件 example_03_serialization.py：

# ============================================
# 数据序列化和反序列化
# ============================================

from pydantic import BaseModel
import json

# 定义用户模型
class User(BaseModel):
    id: int
    name: str
    email: str
    age: int = 18

# 创建一个用户对象
user = User(id=1, name="张三", email="zhangsan@example.com", age=25)

print("=" * 50)
print("原始对象")
print("=" * 50)
print(f"用户对象: {user}")
print(f"对象类型: {type(user)}")

# 方法1：转换为字典
print("\n" + "=" * 50)
print("方法1：转换为字典（dict()）")
print("=" * 50)
# dict() 方法将 Pydantic 对象转换为普通字典
user_dict = user.dict()
print(f"字典: {user_dict}")
print(f"字典类型: {type(user_dict)}")
print(f"可以像普通字典一样访问: {user_dict['name']}")

# 方法2：转换为 JSON 字符串
print("\n" + "=" * 50)
print("方法2：转换为 JSON 字符串（json()）")
print("=" * 50)
# json() 方法将对象转换为 JSON 格式的字符串
user_json = user.json()
print(f"JSON 字符串: {user_json}")
print(f"JSON 类型: {type(user_json)}")
# JSON 字符串可以保存到文件或通过网络传输

# 方法3：转换为格式化的 JSON（更易读）
print("\n" + "=" * 50)
print("方法3：格式化的 JSON")
print("=" * 50)
# 使用 json.dumps 格式化输出
user_json_pretty = user.json(indent=2)
print(user_json_pretty)

# 方法4：从字典创建对象（反序列化）
print("\n" + "=" * 50)
print("方法4：从字典创建对象")
print("=" * 50)
# 假设我们从 API 或数据库获取了字典数据
data_from_api = {
    "id": 2,
    "name": "李四",
    "email": "lisi@example.com",
    "age": 30
}
# 使用 ** 解包字典创建对象
user_from_dict = User(**data_from_api)
print(f"从字典创建的对象: {user_from_dict}")

# 方法5：从 JSON 字符串创建对象
print("\n" + "=" * 50)
print("方法5：从 JSON 字符串创建对象")
print("=" * 50)
# 假设我们收到 JSON 字符串（比如从网络请求）
json_string = '{"id": 3, "name": "王五", "email": "wangwu@example.com", "age": 28}'
# parse_raw() 方法从 JSON 字符串创建对象
user_from_json = User.parse_raw(json_string)
print(f"从 JSON 创建的对象: {user_from_json}")

# 方法6：从文件读取 JSON 并创建对象
print("\n" + "=" * 50)
print("方法6：从文件读取（示例）")
print("=" * 50)
# 首先创建一个 JSON 文件
json_data = {"id": 4, "name": "赵六", "email": "zhaoliu@example.com", "age": 35}
with open("user_data.json", "w", encoding="utf-8") as f:
    json.dump(json_data, f, ensure_ascii=False, indent=2)
print("已创建 user_data.json 文件")

# 从文件读取并创建对象
with open("user_data.json", "r", encoding="utf-8") as f:
    data = json.load(f)
    user_from_file = User(**data)
    print(f"从文件创建的对象: {user_from_file}")

# 实际应用场景：API 数据交换
print("\n" + "=" * 50)
print("实际应用：模拟 API 数据交换")
print("=" * 50)
# 模拟：客户端发送数据到服务器
client_data = {"id": 5, "name": "孙七", "email": "sunqi@example.com"}
print(f"客户端发送: {client_data}")

# 服务器接收并验证
server_user = User(**client_data)
print(f"服务器验证通过: {server_user}")

# 服务器处理后将对象转换为 JSON 返回
response_json = server_user.json()
print(f"服务器返回 JSON: {response_json}")

6.3 字段验证器

除了类型验证，我们还可以自定义验证规则。

创建文件 example_04_validator.py：

# ============================================
# 自定义字段验证器
# ============================================

from pydantic import BaseModel, validator, ValidationError

# 定义商品模型，包含自定义验证
class Product(BaseModel):
    # 商品名称
    name: str
    # 商品价格
    price: float
    # 商品库存
    stock: int

    # 使用 @validator 装饰器定义价格验证器
    # 'price' 表示验证 price 字段
    @validator('price')
    def price_must_be_positive(cls, v):
        """
        验证价格必须大于 0
        cls: 类本身（Product）
        v: 字段的值（price 的值）
        """
        # 如果价格小于等于 0，抛出错误
        if v <= 0:
            raise ValueError('价格必须大于 0')
        # 如果验证通过，返回原值（也可以返回修改后的值）
        return v

    # 验证库存
    @validator('stock')
    def stock_must_be_non_negative(cls, v):
        """
        验证库存不能为负数
        """
        if v < 0:
            raise ValueError('库存不能为负数')
        return v

    # 验证商品名称
    @validator('name')
    def name_must_not_be_empty(cls, v):
        """
        验证商品名称不能为空
        """
        # strip() 去除首尾空格
        v = v.strip()
        if not v:  # 如果去除空格后为空
            raise ValueError('商品名称不能为空')
        return v  # 返回去除空格后的值

# 示例1：正确的数据
print("=" * 50)
print("示例1：正确的数据")
print("=" * 50)
product1 = Product(name="笔记本电脑", price=5999.99, stock=10)
print(f"商品: {product1}")
print("验证通过！")

# 示例2：价格验证失败
print("\n" + "=" * 50)
print("示例2：价格验证失败")
print("=" * 50)
try:
    # 价格是负数，验证会失败
    product2 = Product(name="鼠标", price=-10.0, stock=5)
except ValidationError as e:
    print("验证失败！")
    for error in e.errors():
        print(f"  字段: {error['loc']}")
        print(f"  错误: {error['msg']}")

# 示例3：库存验证失败
print("\n" + "=" * 50)
print("示例3：库存验证失败")
print("=" * 50)
try:
    # 库存是负数，验证会失败
    product3 = Product(name="键盘", price=99.99, stock=-5)
except ValidationError as e:
    print("验证失败！")
    for error in e.errors():
        print(f"  字段: {error['loc']}")
        print(f"  错误: {error['msg']}")

# 示例4：名称验证（自动去除空格）
print("\n" + "=" * 50)
print("示例4：名称验证（自动处理）")
print("=" * 50)
# 名称前后有空格，验证器会自动去除
product4 = Product(name="  显示器  ", price=1999.99, stock=8)
print(f"商品名称（已去除空格）: '{product4.name}'")

# 示例5：多个验证器同时工作
print("\n" + "=" * 50)
print("示例5：多个验证器")
print("=" * 50)
try:
    # 多个字段都有问题
    product5 = Product(name="", price=-100, stock=-10)
except ValidationError as e:
    print("验证失败！发现多个错误：")
    for error in e.errors():
        print(f"  {error['loc']}: {error['msg']}")

6.4 字段配置（Field）

使用 Field 可以更灵活地配置字段。

创建文件 example_05_field.py：

# ============================================
# 字段配置（Field）
# ============================================

from pydantic import BaseModel, Field
from typing import Optional

# 定义商品模型，使用 Field 配置字段
class Item(BaseModel):
    # Field 用于配置字段的详细属性
    # ... 表示该字段是必需的（不能省略）
    # min_length=1 表示最小长度为 1
    # max_length=50 表示最大长度为 50
    # description 是字段的描述信息
    name: str = Field(..., min_length=1, max_length=50, description="商品名称")

    # gt=0 表示必须大于 0（greater than）
    # description 提供字段说明
    price: float = Field(..., gt=0, description="商品价格，必须大于0")

    # Optional[str] 表示可以是字符串或 None
    # None 是默认值
    # max_length=200 限制最大长度
    description: Optional[str] = Field(None, max_length=200, description="商品描述")

    # ge=0 表示大于等于 0（greater than or equal）
    # le=100 表示小于等于 100（less than or equal）
    # 10.0 是默认值
    discount: float = Field(10.0, ge=0, le=100, description="折扣百分比，0-100之间")

# 示例1：正确的数据
print("=" * 50)
print("示例1：正确的数据")
print("=" * 50)
item1 = Item(name="笔记本电脑", price=5999.99, description="高性能游戏本", discount=15.0)
print(f"商品: {item1}")

# 示例2：使用默认值
print("\n" + "=" * 50)
print("示例2：使用默认值")
print("=" * 50)
item2 = Item(name="鼠标", price=29.99)
print(f"商品（使用默认折扣）: {item2}")

# 示例3：字段长度验证
print("\n" + "=" * 50)
print("示例3：字段长度验证")
print("=" * 50)
from pydantic import ValidationError

try:
    # 名称太长，超过 50 个字符
    long_name = "a" * 51  # 创建 51 个字符的字符串
    item3 = Item(name=long_name, price=99.99)
except ValidationError as e:
    print("验证失败！")
    for error in e.errors():
        print(f"  {error['loc']}: {error['msg']}")

# 示例4：数值范围验证
print("\n" + "=" * 50)
print("示例4：数值范围验证")
print("=" * 50)
try:
    # 折扣超过 100，验证失败
    item4 = Item(name="键盘", price=99.99, discount=150.0)
except ValidationError as e:
    print("验证失败！")
    for error in e.errors():
        print(f"  {error['loc']}: {error['msg']}")

# 示例5：查看字段信息
print("\n" + "=" * 50)
print("示例5：查看模型结构")
print("=" * 50)
# schema() 方法返回模型的完整结构信息
schema = Item.schema()
print("模型结构（JSON Schema）:")
import json
print(json.dumps(schema, indent=2, ensure_ascii=False))

6.5 嵌套模型

一个模型可以包含另一个模型，形成嵌套结构。

创建文件 example_06_nested.py：

# ============================================
# 嵌套模型
# ============================================

from pydantic import BaseModel
from typing import List, Optional

# 定义地址模型
class Address(BaseModel):
    # 街道地址
    street: str
    # 城市
    city: str
    # 邮政编码
    zip_code: str

# 定义公司模型，包含地址
class Company(BaseModel):
    # 公司名称
    name: str
    # 公司地址，类型是 Address（嵌套模型）
    address: Address

# 定义员工模型
class Employee(BaseModel):
    # 员工姓名
    name: str
    # 员工年龄
    age: int
    # 所属公司（嵌套模型）
    company: Company
    # 技能列表（List[str] 表示字符串列表）
    skills: List[str] = []

# 示例1：创建嵌套对象
print("=" * 50)
print("示例1：创建嵌套对象")
print("=" * 50)
# 方式1：先创建 Address 对象，再创建 Company 对象
address = Address(street="科技路123号", city="北京", zip_code="100000")
company = Company(name="ABC公司", address=address)
employee = Employee(name="张三", age=25, company=company, skills=["Python", "Java"])
print(f"员工: {employee}")
print(f"员工公司: {employee.company.name}")
print(f"公司地址: {employee.company.address.city}")

# 示例2：使用字典创建（更常用）
print("\n" + "=" * 50)
print("示例2：使用字典创建")
print("=" * 50)
# 可以直接用字典创建，Pydantic 会自动处理嵌套
employee_data = {
    "name": "李四",
    "age": 30,
    "company": {
        "name": "XYZ公司",
        "address": {
            "street": "创新路456号",
            "city": "上海",
            "zip_code": "200000"
        }
    },
    "skills": ["JavaScript", "React", "Node.js"]
}
employee2 = Employee(**employee_data)
print(f"员工: {employee2}")
print(f"技能列表: {employee2.skills}")

# 示例3：嵌套验证
print("\n" + "=" * 50)
print("示例3：嵌套验证")
print("=" * 50)
from pydantic import ValidationError

try:
    # 地址信息不完整（缺少 zip_code）
    employee3 = Employee(
        name="王五",
        age=28,
        company={
            "name": "DEF公司",
            "address": {
                "street": "商业街789号",
                "city": "广州"
                # 缺少 zip_code
            }
        }
    )
except ValidationError as e:
    print("验证失败！嵌套模型验证出错：")
    for error in e.errors():
        print(f"  {error['loc']}: {error['msg']}")

# 示例4：复杂嵌套（列表中的模型）
print("\n" + "=" * 50)
print("示例4：列表中的嵌套模型")
print("=" * 50)

# 定义订单项模型
class OrderItem(BaseModel):
    product_name: str
    quantity: int
    price: float

# 定义订单模型，包含多个订单项
class Order(BaseModel):
    order_id: int
    customer_name: str
    # List[OrderItem] 表示 OrderItem 对象的列表
    items: List[OrderItem]

# 创建包含多个订单项的订单
order = Order(
    order_id=1001,
    customer_name="张三",
    items=[
        {"product_name": "笔记本电脑", "quantity": 1, "price": 5999.99},
        {"product_name": "鼠标", "quantity": 2, "price": 29.99},
        {"product_name": "键盘", "quantity": 1, "price": 99.99}
    ]
)
print(f"订单: {order}")
print(f"订单项数量: {len(order.items)}")
print(f"第一个订单项: {order.items[0].product_name}")

7. 高级功能

7.1 可选字段和默认值

我们已经在前面的例子中看到了可选字段，这里再详细说明。

创建文件 example_07_optional.py：

# ============================================
# 可选字段和默认值
# ============================================

from pydantic import BaseModel, Field
from typing import Optional, List

# 定义用户模型，演示各种默认值用法
class UserProfile(BaseModel):
    # 必需字段：没有默认值，创建对象时必须提供
    username: str
    email: str

    # 可选字段1：使用 Optional 和 None 默认值
    # 如果不提供，值就是 None
    phone: Optional[str] = None

    # 可选字段2：有具体的默认值
    # 如果不提供，值就是 "普通用户"
    role: str = "普通用户"

    # 可选字段3：列表类型，默认是空列表
    tags: List[str] = []

    # 可选字段4：使用 Field 设置默认值和描述
    age: int = Field(18, ge=0, le=150, description="用户年龄")

    # 可选字段5：使用 Field 的 default_factory
    # default_factory 用于生成默认值（每次创建对象时调用）
    from datetime import datetime
    created_at: datetime = Field(default_factory=datetime.now)

# 示例1：只提供必需字段
print("=" * 50)
print("示例1：只提供必需字段")
print("=" * 50)
user1 = UserProfile(username="张三", email="zhangsan@example.com")
print(f"用户: {user1}")
print(f"电话（默认 None）: {user1.phone}")
print(f"角色（默认值）: {user1.role}")
print(f"标签（默认空列表）: {user1.tags}")

# 示例2：提供部分可选字段
print("\n" + "=" * 50)
print("示例2：提供部分可选字段")
print("=" * 50)
user2 = UserProfile(
    username="李四",
    email="lisi@example.com",
    phone="13800138000",
    role="管理员"
)
print(f"用户: {user2}")

# 示例3：修改列表默认值（注意陷阱）
print("\n" + "=" * 50)
print("示例3：列表默认值的陷阱")
print("=" * 50)
# ⚠️ 注意：不要直接修改列表默认值！
# 错误示例（不要这样做）：
# tags: List[str] = []  # 这会导致所有对象共享同一个列表

# 正确做法：使用 Field 的 default_factory
class CorrectUser(BaseModel):
    username: str
    # 使用 default_factory，每次创建对象时都会创建新列表
    tags: List[str] = Field(default_factory=list)

user3 = CorrectUser(username="王五")
user3.tags.append("VIP")  # 修改这个对象的 tags
print(f"用户3的标签: {user3.tags}")

user4 = CorrectUser(username="赵六")
print(f"用户4的标签（应该是空的）: {user4.tags}")

7.2 数据转换和清洗

Pydantic 可以自动转换和清洗数据。

创建文件 example_08_transformation.py：

# ============================================
# 数据转换和清洗
# ============================================

from pydantic import BaseModel, validator
from typing import Optional

# 定义数据处理模型
class CleanedData(BaseModel):
    # 用户ID
    user_id: int
    # 用户名（会自动去除首尾空格）
    user_name: str
    # 邮箱（转换为小写）
    user_email: str

    # 验证器：自动清洗用户名
    @validator('user_name')
    def clean_name(cls, v):
        """
        清洗用户名：去除首尾空格，转换为标题格式
        """
        # strip() 去除首尾空格
        v = v.strip()
        # title() 将首字母大写
        v = v.title()
        return v

    # 验证器：自动清洗邮箱
    @validator('user_email')
    def clean_email(cls, v):
        """
        清洗邮箱：转换为小写，去除空格
        """
        # lower() 转换为小写
        v = v.lower()
        # replace() 去除空格
        v = v.replace(" ", "")
        return v

    # 配置：忽略额外字段
    class Config:
        # extra = "ignore" 表示忽略模型中没有定义的字段
        # 这样即使传入额外字段也不会报错
        extra = "ignore"

# 示例1：自动清洗数据
print("=" * 50)
print("示例1：自动清洗数据")
print("=" * 50)
# 输入数据有空格、大小写混乱
raw_data = {
    "user_id": 1,
    "user_name": "   zhang san   ",  # 有空格，小写
    "user_email": "  ZHANGSAN@EXAMPLE.COM  "  # 有空格，大写
}
cleaned = CleanedData(**raw_data)
print(f"原始数据: {raw_data}")
print(f"清洗后: {cleaned}")
print(f"用户名（已清洗）: '{cleaned.user_name}'")
print(f"邮箱（已清洗）: '{cleaned.user_email}'")

# 示例2：忽略额外字段
print("\n" + "=" * 50)
print("示例2：忽略额外字段")
print("=" * 50)
# 数据中包含模型中没有定义的字段
data_with_extra = {
    "user_id": 2,
    "user_name": "li si",
    "user_email": "lisi@example.com",
    "extra_field_1": "这个字段会被忽略",
    "extra_field_2": 12345
}
cleaned2 = CleanedData(**data_with_extra)
print(f"包含额外字段的数据: {data_with_extra}")
print(f"处理后的对象（额外字段已忽略）: {cleaned2}")

# 示例3：实际应用场景
print("\n" + "=" * 50)
print("示例3：实际应用场景")
print("=" * 50)

def process_user_data(raw_data: dict):
    """
    处理用户数据的函数
    自动验证和清洗数据
    """
    try:
        # 自动验证和清洗
        cleaned_data = CleanedData(**raw_data)
        print(f"✓ 数据验证通过")
        print(f"  用户ID: {cleaned_data.user_id}")
        print(f"  用户名: {cleaned_data.user_name}")
        print(f"  邮箱: {cleaned_data.user_email}")
        return cleaned_data
    except Exception as e:
        print(f"✗ 数据验证失败: {e}")
        return None

# 测试处理函数
test_data = {
    "user_id": "3",  # 字符串，会自动转换为整数
    "user_name": "  wang wu  ",
    "user_email": "WANGWU@EXAMPLE.COM"
}
result = process_user_data(test_data)

8. 实际应用场景

8.1 API 数据验证（FastAPI 示例）

FastAPI 是一个现代 Python Web 框架，它内置支持 Pydantic。

创建文件 example_09_fastapi.py：

# ============================================
# FastAPI 中使用 Pydantic（示例）
# ============================================
# 注意：运行此示例需要安装 fastapi 和 uvicorn
# Windows: pip install fastapi uvicorn
# Mac: pip3 install fastapi uvicorn

from fastapi import FastAPI
from pydantic import BaseModel, EmailStr
from typing import Optional

# 创建 FastAPI 应用
app = FastAPI()

# 定义请求模型（客户端发送的数据）
class CreateUserRequest(BaseModel):
    # 用户名
    username: str
    # 密码
    password: str
    # 邮箱（使用 EmailStr 确保格式正确）
    email: EmailStr
    # 年龄（可选）
    age: Optional[int] = None

# 定义响应模型（服务器返回的数据）
class UserResponse(BaseModel):
    # 用户ID
    id: int
    # 用户名
    username: str
    # 邮箱
    email: str
    # 年龄
    age: Optional[int] = None

# 定义 API 端点
@app.post("/users/", response_model=UserResponse)
async def create_user(user: CreateUserRequest):
    """
    创建用户的 API 端点
    user 参数会自动使用 Pydantic 验证
    """
    # 这里 user 已经是验证过的 CreateUserRequest 对象
    # 可以直接使用，不需要手动验证

    # 模拟创建用户（实际应该保存到数据库）
    new_user = UserResponse(
        id=1,  # 实际应该从数据库获取
        username=user.username,
        email=user.email,
        age=user.age
    )

    # FastAPI 会自动将 UserResponse 转换为 JSON 返回
    return new_user

# 运行说明：
# 在终端运行: uvicorn example_09_fastapi:app --reload
# 然后访问: http://127.0.0.1:8000/docs 查看 API 文档
# 可以测试发送 POST 请求到 http://127.0.0.1:8000/users/

print("=" * 50)
print("FastAPI 示例代码")
print("=" * 50)
print("此文件定义了 FastAPI 应用和 Pydantic 模型")
print("要运行此示例，请执行以下步骤：")
print("1. 安装依赖: pip install fastapi uvicorn")
print("2. 运行服务器: uvicorn example_09_fastapi:app --reload")
print("3. 访问 http://127.0.0.1:8000/docs 查看 API 文档")

8.2 配置文件管理

使用 Pydantic 管理应用配置。

创建文件 example_10_config.py：

# ============================================
# 配置文件管理
# ============================================

from pydantic import BaseSettings
from typing import Optional

# 定义配置模型
# BaseSettings 是 Pydantic 提供的特殊基类，用于管理配置
class Settings(BaseSettings):
    # 应用名称，默认值是 "My App"
    app_name: str = "My App"
    # 数据库 URL（必需，没有默认值）
    database_url: str
    # 调试模式，默认是 False
    debug: bool = False
    # API 密钥（可选）
    api_key: Optional[str] = None
    # 最大连接数，默认是 10
    max_connections: int = 10

    # 配置类
    class Config:
        # 从 .env 文件加载环境变量
        env_file = ".env"
        # 环境变量文件编码
        env_file_encoding = "utf-8"

# 创建配置对象
# 会自动从环境变量和 .env 文件加载配置
try:
    settings = Settings()
    print("=" * 50)
    print("配置加载成功")
    print("=" * 50)
    print(f"应用名称: {settings.app_name}")
    print(f"数据库 URL: {settings.database_url}")
    print(f"调试模式: {settings.debug}")
    print(f"最大连接数: {settings.max_connections}")
except Exception as e:
    print("=" * 50)
    print("配置加载失败")
    print("=" * 50)
    print(f"错误: {e}")
    print("\n提示：")
    print("1. 创建 .env 文件，内容如下：")
    print("   database_url=postgresql://user:password@localhost/dbname")
    print("   app_name=My Application")
    print("   debug=true")
    print("2. 或者设置环境变量：")
    print("   Windows: set database_url=postgresql://...")
    print("   Mac: export database_url=postgresql://...")

# 示例：手动创建配置（不使用环境变量）
print("\n" + "=" * 50)
print("手动创建配置示例")
print("=" * 50)
manual_settings = Settings(
    app_name="手动配置的应用",
    database_url="sqlite:///example.db",
    debug=True,
    max_connections=20
)
print(f"手动配置: {manual_settings}")

创建 .env 文件（可选）：

database_url=postgresql://user:password@localhost/mydb
app_name=My Application
debug=true
max_connections=20

8.3 数据验证和清洗工具

创建一个通用的数据验证工具。

创建文件 example_11_data_processor.py：

# ============================================
# 数据验证和清洗工具
# ============================================

from pydantic import BaseModel, validator, ValidationError
from typing import Optional, List, Dict, Any

# 定义用户数据模型
class UserData(BaseModel):
    # 用户ID
    user_id: int
    # 用户名
    user_name: str
    # 用户邮箱
    user_email: str
    # 创建时间（可选）
    created_at: Optional[str] = None

    # 配置：忽略额外字段
    class Config:
        extra = "ignore"

    # 验证用户名
    @validator('user_name')
    def validate_name(cls, v):
        v = v.strip()
        if not v:
            raise ValueError('用户名不能为空')
        if len(v) < 2:
            raise ValueError('用户名至少2个字符')
        return v

    # 验证邮箱
    @validator('user_email')
    def validate_email(cls, v):
        v = v.strip().lower()
        if '@' not in v:
            raise ValueError('邮箱格式不正确')
        return v

# 数据处理器类
class DataProcessor:
    """
    数据处理器，用于验证和清洗数据
    """

    @staticmethod
    def process_user_data(raw_data: dict) -> Dict[str, Any]:
        """
        处理用户数据

        参数:
        raw_data: 原始数据字典

        返回:
        处理后的数据字典，包含 'success', 'data', 'errors' 字段
        """
        try:
            # 使用 Pydantic 自动验证和清洗
            validated_data = UserData(**raw_data)

            # 转换为字典返回
            return {
                "success": True,
                "data": validated_data.dict(),
                "errors": None
            }
        except ValidationError as e:
            # 收集所有验证错误
            errors = []
            for error in e.errors():
                errors.append({
                    "field": ".".join(str(x) for x in error["loc"]),
                    "message": error["msg"],
                    "type": error["type"]
                })

            return {
                "success": False,
                "data": None,
                "errors": errors
            }
        except Exception as e:
            return {
                "success": False,
                "data": None,
                "errors": [{"message": str(e)}]
            }

# 示例使用
print("=" * 50)
print("数据处理器示例")
print("=" * 50)

# 测试数据1：正确的数据
print("\n测试1：正确的数据")
test_data_1 = {
    "user_id": 1,
    "user_name": "  张三  ",
    "user_email": "  ZHANGSAN@EXAMPLE.COM  "
}
result1 = DataProcessor.process_user_data(test_data_1)
print(f"成功: {result1['success']}")
if result1['success']:
    print(f"处理后的数据: {result1['data']}")
else:
    print(f"错误: {result1['errors']}")

# 测试数据2：错误的数据
print("\n测试2：错误的数据")
test_data_2 = {
    "user_id": "不是数字",
    "user_name": "A",  # 太短
    "user_email": "invalid-email"  # 格式错误
}
result2 = DataProcessor.process_user_data(test_data_2)
print(f"成功: {result2['success']}")
if not result2['success']:
    print("发现的错误：")
    for error in result2['errors']:
        print(f"  - {error['field']}: {error['message']}")

# 测试数据3：包含额外字段
print("\n测试3：包含额外字段（会被忽略）")
test_data_3 = {
    "user_id": 3,
    "user_name": "李四",
    "user_email": "lisi@example.com",
    "extra_field_1": "这个会被忽略",
    "extra_field_2": 12345
}
result3 = DataProcessor.process_user_data(test_data_3)
print(f"成功: {result3['success']}")
if result3['success']:
    print(f"处理后的数据（额外字段已忽略）: {result3['data']}")

9. 常见问题

9.1 Q1: Pydantic 和普通 Python 类有什么区别？

普通 Python 类：

class User:
    def __init__(self, name: str, age: int):
        self.name = name
        self.age = age

# 不会验证类型
user = User(name=123, age="不是数字")  # 不会报错，但类型错误

Pydantic 模型：

from pydantic import BaseModel

class User(BaseModel):
    name: str
    age: int

# 自动验证类型
user = User(name=123, age="不是数字")  # 会抛出 ValidationError

9.2 Q2: 如何查看模型的字段信息？

from pydantic import BaseModel

class User(BaseModel):
    name: str
    age: int = 18

# 查看模型结构
print(User.schema())
# 或者
print(User.schema_json(indent=2))

9.3 Q3: 如何处理日期时间？

from pydantic import BaseModel
from datetime import datetime

class Event(BaseModel):
    name: str
    # datetime 类型，Pydantic 会自动解析字符串
    created_at: datetime

# 可以使用字符串创建
event = Event(name="会议", created_at="2024-01-01 12:00:00")
print(event.created_at)  # 自动转换为 datetime 对象

9.4 Q4: 如何只验证部分字段？

from pydantic import BaseModel, ValidationError

class User(BaseModel):
    name: str
    age: int
    email: str

# 使用 validate_assignment=False 可以部分更新
user = User(name="张三", age=25, email="zhangsan@example.com")
# 直接修改字段（默认会验证）
user.age = "不是数字"  # 会抛出错误

# 如果需要部分验证，可以使用 validate() 方法

9.5 Q5: Pydantic 性能如何？

Pydantic 的性能很好，但对于大量数据的验证，可以考虑：

• 使用 validate_assignment=False 关闭赋值验证
• 缓存验证结果
• 对于简单场景，可以考虑使用 dataclasses

10. 总结

1. Pydantic 是什么

   • 基于类型注解的数据验证库
   • 自动验证、转换和清洗数据

2. 主要功能

   • 类型验证：确保数据类型正确
   • 自动转换：尝试将数据转换为正确类型
   • 自定义验证：使用 @validator 定义验证规则
   • 序列化：轻松转换为字典或 JSON

3. 适用场景

   • API 数据验证（如 FastAPI）
   • 配置文件管理
   • 数据清洗和转换
   • 任何需要验证数据的场景

4. 优势

   • 代码简洁：定义一次，自动验证
   • 错误信息清晰：告诉你具体哪里错了
   • 易于维护：修改模型定义即可
   • 类型安全：基于 Python 类型提示