[from js to rust 系列][宏-01][官网文档 19.5]高级特性：宏[译文]

Posted 2023-02-17

参考技术A 原文链接：The Rust Programming Language

作者：rust 团队

译文首发链接：zhuanlan.zhihu.com/p/516660154

著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。

中间加了一些对于 JavaScript 开发者有帮助的注解。在学习 Rust 的代码时，尤其是有一些经验的开发者，一般都会去看一些相对简单的库，或者项目去学习。Rust 的原生语法本身并不复杂，有一定的 TypeScript 经验的开发者，应该通过看一些教程，都能开始熟悉基本的语法。反而是宏相关内容，虽然就像本文写的，大部分开发者不需要自己去开发宏，但是大家使用宏，和看懂别人代码的主体逻辑，几乎是绕不开宏的。虽然宏在 rust 里属于“高级”内容，但是因为其和 rust 本身语法的正交性，Hugo 认为，反而应该早一些学习。并且，如果一个 JavaScript 开发者之前接触过代码生成器、babel，对这一章的内容反而会比较亲切。

Derive 宏、attribute 宏特别像 rust 里的装饰器。从作用上，和一般库提供的接口来看，也特别像。所以如果之前有装饰器的经验的开发者，对这一章节应该也会比较亲切。

我们一个个来讨论这些内容，但是首先，我们看既然我们已经有了函数，我们为什么需要这些特性。

基本上，宏是指一些代码可以生成另一些代码，这一块的技术一般称为元编程（Hugo 注：代码生成器也属于这一类技术）。在附录 C，我们讨论了 derive 属性，可以帮助你生成一系列的 trait。整本书我们也在用 println! 和 vec! 宏。这些宏在编译时，都会展开成为代码，这样你就不需要手写这些代码。

元编程可以帮助你减少手写和维护的代码量，当然，函数也能帮助你实现类似的功能。但是，宏有函数没有的威力。

宏不好的地方在于，宏很复杂，因为你要用 rust 代码写 rust 代码（Hugo 注：任何元编程都不是简单的事儿，包括 JS 里的。）。因为这种间接性，宏的代码要更难读、难理解、难维护。（Hugo 注：个人学 rust，感觉最难不是生命周期，因为生命周期的问题，可以通过用一些库绕过去，或者无脑 clone，如果是应用程序，则可以通过使用 orm 和数据库来绕过很多生命周期的问题。反而是宏，因为稍微有点规模的代码的，都有一大堆宏。宏最难的不是语法，而是作者的意图，因为本质是他造了一套 DSL）

另一个和函数不一样的地方是，宏需要先定义或者引入作用域，而函数可以在任何地方定义和使用。

我们可以通过 vec! 宏来创建任意类型的 vector，例如 2 个 integer，或者五个 string slice.

一个简化的 vec! 宏：

#[macro_export] 标注指明了这个宏在 crate 的作用域里可用。没有这个标注，宏不会被带入到作用域里。

macro_rules! 后面就是宏的名字。这里只有一种模式匹配的边（arm）：( (( (x:expr ),* ) ，=> 后面是这个模式对应要生成的代码。如果这个模式匹配成功，对应的代码和输入的参数组成的代码就会生成在最终的代码中。因为这里只有一种边，所以只有这一种可以匹配的条件。不符合这个条件的输入，都会报错。一般复杂的宏，都会有多个边。

这里匹配的规则和 match 是不一样的，因为这里的语法匹配的是 rust 的语法，而不是 rust 的类型，或者值。更全的宏匹配语法，见文档。

对于 宏的输入条件 ( (( (x:expr ),* )，()内部是匹配的语法，expr表示所有Rust的表达式。() 内部是匹配的语法，expr 表示所有 Rust 的表达式。()内部是匹配的语法，expr表示所有Rust的表达式。() 后面的都喊表示这个变量后面有可能有逗号，* 表示前面的模式会出现一次或者多次。（Hugo 注：像不像正则？宏语法其实挺简单的，不要被高级唬住了。当然，宏还是难的，宏要考虑的问题本身是一个复杂的问题。）

当我们调用：vec![1, 2, 3]; 时，$x 模式会匹配 3 个表达式 1 ， 2 和 3。

现在我们看一下和这个边匹配的生成代码的部分：

在 ()里的tempvec.push(() 里的 temp_vec.push(()里的tempvec.push(x); 就是生成的代码的部分。* 号仍然表示生成零个和多个，这个匹配的具体个数，要看匹配条件命中的个数。

你传任意参数，最后就生成符合上面条件的代码。

虽然过程宏有三种：custom derive、attribute-like 和 function-like，但是原理都是一样的。

如果要创建过程宏，定义的部分需要在自己的 crate 里，并且要定义特殊的 crate 类型。（Hugo 注：相当于定义了一个 babel 插件，只不过有一套 rust 自己的体系。这些宏会在编译的时候，按照书写的规则，转成对应的代码。所有的宏，都是代码生成的手段，输入是代码，输入是代码。）这种设计，我们有可能会在未来消除。

下面是一个过程宏的例子：

过程宏接收一个 TokenStream，输出一个 TokenStream。TokenStream 类型定义在 proc_macro 里，表示一系列的 tokens。这个就是这种宏的核心机制，输入的代码(会被 rust) 转成 TokenStream，然后做一些按照业务逻辑的操作，最后生成 TokenStream。这个函数也可以叠加其他的属性宏(#[some_attribute], 看起来像装饰器的逻辑，也可以理解为一种链式调用)，可以在一个 crate 里定义多个过程。（Hugo 注：搞过 babel 的同学肯定很熟悉，一样的味道。没搞过的同学，强烈建议先学学 babel。）

下面我们来看看不同类型的过程宏。首先从自定义 derive 宏开始，然后我们介绍这种宏和其他几种的区别。

我们创建一个 crate 名字叫 hello_macro，定义一个 HelloMacro 的 trait，关联的函数名字叫 hello_macro。通过使用这个宏，用户的结构可以直接获得默认定义的 hello_macro 函数，而不需要实现这个 trait。默认的 hello_macro 可以打印 Hello, Macro! My name is TypeName!，其中 TypeName 是实现这个 derive 宏的结构的类型名称。

创建这个宏的过程如下，首先

然后定义 HelloMacro trait

这样我们就有了一个 trait，和这个triat 的函数。用户可以通过这个 trait 直接实现对应的函数。

但是，用户需要每次都实现一遍 hello_macro。如果 hello_macro 的实现都差不多，就可以通过 derive 宏来是实现。

因为 Rust 没有反射机制，我们不可以在执行时知道对应类型的名字。我们需要在编译时生成对应的代码。

下一步，定义过程宏。在这个文章编写时，过程宏需要在自己的 crates 里。最终，这个设计可能改变。关于 宏 crate 的约定是：对于一个名为 foo 的 crate，自定义 drive 宏的crate 名字为 foo_derive。我们在 hello_macro 项目中创建 hello_macro_derive crate。

我们的两个的 crate 关联紧密，所以我们在 hello_macro crate 里创建这个 crate。如果我们要改变 hello_macro 的定义，我们同样也要更改 hello_macro_derive 的定义。这两个 crates 要隔离发布。当用户使用时，要同时添加这两个依赖。为了简化依赖，我们可以让 hello_macro 使用 hello_macro_derive 作为依赖，然后导出这个依赖。但是，这样，如果用户不想使用 hello_macro_derive，也会自动添加上这个依赖。

下面开始创建 hello_macro_derive，作为一个过程宏 crate。需要添加依赖 syn 和 quote。下面是这个 crate 的 Cargo.toml。

在 lib.rs 里添加下述代码。注意，这个代码如果不增加 impl_hello_macro 的实现是通不过编译的。

注意，这里把代码分散成两部分，一部分在 hello_macro_derive 函数里，这个函数主要负责处理 TokenStream，另一部分在 impl_hello_macro，这里负责转换语法树：这样编写过程宏可以简单一些。在绝大部分过程宏立，对于前者的过程一般都是一样的。一般来说，真正的区别在 impl_hello_macro，这里的逻辑一般是一个过程宏的业务决定的。

我们引入了三个 crates: proc_macro, syn 和 quote。proc_macro 内置在 rust 立，不需要在 Cargo.toml 中引入。proc_macro 实际是 rust 编译器的一个接口，用来读取和操作 Rust 代码。

syn crate 把 Rust 代码从字符串转换为可以操作的结构体。quote crate 把 syn 数据在转回 Rust 代码。这些 Crate 可以极大简化过程宏的编写：写一个 Rust 代码的 full parser 可不是容易的事儿！

当在一个类型上标注 [derive(HelloMacro)] 时，会调用 hello_macro_derive 函数。之所以会有这样的行为，是因为在定义 hello_macro_derive 时，标注了 #[proc_macro_derive(HelloMacro)] 在函数前面。

hello_macro_derive 会把输入从 TokenStream 转换为一个我们可以操作的数据结构。这就是为什么需要引入 syn 。sync 的 parse 函数会把 TokenStream 转换为 DeriveInput。

上述这个结构的意思是：正在处理的是 ident(identifier, 意味着名字)为 Pancakes 的 unit struct。其他的字段表示其余的 Rust 代码。如果想了解更详细的内容，请参考。

接下来，我们就要开始定义 impl_hello_macro。这个函数实现了添加到 Rust 代码上的函数。在我们做之前，注意 derive macro 的输出也是 TokenStream。返回的 TokenStream 就是添加完代码以后的代码。当编译 crate 时，最终的代码，就是处理完成的代码了。

你也许也会发现，这里调用 syn::parse 时使用了 unwrap，如果报错就中断。这里必须这么做，因为最终返回的是 TokenStream，而不是 Result。这里是为了简化代码说明这个问题。在生产代码，你应该处理好报错，提供更详细的报错信息，例如使用 panic! 或者 expect。

下面是代码：

通过上面的代码，cargo build 就可以正常工作了。如果要使用这个代码，需要把两个依赖都加上。

现在执行下面的代码，就可以看到 Hello, Macro! My name is Pancakes!

下一步，我们来 探索 其他类型的过程宏。

属性宏和 derive 宏类似，但是可以创造除了 derive 意外的属性。derive 只能作用于 structs 和 enums，属性宏可以作用于其他的东西，比如函数。下面是一个属性宏的例子：例如你制作了一个名为 route 的属性宏来在一个web 框架中标注函数。

#[route] 是框架定义的过程宏。定义这个宏的函数类似：

这里，有两个参数，类型都是 TokenStream。第一个是属性的内容，GET, "/" 部分，第二个是标注属性宏传入的语法部分，在这个例子里，就是剩下的 fn index() 。

工作原理和 derive 宏是一样的。

函数宏的使用比较像调用一个 rust 函数。函数宏有点像 macro_rules! ，能提供比函数更高的灵活性。例如，可以接受未知个数的参数。但是，macro_rules！ 只能使用在上述章节的匹配型的语法。而函数宏接受 TokenStream 参数作为入参，和其他过程宏一样，可以做任何变换，然后返回 TokenStream。下面是一个函数宏 sql！

这个宏接受 SQL 语句，可以检查这个 SQL 的语法是否正确，这种功能比 macro_rules! 提供的要复杂的多。这个 sql! 的宏可以定义为：

这个定义和自定义 derive 宏类似：接受括号内的 tokens，返回生成的代码。

好了，现在你有了一些可能不常用的 Rust 新工具，但是你要知道的是，在需要的场合，他们的运行原理是什么。我们介绍了一些复杂的话题，当你在错误处理或者别人的代码里看到这些宏时，可以认出这些概念和语法。可以使用这一章的内容作为解决这些问题的索引。