在 Python 中使用 Pydantic 的最佳实践

由 Mux 主办的 DEV 全球展示挑战赛：展示你的项目！

Pydantic 是一个 Python 库，它使用类型提示简化数据验证。它确保数据完整性，并提供了一种简便的方法来创建具有自动类型检查和验证功能的数据模型。

在软件应用中，可靠的数据验证对于防止错误、安全问题和不可预测的行为至关重要。

本指南提供了在 Python 项目中使用 Pydantic 的最佳实践，涵盖模型定义、数据验证、错误处理和性能优化。

安装 Pydantic

要安装 Pydantic，请使用 Python 包安装程序 pip，命令如下：

pip install pydantic

此命令安装 Pydantic 及其依赖项。

基本用法

通过创建继承自 BaseModel 的类来创建 Pydantic 模型。使用 Python 类型注解来指定每个字段的类型：

from pydantic import BaseModel

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

Pydantic 支持多种字段类型，包括 int、str、float、bool、list 和 dict。您还可以定义嵌套模型和自定义类型：

from typing import List, Optional
from pydantic import BaseModel

class Address(BaseModel):
    street: str
    city: str
    zip_code: Optional[str] = None

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

定义好 Pydantic 模型后，通过提供所需数据来创建实例。Pydantic 将验证数据，如果任何字段不符合指定要求，则会引发错误：

user = User(
    id=1,
    name="John Doe",
    email="john.doe@example.com",
    addresses=[{"street": "123 Main St", "city": "Anytown", "zip_code": "12345"}]
)

print(user)

# Output:
# id=1 name='John Doe' email='john.doe@example.com' age=None addresses=[Address(street='123 Main St', city='Anytown', zip_code='12345')]

定义皮丹模型

Pydantic 模型使用 Python 类型注解来定义数据字段类型。

它们支持多种内置类型，包括：

基本类型：str、int、float、bool
集合类型：列表、元组、集合、字典
可选类型：类型模块中为字段提供的可选类型，这些字段的值为 None。
联合类型：类型模块中的联合类型可以指定字段为以下几种类型之一。

例子：

from typing import List, Dict, Optional, Union
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    tags: List[str]
    metadata: Dict[str, Union[str, int, float]]

class Order(BaseModel):
    order_id: int
    items: List[Item]
    discount: Optional[float] = None

自定义类型

除了内置类型之外，您还可以使用 Pydantic 的 conint、constr 和其他约束函数定义自定义类型。

这些功能允许您添加额外的验证规则，例如字符串的长度限制或整数的值范围。

例子：

from pydantic import BaseModel, conint, constr

class Product(BaseModel):
    name: constr(min_length=2, max_length=50)
    quantity: conint(gt=0, le=1000)
    price: float

product = Product(name="Laptop", quantity=5, price=999.99)

必填字段与选填字段

默认情况下，Pydantic 模型中的字段是必需的，除非明确标记为可选。

如果在模型实例化过程中缺少必填字段，Pydantic 将引发 ValidationError。

例子：

from pydantic import BaseModel

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

user = User(id=1, name="John Doe")


# Output
#  Field required [type=missing, input_value={'id': 1, 'name': 'John Doe'}, input_type=dict]

带默认值的可选字段

可以使用 typing 模块中的 Optional 功能并提供默认值，使字段成为可选字段。

例子：

from pydantic import BaseModel
from typing import Optional

class User(BaseModel):
    id: int
    name: str
    email: Optional[str] = None

user = User(id=1, name="John Doe")

在这个例子中，电子邮件地址是可选的，如果未提供，则默认为 None。

嵌套模型

Pydantic 允许模型相互嵌套，从而实现复杂的数据结构。

嵌套模型被定义为其他模型的字段，从而在多个层面上确保数据的完整性和验证。

例子：

from pydantic import BaseModel
from typing import Optional, List


class Address(BaseModel):
    street: str
    city: str
    zip_code: Optional[str] = None

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

user = User(
    id=1,
    name="John Doe",
    email="john.doe@example.com",
    addresses=[{"street": "123 Main St", "city": "Anytown"}]
)

管理嵌套数据的最佳实践

在使用嵌套模型时，务必注意以下几点：

逐级验证数据：确保每个嵌套模型都有自己的验证规则和约束。
使用清晰一致的命名规则：这可以使您的数据结构更易于阅读和维护。
保持模型简洁：避免过于复杂的嵌套结构。如果模型过于复杂，请考虑将其拆分为更小、更易于管理的组件。

数据验证

Pydantic 包含一组内置验证器，可自动处理常见的数据验证任务。

这些验证者包括：

类型验证：确保字段与指定的类型注释（例如，int、str、list）匹配。
范围验证：使用 conint、constr、confloat 等约束强制执行值范围和长度。
格式验证：检查特定格式，例如 EmailStr，以验证电子邮件地址。
集合验证：确保集合（例如列表、字典）中的元素符合指定的类型和约束。

这些验证器简化了确保模型中数据完整性和一致性的过程。

以下是一些演示内置验证器的示例：

from pydantic import BaseModel, EmailStr, conint, constr

class User(BaseModel):
    id: conint(gt=0)  # id must be greater than 0
    name: constr(min_length=2, max_length=50)  # name must be between 2 and 50 characters
    email: EmailStr  # email must be a valid email address
    age: conint(ge=18)  # age must be 18 or older

user = User(id=1, name="John Doe", email="john.doe@example.com", age=25)

在这个例子中，User 模型使用内置验证器来确保 id 大于 0，姓名长度在 2 到 50 个字符之间，电子邮件地址有效，年龄大于等于 18 岁。
要使用电子邮件验证器，您需要为 pydantic 安装一个扩展：

pip install pydantic[email]

自定义验证器

Pydantic 允许您定义自定义验证器，以实现更复杂的验证逻辑。

自定义验证器可以通过模型类中的 @field_validator 装饰器来定义。

自定义验证器示例：

from pydantic import BaseModel, field_validator


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

    @field_validator('price')
    def price_must_be_positive(cls, value):
        if value <= 0:
            raise ValueError('Price must be positive')
        return value

product = Product(name="Laptop", price=999.99)

这里，price_must_be_positive 验证器确保价格字段为正数。

当您使用 `@field_validator` 装饰器在模型中定义自定义验证器时，它们会自动注册。验证器可以应用于单个字段，也可以应用于多个字段。

注册多个字段验证器的示例：

from pydantic import BaseModel, field_validator


class Person(BaseModel):
    first_name: str
    last_name: str

    @field_validator('first_name', 'last_name')
    def names_cannot_be_empty(cls, value):
        if not value:
            raise ValueError('Name fields cannot be empty')
        return value

person = Person(first_name="John", last_name="Doe")

在这个例子中，names_cannot_be_empty 验证器确保 first_name 和 last_name 字段都不为空。

使用配置类

Pydantic 模型可以使用内部 Config 类进行自定义。

此类允许您设置影响模型行为的各种配置选项，例如验证规则、JSON 序列化等。

配置类示例：

from pydantic import BaseModel

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

    class Config:
        str_strip_whitespace = True  # Strip whitespace from strings
        str_min_length = 1  # Minimum length for any string field

user = User(id=1, name="  John Doe  ", email="john.doe@example.com")

print(user)

# Output:
# id=1 name='John Doe' email='john.doe@example.com'

在这个例子中，Config 类用于从字符串字段中删除空格，并强制任何字符串字段的最小长度为 1。

Pydantic 的 Config 类中的一些常见配置选项包括：

str_strip_whitespace：自动从字符串字段中删除前导和尾随空格。
str_min_length：设置任何字符串字段的最小长度。
validate_default：验证所有字段，即使是具有默认值的字段。
validate_assignment：启用对模型属性赋值的验证。
use_enum_values：直接使用枚举值而不是枚举实例。
json_encoders：为特定类型定义自定义 JSON 编码器。

错误处理

当 Pydantic 发现数据不符合模型的模式时，它会引发 ValidationError。

此错误信息提供了有关问题的详细信息，包括字段名称、错误值和问题描述。

以下是默认错误消息的结构示例：

from pydantic import BaseModel, ValidationError, EmailStr

class User(BaseModel):
    id: int
    name: str
    email: EmailStr

try:
    user = User(id='one', name='John Doe', email='invalid-email')
except ValidationError as e:
    print(e.json())

# Output:
# [{"type":"int_parsing","loc":["id"],"msg":"Input should be a valid integer, unable to parse string as an integer","input":"one","url":"https://errors.pydantic.dev/2.8/v/int_parsing"},{"type":"value_error","loc":["email"],"msg":"value is not a valid email address: An email address must have an @-sign.","input":"invalid-email","ctx":{"reason":"An email address must have an @-sign."},"url":"https://errors.pydantic.dev/2.8/v/value_error"}]

在这个例子中，错误信息会提示 id 必须是整数，email 必须是有效的电子邮件地址。

自定义错误消息

Pydantic 允许您通过在验证器中引发带有自定义消息的异常或设置自定义配置来自定义特定字段的错误消息。

以下是一个自定义错误消息的示例：

from pydantic import BaseModel, ValidationError, field_validator

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

    @field_validator('price')
    def price_must_be_positive(cls, value):
        if value <= 0:
            raise ValueError('Price must be a positive number')
        return value

try:
    product = Product(name='Laptop', price=-1000)
except ValidationError as e:
    print(e.json())

# Output:
# [{"type":"value_error","loc":["price"],"msg":"Value error, Price must be a positive number","input":-1000,"ctx":{"error":"Price must be a positive number"},"url":"https://errors.pydantic.dev/2.8/v/value_error"}]

在这个例子中，价格的错误信息经过自定义，表明价格必须为正数。

错误报告最佳实践

有效的错误报告包括向用户或开发人员提供清晰、简洁且可操作的反馈。

以下是一些最佳实践：

记录错误：使用日志机制记录验证错误，以便进行调试和监控。
返回用户友好的消息：向最终用户显示错误时，避免使用技术术语。相反，应提供清晰的说明，指导用户如何更正数据。
汇总错误：当多个字段无效时，将错误汇总到一个响应中，以帮助用户一次性纠正所有问题。
使用一致的格式：确保应用程序中的错误信息采用一致的格式，以便于处理和理解。

错误报告最佳实践示例：

from pydantic import BaseModel, ValidationError, EmailStr
import logging

logging.basicConfig(level=logging.INFO)

class User(BaseModel):
    id: int
    name: str
    email: EmailStr

def create_user(data):
    try:
        user = User(**data)
        return user
    except ValidationError as e:
        logging.error("Validation error: %s", e.json())
        return {"error": "Invalid data provided", "details": e.errors()}

user_data = {'id': 'one', 'name': 'John Doe', 'email': 'invalid-email'}
response = create_user(user_data)
print(response)

# Output:
# ERROR:root:Validation error: [{"type":"int_parsing","loc":["id"],"msg":"Input should be a valid integer, unable to parse string as an integer","input":"one","url":"https://errors.pydantic.dev/2.8/v/int_parsing"},{"type":"value_error","loc":["email"],"msg":"value is not a valid email address: An email address must have an @-sign.","input":"invalid-email","ctx":{"reason":"An email address must have an @-sign."},"url":"https://errors.pydantic.dev/2.8/v/value_error"}]
# {'error': 'Invalid data provided', 'details': [{'type': 'int_parsing', 'loc': ('id',), 'msg': 'Input should be a valid integer, unable to parse string as an integer', 'input': 'one', 'url': 'https://errors.pydantic.dev/2.8/v/int_parsing'}, {'type': 'value_error', 'loc': ('email',), 'msg': 'value is not a valid email address: An email address must have an @-sign.', 'input': 'invalid-email', 'ctx': {'reason': 'An email address must have an @-sign.'}}]}

在这个例子中，验证错误会被记录下来，并返回用户友好的错误消息，这有助于保持应用程序的稳定性，并为用户提供有用的反馈。

性能考量

延迟初始化是一种将对象的创建推迟到需要它时才进行的技术。

在 Pydantic 中，这对于计算或获取成本较高的字段的模型非常有用。通过延迟初始化这些字段，可以减少初始加载时间并提高性能。

延迟初始化示例：

from pydantic import BaseModel
from functools import lru_cache

class DataModel(BaseModel):
    name: str
    expensive_computation: str = None

    @property
    @lru_cache(maxsize=1)
    def expensive_computation(self):
        # Simulate an expensive computation
        result = "Computed Value"
        return result

data_model = DataModel(name="Test")
print(data_model.expensive_computation)

在这个例子中，expensive_computation 字段仅在第一次访问时计算，从而减少了模型初始化期间不必要的计算。

冗余验证

Pydantic模型在初始化过程中会自动验证数据。

但是，如果您知道某些数据已经过验证，或者在某些情况下验证并非必要，则可以禁用验证以提高性能。

这可以通过使用 model_construct 方法来实现，该方法会绕过验证：

避免冗余验证的示例：

from pydantic import BaseModel

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

# Constructing a User instance without validation
data = {'id': 1, 'name': 'John Doe', 'email': 'john.doe@example.com'}
user = User.model_construct(**data)

在这个例子中，User.model_construct 用于创建一个 User 实例而不触发验证，这在代码中对性能要求较高的部分非常有用。

高效数据解析

处理大型数据集或高吞吐量系统时，高效解析原始数据至关重要。

Pydantic 提供了 model_validate_json 方法，该方法可用于将 JSON 或其他序列化数据格式直接解析为 Pydantic 模型。

高效数据解析示例：

from pydantic import BaseModel

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

json_data = '{"id": 1, "name": "John Doe", "email": "john.doe@example.com"}'
user = User.model_validate_json(json_data)
print(user)

在这个例子中，model_validate_json 直接将 JSON 数据解析为 User 模型，提供了一种更高效的方式来处理序列化数据。

控制验证

Pydantic 模型可以配置为仅在必要时验证数据。

Config 类中的 validate_default 和 validate_assignment 选项控制何时进行验证，这有助于提高性能：

validate_default：设置为 False 时，仅验证初始化期间设置的字段。
validate_assignment：设置为 True 时，将在模型创建后对字段赋值执行验证。

配置示例：

from pydantic import BaseModel

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

    class Config:
        validate_default = False  # Only validate fields set during initialization
        validate_assignment = True  # Validate fields on assignment

user = User(id=1, name="John Doe", email="john.doe@example.com")
user.email = "new.email@example.com"  # This assignment will trigger validation

在本例中，validate_default 设置为 False，以避免在初始化期间进行不必要的验证；validate_assignment 设置为 True，以确保在更新字段时对其进行验证。

设置管理

Pydantic 的 BaseSettings 类旨在管理应用程序设置，支持环境变量加载和类型验证。

这有助于为不同的环境（例如，开发、测试、生产）配置应用程序。

请参考以下 .env 文件：

database_url=db
secret_key=sk
debug=False

使用 BaseSettings 的示例：

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    database_url: str
    secret_key: str
    debug: bool = False

    class Config:
        env_file = ".env"

settings = Settings()
print(settings.model_dump())

# Output:
# {'database_url': 'db', 'secret_key': 'sk', 'debug': False}

在这个例子中，设置是从环境变量加载的，Config 类指定可以从 .env 文件加载变量。

要使用 BaseSettings，您需要安装一个额外的软件包：

pip install pydantic-settings

有效管理环境涉及以下几个最佳实践：

使用环境变量：将配置值存储在环境变量中，以防止敏感数据进入代码库。
提供默认值：为配置设置定义合理的默认值，以确保应用程序以最少的配置运行。
分离环境：对不同的环境使用不同的配置文件或环境变量（例如，.env.development、.env.production）。
验证设置：使用 Pydantic 的验证功能，确保所有设置都正确输入且在可接受的范围内。

常见陷阱及避免方法

使用 Pydantic 时一个常见的错误是错误地应用类型注解，这可能会导致验证错误或意外行为。

以下是一些常见的错误及其解决方法：

误用联合类型：错误地使用联合类型会使类型验证和处理变得复杂。
没有默认值的可选字段：忘记为可选字段提供默认值可能会导致值为 None，从而导致应用程序出错。
类型注解错误：为字段分配错误的类型会导致验证失败。例如，将应该为 int 类型的字段赋值为 str。

忽略性能影响

使用 Pydantic 时忽略性能影响可能会导致应用程序运行缓慢，尤其是在处理大型数据集或频繁实例化模型时。

以下是一些避免性能瓶颈的策略：

利用配置选项：使用 Pydantic 的配置选项，如 validate_default 和 validate_assignment，来控制何时进行验证。
优化嵌套模型：在使用嵌套模型时，请确保不要过度验证或重复验证逻辑。
使用高效的解析方法：利用 model_validate_json 和 model_validate 进行高效的数据解析。
避免不必要的验证：当已知数据有效时，使用 model_construct 方法创建无需验证的模型。

模型过于复杂

过度复杂化的 Pydantic 模型会使其难以维护和理解。

以下是一些保持模型简洁易维护的技巧：

为您的模型编写文档：使用文档字符串和注释来解释模型中嵌入的复杂验证规则或业务逻辑。
适当封装逻辑：将验证和业务逻辑放在适当的模型方法或外部实用程序中，以避免模型定义混乱。
谨慎使用继承：虽然继承可以促进代码重用，但过度使用会使模型层次结构变得复杂且难以理解。
避免过度嵌套：嵌套过深的模型难以管理。应尽量保持适当的嵌套层级。

结论

本指南涵盖了在 Python 项目中有效使用 Pydantic 的各种最佳实践。

我们首先学习了 Pydantic 的入门基础知识，包括安装、基本用法和定义模型。然后，我们深入探讨了自定义类型、序列化和反序列化以及设置管理等高级功能。

重点关注关键性能方面的考虑因素，例如优化模型初始化和高效数据解析，以确保您的应用程序流畅运行。

我们还讨论了常见的陷阱，例如误用类型注解、忽略性能影响和过度复杂化模型，并提供了避免这些陷阱的策略。

将这些最佳实践应用到您的实际项目中，将有助于您充分发挥 Pydantic 的强大功能，使您的代码更加健壮、易于维护和性能更佳。

文章来源：https://dev.to/devasservice/best-practices-for-using-pydantic-in-python-2021

菜单

分享

Python DEV 全球展示挑战赛（由 Mux 呈现）：Pitch Your Projects! 中 Pydantic 的最佳实践：展示你的项目！