attrs17.2中如何正确使用属性验证？

Question

在使用 attrs 17.2 时，如何正确地为属性添加类型和值的验证？常见的问题是：开发者尝试通过 `validator=` 参数实现复杂校验逻辑，但不清楚内置验证器（如 `validators.instance_of()`、`validators.optional()`）的组合用法，导致运行时错误或验证未生效。此外，自定义验证函数中抛出异常的方式不当，也容易引发意料之外的行为。如何在类属性上正确声明验证器以确保实例化时自动触发校验？

Answer 1

一、理解 attrs 中的属性验证机制

在使用 attrs 17.2 版本时，为类属性添加类型和值的验证是构建健壮数据模型的关键环节。该库通过 attr.ib() 提供了 validator= 参数，允许开发者声明校验逻辑。验证器会在实例化时自动触发，前提是正确绑定到属性上。

基本结构如下：

import attr
from attr import validators as v

@attr.s
class Person:
    name = attr.ib(validator=v.instance_of(str))
    age = attr.ib(validator=v.instance_of(int))

上述代码中，v.instance_of(str) 确保 name 必须为字符串类型，否则抛出 TypeError。这是最基础的类型验证用法。

二、内置验证器的组合与嵌套使用

attrs 提供了多个内置验证器，常见包括：

• validators.instance_of(t)：确保值是某类型的实例
• validators.optional(v)：包装另一个验证器，允许值为 None
• validators.in_(allowed)：限制值必须在指定集合内
• validators.and_(*validators)：组合多个验证器

例如，定义一个可选的整数年龄，且范围在 0 到 150 之间：

age = attr.ib(
    validator=v.optional(
        v.and_(
            v.instance_of(int),
            v.in_(range(0, 151))
        )
    )
)

这种组合方式避免了手动编写冗余判断逻辑，同时保持声明式风格。

三、自定义验证函数的正确实现方式

当内置验证器无法满足需求时，可使用自定义函数。其签名必须为：func(instance, attribute, value) -> None or raises。

错误示例（常见误区）：

def validate_email(attr, value):  # 缺少 instance 参数
    if "@" not in value:
        raise ValueError("Invalid email")

正确写法：

def validate_email(instance, attribute, value):
    if not isinstance(value, str):
        raise TypeError(f"Email must be string, got {type(value)}")
    if "@" not in value:
        raise ValueError("Invalid email format")

email = attr.ib(validator=validate_email)

注意：应抛出 ValueError 或 TypeError，attrs 会捕获并封装为 AttrValidationError。

四、验证器的执行时机与调试策略

所有验证器在调用 __init__ 时由 attr.s 自动生成的构造函数触发。若验证失败，将立即中断实例化。

可通过以下方式调试验证流程：

场景	预期异常	排查建议
类型不符	TypeError	检查是否使用 instance_of
None 值未处理	ValidationError	使用 optional() 包装
自定义函数未执行	无异常但逻辑未生效	确认函数已传入 validator=

五、高级模式：跨字段验证与延迟校验

对于依赖多个属性的复杂逻辑（如密码一致性），需使用 @attr.s 类级别的验证器：

@attr.s
class User:
    password = attr.ib()
    confirm_password = attr.ib()

    @confirm_password.validator
    def check_match(self, attribute, value):
        if self.password != value:
            raise ValueError("Passwords do not match")

此类验证在所有属性赋值后执行，适用于关联性校验。

六、流程图：验证器执行路径分析

graph TD A[实例化对象] --> B{调用 __init__} B --> C[设置各属性值] C --> D[触发每个属性的 validator] D --> E[执行内置或自定义验证] E --> F{验证通过?} F -- 是 --> G[继续下一属性] F -- 否 --> H[抛出异常，终止构造] G --> I[执行类级 validator（如有）] I --> J[返回实例]

该流程清晰展示了从初始化到最终实例生成的完整验证链条。