如何让Python单例类在多模块中实例化保持一致？

问题根源 #

你的单例在同模块内正常，但跨模块调用时重复创建实例，核心原因是Python模块的双重加载机制：

• 当直接运行main.py（python main.py）时，该模块会被Python标记为__main__；
• 其他模块通过from main import ServerController导入时，会加载一个全新的main模块实例（命名为main）；
• 这两个模块中的ServerController是完全独立的类对象，各自维护自己的__instance属性，自然会生成多个实例。

解决方案 #

方案1：修复模块导入逻辑（最根本） #

避免直接运行main.py作为程序入口，创建单独的启动文件（比如run.py）：

# run.py
from main import ServerController

if __name__ == "__main__":
    # 初始化单例并执行业务逻辑
    ctrl = ServerController.get_ctrl()
    print("当前实例:", ctrl)

之后通过python run.py启动程序，所有模块导入的main都会指向同一个模块实例，单例的类属性会被共享。

方案2：改用模块级缓存实现单例 #

将实例缓存放在模块级别（而非类属性），模块级变量在整个Python进程中只会初始化一次，不受模块加载方式影响：

# main.py
# 模块级全局缓存
_server_ctrl_instance = None

class ServerController():
    def __init__(self):
        print("创建新实例:", self)
        # 这里添加你的初始化逻辑

    @classmethod
    def get_ctrl(cls):
        global _server_ctrl_instance
        if _server_ctrl_instance is None:
            _server_ctrl_instance = cls()
        return _server_ctrl_instance

方案3：修复装饰器实现（适配类方法） #

针对你尝试的SingletonCache装饰器，修改其调用逻辑以适配类方法的参数传递：

import functools

class SingletonCache:
    def __init__(self, func):
        self.func = func
        self.cache = {}
        functools.update_wrapper(self, func)  # 保留原函数元信息

    def __call__(self, *args, **kwargs):
        # 类方法的第一个参数是类对象cls，以此作为缓存键
        cls = args[0]
        if cls not in self.cache:
            self.cache[cls] = self.func(*args, **kwargs)
        return self.cache[cls]

使用方式：

class ServerController():
    def __new__(cls):
        print("创建新实例:", cls)
        return super().__new__(cls)

    @classmethod
    @SingletonCache
    def get_ctrl(cls):
        return cls()

方案4：正确使用functools.lru_cache #

你之前的functools.cache用法错误，类方法需要以cls作为缓存键，改用lru_cache（cache是lru_cache(maxsize=None)的别名）：

import functools

class ServerController():
    def __new__(cls):
        print("创建新实例:", cls)
        return super().__new__(cls)

    @classmethod
    @functools.lru_cache(maxsize=None)
    def get_ctrl(cls):
        return cls()

该方案会自动缓存每个cls对应的实例，确保跨模块调用时复用同一实例（需先解决模块双重加载问题）。

内容的提问来源于stack exchange，提问作者jie