【Pydantic】如何在 Pydantic 中实现严格模式校验

如何在 Pydantic 中实现严格模式校验

在 Python 数据校验库中，Pydantic 是一个非常受欢迎的选择，因其提供了简单易用且高效的数据验证和解析功能。默认情况下，Pydantic 会在模型实例化时自动将输入数据转换为预定义类型，但在某些应用场景下，我们可能需要更严格的类型校验，确保输入数据完全符合要求，而不进行隐式转换。本文将探讨在 Pydantic 中实现“严格模式”的几种方法，以确保模型的数据校验更加严谨可靠。

为什么需要严格模式？

在很多实际应用中，数据源可能是用户输入、外部 API 响应或者数据库中的数据。这些数据往往是不可靠的，甚至可能会出现类型错误。如果仅依赖隐式转换，可能会导致不符合预期的结果，从而引发逻辑错误。严格模式可以强制要求输入数据必须完全符合预期类型，避免不必要的类型转换，从根本上减少潜在的错误风险。

Pydantic 中的几种严格模式实现方法

1. 使用严格类型

Pydantic 提供了多种内置的严格类型，如 StrictInt, StrictStr, StrictBool 等。与普通类型不同，这些严格类型不允许自动类型转换，确保输入数据严格遵循定义的类型要求。

from pydantic import BaseModel, StrictInt, StrictStr

class MyModel(BaseModel):
    age: StrictInt
    name: StrictStr

# 正确的用例
model = MyModel(age=30, name="John")  # 校验通过

# 错误的用例
model = MyModel(age="30", name=123)  # 抛出 ValidationError，类型不匹配

在这个例子中，StrictInt 和 StrictStr 会严格校验输入的数据类型，输入值不能是字符串或其他可转换类型。

2. 设置全局严格模式

在 Pydantic 2.x 中，可以通过模型的 Config 类开启全局的严格模式。通过设置 strict = True，所有字段都会进入严格模式，禁止隐式的类型转换。

from pydantic import BaseModel

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

    class Config:
        strict = True  # 全局开启严格模式

# 正确的用例
model = MyModel(age=30, name="John")

# 错误的用例
model = MyModel(age="30", name=123)  # 抛出 ValidationError

通过开启全局的严格模式，Pydantic 将不再进行类型推导和转换，这样可以确保输入的数据与模型字段类型严格匹配。

3. 使用 Field 添加字段约束

通过 Pydantic 的 Field 方法，可以为模型字段添加更多的约束条件，比如最小值、最大值、字符串长度等。Field 能让模型校验更加细致。

from pydantic import BaseModel, Field

class MyModel(BaseModel):
    age: int = Field(..., gt=0, lt=120, description="年龄必须在 0 到 120 之间")
    name: str = Field(..., min_length=2, max_length=50)

# 正确的用例
model = MyModel(age=30, name="Alice")

# 错误的用例
model = MyModel(age=-5, name="A")  # 抛出 ValidationError

这里 Field 方法为 age 和 name 字段添加了更多的校验约束，确保输入值不仅要符合类型，还要满足数值范围和字符串长度的限制。

4. 使用 root_validator 校验多个字段

有时，单个字段的校验并不足够，可能需要对多个字段进行交叉校验。例如，在注册系统中，我们需要确保用户输入的密码和确认密码一致。这种情况下可以使用 root_validator。

from pydantic import BaseModel, root_validator

class MyModel(BaseModel):
    password: str
    confirm_password: str

    @root_validator
    def check_password_match(cls, values):
        if values['password'] != values['confirm_password']:
            raise ValueError('Passwords do not match')
        return values

# 正确的用例
model = MyModel(password="123456", confirm_password="123456")

# 错误的用例
model = MyModel(password="123456", confirm_password="654321")  # 抛出 ValidationError

root_validator 允许我们对整个模型的字段进行综合校验，这对于涉及多个字段间相互依赖的场景非常有用。

5. 自定义数据类型

Pydantic 支持自定义数据类型，并允许为其定义自己的校验逻辑。自定义数据类型非常适合那些特定领域的严格数据规则。

from pydantic import BaseModel

class HexColor(str):
    @classmethod
    def __get_validators__(cls):
        yield cls.validate

    @classmethod
    def validate(cls, value):
        if not isinstance(value, str):
            raise TypeError('HexColor must be a string')
        if not value.startswith('#') or len(value) not in {4, 7}:
            raise ValueError('Invalid hex color format')
        return value

class MyModel(BaseModel):
    color: HexColor

# 正确的用例
model = MyModel(color="#123456")

# 错误的用例
model = MyModel(color="123456")  # 抛出 ValidationError

通过自定义类型，我们可以为 HexColor 添加非常具体的规则，并确保这些规则在模型校验时生效。

6. 使用 validate_assignment 实现动态赋值校验

默认情况下，Pydantic 只会在模型实例化时进行校验。如果需要在模型字段更新时重新进行校验，可以通过设置 validate_assignment=True 来实现动态校验。

from pydantic import BaseModel, StrictInt

class MyModel(BaseModel):
    age: StrictInt

    class Config:
        validate_assignment = True  # 开启赋值校验

model = MyModel(age=30)

# 正确的用例
model.age = 25  # 校验通过

# 错误的用例
model.age = "25"  # 抛出 ValidationError

开启 validate_assignment 后，模型字段在被修改时也会触发校验逻辑，确保数据始终符合要求。

7. 使用不可变模型

有些数据在初始化后应保持不可变，以保证数据一致性。通过设置 allow_mutation = False 或 frozen = True 可以实现模型的不可变性。

from pydantic import BaseModel

class MyModel(BaseModel):
    age: int

    class Config:
        frozen = True  # 模型不可变

model = MyModel(age=30)

# model.age = 35  # 抛出 TypeError，模型冻结，字段不可修改

这种设置确保数据一旦创建，模型实例的状态就不能被更改，非常适合处理那些需要保持状态一致性的场景。

8. 严格解析日期和时间类型

Pydantic 默认支持日期和时间类型的解析，但通常会允许字符串自动转换为 datetime 或 date 类型。如果希望禁止自动转换，可以在严格模式下强制要求输入的数据必须是 datetime 或 date 对象。

from pydantic import BaseModel
from datetime import datetime

class MyModel(BaseModel):
    created_at: datetime

    class Config:
        strict = True  # 严格模式，禁止字符串自动解析为 datetime

# 正确的用例
model = MyModel(created_at=datetime.now())

# 错误的用例
model = MyModel(created_at="2023-10-10T00:00:00")  # 抛出 ValidationError

通过严格模式，可以确保日期和时间数据严格符合 datetime 类型，避免字符串的自动转换。

总结

Pydantic 是一个强大且灵活的工具，能够帮助开发者快速构建数据模型并进行高效的数据校验。在某些场景下，默认的类型转换行为可能导致隐式错误，因此引入严格模式显得尤为重要。通过使用 Pydantic 的严格类型、全局严格模式、自定义校验逻辑等，我们可以确保输入数据的精确性，从而大幅提高系统的健壮性。

无论是处理用户输入、API 响应，还是处理数据库中的复杂数据，严格模式校验都可以帮助你构建更安全可靠的应用。如果你在日常开发中遇到类似问题，不妨试试这些严格模式的实现方法，确保你的数据模型更加稳健。