Pydantic 入门：Python 中的类型安全数据模型

Pydantic 是一个强大的 Python 库，利用类型提示提供强健的数据验证和序列化功能。它简化了定义、验证和解析数据模型的过程，使其成为开发者在处理 API、配置文件或任何数据驱动应用时的必备工具。在本文中，我们将探讨 Pydantic 的核心概念，介绍其安装过程，并演示如何创建一个类型安全的 User 模型。

什么是 Pydantic，为什么要使用它？

Pydantic 允许您使用 Python 的类型注解来定义数据模型。它会自动根据这些类型验证数据，确保在运行时的正确性。其主要优点包括：

类型安全：通过最小的样板代码及早捕获类型错误。
数据验证：强制执行字符串长度、数字范围或必填字段等约束。
自动解析：将数据（例如 JSON）转换为 Python 对象。
开发者体验：与 IDE 无缝集成，支持自动补全和类型检查。

Pydantic 在 FastAPI 等框架中被广泛使用，也用于验证配置文件，使其成为现代 Python 开发的首选工具。

安装 Pydantic

要开始使用，请使用 uv 安装 Pydantic，uv 是一个快速现代的 Python 包管理器。打开终端并运行：

uv install pydantic

确保您使用的是 Python 3.7 或更高版本，因为 Pydantic 依赖于最近 Python 版本中引入的类型提示。如果您还没有安装 uv，可以从 uv 的官方文档获取。

基本的 BaseModel 使用

Pydantic 模型通过继承 BaseModel 来定义。模型中的每个字段都带有类型注解，Pydantic 会自动处理验证。

这里是一个简单的例子：

from pydantic import BaseModel


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

# 有效数据
person = Person(name="Alice", age=25)
print(person)  # name='Alice' age=25

# 无效数据
try:


Person(name="Bob", age="thirty")  # 类型错误：年龄应该是一个整数
except ValueError as e:
    print(e)

在这个例子中，Pydantic 确保 name 是一个字符串，age 是一个整数。如果数据不匹配，将引发 ValidationError。

原始类型的类型验证

Pydantic 支持多种原始类型，包括 int、str、bool、float、datetime 等。你还可以使用 Pydantic 的字段选项添加约束。例如：

from pydantic import BaseModel, EmailStr
from datetime import date

class Employee(BaseModel):
    name: str
    email: EmailStr  # 验证电子邮件格式
    is_active: bool
    joined_on: date

employee = Employee(
    name="Charlie",
    email="charlie@example.com",
    is_active=True,
    joined_on="2023-01-15"
)
print(employee)

在这里，EmailStr 确保电子邮件字段是一个有效的电子邮件地址，而 date 将字符串 "2023-01-15" 解析为一个 datetime.date 对象。Pydantic 的类型强制转换会自动将兼容的输入（例如，将字符串转换为 date）进行转换。

错误处理和验证错误

当验证失败时，Pydantic 会引发一个 ValidationError，并提供详细的错误信息。这使得调试问题或提供用户友好的反馈变得容易。

示例：

from pydantic import BaseModel, ValidationError

class Product(BaseModel):
    id: int
    name: str
    price: float

try:


产品(id="not-an-int", name="笔记本电脑", price=999.99)
except ValidationError as e:
    print(e)

输出将类似于：

验证错误信息如下：

1 validation error for Product
id
  value is not a valid integer (type=type_error.integer)

ValidationError 提供了清晰的错误描述，包括字段和错误类型。

示例：定义用户模型

让我们通过定义一个 User 模型并从字典中解析数据，将所有内容结合起来，这通常是在处理来自 API 的 JSON 数据时所做的。


from pydantic import BaseModel, EmailStr, ValidationError
from datetime import date

class User(BaseModel):
    id: int
    username: str
    email: EmailStr
    birth_date: date
    is_active: bool = True  # 默认值

# 示例数据（例如，来自API）
user_data = {
    "id": 1,


{
    "username": "johndoe",
    "email": "john.doe@example.com",
    "birth_date": "1990-05-20",
    "is_active": False
}

try:
    # 解析并验证字典
    user = User(**user_data)
    print(user)
    print(user.dict())  # 转换回字典


except ValidationError as e:
    print("验证失败：", e)

输出:

id=1 username='johndoe' email='john.doe@example.com' birth_date=datetime.date(1990, 5, 20) is_active=False
{'id': 1, 'username': 'johndoe', 'email': 'john.doe@example.com', 'birth_date': datetime.date(1990, 5, 20), 'is_active': False}

在这个例子中：