@property不能被字段直接覆盖，因其属于运行时计算逻辑而非字段体系；Pydantic会报NameError，正确做法是改用字段+初始化逻辑实现差异化控制。
类字段覆盖父类字段，本质是Python属性查找机制和MRO（方法解析顺序）共同作用的结果，不是“自动替换”，而是“就近遮蔽”。只要子类定义了同名字段（包括实例属性、类属性、方法、@property），在访问该名称时，解释器会优先使用子类定义的版本，跳过父类中同名项。
字段遮蔽发生的典型场景
以下情况都会触发遮蔽，但行为逻辑不同：
-
普通类属性或实例属性：子类直接赋值同名变量（如
name = "child"），会完全屏蔽父类同名类属性；若在__init__中设置self.name = ...，则只影响该实例，不改变类层级遮蔽关系 -
方法（含
__init__）：子类定义同名方法即完成覆盖，调用时不会执行父类版本，除非显式用super() -
@property属性：这是最容易出错的——父类用@property定义计算属性，子类若试图用字段（如Field或普通赋值）覆盖它，Pydantic 会报NameError: Field name "xxx" shadows a BaseModel attribute，因为@property在模型内部被视作“不可覆盖的动态属性”，而非数据字段 -
dataclass字段：子类可定义同名字段，但必须确保父类也用了@dataclass；否则字段不参与继承，子类字段仅属于自身，不构成严格意义上的“覆盖”而是独立定义
为什么 @property 不能被字段直接覆盖？
Pydantic 的 BaseModel 在构建模型时，会将 @property 视为运行时计算逻辑，不属于字段（FieldInfo）体系。当你在子类写：
name_new = Field("foo_bar_foo", alias="name_new")
Claw Code Suite (Python-Only Edition)
下载
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
这只会注册一个新字段，并映射到序列化键 "name_new"，但 c.name_new 访问时仍走属性访问协议，触发父类的 @property 方法，而不是返回你设的默认值。
真正可行的做法是：把原 @property 拆成普通字段 + 初始化逻辑，例如在子类 __init__ 中根据条件赋值，让 name_new 成为真实字段。
安全覆盖字段的推荐方式
想让子类控制某个值的行为（尤其是需要差异化默认值或计算逻辑时），应避免依赖 @property，改用以下结构：
- 父类定义字段（如
name_new: str），不加@property - 在父类
__init__或model_post_init（Pydantic v2）中按需计算并赋值 - 子类重写
__init__或model_post_init，对同一字段赋予不同值或逻辑 - 若需保持接口一致，可在子类中重新定义同名
@property，但内部逻辑完全自控（注意：此时已不是“覆盖”，而是全新实现）
多继承时的遮蔽优先级
当子类继承多个父类（如 class C(A, B):），遮蔽遵循 MRO 顺序：C → A → B → object。同名字段/方法在 A 中定义，就不会再往 B 中查找。可通过 C.mro() 查看实际顺序。若 A 和 B 都定义了 value，则 C().value 总取 A 版本。
