Python类属性与全局变量：何时选择哪种状态管理

图 0：Python 模块全局变量与类属性的状态管理定位概览

在 Python 中，当需要在多次调用或多个执行单元之间共享数据时，开发者通常会在“模块全局变量”与“类属性”之间做出抉择。简明的结论是：全局变量适合跨函数流通且无需派生子类的轻量级环境常量或只读配置；而一旦状态与特定业务实体的生命周期、类型派生、多态重写或实例集群绑定，类属性则是更为安全且内聚的架构选择。

一、底层存储与作用域机制的本质差异

要做出准确的技术选型，必须先看透二者在 Python 解释器内部的存储容器与属性查找逻辑。Python 中一切皆对象，无论是模块还是类，本质上都是拥有独立字典（__dict__）的命名空间容器。

模块全局变量并不是真正意义上穿透全系统的“绝对全局”，而是模块作用域（Module Scope）下的全局。当在模块顶层定义 DB_POOL = None 时，该引用直接注册在当前模块的 globals() 字典中。其他模块若要访问，必须显式通过 import 导入该模块对象；而在函数内部如果要修改该变量的指向，必须显式使用 global 关键字，否则 Python 解释器会默认在当前局部作用域创建一个同名局部变量。

类属性则存储在类的 __dict__ 中。当创建该类的多个实例时，这些实例本身并不复制类属性，而是通过指针保持对所属类对象的引用。当通过实例对象访问一个属性（例如 instance.retry_limit）时，Python 首先在该实例自身的 __dict__ 中查找；若未找到，便沿着类的继承链（MRO，方法解析顺序）向上在类及基类的 __dict__ 中定位。

图 1：Python 模块全局符号表 vs 类的属性解析链（MRO）内存模型对比

二、核心场景深度对比与代码实现

为了清晰展示两者的行为边界，我们通过状态同步、修改影响以及并发隔离三个具体场景进行代码分析。

1. 模块全局变量的适用场景：跨函数的环境常量与只读上下文

当一个状态是天然全局唯一且具有静态声明或极低频写操作特征时，模块级全局变量能提供极佳的简洁度。例如系统版本标识、默认日志级别或模块内的连接池单例：

# module: payment_gateway.py
import logging

# 推荐：全局只读配置或常量（大写表示）
DEFAULT_TIMEOUT: int = 10
MAX_RETRY_COUNT: int = 3

# 轻量级单例资源句柄
_client_instance = None

def get_client():
    global _client_instance
    if _client_instance is None:
        # 延迟初始化单例资源
        _client_instance = initialize_client(timeout=DEFAULT_TIMEOUT)
    return _client_instance

这种模式的优势在于调用方无需实例化任何类，直接通过 from payment_gateway import get_client 即可使用。但其致命缺陷也随之而来：如果两个不同的业务线需要不同的 DEFAULT_TIMEOUT，全局变量将完全无法支持；任何调用方执行 payment_gateway.DEFAULT_TIMEOUT = 30，都将直接影响系统中的所有其他调用方。

2. 类属性的适用场景：类型级状态共享与业务多态继承

当状态与特定的业务模型紧密相关，且需要根据不同的子业务类型进行差异化配置时，类属性表现出强大的扩展性。例如不同级别的任务处理器拥有不同的配额限制：

# 任务基类与业务派生类
class BaseWorker:
    # 类属性：该类型所有实例的默认配置
    concurrency_limit: int = 5
    active_instances_count: int = 0

    def __init__(self, worker_name: str):
        self.worker_name = worker_name
        # 正确修改共享计数：显式指定类名
        self.__class__.active_instances_count += 1

    def close(self):
        self.__class__.active_instances_count -= 1

class VipWorker(BaseWorker):
    # 子类通过类属性覆盖父类配置，不影响 BaseWorker 的其他子类
    concurrency_limit: int = 20

在上述代码中，VipWorker 享受更大的并发配额，而普通 BaseWorker 依然维持配额 5。如果使用模块全局变量，为了实现这种差异化，代码将被迫写满 if worker_type == 'vip' 的分支判断。

三、类属性最严重的陷阱：实例遮蔽与可变对象共享

许多开发者在初次使用类属性进行状态管理时，往往会遭遇两大反直觉的隐蔽错误：实例赋值遮蔽（Shadowing）与可变容器串味（Mutable Object Sharing）。

图 2：类属性最易触发的“实例遮蔽效应”与“可变容器共享篡改”执行细节

为了避免上述问题，在工程实现中必须确立以下编码准则：

• 如果要修改类属性，永远使用类名或 self.__class__ 进行定位：编写 self.__class__.count += 1，而绝不能写 self.count += 1。
• 避免在类属性上直接挂载可变数据类型（如空列表或字典）：如果每个实例需要独立的容器，应在 __init__ 构造函数中初始化 self.items = []；若确需在类级别共享容器，应封装为带线程锁的操作方法。

四、工程架构选型：四大维度的决策推导流程

在实际大型工程项目中，选择全局变量还是类属性，并非单纯的技术习惯问题，而是直接关系到测试成本、代码生命周期与架构可维护性。我们从四个核心维度进行评估：

1. 状态的生命周期与重置便利性（单元测试要求）：测试运行器（如 pytest）通常在同一个 Python 进程中执行数百个用例。如果使用模块全局变量存储业务状态，用例 A 对全局状态的修改很容易污染用例 B，导致难以调试的顺序偶发 Bug。类属性虽然同样跨实例共享，但我们可以很容易通过 setup_method 或类夹具统一重置，甚至直接通过子类化或工厂模式派生独立沙箱。
2. 多实例并存与隔离需求：如果一个系统当前只连接一个数据库，全局变量看似足够；但未来一旦需要引入“双数据源”或“多租户隔离”，全局变量将带来灾难性的重构工作量。而类属性能够与类实例无缝配合，平滑过渡到支持多实例各自覆盖参数的设计。
3. 封装性与修改追溯（可读性与审查）：全局变量的读写分散在各个函数的任意角落，难以通过断点或属性拦截（property / descriptor）来审查改动。而类属性可以通过 @classmethod 配合清晰的入口进行更新，具备明确的责任边界。
4. 并发安全性与上下文传递：无论是全局变量还是类属性，在多线程或多协程环境下修改共享可变对象都必须配备互斥锁（threading.Lock）。对于具有请求生命周期特征的状态（如 Web 请求中的 Request ID），二者均非最佳方案，而应选用 Python 3.7+ 原生的 contextvars.ContextVar。

图 3：从状态性质、业务归属到技术落地的推导决策流程图

五、规范总结与选型矩阵表

为了在团队协作与工程重构中建立统一标准，我们将全局变量与类属性的各项特性汇总为如下对比矩阵：

图 4：Python 状态管理落地规范与边界场景替代方案矩阵