Python dataclass 怎样定义不可变配置对象

我在把环境变量整理成应用配置时，最希望避免的不是少写几行代码，而是配置对象在服务启动后被某个函数悄悄改掉。Python 的 dataclass 可以用 frozen=True 拒绝直接字段赋值，让配置在创建后保持稳定；但它模拟的是不可变语义，并不等于所有嵌套对象都被冻结。

官方文档：https://docs.python.org/3/library/dataclasses.html

下面用一个小型 AppConfig 说明完整写法：字段在创建时校验，后续修改通过创建新实例完成，列表这类可变嵌套值则改成元组或其他不可变表示。

用 frozen=True 声明配置对象的写法

最小实现只需要在装饰器中传入 frozen=True。下面的例子把端口和超时的检查放在 __post_init__，这样对象一旦构造成功，外部拿到的就是一份已经满足基本约束的配置。

# config.py：配置只在创建时校验，运行期间不直接改字段。
from dataclasses import dataclass

@dataclass(frozen=True)
class AppConfig:
    host: str = "127.0.0.1"
    port: int = 8080
    timeout_seconds: float = 3.0

    def __post_init__(self) -> None:
        # frozen 实例仍可在初始化阶段做检查，但不要把它当成动态配置中心。
        if not 1 

frozen=True 会让 dataclass 为实例提供受限的 __setattr__() 和 __delattr__()。当代码执行 config.port = 9090 时，会得到 FrozenInstanceError，它是 AttributeError 的子类。这里的“不可变”重点是防止普通字段被直接重新绑定。

创建时校验，使用时只读

配置对象适合在程序入口或依赖装配阶段创建一次，再把它传给需要读取配置的函数。校验失败应当让构造过程失败，而不是先创建一个半有效对象，再等业务运行到深处才暴露问题。

# 使用示例：错误配置在构造阶段暴露，正确配置在业务函数中只读。
from dataclasses import FrozenInstanceError

config = AppConfig(host="0.0.0.0", port=9000, timeout_seconds=2.5)
print(config.host, config.port)

try:
    config.port = 9001
except FrozenInstanceError as exc:
    # 这里捕获的是直接改字段的错误；生产代码通常应修正调用方，而不是吞掉异常。
    print(type(exc).__name__)

try:
    AppConfig(port=70000)
except ValueError as exc:
    # 无效端口在创建时被拒绝，避免错误配置进入后续依赖。
    print(exc)

实际项目里不一定要捕获 FrozenInstanceError。示例捕获它只是为了展示边界；更常见的做法是让异常尽早失败，并检查是谁试图修改配置。

frozen 不会自动冻结嵌套列表

这是最容易踩坑的地方。frozen=True 约束的是 dataclass 实例的字段重新赋值。如果字段本身指向一个列表，列表仍然可以调用 append()。配置中需要表达“创建后不变”的集合时，优先使用元组，或者在构造时复制输入并转成元组。

# 不把 list 暴露在配置对象里，避免调用方通过 append 改变内部状态。
from dataclasses import dataclass

@dataclass(frozen=True)
class FeatureConfig:
    enabled_features: tuple[str, ...] = ()

    @classmethod
    def from_names(cls, names: list[str]) -> "FeatureConfig":
        # 复制并转换为 tuple；调用方之后修改 names 不会影响配置内容。
        return cls(enabled_features=tuple(names))

features = ["cache", "metrics"]
config = FeatureConfig.from_names(features)
features.append("debug")
print(config.enabled_features)  # 仍然只有 cache 和 metrics

如果嵌套值必须是字典、列表或自定义可变对象，frozen=True 只能保护字段引用本身，不能提供深度冻结。此时可以在边界层复制数据、转换为元组，或使用专门的只读容器。

需要改配置时创建新实例

冻结配置并不意味着配置永远不能变化，而是把变化从“原地修改”改成“用新对象替换”。标准库的 dataclasses.replace() 会基于原实例创建副本，并把指定字段替换成新值，适合测试或按请求构造一份临时配置。

# 用 replace 产生新配置；旧实例继续保持原值。
from dataclasses import replace

base = AppConfig(host="127.0.0.1", port=8080)
debug_config = replace(base, timeout_seconds=10.0)

print(base.timeout_seconds)         # 3.0
print(debug_config.timeout_seconds) # 10.0

如果配置包含需要重新计算的派生字段，新的实例仍会经过 dataclass 的初始化路径，因此可以继续使用 __post_init__ 做一致性检查。要注意，replace() 是浅层替换；嵌套对象是否安全，仍取决于你是否在创建边界完成复制或不可变转换。

两个容易混淆的问题

frozen=True 能不能让配置对象真正深度不可变？ 不能。它主要阻止实例字段重新绑定；列表、字典等嵌套对象仍可能被修改。需要深度稳定时，从输入边界开始使用元组、只读映射或防御性复制。

frozen=True 会不会影响性能或哈希？ 初始化时会有很小的额外开销，因为字段不能像普通 dataclass 那样直接赋值。默认情况下，eq=True 且 frozen=True 时 dataclass 可以生成哈希方法；只有当字段也具备稳定哈希语义时，才适合把实例放进集合或作为字典键。

我的取舍是：进程级配置、路由参数和测试基线适合用冻结 dataclass 表达；会被频繁逐项修改的表单状态或动态缓存，则不必强行套上 frozen=True。关键是让“创建时校验、使用时只读、修改时换对象”的边界清晰。