Qt 设计模式：单例模式

系列：Qt / VTK 设计模式 · Qt 07/11
参考：Qt 6 QCoreApplication、Q_GLOBAL_STATIC

---

引子

整个 GUI 应用程序中只能有一个唯一的全局事件循环与应用管理者——QApplication。在代码的任何角落，通过 QCoreApplication::instance() 或快捷宏 qApp 都能随时访问这个唯一实例。

这就是单例模式（Singleton Pattern）：保证一个类仅有一个实例，并提供一个访问它的全局访问点。在 Qt 中，单例模式既被用于底层全局管理（如事件循环、全局剪贴板、渲染样式），也有 Q_GLOBAL_STATIC 这类跨模块惰性初始化的工业级实现。

---

核心痛点与 GoF 单例结构

痛点场景：全局变量与初始化顺序灾难

// 坏方案：直接使用全局变量
extern Settings g_settings; 
// 痛点 1: C++ 静态变量跨编译单元初始化顺序不确定 (Static Initialization Order Fiasco)
// 痛点 2: 多线程并发访问没有安全性保障
// 痛点 3: 无法做到“按需延迟加载 (Lazy Initialization)”

GoF 单例模式结构映射

单例实现角色	Qt 对应实现	职责说明
单例类 (Singleton)	QCoreApplication / QApplication	保证进程生命周期内物理实例的唯一性
全局访问点 (Instance Gate)	QCoreApplication::instance() / qApp	提供全局可访问的静态接口指针
线程安全惰性宏	Q_GLOBAL_STATIC(Type, Name)	替代局域静态变量，实现线程安全的延迟实例化

---

底层原理：Q_GLOBAL_STATIC 的原理与生命周期

C++11 保证了局域静态变量（Meyers Singleton）的线程安全，但在动态库（DLL/SO）插件卸载以及静态析构顺序控制上，Qt 提供了官方宏 Q_GLOBAL_STATIC：

• 双重检查与原子保障：保证多线程并发第一次访问时的线程安全。
• 安全的析构顺序：通过 qAddPostRoutine 注册回调，确保在 QCoreApplication 销毁时按照正确的逆序清理全局资源，避免 DLL 卸载时的悬挂指针。

---

完整代码示例

1. 标准 C++11 线程安全单例（Meyers Singleton）

#include <QString>
#include <QMutex>
#include <QDebug>

class GlobalConfig {
public:
  // C++11 起局域静态变量构造天生线程安全
  static GlobalConfig& instance() {
    static GlobalConfig s_instance;
    return s_instance;
  }

  // 禁用拷贝与赋值
  GlobalConfig(const GlobalConfig&) = delete;
  GlobalConfig& operator=(const GlobalConfig&) = delete;

  void setAppTitle(const QString& title) {
    QMutexLocker locker(&m_mutex);
    m_title = title;
  }

  QString appTitle() const {
    QMutexLocker locker(&m_mutex);
    return m_title;
  }

private:
  GlobalConfig() = default; // 私有构造
  mutable QMutex m_mutex;
  QString m_title = "Default Title";
};

2. Qt 官方推荐：Q_GLOBAL_STATIC 模块级单例

#include <QCoreApplication>
#include <QGlobalStatic>
#include <QStringList>

class PluginRegistry {
public:
  PluginRegistry() {
    qDebug() << "PluginRegistry Created (Lazy)";
  }
  ~PluginRegistry() {
    qDebug() << "PluginRegistry Destroyed";
  }

  void registerPlugin(const QString& name) {
    m_plugins.append(name);
  }

  QStringList plugins() const { return m_plugins; }

private:
  QStringList m_plugins;
};

// 使用 Q_GLOBAL_STATIC 声明全局静态单例包装器
Q_GLOBAL_STATIC(PluginRegistry, s_registry)

int main(int argc, char *argv[]) {
  QCoreApplication app(argc, argv);

  // 首次访问时才会触发构造 (Lazy Initialization)
  s_registry()->registerPlugin("OpticalScannerPlugin");
  qDebug() << "Registered:" << s_registry()->plugins();

  return 0; // 程序退出时由 Qt 自动安全析构 s_registry
}

---

易混淆点与设计反思：为什么不要滥用单例？

单例滥用缺陷	现象说明	推荐替代方案
隐藏依赖网络	类内部直接调用 Singleton::instance()，使其依赖无法在构造函数中显式展现	依赖注入 (DI)：将上下文对象通过构造函数参数传入
破坏单元测试	全局唯一状态在测试用例间共享，导致测试环境相互污染	接口多态：定义 ISettings，测试时注入 MockSettings
生命周期不可控	静态单例如果依赖其他 QObject 父子树，析构顺序易产生野指针崩溃	显式栈构造：在 main() 栈上创建，控制销毁时机

---

最佳实践与踩坑避坑

1. GUI 程序绝对不能创建多个 QApplication：
   • 只能在 main() 函数的主线程栈上实例化一次 QApplication，不要在子线程或 DLL 中多次构造。
2. 正确使用 qApp 快捷指针：
   • #define qApp QCoreApplication::instance()。在包含 GUI 的程序中，需要强转为 qobject_cast<QApplication*>(qApp) 才能访问 GUI 专属属性。
3. 线程安全与同步：
   • 单例本身创建是线程安全的，但单例内部的成员变量读写依然需要加锁（如 QMutex）。

---

重点与注意

重点：QApplication 在 main() 栈上构造时注册为全局唯一实例，QCoreApplication::instance() 是单例模式的标准入口。
重点：Q_GLOBAL_STATIC 实现了惰性初始化 + 线程安全 + 动态库安全析构，是 Qt 库代码中单例的首选方案。
注意：切忌将单例当作全局变量仓库随意滥用，那会使隐式依赖爆炸，导致单元测试极难开展。

---

小结

Qt 单例模式在管理进程级核心资源（如事件循环与应用配置）时发挥着巨大作用，但在业务开发中应节制使用，适时采用依赖注入来提升工程的可测试性。

延伸阅读

• 上一篇：06 工厂 · 下一篇：08 代理
• 系列索引：README