6 Pydantic 模型简介

最新推荐文章于 2025-07-28 22:34:03 发布

原创最新推荐文章于 2025-07-28 22:34:03 发布 · 1k 阅读

本内容遵循CC 4.0 BY-SA版权协议

在 Python 中，数据验证和序列化是构建 Web 应用、API 和微服务时常见的需求。Pydantic 是一个用于数据验证和设置管理的 Python 库，广泛应用于 FastAPI 中。它允许开发者通过简单的 Python 类来定义数据结构，自动进行数据验证、转换，并生成清晰、易用的接口。

本文将介绍 Pydantic 模型的基础知识，包括如何定义模型、进行数据验证和转换、以及如何使用 Pydantic 的其他特性。

1. 安装 Pydantic

要使用 Pydantic，我们首先需要安装它。你可以通过以下命令进行安装：


pip install pydantic

2. Pydantic 基本模型定义

Pydantic 的核心功能是通过创建继承自 pydantic.BaseModel 的类来定义数据模型。这个类提供了自动的数据验证、序列化和反序列化功能。

2.1 定义一个简单的模型

首先，定义一个简单的 Pydantic 模型来描述一个用户信息：

from pydantic import BaseModel

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

在这个例子中，User 类继承自 BaseModel，定义了三个字段：name（字符串类型）、age（整数类型）和 email（字符串类型）。

2.2 创建模型实例

你可以通过传入字典或者关键字参数来创建 Pydantic 模型实例：

user = User(name="John Doe", age=30, email="john.doe@example.com")
print(user)

这将输出：


name='John Doe' age=30 email='john.doe@example.com'

Pydantic 自动将数据转换为相应的类型，并且可以通过模型实例访问各个字段。

3. 数据验证

Pydantic 会根据字段类型自动进行数据验证。如果传入的数据不符合指定类型，Pydantic 会抛出 ValidationError。

3.1 示例：验证数据类型

from pydantic import ValidationError

try:
    user = User(name="John Doe", age="30", email="john.doe@example.com")
except ValidationError as e:
    print(e)

输出：

1 validation error for User
age
  str type expected (type=value_error.str)

在这个例子中，我们传入了字符串 "30" 给 age 字段，而 age 期望是一个整数。因此，Pydantic 会抛出一个验证错误，并指出字段类型不匹配。

3.2 自定义验证器

你还可以使用 @validator 装饰器为模型字段添加自定义验证逻辑。例如，验证邮箱是否符合基本格式：

from pydantic import validator

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

    @validator('email')
    def email_must_contain_at_symbol(cls, v):
        if '@' not in v:
            raise ValueError('Email must contain @ symbol')
        return v

如果邮箱地址不符合验证规则，Pydantic 会抛出 ValidationError。

4. 数据转换

Pydantic 模型不仅能够验证数据类型，还能够将数据转换为正确的类型。例如，将字符串 "30" 自动转换为整数 30。

python复制编辑user = User(name="Jane Doe", age="30", email="jane.doe@example.com")
print(user.age)  # 输出: 30 (整数类型)

5. 模型的序列化与反序列化

Pydantic 模型提供了 dict() 和 json() 方法，方便将模型数据转换为字典或 JSON 格式。

5.1 转换为字典

user = User(name="Alice", age=25, email="alice@example.com")
user_dict = user.dict()
print(user_dict)

输出：

{'name': 'Alice', 'age': 25, 'email': 'alice@example.com'}

5.2 转换为 JSON

ser_json = user.json()
print(user_json)

输出：

{"name": "Alice", "age": 25, "email": "alice@example.com"}

json() 方法返回一个 JSON 格式的字符串，可以方便地与 Web 应用和 API 进行交互。

6. 嵌套模型

Pydantic 支持嵌套模型，你可以定义一个模型中的字段为其他 Pydantic 模型。

6.1 示例：嵌套模型

from typing import List

class Address(BaseModel):
    street: str
    city: str
    postal_code: str

class User(BaseModel):
    name: str
    age: int
    email: str
    addresses: List[Address]

# 创建一个用户和地址的实例
user_data = {
    'name': 'Bob',
    'age': 40,
    'email': 'bob@example.com',
    'addresses': [
        {'street': '123 Main St', 'city': 'Springfield', 'postal_code': '12345'},
        {'street': '456 Oak St', 'city': 'Shelbyville', 'postal_code': '67890'}
    ]
}

user = User(**user_data)
print(user)

输出：


name='Bob' age=40 email='bob@example.com' addresses=[Address(street='123 Main St', city='Springfield', postal_code='12345'), Address(street='456 Oak St', city='Shelbyville', postal_code='67890')]