FinalizationRegistry 的应用：在原生资源销毁时自动清理 JS 关联句柄 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

大家好，今天我们将深入探讨一个在现代JavaScript应用开发中至关重要的话题：如何利用 FinalizationRegistry 这个强大的Web API，在原生资源被销毁时，自动且优雅地清理与之关联的JavaScript句柄。这不仅能帮助我们构建更健壮、无内存泄露的应用，还能极大地提升开发体验和系统的稳定性。

问题背景：JavaScript垃圾回收与原生资源

在JavaScript的世界里，我们习惯于依赖垃圾回收（Garbage Collection, GC）机制来自动管理内存。当我们创建对象、数组、函数等JavaScript值时，它们占据内存；当它们不再被任何活动部分的代码引用时，GC会自动识别并回收这部分内存。这极大地简化了内存管理的复杂性，让我们能够专注于业务逻辑。

然而，JavaScript应用经常需要与各种“原生资源”进行交互。这些原生资源不直接由JavaScript引擎的GC管理，它们通常存在于JavaScript运行环境之外，例如：

文件句柄（File Handles）：在Node.js中打开一个文件，操作系统会分配一个文件句柄。
数据库连接（Database Connections）：连接到MySQL、PostgreSQL等数据库，会建立一个TCP连接并可能在服务器端占用资源。
网络套接字（Network Sockets）：进行网络通信时创建的套接字。
WebGL/WebGPU纹理、缓冲区（Textures, Buffers）：在图形编程中，这些资源存在于显存中。
WebAssembly内存（WASM Memory）：WASM模块直接操作的内存区域。
C++或Rust绑定对象（Native Bindings）：通过FFI（Foreign Function Interface）或N-API等方式，JS对象可能包裹着指向原生内存或结构体的指针。

这些原生资源的一个共同特点是：它们必须被显式地释放或关闭。如果一个JavaScript对象包裹着一个原生资源，并且这个JS对象被GC回收了，但其对应的原生资源却没有被显式释放，那么就会导致原生资源泄露。虽然JavaScript的内存被回收了，但操作系统或硬件上的资源依然被占用，长此以往可能导致系统性能下降、服务崩溃，甚至耗尽可用资源。

考虑一个典型的场景：你有一个JavaScript类 FileWrapper，它在构造函数中打开一个文件，并在析构时（或者通过一个 close() 方法）关闭这个文件。

class FileWrapper {
    constructor(filePath) {
        console.log(`[JS] Opening file: ${filePath}`);
        // 模拟调用原生API打开文件，获取一个原生文件句柄ID
        this.nativeHandle = NativeFileManager.openFile(filePath);
        this.filePath = filePath;
    }

    read() {
        if (this.nativeHandle === null) {
            console.error(`[JS] Error: File "${this.filePath}" is already closed.`);
            return;
        }
        console.log(`[JS] Reading from file: ${this.filePath} (handle: ${this.nativeHandle})`);
        // 模拟使用原生句柄进行读操作
        // ...
    }

    close() {
        if (this.nativeHandle !== null) {
            console.log(`[JS] Explicitly closing file: ${this.filePath} (handle: ${this.nativeHandle})`);
            // 模拟调用原生API关闭文件
            NativeFileManager.closeFile(this.nativeHandle);
            this.nativeHandle = null; // 标记为已关闭
        } else {
            console.warn(`[JS] Warning: File "${this.filePath}" was already closed.`);
        }
    }
}

// 模拟原生文件管理器
const nativeResourceStore = new Map();
let nextHandleId = 1;

class NativeFileManager {
    static openFile(path) {
        const handleId = nextHandleId++;
        console.log(`[Native] Allocating handle ${handleId} for ${path}`);
        nativeResourceStore.set(handleId, { path, status: 'open' });
        return handleId;
    }

    static closeFile(handleId) {
        if (nativeResourceStore.has(handleId)) {
            const resource = nativeResourceStore.get(handleId);
            if (resource.status === 'open') {
                console.log(`[Native] Releasing handle ${handleId} for ${resource.path}`);
                nativeResourceStore.delete(handleId);
            } else {
                console.warn(`[Native] Handle ${handleId} was already closed.`);
            }
        } else {
            console.warn(`[Native] Attempted to close unknown handle ${handleId}.`);
        }
    }

    static getActiveHandles() {
        return Array.from(nativeResourceStore.keys());
    }
}

如果开发者总是记得调用 fileWrapperInstance.close()，那么一切安好。但人非圣贤，孰能无过？一旦忘记调用 close()，即使 fileWrapperInstance 被GC回收了，其对应的原生文件句柄 this.nativeHandle 仍将保持打开状态，直到程序退出或操作系统回收。这就是资源泄露。

为了解决这个问题，JavaScript引入了 FinalizationRegistry。

`FinalizationRegistry`：连接JavaScript GC与原生资源清理的桥梁

FinalizationRegistry 是一个JavaScript内置对象，它允许你注册一个清理回调函数，这个回调函数会在被注册的对象被垃圾回收器回收之后被异步调用。这提供了一种机制，使得我们可以在JavaScript对象生命周期结束时，自动触发对关联原生资源的清理操作。

其核心思想是：当JavaScript对象（例如我们的 FileWrapper 实例）不再被引用，并最终被GC回收时，FinalizationRegistry 能够“感知”到这一事件，并执行预先注册的清理逻辑。

`FinalizationRegistry` 的工作原理

创建 FinalizationRegistry 实例：你需要创建一个 FinalizationRegistry 的实例，并为其提供一个 cleanupCallback 函数。这个回调函数将在注册的对象被GC回收后被调用。

const myRegistry = new FinalizationRegistry(heldValue => {
    // heldValue 是你在注册时提供的数据，用于清理原生资源
    console.log(`[FinalizationRegistry] Object was GC'd, cleaning up with heldValue:`, heldValue);
    // ...执行原生资源清理逻辑...
});

注册对象：使用 myRegistry.register(target, heldValue, unregisterToken) 方法来注册一个对象。
- target：这是你想要监控其生命周期的JavaScript对象。当这个 target 对象被GC回收时，cleanupCallback 将被触发。FinalizationRegistry 会对 target 持有一个弱引用，这意味着 target 不会因为被注册而阻止其被GC回收。
- heldValue：这是一个任意的JavaScript值，它会在 target 被GC回收时，作为参数传递给 cleanupCallback。这个值通常包含清理原生资源所需的信息（例如，原生句柄ID、指针等）。FinalizationRegistry 会对 heldValue 持有强引用，直到 cleanupCallback 被调用或注册被取消。注意：heldValue 绝对不能直接或间接地强引用 target 对象，否则会导致循环引用，target 将永远不会被GC回收。
- unregisterToken (可选)：这是另一个任意的JavaScript值，它用于后续通过 unregister() 方法取消注册。如果提供，FinalizationRegistry 会对 unregisterToken 持有弱引用。通常，target 对象本身就可以作为 unregisterToken，因为我们希望在 target 被明确关闭时取消自动清理。
取消注册：如果原生资源在 target 对象被GC回收之前就已经被显式地清理了（例如，用户调用了 fileWrapperInstance.close()），那么我们需要通过 myRegistry.unregister(unregisterToken) 方法来取消之前的注册。这可以防止 cleanupCallback 再次尝试清理一个已经关闭的资源，避免潜在的错误或性能开销。

关键特性与注意事项

异步与非确定性：FinalizationRegistry 的回调是异步的，并且执行时机是非确定性的。它只会在GC运行之后才被调用，而GC何时运行，取决于JavaScript引擎的内部策略和系统负载。这意味这回调可能在 target 对象变得不可达后的几毫秒、几秒、甚至更长时间才执行。在某些极端情况下（例如程序在GC运行前就退出），回调甚至可能永远不会执行。
安全网而非主要机制：由于其非确定性，FinalizationRegistry 应该被视为原生资源清理的最后一道安全网，而不是主要的清理机制。开发者仍然应该优先通过显式的 close() 或 dispose() 方法来管理原生资源。
主线程执行：cleanupCallback 通常在主线程上执行。这意味着你不应该在其中执行长时间运行或阻塞性的操作，以免影响应用的响应性。
heldValue 的引用问题：如前所述，heldValue 必须谨慎设计，确保它不会强引用 target 对象。通常，heldValue 应该是一个原始值（如数字、字符串）或一个不包含 target 引用的简单对象。

实战应用：自动清理文件句柄

现在，让我们将 FinalizationRegistry 应用到之前的文件包装器示例中，来构建一个更健壮的 ManagedFile 类。

// 模拟原生文件管理器 (与之前相同)
const nativeResourceStore = new Map();
let nextHandleId = 1;

class NativeFileManager {
    static openFile(path) {
        const handleId = nextHandleId++;
        console.log(`[Native] Allocating handle ${handleId} for ${path}`);
        nativeResourceStore.set(handleId, { path, status: 'open' });
        return handleId;
    }

    static closeFile(handleId) {
        if (nativeResourceStore.has(handleId)) {
            const resource = nativeResourceStore.get(handleId);
            if (resource.status === 'open') {
                console.log(`[Native] Releasing handle ${handleId} for ${resource.path}`);
                nativeResourceStore.delete(handleId);
            } else {
                console.warn(`[Native] Handle ${handleId} for ${resource.path} was already closed.`);
            }
        } else {
            console.warn(`[Native] Attempted to close unknown handle ${handleId}.`);
        }
    }

    static getActiveHandles() {
        return Array.from(nativeResourceStore.keys());
    }
}

// ----------------------------------------------------------------------
// FinalizationRegistry 的初始化
// 创建一个 FinalizationRegistry 实例，用于监听 ManagedFile 对象的GC
// 当 ManagedFile 对象被GC时，会调用这个回调，并传入注册时提供的 handleId
const fileCleanupRegistry = new FinalizationRegistry(handleId => {
    console.log(`n[FinalizationRegistry Callback] ManagedFile object was GC'd. Attempting to clean up native handle: ${handleId}`);
    NativeFileManager.closeFile(handleId);
});

// ----------------------------------------------------------------------
// ManagedFile 类，集成 FinalizationRegistry
class ManagedFile {
    constructor(filePath) {
        this.filePath = filePath;
        // 1. 打开原生文件，获取句柄
        this.nativeHandle = NativeFileManager.openFile(filePath);

        // 2. 将当前 ManagedFile 实例注册到 FinalizationRegistry
        //    - target: this (ManagedFile 实例自身)
        //    - heldValue: this.nativeHandle (当GC发生时，这个值会被传递给 cleanupCallback)
        //    - unregisterToken: this (使用实例自身作为取消注册的token，方便在显式关闭时取消自动清理)
        fileCleanupRegistry.register(this, this.nativeHandle, this);
        console.log(`[JS] ManagedFile created for ${filePath}, native handle: ${this.nativeHandle}`);
    }

    read() {
        if (this.nativeHandle === null) {
            console.error(`[JS] Error: File "${this.filePath}" is already closed.`);
            return;
        }
        console.log(`[JS] Reading from file: ${this.filePath} (handle: ${this.nativeHandle})`);
        // 模拟使用原生句柄进行读操作
    }

    close() {
        if (this.nativeHandle !== null) {
            console.log(`[JS] Explicitly closing ManagedFile for ${this.filePath}, native handle: ${this.nativeHandle}`);
            // 1. 显式关闭原生句柄
            NativeFileManager.closeFile(this.nativeHandle);

            // 2. 关键步骤：取消在 FinalizationRegistry 中的注册
            //    这可以防止在 ManagedFile 实例随后被GC时，FinalizationRegistry 再次尝试关闭这个已经关闭的句柄
            fileCleanupRegistry.unregister(this);

            this.nativeHandle = null; // 标记为已关闭
        } else {
            console.warn(`[JS] Warning: ManagedFile "${this.filePath}" was already closed.`);
        }
    }
}

演示场景与行为观察

为了更好地理解 FinalizationRegistry 的行为，我们设计几个演示场景。由于JavaScript的GC是非确定性的，我们不能保证回调会立即执行。在Node.js环境中，可以使用 --expose-gc 标志并在代码中通过 global.gc() 强制触发GC，但这在浏览器环境中是不推荐或不可行的。通常，我们会模拟GC的发生，或者在长时间运行的程序中观察其效果。

场景一：显式关闭文件

在这种情况下，我们遵循最佳实践，显式地调用 close() 方法。

console.log("--- Scenario 1: Explicitly closing file ---");
let file1 = new ManagedFile("data.txt");
file1.read();
console.log(`Active native handles before close: ${NativeFileManager.getActiveHandles()}`);
file1.close();
console.log(`Active native handles after close: ${NativeFileManager.getActiveHandles()}`);
file1 = null; // 解除引用，使其可被GC
// 强制GC (仅Node.js with --expose-gc)
// global.gc();
console.log("-------------------------------------------n");

预期输出：

[Native] Allocating handle 1 for data.txt
[JS] ManagedFile created for data.txt, native handle: 1
[JS] Reading from file: data.txt (handle: 1)
Active native handles before close: 1
[JS] Explicitly closing ManagedFile for data.txt, native handle: 1
[Native] Releasing handle 1 for data.txt
Active native handles after close: (空数组)
不会有 [FinalizationRegistry Callback] 的输出，因为我们显式地取消了注册。

场景二：忘记关闭文件（依赖GC自动清理）

这是 FinalizationRegistry 发挥作用的主要场景。我们创建文件，但不调用 close()，然后解除对JS对象的引用，等待GC发生。

console.log("--- Scenario 2: Forgetting to close file, relying on GC ---");
let file2 = new ManagedFile("config.json");
file2.read();
console.log(`Active native handles before unreferencing: ${NativeFileManager.getActiveHandles()}`);
file2 = null; // 解除引用，使其成为GC的候选对象
console.log(`Active native handles after unreferencing: ${NativeFileManager.getActiveHandles()}`);

// 模拟等待GC发生 (在实际应用中，这可能是程序运行一段时间后自动发生)
// 在Node.js中，可以通过 global.gc() 强制触发GC，但需要 --expose-gc 启动参数
console.log("nSimulating a delay for GC to potentially run...");
// 通常你会看到这里有一个延迟，GC会在某个时刻运行
// 如果没有 global.gc()，你可能需要运行更长时间或创建更多对象来触发GC
// 或者，在浏览器中，这会是一个不可预测的等待
for (let i = 0; i < 100000000; i++) { /* busy-wait to encourage GC */ } // 粗略模拟
// global.gc && global.gc(); // 尝试强制GC
console.log(`Active native handles after simulated GC delay: ${NativeFileManager.getActiveHandles()}`);
console.log("----------------------------------------------------------n");

预期输出：

[Native] Allocating handle 2 for config.json
[JS] ManagedFile created for config.json, native handle: 2
[JS] Reading from file: config.json (handle: 2)
Active native handles before unreferencing: 2
Active native handles after unreferencing: 2 (此时JS对象已不可达，但GC可能尚未运行)
Simulating a delay for GC to potentially run...
[FinalizationRegistry Callback] ManagedFile object was GC'd. Attempting to clean up native handle: 2 (这一行会在GC发生后异步出现)
[Native] Releasing handle 2 for config.json
Active native handles after simulated GC delay: (空数组，如果GC成功执行)

场景三：混合行为与多个资源

console.log("--- Scenario 3: Mixed behavior with multiple resources ---");
let file3 = new ManagedFile("log.txt");
let file4 = new ManagedFile("settings.ini");

console.log(`Active native handles initially: ${NativeFileManager.getActiveHandles()}`);

file4.close(); // 显式关闭一个

let file5 = new ManagedFile("temp.bin");
console.log(`Active native handles mid-run: ${NativeFileManager.getActiveHandles()}`);

file3 = null; // 让 file3 成为GC候选
// file5 仍然被引用着，或者我们模拟它在某个作用域结束后被释放

console.log("nSimulating more work and potential GC opportunities...");
for (let i = 0; i < 200000000; i++) { /* more busy-wait */ }
// global.gc && global.gc(); // 尝试强制GC

console.log(`Active native handles at end of scenario 3: ${NativeFileManager.getActiveHandles()}`);
file5.close(); // 最后显式关闭 file5
console.log(`Active native handles after all closes: ${NativeFileManager.getActiveHandles()}`);
console.log("---------------------------------------------------------n");

预期输出：

file3 (handle 3) 和 file4 (handle 4) 被创建。
file4.close() 被调用，handle 4 被显式关闭并从 fileCleanupRegistry 中取消注册。
file5 (handle 5) 被创建。
file3 = null，handle 3 变为GC候选。
经过一段时间和/或GC触发后，FinalizationRegistry 的回调会被调用，清理 handle 3。
file5.close() 被调用，handle 5 被显式关闭并从 fileCleanupRegistry 中取消注册。
最终所有原生句柄都应该被释放。

通过这些场景，我们可以清晰地看到 FinalizationRegistry 如何作为一道重要的安全网，确保即使开发者疏忽了显式清理，原生资源最终也能得到释放。

`WeakRef` 与 `FinalizationRegistry` 的关系

在讨论 FinalizationRegistry 时，经常会提及 WeakRef（弱引用）。它们都是ECMAScript 2021（ES12）引入的新特性，都与对象的弱引用和GC相关，但用途不同：

WeakRef：允许你创建一个对对象的弱引用。这意味着如果只有 WeakRef 实例引用一个对象，该对象仍然可以被垃圾回收。你可以通过 weakRef.deref() 方法尝试获取原始对象的强引用。如果对象已被GC回收，deref() 将返回 undefined。WeakRef 主要用于观察对象的生命周期，或者构建一些缓存机制（当内存不足时，缓存项可以被回收）。
FinalizationRegistry：用于在对象被GC回收之后执行清理操作。它不提供访问已回收对象的能力，而是通过 heldValue 传递清理所需的上下文信息。

虽然它们都处理弱引用，但 FinalizationRegistry 是专门为资源清理而设计的，而 WeakRef 更侧重于生命周期观察和缓存管理。在某些高级场景中，它们可以结合使用，例如，使用 WeakRef 存储一个对象的特定属性，并在 FinalizationRegistry 的回调中根据这个属性来清理，但对于大多数原生资源清理场景，FinalizationRegistry 搭配 heldValue 足以胜任。

进阶考量与最佳实践

1. 避免 `heldValue` 强引用 `target`

这是使用 FinalizationRegistry 最重要也是最容易出错的地方。如果 heldValue 强引用了 target 对象，那么 target 将永远不会被GC，从而导致 FinalizationRegistry 的回调永远不会被调用，资源也永远不会被清理。

错误示例：

// 假设 MyResource 有一个 .id 属性
class MyResource { /* ... */ }

const registry = new FinalizationRegistry(resource => {
    // 这里的 resource 实际上是 MyResource 实例
    // 如果 MyResource 实例被GC了，这个回调才会触发
    // 但如果 heldValue 强引用了 MyResource 实例，它就永远不会被GC
    console.log(`Cleaning up resource with ID: ${resource.id}`);
});

let myObj = new MyResource();
// 错误！heldValue 强引用了 myObj
registry.register(myObj, myObj, myObj);
myObj = null; // 尝试解除引用，但因为 heldValue 的强引用，myObj 仍不会被GC

正确做法： heldValue 应该只包含清理所需的信息，且这些信息不应直接或间接强引用 target。原始类型（如数字、字符串）是安全的。

const registry = new FinalizationRegistry(resourceId => {
    console.log(`Cleaning up resource with ID: ${resourceId}`);
});

let myObj = new MyResource();
// 正确！heldValue 只是资源ID，不会强引用 myObj
registry.register(myObj, myObj.id, myObj);
myObj = null; // 现在 myObj 可以被GC了

2. `unregister` 的重要性

正如在演示中看到的，当原生资源被显式关闭时，务必调用 unregister。这有几个好处：

避免重复清理：防止 FinalizationRegistry 在对象被GC时再次尝试清理一个已经关闭的资源。
资源效率：减少不必要的清理回调的调度和执行。
避免错误：某些原生API在尝试关闭一个已经关闭的句柄时可能会抛出错误或产生警告。

3. 性能考量

FinalizationRegistry 的回调是在GC发生之后才执行的，这可能会引入轻微的性能开销，因为JavaScript引擎需要在GC周期中额外处理这些注册。因此，不应滥用 FinalizationRegistry，仅在确实需要自动清理原生资源的场景中使用。回调函数内部也应尽量轻量，避免执行复杂的计算或长时间阻塞操作。

4. 作为后备方案

再次强调，FinalizationRegistry 是一个安全网。它不能替代良好的资源管理实践，例如使用 try...finally 块、using 声明（未来的JavaScript提案）或 dispose() 方法来显式管理资源。在同步代码流中，显式清理总是更及时、更可预测的。FinalizationRegistry 的价值在于捕获那些因编程错误或意外情况而未能显式清理的资源。

特性	显式 `close()` / `dispose()`	`FinalizationRegistry`
执行时机	立即，可预测	异步，非确定性，GC之后
保证清理	强保证，如果代码路径被执行	不保证在程序退出前执行，是最佳尝试
主要用途	主要资源管理机制	资源泄露的安全网，辅助显式清理
开发者控制	完全控制	GC控制，开发者通过注册/取消注册间接影响
性能影响	在调用时发生	GC周期中额外开销，回调执行时有轻微影响
复杂性	相对简单	需理解弱引用、GC行为、`heldValue` 引用等

总结

FinalizationRegistry 是JavaScript语言为解决原生资源管理痛点而提供的一个强大工具。它通过在JavaScript对象被垃圾回收后触发清理回调，有效地弥补了JavaScript垃圾回收机制无法直接管理原生资源的不足。

然而，它的非确定性和异步特性决定了它不应作为主要的资源管理策略，而应作为一道坚实的安全网，与显式的 close() 或 dispose() 方法协同工作。正确理解并应用 FinalizationRegistry，能够帮助我们构建更健壮、更可靠的JavaScript应用程序，有效防止原生资源泄露。

问题背景：JavaScript垃圾回收与原生资源

FinalizationRegistry：连接JavaScript GC与原生资源清理的桥梁

FinalizationRegistry 的工作原理

关键特性与注意事项

实战应用：自动清理文件句柄

演示场景与行为观察

WeakRef 与 FinalizationRegistry 的关系

进阶考量与最佳实践

1. 避免 heldValue 强引用 target

2. unregister 的重要性

3. 性能考量

4. 作为后备方案

总结

发表回复 取消回复

`FinalizationRegistry`：连接JavaScript GC与原生资源清理的桥梁

`FinalizationRegistry` 的工作原理

`WeakRef` 与 `FinalizationRegistry` 的关系

1. 避免 `heldValue` 强引用 `target`

2. `unregister` 的重要性

发表回复取消回复