原生插件支持 (NAPI)

相关源文件

• src/bun.js/bindings/napi.cpp
• src/bun.js/bindings/napi.h
• src/bun.js/bindings/v8/V8Isolate.cpp
• src/bun.js/bindings/v8/V8Object.cpp
• src/bun.js/bindings/v8/V8String.cpp
• src/bun.js/bindings/v8/V8String.h
• src/bun.js/bindings/v8/node.cpp
• src/bun.js/bindings/v8/v8.h
• src/bun.js/bindings/v8/v8_api_internal.cpp
• src/bun.js/bindings/v8/v8_api_internal.h
• src/napi/napi.zig
• src/symbols.def
• src/symbols.dyn
• src/symbols.txt
• test/napi/napi-app/.gitignore
• test/napi/napi-app/async_finalize_addon.c
• test/napi/napi-app/binding.gyp
• test/napi/napi-app/main.cpp
• test/napi/napi-app/main.js
• test/napi/napi-app/module.js
• test/napi/napi-app/package.json
• test/napi/napi.test.ts
• test/v8/v8-module/main.cpp
• test/v8/v8.test.ts

本文档涵盖了 Bun 对 Node-API (NAPI) 的实现，它提供了一个稳定的 C ABI，用于构建可与 JavaScript 接口的原生插件。NAPI 系统使 C/C++ 模块能够创建、操作和与 JavaScript 值、对象和函数交互，同时保持与 Node.js 原生模块的兼容性。

有关 Node.js 模块兼容性的更广泛信息，请参阅 核心模块实现。有关 Web 标准合规性，请参阅 Web API 和标准合规性。

架构概述

Bun 的 NAPI 实现通过多层架构连接了 C/C++ 原生代码和 JavaScriptCore

来源: src/bun.js/bindings/napi.cpp src/napi/napi.zig src/bun.js/bindings/napi.h

环境和上下文管理

NAPI 环境 (napi_env) 是原生模块的主要执行上下文

napi_env__ 结构管理

• 全局对象引用: 连接到 JavaScript 运行时上下文
• 模块信息: 被执行的原生模块的元数据
• 清理管理: 用于资源释放的环境和异步清理钩子
• 最终化跟踪: 在 JavaScript 对象被垃圾回收时执行的回调
• 错误状态: 用于调试和错误传播的最后一条错误信息
• 实例数据: 每个模块的持久数据存储

来源: src/bun.js/bindings/napi.h64-301

值系统和类型转换

NAPI 值通过包装 JavaScriptCore JSValue 实例的 napi_value 枚举来表示

值系统提供

• 类型安全创建: 用于创建特定类型 JavaScript 值的函数
• 类型检查: 运行时类型识别和验证
• 转换函数: C 类型和 JavaScript 值之间的双向转换
• 内存集成: 自动与句柄作用域集成以进行垃圾回收

来源: src/napi/napi.zig118-138 src/napi/napi.zig264-485

句柄作用域内存管理

句柄作用域管理 NAPI 值的生命周期，以防止过早垃圾回收

句柄作用域特性

• 自动注册: 创建时，值会自动添加到当前作用域
• 嵌套作用域: 支持分层作用域管理
• 逃逸机制: 值可以从内部作用域移动到外部作用域
• 垃圾回收保护: 防止 JavaScript 值被过早收集
• 作用域安全: 在垃圾回收期间验证作用域操作

来源: src/napi/napi.zig76-109 src/napi/napi.zig616-751

对象和属性管理

NAPI 提供了全面的对象操作功能

属性管理包括

• 动态属性访问: 按名称或符号设置、获取和删除属性
• 属性描述符: 支持可配置、可枚举和可写属性
• 原型链: 访问对象原型和继承
• 类型检查: 运行时类型验证和 instanceof 操作

来源: src/bun.js/bindings/napi.cpp456-750 src/napi/napi.zig513-575

函数和回调系统

NAPI 使原生函数能够从 JavaScript 调用，反之亦然

回调系统提供

• 原生函数注册: 将 C 函数暴露给 JavaScript
• 参数处理: 提取和验证函数参数
• This 绑定: 正确处理 JavaScript this 上下文
• 构造函数支持: 创建支持 new 运算符的可调用构造函数
• 错误传播: 原生代码和 JavaScript 代码之间的异常处理

来源: src/bun.js/bindings/napi.cpp287-382 src/napi/napi.zig662-695

引用管理和最终化

NAPI 提供持久引用和清理机制

引用管理特性

• 弱引用: 允许在保持访问的同时进行垃圾回收
• 强引用: 防止被引用对象的垃圾回收
• 对象包装: 将原生数据与 JavaScript 对象关联
• 最终化回调: 在对象被收集时执行清理代码
• 延迟清理: 在需要时安排最终化到下一个事件循环滴答

来源: src/bun.js/bindings/napi.h236-291 test/napi/napi-app/module.js504-594

异步操作

NAPI 支持后台工作执行和线程安全的 JavaScript 交互

异步功能包括

• 后台工作: 将 CPU 密集型任务移出主线程执行
• 线程安全回调: 从任何线程安全地调用 JavaScript 函数
• Promise 支持: 从原生代码创建和解析 JavaScript Promises
• 事件循环集成: 与 Bun 的事件循环正确集成

来源: test/napi/napi-app/module.js src/napi/napi.zig913-970

错误处理和状态码

NAPI 使用全面的错误报告系统

状态码	描述	用途
napi_ok	成功	正常操作完成
napi_invalid_arg	无效参数	参数验证失败
napi_object_expected	对象类型错误	对象操作的类型不匹配
napi_string_expected	字符串类型错误	字符串操作的类型不匹配
napi_function_expected	函数类型错误	函数操作的类型不匹配
napi_pending_exception	挂起的异常	需要处理 JavaScript 异常
napi_generic_failure	通用失败	未指定的]操作失败

错误系统提供

• 状态码返回: 所有 NAPI 函数都返回状态指示符
• 扩展错误信息: 详细的错误消息和上下文
• 异常集成: JavaScript 异常的正确处理
• 错误状态跟踪: 每个环境的错误状态管理

来源: src/napi/napi.zig205-228 src/bun.js/bindings/napi.cpp166-226

测试与验证

Bun 的 NAPI 实现包含全面的测试覆盖

测试套件验证

• Node.js 兼容性: 确保与 Node.js NAPI 的行为一致
• 内存安全: 测试句柄作用域和垃圾回收集成
• 类型系统: 验证 JavaScript 和原生类型之间的转换
• 错误条件: 测试正确的错误处理和状态报告
• 性能: 验证 NAPI 操作的高效执行

来源: test/napi/napi.test.ts test/napi/napi-app/main.cpp test/napi/napi-app/module.js