# 类型转换

每个导出参数都必须实现 FromNapiValue（或某个引用转换 trait），每个返回值都必须实现 ToNapiValue。生成的 TypeScript 类型是有用的文档，但真正决定转换是否可用的是 Rust trait 实现。

本参考描述 napi-rs v3 的 bindgen 运行时。有关 JsString 和 JsObject 等底层句柄，请参阅 Env 与底层值。

# 方向图例

# 原始值

i64 特意映射到 number，而 i64n 映射到 bigint。只有当 JavaScript API 确实要暴露 BigInt 时，才应优先使用该包装类型。

#[napi]
pub fn inspect_bigint(value: BigInt) -> Result<u64> {
  let (negative, narrowed, lossless) = value.get_u64();
  if negative || !lossless {
    return Err(Error::from_reason("value does not fit in u64"));
  }
  Ok(narrowed)
}

上面的返回类型是 bigint，因为 u64 是 BigInt 输出类型。

# Option、null 与 undefined

Option<T> 有意采用非对称映射：

当区分本身就是 API 的一部分时，请使用 Null 或 Undefined。只接受一种 nullish 值时，请使用 Either<T, Null> 或 Either<T, Undefined>。

#[napi]
pub fn optional_name(value: Option<String>) -> Option<String> {
  value.filter(|name| !name.is_empty())
}

#[napi]
pub fn null_but_not_undefined(value: Either<String, Null>) -> bool {
  matches!(value, Either::B(Null))
}

# 使用 Either 表示联合类型

Either<A, B> 一直到 Either26<A, ..., Z> 都会映射为 TypeScript 联合类型。输入时，napi-rs 按从左到右的顺序，用每个类型的 ValidateNapiValue 实现测试变体，然后转换第一个匹配项。

#[napi]
pub fn normalize_id(value: Either<u32, String>) -> String {
  match value {
    Either::A(number) => number.to_string(),
    Either::B(text) => text,
  }
}

export function normalizeId(value: number | string): string

如果多个备选类型可能重叠，请从最具体到最宽泛排序。例如，普通 Object 的校验无法证明完整的对象 schema。Either 是运行时联合类型，并不是会在任意用户代码运行后回溯的 serde 风格无标签枚举。

# 数组、元组、map 与 set

Vec<T> 和集合转换的复杂度为 O(n)。如果需要增量访问而不是拥有所有权的副本，请使用作用域内的 Array、Object、typed-array 视图或 stream。

# 对象、类与自定义形状

不要把类当作对象形状。普通的可读写公开类字段需要为 getter 提供输出转换，并为 setter 提供输入转换；readonly 字段只需要输出转换，而跳过的类字段没有访问器。对于嵌套类值，请接受 &T、ClassInstance<T>，或使用 Array::get_ref；Vec<T> 需要拥有所有权的 FromNapiValue 实现，因此不适合接收类实例列表。

有关不同形状的示例，请参阅类、对象、枚举和 #[napi] 属性。

# Buffer、ArrayBuffer 与 typed array

当运行时接受外部后备存储时，外部 Buffer 和 ArrayBuffer 可以实现零拷贝。运行时也可能拒绝外部 buffer；此时 BufferSlice::from_data 等构造函数会回退为复制。不要承诺在所有 Node 兼容运行时上都能实现零拷贝。参阅 Typed array 和理解生命周期。

# Date 与 serde JSON

serde_json::Value 不能无损表示任意 JavaScript 值。特别是，大型输入 BigInt 在适合时可能变成 JSON number，否则变成十进制字符串。如果 BigInt 身份和精确的窄化规则很重要，请使用 BigInt。

serde-json-ordered 还会启用 serde_json 的 preserve_order 行为。

# 函数、Promise 与 stream

ReadableStream::new 会检查运行时是否提供全局 ReadableStream。仅有 Node-API 4 并不保证 Web Streams 全局对象存在；with_readable_stream_class 可以显式接收兼容的构造函数。

# 外部原生数据

External<T> 向 JavaScript 暴露一个不透明、带类型标签的原生分配。它不会被序列化，生成的类型为 ExternalObject<T>。

• 返回拥有所有权的 External<T>，可将它转移到 JavaScript external 值中。
• 接受 &External<T> 或 &mut External<T>，可以借用并检查所包装值的类型。
• 当 Rust 必须持有指向 external 的 JavaScript 引用时，请使用 ExternalRef<T>。
• External::new_with_size_hint 会向 JavaScript 垃圾回收器报告原生分配大小；该数字是 GC 记账提示，不是内存限制。

有关生命周期细节，请参阅 External。

# 校验不是强制转换

大多数生成的函数都根据其 FromNapiValue 实现执行转换。添加 #[napi(strict)] 后，会先调用 ValidateNapiValue 并拒绝顶层 JavaScript 类型不匹配的值。它不会把字符串强制转换为数字，也不会在转换前递归校验所有属性。

#[napi(return_if_invalid)] 执行相同的校验，但在输入无效时返回 undefined，而不是抛出异常。有关约束，请参阅 #[napi] 属性。

# 选择所有权模型

请按以下优先顺序选择：

1. 当复制成本可接受，且值必须跨线程或跨越 await 点时，使用拥有所有权的 Rust 值（String、Vec<T>、#[napi(object)]）。
2. 对同步的零拷贝或低拷贝访问，使用作用域句柄和切片（Object<'env>、Array<'env>、BufferSlice<'env>、typed-array 切片）。
3. 当 JavaScript 拥有的数据必须比回调存活更久时，使用保留引用的包装类型（Buffer、ObjectRef、FunctionRef、Reference<T>）。
4. 从其他线程调用 JavaScript 时使用 ThreadsafeFunction；绝不要把作用域 JavaScript 句柄移到那个线程。
5. 当数据应增量生成，而不是复制到一个集合中时，使用 stream。

编译器会通过生命周期和 Send 强制执行其中许多边界，但 unsafe 方法或原始 Node-API 句柄可以绕过这些限制。在这样做之前，请阅读理解生命周期。