Read OSS
nodejs/node

C++↔JavaScript 的桥梁：BaseObject、Wrap 体系与 Binding 机制

•高级

前置知识

  • ›第 1 篇：architecture-overview
  • ›第 2 篇：startup-and-bootstrap
  • ›C++ 基础知识（模板、RAII、智能指针）
  • ›V8 嵌入概念（Isolate、Context、HandleScope、FunctionCallbackInfo、ObjectTemplate）

C++↔JavaScript 的桥梁：BaseObject、Wrap 体系与 Binding 机制

每次你在 Node.js 中打开 TCP socket、读取文件或设置定时器，背后都会创建一个 C++ 对象，并将其绑定到对应的 JavaScript 对象上。这套 binding 机制是整个代码库中最具架构意义的设计模式——正是它让 V8 从一个 JavaScript 引擎变成了一个完整的运行时。深入理解这套类层次结构、binding 加载器以及跨 JS↔C++ 边界的数据流，是参与 Node.js 贡献或开发原生插件的必备知识。

Wrap 类层次结构

Node.js 中所有 I/O 原语的基础，是以 BaseObject 为根的类层次结构。这套体系通过 V8 的内部字段机制，将 C++ 对象与 JavaScript 对象一一映射。

classDiagram
    class BaseObject {
        +Realm* realm_
        +Global~Object~ persistent_
        +object() Local~Object~
        +env() Environment*
        +MakeWeak()
    }
    
    class AsyncWrap {
        +ProviderType provider_type_
        +double async_id_
        +double trigger_async_id_
        +MakeCallback()
        +EmitAsyncInit()
    }
    
    class HandleWrap {
        +uv_handle_t* handle_
        +Close()
        +Ref() / Unref()
        +GetHandle()
    }
    
    class ReqWrap~T~ {
        +T req_
        +Dispatch(fn, args...)
        +Cancel()
    }
    
    class LibuvStreamWrap {
        +ReadStart() / ReadStop()
        +DoShutdown()
        +DoWrite()
    }
    
    class ConnectionWrap~WrapType UVType~ {
        +UVType handle_
        +OnConnection()
        +AfterConnect()
    }
    
    class TCPWrap {
        +Initialize()
        +New()
        +Bind() / Listen()
    }
    
    BaseObject <|-- AsyncWrap
    AsyncWrap <|-- HandleWrap
    AsyncWrap <|-- ReqWrap
    HandleWrap <|-- LibuvStreamWrap
    LibuvStreamWrap <|-- ConnectionWrap
    ConnectionWrap <|-- TCPWrap

BaseObject 是整个体系的根节点。它通过 persistent_ 持有对 V8 Object 的弱引用或强引用，并保存一个指向所属 Realm 的指针。其核心机制在于构造函数：它将指向 this（即 C++ 对象）的指针存入 JavaScript 对象的内部字段槽（kSlot）。这意味着，对于任何封装了原生资源的 JavaScript 对象，都可以在 O(1) 时间内取出对应的 C++ 对象。

AsyncWrap 在此基础上增加了异步追踪能力——每个异步操作都会获得 async_id 和 trigger_async_id，供 async_hooks API 使用。它还提供了 MakeCallback()，这是从 C++ 回调 JavaScript 的标准方式，能正确处理 async hook 的完整生命周期（init/before/after/destroy）以及微任务检查点。

HandleWrap 封装了 libuv 的 uv_handle_t——即 TCP socket、定时器、文件系统监听器等长期存活的资源。其关键在于 ref/unref 机制：被 ref 的 handle 会让事件循环保持运行，而被 unref 的则不会。这正是 setTimeout() 能让进程保持运行，而调用了 unref() 的定时器不会的原因。

ReqWrap<T> 封装了 libuv 的 uv_req_t——即文件读取、DNS 查询、连接请求等一次性操作。它的 Dispatch() 模板方法设计精巧：在向 libuv 提交请求的同时，自动将回调路由回 wrap 层，整个过程无需手动连接。

Environment：上帝对象

Environment 类的头文件长达 1264 行，承载了一个 Node.js 执行上下文所需的一切。称其为"上帝对象"并不夸张——事实上，这正是它的设计初衷。

classDiagram
    class Environment {
        +Isolate* isolate_
        +uv_loop_t* event_loop_
        +PrincipalRealm* principal_realm_
        +ImmediateInfo immediate_info_
        +TickInfo tick_info_
        +AsyncHooks async_hooks_
        +Permission permission_
        +InspectorAgent* inspector_agent_
        +EnvironmentOptions* options_
        +HandleWrapQueue handle_wrap_queue_
        +ReqWrapQueue req_wrap_queue_
        +GetCurrent(isolate) Environment*
        +CreateEnvironment()
        +RunBootstrapping()
    }

每个 HandleWrap 和 ReqWrap 实例都会向 Environment 的队列注册自身。这为安全关闭提供了支撑：当 Environment 被销毁时，它可以遍历所有未完成的 handle 和请求，将其逐一关闭。

GetCurrent() 静态方法是 C++ 回调函数找到对应 Environment 的方式。V8 回调接收 Isolate* 或 FunctionCallbackInfo，Environment::GetCurrent() 则从 V8 context 的 embedder 数据槽中提取 Environment。在繁忙的 Node.js 进程中，这个方法每秒会被调用数百次。

提示： 如果你在编写 C++ binding 时需要访问 Environment，请使用 Environment::GetCurrent(args)，其中 args 是传入回调的 FunctionCallbackInfo。切勿跨异步边界缓存 Environment 指针——它可能已经失效。

Realm 与 Binding 数据

正如第 2 篇所介绍的，Realm 是对 ECMAScript realm 的抽象封装。PrincipalRealm 是用户代码运行的主 realm，ShadowRealm 实例则由 JavaScript 的 ShadowRealm API 创建。

每个 Realm 拥有独立的：

  • Binding 数据存储：一个以 BindingDataType 为索引的 BaseObject 弱指针数组。每个 C++ binding 模块可以在此注册各自的 per-realm 数据。
  • Base object 列表：追踪该 realm 内创建的所有 BaseObject 实例。
  • 内置模块缓存：记录哪些内置模块已经以带或不带代码缓存的方式完成编译。

Realm 的 RunBootstrapping() 方法会首先执行 realm.js（用于初始化模块加载器），然后委托给 BootstrapRealm() 完成 realm 的专项初始化。对于主 realm，这意味着依次运行 node.js、Web API 脚本以及线程切换脚本。

X-Macro 属性模式

Node.js 需要快速访问数百个 V8 值——例如 "message"、"code"、"stack" 等字符串，以及各类 symbol 和对象模板。每次都按名称查找代价高昂。为此，src/env_properties.h 采用了 X-macro 模式，自动生成存储字段与访问器。

其原理是：用一个宏定义 (属性名, 字符串值) 的元组列表，再通过其他宏以不同方式"展开"这份列表：

// In env_properties.h — define the list once
#define PER_ISOLATE_PRIVATE_SYMBOL_PROPERTIES(V)                \
  V(arrow_message_private_symbol, "node:arrowMessage")          \
  V(contextify_context_private_symbol, "node:contextify:context") \
  // ... dozens more

#define PER_ISOLATE_STRING_PROPERTIES(V)                        \
  V(__filename_string, "__filename")                             \
  V(__dirname_string, "__dirname")                               \
  // ... hundreds more

在 IsolateData 和 Environment 中，这些宏负责生成成员变量、getter 方法以及初始化代码。字符串 "__filename" 在 Isolate 创建时仅被内化（intern）一次，此后每次使用只需廉价的指针比较，而非字符串查找。

这一模式贯穿整个 Node.js 代码库。虽然写起来较为繁琐，但它从根本上消除了一类性能问题和笔误引发的 bug。

三种 Binding 加载器

Node.js 提供了三种让 JavaScript 代码访问 C++ 功能的机制，在 realm.js 的头部注释 中均有说明：

flowchart TD
    JS["JavaScript Code"] --> IB["internalBinding(name)<br/>Primary mechanism<br/>Internal only"]
    JS --> PB["process.binding(name)<br/>Legacy, deprecated<br/>User-accessible"]
    JS --> LB["process._linkedBinding(name)<br/>For embedders<br/>Linked modules"]
    
    IB --> REG_INT["NODE_BINDING_CONTEXT_AWARE_INTERNAL()<br/>nm_flags = NM_F_INTERNAL"]
    PB --> REG_BUILT["NODE_BUILTIN_MODULE_CONTEXT_AWARE()<br/>nm_flags = NM_F_BUILTIN"]
    LB --> REG_LINK["NODE_BINDING_CONTEXT_AWARE_CPP()<br/>nm_flags = NM_F_LINKED"]
    
    REG_INT --> LOOKUP["node_binding.cc<br/>FindModule() lookup"]
    REG_BUILT --> LOOKUP
    REG_LINK --> LOOKUP

binding 的注册逻辑定义在 src/node_binding.h 中。NODE_BINDINGS_WITH_PER_ISOLATE_INIT 宏列出了所有需要 per-isolate 初始化的 binding，包括 async_wrap、fs、http_parser、module_wrap、worker 等。每个 binding 模块都有一个 Initialize() 函数，负责创建 V8 函数模板并将其挂载到目标对象上。

当 JavaScript 调用 internalBinding('fs') 时，C++ 侧会依次执行：

  1. 在 binding 注册表中按名称查找模块
  2. 调用该模块的 Initialize() 或 context-aware 注册函数
  3. 缓存结果，使后续调用返回同一对象
  4. 将该对象返回给 JavaScript

BuiltinLoader 与 js2c 流水线

lib/ 目录下的所有 JavaScript 文件，在构建阶段由 tools/js2c.cc 编译进 Node.js 二进制文件。该工具读取每个 JavaScript 文件，并输出以静态数据形式存储文件内容的 C++ 源码（使用 UnionBytes 以提高存储效率）。

flowchart LR
    LIB["lib/**/*.js<br/>~200 JavaScript files"] --> JS2C["tools/js2c.cc"]
    JS2C --> NODE_JS_CC["node_javascript.cc<br/>Static byte arrays"]
    NODE_JS_CC --> LOADER["BuiltinLoader<br/>(node_builtins.cc)"]
    LOADER --> COMPILE["V8 ScriptCompiler<br/>Compile + optional<br/>code cache"]
    COMPILE --> EXEC["Execute in Realm"]

在运行时，BuiltinLoader 负责管理这些内嵌源码的编译与缓存。当某个内置模块首次加载时，BuiltinLoader 会：

  1. 从静态数据中取出源码
  2. 将其包裹在一个带有标准参数的函数中（exports、require、module、__filename、__dirname，以及 Node.js 专有参数如 internalBinding 和 primordials）
  3. 使用 V8 的 ScriptCompiler 进行编译，并启用代码缓存
  4. 缓存编译后的函数以供复用

代码缓存对 snapshot 构建尤为关键——构建 snapshot 时，模块会被编译并将代码缓存序列化存储；在运行时，V8 可以直接反序列化代码缓存，而无需重新解析和编译 JavaScript。

实战示例：追踪 fs.readFile() 的完整调用链

让我们追踪一次从 JavaScript 经 C++ 到 libuv、再返回的完整调用过程。当你调用 fs.readFile('hello.txt', callback) 时：

sequenceDiagram
    participant USER as User Code
    participant FS_JS as lib/fs.js
    participant FS_CC as src/node_file.cc
    participant UV as libuv
    participant OS as Kernel

    USER->>FS_JS: fs.readFile('hello.txt', cb)
    FS_JS->>FS_JS: Validate args, create FSReqCallback
    FS_JS->>FS_CC: binding.open(path, flags, mode, req)
    Note over FS_CC: internalBinding('fs')
    FS_CC->>FS_CC: Permission check (THROW_IF_INSUFFICIENT_PERMISSIONS)
    FS_CC->>UV: uv_fs_open(loop, &req, path, ...)
    UV->>OS: open() syscall on thread pool
    OS-->>UV: file descriptor
    UV-->>FS_CC: Callback with fd
    FS_CC->>FS_JS: FSReqCallback triggers JS callback
    FS_JS->>FS_CC: binding.read(fd, buffer, ...)
    FS_CC->>UV: uv_fs_read(loop, &req, fd, ...)
    UV->>OS: read() syscall on thread pool
    OS-->>UV: data
    UV-->>FS_CC: Callback with bytes read
    FS_CC->>FS_JS: FSReqCallback triggers JS callback
    FS_JS-->>USER: callback(null, data)

各层关键角色的职责如下：

  1. lib/fs.js 负责参数校验、管理多步读取流程（open → stat → read → close），以及 Buffer 与字符串编码之间的转换。

  2. internalBinding('fs') 返回来自 src/node_file.cc 的 C++ binding 对象，该对象暴露了 open、read、close、stat 等函数。

  3. 每个异步操作都会创建一个 FSReqCallback（ReqWrap<uv_fs_t> 的子类），它持有 JavaScript 回调并向 libuv 发起调度。

  4. libuv 在线程池中执行实际的系统调用，完成后将结果投递回事件循环线程。

  5. 事件循环线程上的完成回调调用 FSReqCallback::Resolve()，后者通过 AsyncWrap::MakeCallback() 在正确的异步上下文中触发 JavaScript 回调。

值得注意的是权限检查：src/node_file.cc 引入了 permission/permission.h，每个文件操作都会通过 THROW_IF_INSUFFICIENT_PERMISSIONS 来执行 --allow-fs-read / --allow-fs-write 权限模型的限制。

提示： 调试原生 binding 时，可以在 C++ 的 Initialize() 函数中打断点，观察哪些方法和属性被暴露给了 JavaScript。函数模板的设置代码会清晰地告诉你，哪些 JavaScript 调用对应哪些 C++ 函数。

下一步

至此，我们已经了解了 C++ 与 JavaScript 对象的连接方式，以及数据如何跨越这座桥梁流动。在下一篇文章中，我们将深入探讨 Node.js 是如何加载你的代码的——包括 CommonJS 与 ES module 加载器、primordials 防御机制，以及支持 TypeScript 的模块定制钩子。