deno_ops 深度解析：Deno 运行时中用 proc macro 生成高性能 V8 函数接口的完整指南

本篇以 Deno 仓库中的 libs/ops crate（deno_ops）为核心，系统讲解它是如何通过 #[op2] 过程宏把 Rust 函数自动翻译成高度优化的 V8 函数接口：包括 op 的声明与注册、字符串/异步/fallible 调用的语义、fastcall 优化路径、参数与返回值类型映射表、基于 V8 CppGC 的原生 JavaScript 类定义，以及配套的类型推导宏与宏展开测试基础设施。读完后，你能够独立编写、注册并调试 Deno 扩展中的 Rust op，并理解其底层代码生成机制。

deno_ops 是什么

libs/ops/README.md 对 crate 的定位只有一句话："proc macro for generating highly optimized V8 functions from Rust functions"——即一个过程宏工具，把 Rust 函数转换为高度优化的 V8 函数。crate 的元信息见 libs/ops/Cargo.toml：包名为 deno_ops（当前版本 0.287.0），[lib] 配置了 proc-macro = true，依赖 syn、proc-macro2、quote、thiserror 等标准宏开发库。

入口文件 libs/ops/lib.rs 用 #![doc = include_str!("README.md")] 把 README 直接嵌入 crate 文档，并对外暴露五个宏入口：

• #[op2(...)]：属性宏，核心的"Rust 函数 → V8 函数"生成器（文档直接包含 libs/ops/op2/README.md）；
• #[derive(WebIDL)]：为 struct/enum 生成 WebIDL 风格的字典/枚举转换实现；
• #[derive(FromV8)] / #[derive(ToV8)]：自定义类型与 V8 值互转的 derive；
• #[derive(CppgcInherits)] / #[derive(CppgcBase)]：支撑 CppGC 对象继承体系的两个 derive。

声明一个 op 并注册到扩展

README 给出的最小示例就是实际用法的全部骨架：

use deno_core::{op2, extension};

// 声明一个 op。
#[op2(fast)]
pub fn op_add(a: i32, b: i32) -> i32 {
  a + b
}

// 注册到扩展中。
extension!(
  math,
  ops = [op_add]
)

#[op2] 只负责在编译期生成 V8 绑定代码，真正让 op 在运行时可用的是 deno_core::extension! 宏的 ops = [...] 列表。仓库内大量扩展遵循这一模式，例如 ext/fs/ops.rs、ext/fetch/lib.rs、ext/crypto/lib.rs、ext/http/http_next.rs 等，都是 #[op2] 的密集使用方——这也是理解本 crate 价值的关键背景：Deno 几乎所有 JS API 背后的系统调用都经过这一层。

op2 宏的内部工作流

理解生成机制有助于读懂编译错误。入口函数在 libs/ops/op2/mod.rs：

1. 先把输入 token stream 尝试解析为 ItemFn（普通函数）；若失败则尝试 syn::ItemImpl，此时转入 libs/ops/op2/object_wrap.rs 的 generate_impl_ops，处理 CppGC 对象的 impl 块；
2. 用 Punctuated<CustomMeta, _> 解析 #[op2(...)] 括号内的标志，交给 libs/ops/op2/config.rs 的 MacroConfig；
3. generate_op2 把原函数重命名为 call、解析签名（parse_signature）、逐参数做 V8 类型映射，再分发给三条代码生成路径：dispatch_slow（慢速通用路径）、dispatch_fast（fastcall 快速路径）、dispatch_async（异步包装），见 libs/ops/op2/dispatch_slow.rs、libs/ops/op2/dispatch_fast.rs、libs/ops/op2/dispatch_async.rs。

错误类型集中在 Op2Error/Op2ErrorKind（libs/ops/op2/mod.rs），其中有几条对使用者很有指导意义的编译期诊断：

• ShouldBeFast："This op is fast-compatible and should be marked as (fast)"——op 明明可以走 fastcall 却没标注；
• ShouldNotBeFast：标注了 fast 但签名不兼容 fastcall；
• InvalidAttributeCombination：非法标志组合（见下文）。

属性标志（MacroConfig）全解

libs/ops/op2/config.rs 的 MacroConfig 结构体列出了 #[op2] 支持的全部标志，这里结合源码注释完整整理：

标志	字段	作用
fast	fast: bool	生成 fastcall 方法（要求签名 fastcall 兼容）
nofast	nofast: bool	显式禁止 fastcall（文档认为"unlikely"）
fast(op_XYZ)	fast_alternative: Option<String>	指定另一个已标注 #[op2(fast)] 的 op 作为 fastcall 替代实现，无需注册
async(fake) / async(lazy) / async(deferred)	fake_async / async_lazy / async_deferred	异步 op 的三种模式，见下文
constructable	constructable: bool	顶层 op 需要 JS 函数原型（可 new）
constructor	constructor: bool	标记为 CppGC 对象的构造函数
getter / setter	getter / setter: bool	标记为属性访问器
static_method	static_member: bool	标记为类静态方法
reentrant	reentrant: bool	标记 op 可重入（可安全地调用其他 op）
no_side_effects	no_side_effects: bool	标记 op 无副作用
stack_trace	stack_trace: bool	在 OpState 中采集调用点的 JS 堆栈
required(N)	required: Option<u8>	op 要求的参数个数
rename("name")	rename: Option<String>	重命名 op 在 JS 侧的可见名
symbol("op_name")	symbol: bool	以 Symbol.for("op_name") 的形式暴露
promise_id	promise_id: bool	调用函数时传入异步 op 的 promise_id
validate(...)	validate: Option<Path>	指定校验路径

from_metas（libs/ops/op2/config.rs）还强制两条纪律：其一，标志必须按字母顺序书写，否则报 "The flags for this attribute were not sorted alphabetically"（代码注释说明目的是保持一致性与可搜索性）；其二，非法组合在编译期直接拒绝，目前包括 fast + nofast、fast + fast(...)、no_side_effects + reentrant。此外解析时会自动跳过 doc/allow/cfg 三个常规 Rust 属性。

op2 的入口文档 libs/ops/op2/README.md 开篇即声明：#[op2] 是 #[op] 的替换实现，即 op 系统的当前世代。

字符串参数：UTF-8 与 Latin-1 的边界问题

op2 文档 专门用一节解释字符串为什么总是需要拷贝：Rust 的 String 恒为 UTF-8，而 V8 字符串要么是两个字节 UTF-16、要么是一字节 Latin-1；后者的 128–255 区间字符在 UTF-8 中需要两字节，因此两者不字节兼容。结论是：op 中的 String 参数至少需要一次拷贝，目前无法避免，宏生成代码会尽量用栈缓冲减少分配。

结合参数映射表（libs/ops/op2/valid_args.md），字符串族参数的取舍如下：

Rust 类型	行为
#[string] String	始终产生一次堆上 UTF-8 拷贝；仅当 V8 侧为 Latin-1 时 fastcall 可用
#[string] &str	放得下栈缓冲时零分配；fastcall 中从不分配，但仍拷贝 Latin-1 → UTF-8
#[string] Cow<str>	类似 &str；fastcall 中恒为 Cow::Borrowed，慢速路径放不下栈时升级为 Cow::Owned
#[string(onebyte)] Cow<[u8]>	最快的 String 参数形式；若字符串不是 Latin-1 直接抛 TypeError

如果只关心 ASCII 性能上限，#[string(onebyte)] 是最激进的选择；对一般场景，#[string] &str 是分配友好的默认推荐。

Fallible op 与 async op

Fallible op

文档明确：op 函数可以返回 Result 表示可失败，错误类型必须实现 deno_error::JsErrorClass；返回 Err 时向 JS 侧抛出异常。这让 Rust 侧的 thiserror 错误体系可以直接桥接到 JS 异常。

async op 的三种模式

异步形式完全从函数签名推断，支持 async fn op_xyz() -> X 与 fn op_xyz() -> impl Future<Output = X> 两种写法。宏会把它"脱糖"成一个隐藏了 promise_id 参数、返回 Option<X> 的函数（op2 文档）：

// 概念上的脱糖结果
fn op_xyz(promise_id: i32 /* ... */) -> Option<X> {}

Deno 会立即（eagerly）poll 该 op：若当场就绪返回 Some(X)，否则返回 None，后续由 Deno 的 pending op 系统接管。三种模式对应的标志：

• 默认 eager：最大限度降低延迟，适合大多数场景；
• async(lazy)：推迟到稍后才 poll 该 op，提交本身可能更快，但"第一次 poll 就能就绪"的 op 延迟变高。文档强调它"可能与 fastcall 兼容，但决议仍走慢速路径"，只应在仔细 benchmark 后使用，以延迟换吞吐；
• async(deferred)：立即 poll，但把已就绪的结果推迟到事件循环的后续轮次处理。文档直言"这几乎肯定不是你要用的"，仅限真正理解后果的场合。

fastcall 与参数转换

fastcall 三态

op2 文档 指出：op2 要求 fastcall 兼容的 op 必须显式标注 fast（不标注会触发 ShouldBeFast 编译错误）；nofast 可显式禁用；fast(op_XYZ) 则让慢速函数借用另一个已标注 #[op2(fast)] 的 op 作为快速实现——典型场景是慢速路径接受任意 buffer 类型、快速路径使用 u8 typed buffer。

参数到 V8 快速类型的映射在 libs/ops/op2/dispatch_fast.rs 中完成：FastSignature 持有 V8FastCallType 化的参数与返回值，FastArg 区分真实参数、虚拟参数（仅输出名）、CallbackOptions 与 PromiseId 这几类特殊槽位。

参数类型映射表（慢速路径要点）

完整表格见 libs/ops/op2/valid_args.md，核心行摘录如下（"Fastcall" 列 ✅ 表示可走快速路径）：

Rust	Fastcall	V8 侧	说明
bool / i8 / u8 / i16 / u16 / i32 / u32 / f32 / f64	✅	数值	直接映射
#[smi] ResourceId	✅	数值	SMI 内部是有符号整数，无符号 #[smi] 类型会做位转换为无符号值传入 Rust，JS 侧仍看到有符号整数
#[bigint] i64/u64/isize/usize	✅	数值/BigInt	64 位整数走 BigInt
&v8::Value、&v8::String、v8::Local<v8::...>	✅	any	直接拿 V8 句柄
FromV8Scopeless 类型	—	any	无需 v8 scope 的转换，多数类型更高效的默认路径
#[scoped] FromV8Type	—	any	转换时可访问 v8 scope；文档标注"⚠️ May be slow"
#[serde] SerdeType	—	any	遗留方式，不推荐，改用 FromV8 trait 与宏
#[arraybuffer] &[u8] / *mut u8 / ...	✅	ArrayBuffer	⚠️ V8 被重入调用时 JS 可能修改内容；空数组在 fastcall 中恒为 null
#[arraybuffer(copy)] Vec<u8>/Box<[u8]>/bytes::Bytes	✅	ArrayBuffer	安全，强制拷贝
#[buffer(copy)] Vec<u8> / Vec<u32> ...	✅	TypedArray	安全，强制拷贝
#[buffer(detach)] JsBuffer / bytes::Bytes	部分	ArrayBufferView	detach 模式安全
*const/*mut std::ffi::c_void	✅	External	外部指针
&OpState / &mut OpState / Rc<RefCell<OpState>>	✅	—	自动注入运行时状态
&JsRuntimeState	✅	—	仅在 deno_core 内可用

文档对转换 trait 的分工（op2 文档）：非 fast op 的参数默认走 deno_core::convert::FromV8Scopeless（不要求 scope，更高效）；需要 scope 时给参数加 #[scoped]。

返回值类型映射表

返回值侧的完整表在 op2 文档（<!-- START RV --> 区段），要点：

Rust	说明
基础数值（bool、i8–u32、f32、f64）	✅ 支持 fastcall
#[smi] ResourceId	SMI 语义同参数侧
#[bigint] i64/u64/isize/usize	✅ BigInt
#[number] i64/u64/isize/usize	✅ 但结果必须落在 Number.MIN_SAFE_INTEGER 与 Number.MAX_SAFE_INTEGER 之间
#[string] String/&str/Cow<str>、#[string(onebyte)] Cow<[u8]>	字符串族（返回值不走 fastcall）
#[arraybuffer] / #[buffer] 配 V8Slice/Vec/Box<[u8]>/bytes::BytesMut	以零拷贝视图或堆缓冲形式返回二进制数据
*const/*mut c_void	✅ External
v8::Local<v8::Value/String/Object/Function>	直接返回 V8 句柄
ToV8 类型及其二元组	任何实现 deno_core::convert::ToV8 的类型均可直接返回，无需属性
#[serde] ...	遗留方式，不推荐

CppGC 对象：用 Rust 定义原生 JavaScript 类

op2 文档 篇幅最大的部分定义了用 V8 CppGC（C++ 垃圾回收器）支撑的原生 JS 类：对象生活在 V8 堆上、由 GC 自动回收。生成逻辑位于 libs/ops/op2/object_wrap.rs。

基本用法

use deno_core::GarbageCollected;
use deno_core::v8::cppgc::GcCell;

#[repr(C)]
pub struct MyObject {
  value: GcCell<f64>,
}

unsafe impl GarbageCollected for MyObject {
  fn trace(&self, _visitor: &mut v8::cppgc::Visitor) {}
  fn get_name(&self) -> &'static std::ffi::CStr {
    c"MyObject"
  }
}

#[op2]
impl MyObject {
  #[constructor]
  #[cppgc]
  fn new(value: f64) -> MyObject {
    MyObject { value: GcCell::new(value) }
  }

  #[getter]
  fn value(&self, isolate: &v8::Isolate) -> f64 {
    *self.value.get(isolate)
  }

  #[setter]
  fn value(&self, isolate: &mut v8::Isolate, value: f64) {
    self.value.set(isolate, value)
  }

  #[fast]
  fn double_value(&self, isolate: &v8::Isolate) -> f64 {
    *self.value.get(isolate) * 2.0
  }

  #[static_method]
  #[cppgc]
  fn create(value: f64) -> MyObject {
    MyObject { value: GcCell::new(value) }
  }
}

注册进扩展（注意 objects = [...] 与 ops = [...] 是两个平行的注册列表）：

deno_core::extension!(
  my_ext,
  objects = [MyObject],
  // ...
);

JS 侧即可使用：

import { MyObject } from "ext:core/ops";

const obj = new MyObject(42);
console.log(obj.value);       // 42
console.log(obj.doubleValue()); // 84
obj.value = 10;

支持的成员类型：#[constructor]（构造函数，必须返回该 struct 类型，可包 Result；返回 CppGC 对象需加 #[cppgc]）、#[getter]/#[setter]（同名 getter/setter 绑定同一属性）、#[static_method]（如 MyObject.create()）、#[fast]（普通方法，首参 &self 接收原生对象）。实现细节上，generate_op2 会把 setter 函数重命名为 __set_<name>、静态方法重命名为 __static_<name>（libs/ops/op2/mod.rs），并限制每个对象至多一个 constructor（MultipleConstructors 错误）。

继承体系

CppGC 对象支持镜像 JS class Child extends Parent 的原型继承：

• 基类：struct 加 #[derive(CppgcBase)]，impl 块加 #[op2(base)]。base 标志让 &self 使用多态解包，使基类方法可以在任何子类实例上被调用；
• 派生类：struct 加 #[derive(CppgcInherits)] 与 #[cppgc_inherits_from(Base)]，基类类型必须是第一个字段，impl 块用 #[op2(inherit = BaseType)]；
• 中间层：既被继承又要继承别人的类型需同时 #[derive(CppgcInherits, CppgcBase)] 并写 #[op2(base, inherit = ParentType)]。

文档给出的 Shape → Rectangle → Square 链式示例可直接照搬：

#[derive(CppgcInherits)]
#[cppgc_inherits_from(Shape)]
#[repr(C)]
pub struct Rectangle {
  base: Shape, // must be the first field
  width: GcCell<f64>,
  height: GcCell<f64>,
}

#[op2(inherit = Shape)]
impl Rectangle {
  #[constructor]
  #[cppgc]
  fn new(width: f64, height: f64) -> Rectangle { /* ... */ }

  #[fast]
  fn area(&self, isolate: &v8::Isolate) -> f64 {
    *self.width.get(isolate) * *self.height.get(isolate)
  }
}

const rect = new Rectangle(3, 4);
console.log(rect.sides);                    // 4 (inherited from Shape)
console.log(rect.area());                    // 12
console.log(rect instanceof Shape);         // true

class Square extends Rectangle {
  constructor(size) { super(size, size); }
}
console.log(new Square(5).area());           // 25

硬性约束（文档 Requirements 小节）：继承链上所有类型必须 #[repr(C)]；基类字段必须位于偏移 0；所有类型都要注册进 objects = [...]，且基类必须先于派生类列出。

WebIDL 与 FromV8/ToV8 derive

对普通 op 参数/返回值，deno_ops 还提供三个 derive 补全类型生态：

• #[derive(WebIDL)]（实现见 libs/ops/webidl/mod.rs）：要求类型带顶层 #[webidl(dictionary)] 或 #[webidl(enum)] 属性——struct 只能配 dictionary，enum 只能配 enum，union 直接报错；dictionary 侧还支持 default、rename、required 字段属性；
• #[derive(FromV8)] / #[derive(ToV8)]（实现在 libs/ops/conversion/）：字段上可加 #[v8(rename = "...")] 调整 JS 侧字段名，#[v8(serde)] 回退到 serde 式转换。

这两个 derive 与 op2 文档中的 FromV8Scopeless 默认路径、#[scoped] FromV8 路径共同构成参数/返回值转换的完整谱系。

宏展开测试基础设施

deno_ops 本身的可信度由一套宏展开快照测试保证，值得在改动或依赖该 crate 时了解：

• 测试用例集中在 libs/ops/op2/test_cases/（sync/async 两族，覆盖 string_onebyte、buffers_out、cppgc_resource、object_wrap、fast_alternative、async_lazy 等每个特性面），每个 .rs 输入都有同名 .out 期望输出文件；
• 统一入口 run_macro_expansion_test（libs/ops/lib.rs）要求源文件以固定 prelude（deno_ops_compile_test_runner::prelude!()，见 libs/ops/compile_test_runner）开头，展开后用 prettyplease 美化并逐字比对 .out 文件；设置环境变量 UPDATE_EXPECTED 后可重写期望文件；
• 负向用例放在 libs/ops/op2/test_cases_fail/，配对 .stderr 文件校验编译错误信息。

这套机制意味着：任何 op2 生成的代码变化都会体现在 .out 快照 diff 中，是阅读该 crate 提交史时最值得看的文件。

小结

libs/ops 是 Deno "Rust 与 V8 之间的那层纸"：一个 #[op2] 属性宏 + 四个 derive 宏，换来的是编译期完成的签名解析、类型映射、fastcall 生成与 CppGC 对象绑定，以及编译期即暴露的 ShouldBeFast、标志乱序、非法组合等防御性检查。编写 op 时可按此决策路径：签名能 fastcall 就标 fast；字符串按性能需求在 &str 与 string(onebyte) 间选择；异步 op 默认 eager、谨慎使用 lazy/deferred；复杂参数结构用 #[derive(FromV8)]；需要原生 JS 类时用 CppGC 对象并注意 objects 注册顺序。所有细节均可回溯到 libs/ops/README.md、libs/ops/op2/README.md、libs/ops/op2/config.rs 与 libs/ops/op2/valid_args.md。