Python字段验证：描述符协议实现get与set

本文深入探讨了如何利用Python描述符协议（__get__和__set__）实现轻量、可控且健壮的类字段验证，重点剖析了开发者常踩的“__set__未被调用”陷阱——根源在于描述符必须定义为类属性而非实例属性，并严格避免通过instance.__dict__或直接赋值绕过协议；文章不仅给出整数范围验证的最小可行实现，还详解了安全存值（防止递归）、延迟初始化支持、私有存储键生成等关键实践，帮助你在不引入pydantic等重型依赖的前提下，写出既清晰又可靠的验证逻辑。

直接用描述符实现字段验证，比在 __init__ 里写一堆 if 判断更干净，也比依赖第三方库（如 pydantic）更轻量可控——但必须理解 __get__ 和 __set__ 的调用时机与绑定对象，否则容易踩“值没存对”或“验证被绕过”的坑。

描述符的 __set__ 为什么没被调用？

最常见原因是：描述符实例被赋给了类属性，但你误把它当成了实例属性去设值。Python 只有在通过实例访问该属性时，才会触发描述符协议；如果直接对实例对象动态设置同名属性（比如 obj.age = -5），而该实例字典里已存在 'age' 键，就根本不会走到 __set__。

• 确保描述符是定义在类体中（class Person: 下的 age = IntField()），不是在 __init__ 里赋给 self
• 避免在实例上手动写入同名属性：obj.__dict__['age'] = -5 会完全跳过验证
• 若需支持“延迟初始化”，可在描述符 __get__ 中检查 instance.__dict__.get(self.name) 并按需触发默认逻辑

__set__ 里怎么安全地存值而不递归？

描述符要存值，不能直接写 instance.attr = value，否则又会触发自己的 __set__，导致无限递归。标准做法是把值存在实例的 __dict__ 里，用一个带下划线的唯一 key（比如 _IntField_age）隔离。

• 推荐在描述符 __init__ 中生成私有存储名：self.name = f'_{type(self).__name__}_{field_name}'
• 在 __set__ 中用 instance.__dict__[self.name] = validated_value
• 在 __get__ 中先查 instance.__dict__.get(self.name)，不存在再返回默认值或抛错
• 不要用 setattr(instance, self.name, ...) —— 它仍可能触发其他描述符或 property

整数范围验证描述符的最小可用实现

下面是一个带上下限检查的 IntField，它只在赋值时验证，读取时不干预：

class IntField:
    def __init__(self, min_val=None, max_val=None):
        self.min_val = min_val
        self.max_val = max_val
        self.name = None  # 稍后由 __set_name__ 填充
<pre class="brush:php;toolbar:false"><code>def __set_name__(self, owner, name):
    self.name = f'_{name}'

def __get__(self, instance, owner):
    if instance is None:
        return self
    return getattr(instance, self.name, None)

def __set__(self, instance, value):
    if not isinstance(value, int):
        raise TypeError(f'{self.name[1:]} must be an integer')
    if self.min_val is not None and value < self.min_val:
        raise ValueError(f'{self.name[1:]} must be >= {self.min_val}')
    if self.max_val is not None and value > self.max_val:
        raise ValueError(f'{self.name[1:]} must be <= {self.max_val}')
    setattr(instance, self.name, value)</code>

class Person: age = IntField(min_val=0, max_val=150)

注意：__set_name__ 是 Python 3.6+ 提供的钩子，能自动拿到属性名，比手动传参更可靠；没有它就得在类外显式传 IntField('age', ...)，容易出错。

真正难的是处理继承场景下的属性名冲突和多描述符协作——比如一个类同时有 IntField 和 StringField，它们共用同一个 __set_name__ 机制，但存储键不能撞车。这时候得靠命名空间隔离或引入 descriptor 协议的完整生命周期意识，而不是只盯着 __set__。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Python字段验证：描述符协议实现get与set》文章吧，也可关注golang学习网公众号了解相关技术文章。