NodeGui WrapperCache 源码级解析：Qt 对象 JS 包装缓存的机制、API 与实战

• 桌面应用
• 跨平台

导读：NodeGui 通过在 JS 侧为底层 Qt 对象维护一层"包装对象（wrapper）"来衔接 JavaScript 与 C++ 世界，而WrapperCache正是这层包装的缓存与生命周期管理中心。本文以 WrapperCache API 文档 为主体，结合 JS 实现 src/lib/core/WrapperCache.ts、C++ 侧 wrappercache.h 及 WrapperCache.test.ts 测试用例，完整讲解其双缓存结构、全部公开 API、底层销毁回调机制，以及 "Wrapper Keep Alive" 与 "Wrapper Recycle" 两种典型生命周期场景。读完本文，你将掌握 NodeGui 包装对象缓存的工作原理，并能在自己的插件或业务代码中正确使用get/getWrapper/store/registerWrapper等 API。

一、为什么需要 WrapperCache：包装对象的一生

NodeGui 应用中的绝大多数QObject由 JS 侧直接new出来（例如new QPushButton()），这类对象的生命周期由 JS 主导。但还有一类 Qt 对象并非由 Node.js 应用创建，而是由 Qt 自身创建并管理的——典型如QScreen（屏幕信息）、QClipboard（剪贴板）以及QObject.parent()返回的父对象。

问题随之而来：JS 侧拿到的 wrapper 只是一个普通的 JavaScript 对象，V8 垃圾回收器并不了解它与 C++ 对象之间的绑定关系。如果 wrapper 被 GC 回收，而它内部连接的 Qt 信号（signal handler）也随之失效，轻则功能中断，重则触发 C++ 侧空指针崩溃。

WrapperCache的官方职责说明（见 wrappercache.md）正是：

JS side cache for wrapper objects. This is mainly used for caching wrappers of Qt objects which are not directly created by our Nodejs application. The purpose of the cache is to keep "alive" wrapper objects and their underlying C++ wrappers which may be connected to Qt signals from the real Qt object.

也就是说，缓存的核心目的是让应用能拿到这类 Qt 对象、绑定事件处理器、然后放心地释放引用而不用担心 wrapper 被意外 GC——缓存会替应用把 wrapper 牢牢"按住"，直到底层 Qt 对象真正销毁。

二、双缓存结构：强缓存与弱缓存的分工

打开 src/lib/core/WrapperCache.ts，可以看到WrapperCache类的三块核心状态：

// 强缓存：一直持有 wrapper，直到 C++ 对象被 Qt 销毁 private _strongCache = new Map<number, QObject>(); // 弱缓存：用于普通基于 QObject 的 NFooBar 子类包装 private _weakCache = new Map<number, WeakRef<QObject>>(); // 包装器注册表：C++ 类名 -> 对应 JS wrapper 构造函数 private _wrapperRegistry = new Map<string, { new (native: any): QObject }>();

• _strongCache（强引用缓存）：键为底层 C++ 对象的数字 ID（由native.__id__()得到），值为 JS wrapper。缓存持有强引用，wrapper 绝不会被 V8 GC 回收。源码注释明确指出这类 wrapper 通常挂载了信号处理器，例如QScreen把信号处理器绑定到 C++ 侧QScreen上——一旦 wrapper 被回收，信号处理器也就失效了。
• _weakCache（弱引用缓存）：同样以对象 ID 为键，但值用WeakRef<QObject>包装。它只保证"同一时刻一个 C++ 对象只有一个活跃 wrapper"，但不阻止 GC 回收。这是为普通QObject子类包装准备的，JS 引用消失后 wrapper 可被回收，缓存项随后自然失效。
• _wrapperRegistry（包装器注册表）：把 C++ 类名（如QObjectWrap、QScreenWrap）映射到对应的 JS 构造函数，供getWrapper在遇到"未缓存过的新 C++ 对象"时按类名动态创建 wrapper。

此外，构造函数中还有一条关键初始化语句：

constructor() { addon.WrapperCache_injectCallback(this._objectDestroyedCallback.bind(this)); }

它把 JS 侧的_objectDestroyedCallback回调注入 C++ 原生插件（对应 C++ 侧injectDestroyCallback，见 wrappercache.h），从而让 C++ 对象销毁事件能通知到 JS 缓存。

三、API 全面讲解

以下内容完整覆盖 wrappercache.md 中列出的全部构造器、属性和方法，并补充实现细节与使用要点。

3.1 构造器constructor

new WrapperCache(): WrapperCache

默认构造器。除了上文提到的注入销毁回调，模块末尾还导出了进程级单例：

export const wrapperCache = new WrapperCache();

NodeGui 内部各模块均直接复用这个wrapperCache单例，应用代码通常无需自行实例化。

3.2 属性logCreateQObject与logDestoryQObject

两个布尔型日志开关，默认值均为false：

• logCreateQObject：置为true后，每次 C++ 对象被缓存记录时输出日志，格式为NodeGui: Created C++ object with ID: <id>.（见store实现）。
• logDestoryQObject：置为true后，每次 C++ 对象销毁并从缓存移除时输出NodeGui: Destroyed C++ object with ID: <id>.（见_objectDestroyedCallback实现）。

更推荐通过模块导出的辅助函数切换，见本文第六节"调试辅助"。

3.3 方法_flush()

_flush(): void

清空强缓存与弱缓存（新建空Map）。源码注释明确说明"This is only need for testing purposes"——它主要用于测试用例隔离状态，例如 WrapperCache.test.ts 中每个it块开头都会调用wrapperCache._flush()。生产代码中不应调用。

3.4 方法get<T>

get<T extends QObject>(wrapperConstructor: { new (native: any): T }, native: NativeElement): T

这是"按构造器 + 原生对象取包装"的入口，典型使用场景是获取由 Qt 管理的全局单例对象。实现逻辑（WrapperCache.ts）：

1. 通过native.__id__()取得对象 ID；
2. 若强缓存命中，直接返回缓存的 wrapper（保证同一 C++ 对象只有一个 JS wrapper）；
3. 未命中则new wrapperConstructor(native)创建新 wrapper，存入强缓存后返回。

关键区别：get走强缓存（keepAlive语义），因为QScreen、QClipboard这类对象需要持续存活以维持信号连接。例如 QClipboard.ts 中：

return wrapperCache.get<QClipboard>(QClipboard, native);

以及 QApplication.ts 获取QScreen时：

return wrapperCache.get<QScreen>(QScreen, screenNative);

泛型参数T要求继承QObject，其约束类型可参见 globals.md 中的NativeElement定义。

3.5 方法getWrapper

getWrapper(native: any): QObject | null

这是"只凭原生对象自动匹配 wrapper"的入口，也是实现中逻辑最完整的路径（WrapperCache.ts）：

1. native == null时直接返回null（防止空指针）；
2. 先查强缓存，命中即返回；
3. 再查弱缓存，deref()出 wrapper；若 wrapper 已被 GC（deref()返回 null），则跳过；
4. 仍找不到时，用native.wrapperType（C++ 侧记录的类型名）查_wrapperRegistry；命中则new出 wrapper 并调用this.store(wrapper)登记到弱缓存；
5. 注册表中也没有对应类型时，打印警告：NodeGui: Unable to find JS wrapper for type '<wrapperType>'.并返回null。

典型调用方是QObject.parent()与QObject.children()（QObject.ts）：

parent(): QObject { return wrapperCache.getWrapper(this.native.parent()); } children(): QObject[] { return this.native.children().map((kid: any) => wrapperCache.getWrapper(kid)); }

这保证了重复调用parent()总是返回同一个 wrapper 实例——测试用例 WrapperCache.test.ts 中专门验证了这一点：对b.parent()添加的magic属性能在a上读到，证明二者是同一对象。

3.6 方法registerWrapper

registerWrapper(qobjectClassName: string, wrapperConstructor: object): void

把C++ 类名与JS wrapper 构造函数登记进_wrapperRegistry。这是自定义 wrapper 能通过getWrapper被自动创建的前提。

NodeGui 各模块在文件末尾统一注册，例如：

• QObject.ts：wrapperCache.registerWrapper('QObjectWrap', QObject);
• QScreen.ts：wrapperCache.registerWrapper('QScreenWrap', QScreen);
• QItemSelectionModel.ts：wrapperCache.registerWrapper('QItemSelectionModelWrap', QItemSelectionModel);

测试辅助类 CacheTestQObject.ts 同样示范了自定义类的注册方式：

wrapperCache.registerWrapper('CacheTestQObjectWrap', CacheTestQObject);

值得注意的是，C++ 侧getWrapper在按类型名查找时会沿QMetaObject类继承链向上爬（见 wrappercache.h），例如拿到 Qt 内部子类QWidgetWindow时也能匹配到注册的QWindowWrap，从而对 Qt 内部子类免疫。

3.7 方法store

store(wrapper: QObject): void

把一个 wrapper 登记进弱缓存，并同步通知 C++ 侧建立映射（WrapperCache.ts）：

store(wrapper: QObject): void { if (wrapper.native != null) { const objectId = wrapper.native.__id__(); this._weakCache.set(objectId, new WeakRef<QObject>(wrapper)); addon.WrapperCache_store(wrapper.native, wrapper.native.__external_qobject__()); if (this.logCreateQObject) { console.log(`NodeGui: Created C++ object with ID: ${objectId}.`); } } }

QObject构造函数在创建 wrapper 后都会调用wrapperCache.store(this)（见 QObject.ts），因此普通new出来的 QObject 子类包装天然进入弱缓存。C++ 侧的storeJS（wrappercache.h）会以弱引用（isWeak=false时引用计数为 0……即不阻止 JS 侧回收）登记对象，并连接 Qt 的destroyed信号到handleDestroyed。

四、C++ 侧协作：destroyed 信号与缓存清理

JS 侧WrapperCache只是半壁江山，另一半在 C++ 侧的同名类WrapperCache : public QObject（单例WrapperCache::instance，见 wrappercache.cpp）。其核心机制：

1. 登记：store(env, ptrHash, qobject, wrapper, isWeak)用extrautils::hashPointerTo53bit(qobject)计算对象指针的 53 位哈希作为键，存入QMap<uint64_t, CachedObject>；CachedObject持有napi_ref（引用）与napi_env；同时对qobject的destroyed信号建立连接。
2. 销毁回调：槽函数handleDestroyed(const QObject*)（wrappercache.h）在 Qt 对象销毁时触发，先通过destroyedCallback（即 JS 侧注入的_objectDestroyedCallback）把对象 ID 传回 JS，再napi_reference_unref并移除缓存项。
3. JS 侧善后：_objectDestroyedCallback(objectId)（WrapperCache.ts）把对应 wrapper 的native字段置为null并从缓存删除，同时输出销毁日志。

这就实现了开发文档 wrapper_caching.md 中描述的优雅降级：C++ 对象被 Qt 销毁后，JS 侧再用旧 wrapper 会得到干净的 JS 空指针异常（含堆栈），而不是 C++ 侧段错误。测试用例 WrapperCache.test.ts 验证了clearFoo()后foo.native变为null。

五、两种生命周期场景：Keep Alive 与 Recycle

wrapper_caching.md 将缓存行为归纳为两种场景，正好对应_strongCache与_weakCache的分工：

5.1 "Wrapper Keep Alive"：生命周期由 Qt 掌控的对象

适用于QScreen、QClipboard这类由 Qt 创建并销毁的对象。应用通过QWindow.screen()或QApplication.clipboard()获取包装后，即使 JS 侧不再持有引用，强缓存也会保住 wrapper，使信号处理器在整个 C++ 对象生命周期内持续工作。

时序要点：应用调用QWindow.screen()→ C++ 返回 Qt 管理的QScreen指针 →WrapperCache::getWrapper（C++）查找/创建 Napi wrapper 并存入缓存 → JS 侧通过wrapperCache.get<QScreen>(...)取到（或缓存命中）wrapper → Qt 销毁QScreen时destroyed信号触发 C++ 缓存清理与 JS 回调置空native。

5.2 "Wrapper Recycle"：保证唯一活跃包装

适用于应用自己创建对象的场景：同一个 C++ QObject 在同一时刻只应有一个 JS wrapper。反复调用QObject.parent()必须返回同一个对象（这正是 WrapperCache.test.ts 所断言的）。此时走弱缓存：JS 引用消失后 wrapper 可被 GC，但缓存映射会在下次访问时重新创建 wrapper 或自然清理。

测试用例 WrapperCache.test.ts 中"缓存命中"验证了 Recycle 语义：连续两次a.foo()返回的 wrapper 的native.__id__()相同、且foo === foo2；而clearFoo()销毁底层对象后再取foo()会得到新的wrapper 与新的 ID（第 31-42 行）。

六、调试辅助：对象创建/销毁日志

排查包装对象泄漏或信号失效问题时，可用模块导出的两个开关（WrapperCache.ts）：

setLogCreateQObject(on: boolean): void // 开启：NodeGui: Created C++ object with ID: <id>. setLogDestroyQObject(on: boolean): void // 开启：NodeGui: Destroyed C++ object with ID: <id>.

在应用入口处开启后，控制台会打印所有被缓存与销毁的 C++ 对象 ID，帮助确认"对象是否被 Qt 提前销毁"、"wrapper 是否泄漏"。QObject的构造文档（见 QObject.ts）也明确提到了这两个辅助函数。

七、实践要点与注意事项

1. get与getWrapper的选择：get面向已知构造器、需要强保活的场景（QScreen、QClipboard）；getWrapper面向"按类型自动匹配"的场景（parent()、children()、滚动条、视图控件等，见 QAbstractScrollArea.ts），未注册的类型会打印警告并返回null。
2. 注册是前提：要让getWrapper自动创建自定义 wrapper，必须先用registerWrapper登记 C++ 类名（*Wrap后缀）与构造函数，且构造函数签名需兼容new (native: any)。
3. 销毁后勿复用：C++ 对象销毁后，旧 wrapper 的native为null，继续调用其方法会抛 JS 异常而非 C++ 段错误——这是设计预期的行为，不应自行"复活"。
4. _flush仅限测试：它会清空全部缓存，可能切断正在进行的信号连接，生产环境不要调用。
5. 扩展阅读：缓存整体架构可参考 wrapper_caching.md 与 understanding-memory.md；若需在自定义原生插件中复用缓存机制，可参阅 custom-nodegui-native-plugin.md。

• 桌面应用
• 跨平台