pydantic 默认的 `allow_mutation` 配置仅作用于实例字段的不可变性。本文深入探讨了如何在 pydantic 中实现类字段的不可变性。通过自定义 metaclass 并重写 `__setattr__` 方法，我们可以有效地阻止类属性在定义后被修改，从而确保类级别的字段具有不可变性。文章提供了详细的代码示例，并强调了此高级技术的使用注意事项。
在 Pydantic 模型设计中，有时我们需要确保某些字段在模型实例化后或类定义后不可被修改，以维护数据的完整性和一致性。Pydantic 提供了一种内置机制来处理实例字段的不可变性，但对于类字段（即直接定义在类上的属性），则需要更高级的元编程技术来实现。
Pydantic 实例字段的不可变性
Pydantic 提供了 Config 类中的 allow_mutation 配置项，用于控制模型实例的字段是否可变。当 allow_mutation 设置为 False 时，一旦模型实例被创建，其字段将不可被重新赋值。
示例代码：
from pydantic import BaseModel, Field
class ImmutableInstanceModel(BaseModel):
name: str = Field(default="My Name")
age: int = Field(default=25)
class Config:
allow_mutation = False # 禁止实例字段修改
# 创建模型实例
m = ImmutableInstanceModel()
print(f"初始实例值 - Name: {m.name}, Age: {m.age}")
# 尝试修改实例字段，这将引发ValidationError
try:
m.age = 100
except Exception as e:
print(f"尝试修改实例字段失败: {e}")
# 验证类字段仍然可变
ImmutableInstanceModel.age = 50 # 直接修改类属性
print(f"修改类属性后 - ImmutableInstanceModel.age: {ImmutableInstanceModel.age}")输出分析：
上述代码中，m.age = 100 会因为 allow_mutation = False 而抛出 ValidationError，这表明实例字段的不可变性已生效。然而，ImmutableInstanceModel.age = 50 这行代码却能够成功执行，直接修改了类上的 age 属性。这说明 allow_mutation 配置只对模型实例的属性有效，无法阻止直接修改类本身的属性。
实现 Pydantic 类字段的不可变性：Metaclass 方法
要实现 Pydantic 类字段的不可变性，我们需要在类创建或属性设置的更底层进行干预。Python 的 Metaclass（元类）正是为此目的而生。Metaclass 是创建类的类，通过自定义 Metaclass，我们可以控制类的创建过程和行为，包括属性的设置。
Pydantic 模型本身就是通过其内部的 ModelMetaclass 创建的。我们可以继承 ModelMetaclass 并重写其 __setattr__ 方法，以在类属性被设置时进行拦截和验证。
核心思路：
- 定义一个继承自 pydantic.main.ModelMetaclass 的自定义 Metaclass。
- 在该 Metaclass 中，维护一个列表 IMMUTABLE_ATTRS，用于存放需要保护的类属性名称。
- 重写 Metaclass 的 __setattr__ 方法。当尝试设置 Metaclass 实例（即 Pydantic 类本身）的属性时，__setattr__ 会被调用。
- 在 __setattr__ 方法中，检查正在设置的属性名称是否在 IMMUTABLE_ATTRS 列表中。如果是，则抛出错误阻止修改；否则，调用父类的 __setattr__ 方法执行正常的属性设置。
代码示例：
from pydantic import BaseModel, Field
from pydantic.main import ModelMetaclass
# 1. 定义自定义Metaclass
class ImmutableMeta(ModelMetaclass):
# 2. 定义需要保护的类属性列表
IMMUTABLE_ATTRS = ['_name']
# 3. 重写__setattr__方法，在类属性被设置时进行拦截
def __setattr__(cls, name, value):
# 检查属性是否已存在，并且是否在不可变列表中
if hasattr(cls, name) and name in cls.IMMUTABLE_ATTRS:
raise AssertionError(f"无法修改类属性 '{name}'，因为它被声明为不可变。")
super().__setattr__(cls, name, value) # 调用父类方法进行属性设置
# 4. 将Metaclass应用于Pydantic模型
class ImmutableModel(BaseModel, metaclass=ImmutableMeta):
# 这是一个受Metaclass保护的类属性
_name: str = '这是一个不可变的类属性'
# 这是一个普通的实例字段，受allow_mutation=False保护
instance_name: str = Field(default="这是一个不可变的实例字段")
class Config:
allow_mutation = False # 确保实例字段也不可变
print("--- 验证类字段不可变性 ---")
print(f"初始类属性 _name: {ImmutableModel._name}")
# 尝试修改受保护的类属性，这将引发AssertionError
try:
ImmutableModel._name = '新名称'
except AssertionError as e:
print(f"尝试修改类属性 _name 失败: {e}")
print(f"修改失败后类属性 _name: {ImmutableModel._name}")
print("\n--- 验证实例字段不可变性 ---")
m = ImmutableModel()
print(f"初始实例字段 instance_name: {m.instance_name}")
# 尝试修改实例字段，这将引发ValidationError
try:
m.instance_name = '新的实例名称'
except Exception as e:
print(f"尝试修改实例字段 instance_name 失败: {e}")
print(f"修改失败后实例字段 instance_name: {m.instance_name}")
# 尝试通过实例修改类属性，这是不允许的（Pydantic默认行为）
try:
m._name = '通过实例修改类属性'
except AttributeError as e: # Pydantic实例通常不允许直接修改类属性
print(f"尝试通过实例修改类属性 _name 失败: {e}")输出分析：
- 当我们尝试执行 ImmutableModel._name = '新名称' 时，ImmutableMeta 的 __setattr__ 方法会被触发，检测到 _name 在 IMMUTABLE_ATTRS 中，并抛出 AssertionError，成功阻止了类属性的修改。
- m.instance_name = '新的实例名称' 依然会因为 Config.allow_mutation = False 而抛出 ValidationError，验证了实例字段的不可变性。
- m._name = '通过实例修改类属性' 尝试通过实例修改类属性，这在 Pydantic 中通常会被阻止（除非特殊设计），并可能引发 AttributeError。
通过这种 Metaclass 的方法，我们成功地为 Pydantic 模型实现了类字段的不可变性，使其在类级别也保持数据的完整性。
注意事项与潜在风险
使用 Metaclass 是一种强大的元编程技术，但其使用需谨慎，尤其是在修改框架内部机制时：
- 复杂性增加： Metaclass 会增加代码的复杂性和理解难度，可能不适合所有项目。
- 兼容性风险： 此方法通过覆盖 Pydantic 内部的 ModelMetaclass 功能来实现。Pydantic 未来版本的更新可能会改变 ModelMetaclass 的内部实现，导致此自定义 Metaclass 出现兼容性问题或产生意想不到的副作用。
- 调试难度： 当出现问题时，涉及 Metaclass 的代码通常更难调试。
- 替代方案： 在考虑使用 Metaclass 之前，请评估是否有其他更简单、更符合 Pydantic 设计哲学的方法可以满足需求。例如，对于一些简单的类级别常量，直接使用 Python 的 property 装饰器或者将它们定义为模块级别的常量可能更为合适。
建议：
- 在生产环境中使用此方法前，务必进行充分的测试，并理解其对 Pydantic 模型行为的深层影响。
- 清晰地注释 Metaclass 的作用和意图，方便团队成员理解和维护。
- 将 IMMUTABLE_ATTRS 列表设计得清晰明了，避免误保护或漏保护。
总结
本文详细介绍了如何在 Pydantic 模型中实现类字段的不可变性。虽然 Pydantic 内置的 allow_mutation 配置仅作用于实例字段，但通过自定义 Metaclass 并重写其 __setattr__ 方法，我们可以有效地在类级别阻止特定属性的修改。这种方法为需要严格控制类级别数据完整性的场景提供了一种强大的解决方案。然而，鉴于其对框架内部机制的修改，建议在充分理解和测试后谨慎使用。
