Rust 实战丨通过实现 json! 掌握声明宏

在 Rust 编程语言中，宏是一种强大的工具，可以用于在编译时生成代码。json! 是一个在 Rust 中广泛使用的宏，它允许我们在 Rust 代码中方便地创建 JSON 数据。

声明宏（declarative macros）是 Rust 中的一种宏，它们使用 macro_rules! 关键字定义。

本文将参考《Rust 程序设计（第二版）》，通过实现 json! 宏，深入理解声明宏的工作原理。

结论先行

本文我们将构建一个 json! 宏，它支持我们以字符串 JSON 风格的语法来编写 Json 值。如下面这个例子：

let students = json![{"name": "Hedon Wang","class_of": 2022,"major": "Software engineering"},{"name": "Jun Lei","class_of": 1991,"major": "Computor science"}
]

完整代码

实现 json!

定义 Json enum

首先我们需要思考一下 Json 结构是什么样子的？主要是以下 3 种模式：

{"name": "hedon","age": 18,"school": {"name": "Wuhan University","address": "Hubwi Wuhan"}
}

[{"name": "hedon"},{"name": "john"}
]

null

为此我们定义一个 Json 结构的枚举：

#[derive(Clone, PartialEq, Debug)]
pub enum Json {Null,Boolean(bool),Number(f64),String(String),Array(Vec<Json>),Object(HashMap<String, Json>),
}

你应该可以感到非常奇妙，使用一个这么简单的枚举，居然就可以表示所有的 Json 结构了。遗憾的是，现在这个结构编写 Json 值的语法相当冗长。

let people = Json::Object(HashMap::from([("name".to_string(), Json::String("hedon".to_string())),("age".to_string(), Json::Number(10.0)),("is_student".to_string(), Json::Boolean(true)),("detail".to_string(),Json::Object(HashMap::from([("address".to_string(), Json::String("beijing".to_string())),("phone".to_string(), Json::String("1234567890".to_string()))])))
]))

我们期望可以以下面这种方式来声明 Json 变量，这看起来就清爽许多了。

let students = json!([{"name": "Jim Blandy","class_of": 1926,"major": "Tibetan throat singing"},{"name": "Jason Orendorff","class_of": 1702,"major": "Knots"}
]);

猜想 json!

我们可以预见 Json 宏内部将会有多条规则，因为 JSON 数据有多种类型：对象、数组、数值等。事实上，我们可以合理地猜测每种 JSON 类型都将有一条规则：

macro_rules! json {(null)    => { Json::Null };([ ... ]) => { Json::Array(...) };({ ... }) => { Json::Object(...) };(???)     => { Json::Boolean(...) };(???)     => { Json::Number(...) };(???)     => { Json::String(...) };
}

然而这不太正确，因为宏模式无法区分最后 3 种情况，稍后我们会讨论如何处理。至于前 3 种情况，显然它们是以不同的语法标记开始的，所以这几种情况比较好处理。

实现 Null

我们先从最简单的 Null 分支开始，先编写如下测试用例：

#[cfg(test)]
mod tests {use super::*;#[test]fn test_null_json() {let json = json!(null);assert_eq!(json, Json::Null);}
}

想要通过上述测试用例非常简单，我们只需要在 macro_rules! 支持中匹配这种情况即可：

#[macro_export]
macro_rules! json {(null) => {Json::Null};
}

• #[macro_export] 注解是 Rust 中的一个属性，用于指示这个宏应该被导出到调用者的作用域中，这样其他模块也可以使用它。
• macro_rules! 宏定义了一个自定义的宏。在这里，它创建了一个名为 json 的宏，用于生成 JSON 数据。
• 宏定义中 (null) 是匹配模式。这意味着当你调用 json! 宏并传递 null 作为参数时，将会触发这个规则。
• => 符号用于指示匹配模式后的代码块。在这里，它指定了当匹配 (null) 时应该生成的代码块。
• Json::Null 是一个 JSON 类型的枚举值，表示 JSON 中的 null 值。这个宏的目的是将传入的 null 转换为 Json::Null。

实现 Boolean/Number/String

我们先准备如下测试用例：

#[test]
fn test_boolean_number_string_json() {let json = json!(true);assert_eq!(json, Json::Boolean(true));let json = json!(1.0);assert_eq!(json, Json::Number(1.0));let json = json!("hello");assert_eq!(json, Json::String("hello".to_string()));
}

通过观察分析，它们其实都是同一种模式：

现在需要解决的问题就是，如何将这 3 种模式进行统一，这样在 macro_rules! 中才可以统一匹配模式并进行代码生成。

这里我们其实需要做的就是将 bool、f64 和 &str 转为对应的 Json 类型。那就需要用到标准库中的 From trait 了。

做法很简单，我们实现如下代码：

impl From<bool> for Json {fn from(value: bool) -> Self {Json::Boolean(value)}
}impl From<&str> for Json {fn from(value: &str) -> Self {Json::String(value.to_string())}
}impl From<f64> for Json {fn from(value: f64) -> Self {Json::Number(value)}
}

然后完善我们的 json!，目前的实现如下：

#[macro_export]
macro_rules! json {(null) => {Json::Null};($value: tt) => {Json::from($value)};
}

这里我们使用 $value作 为变量来承接匹配到的元素，其类型为 tt ，表示任意的语法标记树。具体可以参考：片段类型。

这时运行上述测试用例，是没有问题的：

  PASS [   0.004s] json-macro tests::test_boolean_number_string_jsonPASS [   0.004s] json-macro tests::test_null_json

美中不足的是，JSON 结构中的数字类型，其实不一定是 f64，也可以是 i32、u32、f32 或其他的数字类型，如果我们要为这全部的数字类型都实现到 Json 的 From trait，那就多冗余。

这个时候我们又可以实现一个宏，用于快速生成 impl From<T> for Json 。这个实现比较简单，本文就不赘述了，代码如下：

#[macro_export]
macro_rules! impl_from_for_primitives {(  $( $type: ty ) * ) => {$(impl From<$type> for Json {fn from(value: $type) -> Self {Json::Number(value as f64)}})*}
}

然后我们只需要用下面这一行代码，就可以为所有的数字类型实现 From trait 了：

impl_from_for_primitives!(u8 u16 u32 u64 i8 i16 i32 i64 f32 f64 isize usize);

记得这个时候你要删除上面手动实现的 impl From<f64> for Json，不然会有 impl 冲突错误。

再次运行测试，也是可以通过的。

实现 Array

准备如下测试用例：

#[test]
fn test_array_json() {let json = json!([1, null, "string", true]);assert_eq!(json,Json::Array(vec![Json::Number(1.0),Json::Null,Json::String("string".to_string()),Json::Boolean(true)]))
}

要匹配 [1, null, "string", true]这个模式，笔者的分析过程如下：

1. 首先是外面的两个中括号 [ 和 ] ；
2. 再往里，是一个重复匹配的模式，以 , 分割，可以匹配 0 到任意多个元素，所以是 $( ,*) ，具体可以参考：重复模式；
3. 最里面就是第 2 步要匹配的元素了，我们先用 $element 作为变量来承接每一个元素，其类型为 tt ，表示任意的语法标记树。

分析完匹配的表达式后，我们就可以得到：

([ $( $element:tt ), * ]) => { /* TODO */ }

我们要生成的代码长这个样子：

Json::Array(vec![Json::Number(1.0),Json::Null,Json::String("string".to_string()),Json::Boolean(true)
])

其实就是一个 vec!，然后里面每个元素都是一个 Json，如此递归下去。

即可以得到代码生成部分的逻辑为：

Json::Array(vec![$(json!($element)),* ])

综上，我们实现的代码如下：

#[macro_export]
macro_rules! json {(null) => {Json::Null};([ $( $element: tt),* ]) => {Json::Array(vec![ $( json!($element)), * ])};($value: tt) => {Json::from($value)};
}

运行测试用例：

PASS [   0.003s] json-macro tests::test_null_json
PASS [   0.003s] json-macro tests::test_boolean_number_string_json
PASS [   0.004s] json-macro tests::test_array_json

实现 Object

写好如下测试用例，这次我们顺带把 Null、Boolean、Number 和 String 带上了：

#[test]
fn test_object_json() {let json = json!({"null": null,"name": "hedon","age": 10,"is_student": true,"detail": {"address": "beijing","phone": "1234567890"}});assert_eq!(json,Json::Object(HashMap::from([("name".to_string(), Json::String("hedon".to_string())),("age".to_string(), Json::Number(10.0)),("is_student".to_string(), Json::Boolean(true)),("detail".to_string(),Json::Object(HashMap::from([("address".to_string(), Json::String("beijing".to_string())),("phone".to_string(), Json::String("1234567890".to_string()))])))])))
}

对比预期的 json! 宏内容和展开后的代码：

完善我们的 macro_rules! json ：

#[macro_export]
macro_rules! json {(null) => {Json::Null};([ $( $element: tt),* ]) => {Json::Array(vec![ $( json!($element)), * ])};({ $( $key:tt : $value:tt ),* }) => {Json::Object(HashMap::from([$(( $key.to_string(), json!($value) )), *]))};($value: tt) => {Json::from($value)};
}

运行测试用例：

PASS [   0.004s] json-macro tests::test_object_json
PASS [   0.005s] json-macro tests::test_array_json
PASS [   0.004s] json-macro tests::test_null_json
PASS [   0.005s] json-macro tests::test_boolean_number_string_json

至此，我们就完成了 json! 宏的构建了！完整源码可见：完整代码

Peace! Enjoy coding~

附录

重复模式

在 实现 Array 中，我们匹配了这样一个模式：

([ $( $element:tt ), * ]) => { /* TODO */ }

其中 $($element:tt), *) 就是一个重复模式，其可以进一步抽象为 $( ... ),* ，表示匹配 0 次或多次，以 , 分隔。

Rust 支持以下全部重复模式：

模式	含义
$( … ) *	匹配 0 次或多次，没有分隔符
$( … ), *	匹配 0 次或多次，以逗号分隔
$( … ); *	匹配 0 次或多次，以分号分隔
$( … ) +	匹配 1 次或多次，没有分隔符
$( … ), +	匹配 1 次或多次，以逗号分隔
$( … ); +	匹配 1 次或多次，以分号分隔
$( … ) ?	匹配 0 次或 1 次，没有分隔符

即：

• * 表示 0 次或多次
• + 表示 1 次或多次
• ? 表示 0 次或 1 次
• 可在上述 3 者之前加入分隔符

片段类型

在 实现 Array 中，我们匹配了这样一个模式：

([ $( $element:tt ), * ]) => { /* TODO */ }

这里我们将 $element 指定为 tt，这个 tt 就是宏中的一种片段类型。

tt 能匹配单个语法标记树，包含：

• 一对括号，如 (..)、[..]、或 {..} ，以及位于其中的所有内容，包括嵌套的语法标记树。
• 单独的非括号语法标记，比如 1926 或 Knots 。

所以为了匹配任意类型的 Json ，我们选择了 tt 作为 $element 的片段类型。

macro_rules! 支持的片段类型如下所示：

片段类型	匹配（带例子）	后面可以跟 ······
expr	表达式：2 + 2, “udon”, x.len()	=>,;
stmt	表达式或声明，不包括任何尾随分号（很难用，请尝试使用 expr 或 block）	=>,;
ty	类型：String, Vec, (&str, bool), dyn Read + Send	=>,; =
path	路径：ferns, ::std::sync::mpsc	=>,; =
pat	模式：_, Some(ref x)	=>,=
item	语法项：struct Point { x: f64, y: f64 }, mod ferns;	任意
block	块：{ s += “ok\n”; true }	任意
meta	属性的主体：inline, derive(Copy, Clone), doc=“3D models.”	任意
literal	字面量值：1024, “Hello, world!”, 1_000_000f64	任意
lifetime	生命周期：'a, 'item, 'static	任意
vis	可见性说明符：pub, pub(crate), pub(in module::submodule)	任意
ident	标识符：std, Json, longish_variable_name	任意
tt	语法标记树：;, >=, {}, [0 1 (+ 0 1)]	任意

完整代码

use std::collections::HashMap;#[derive(Debug, Clone, PartialEq)]
#[allow(unused)]
enum Json {Null,Boolean(bool),String(String),Number(f64),Array(Vec<Json>),Object(HashMap<String, Json>),
}impl From<bool> for Json {fn from(value: bool) -> Self {Json::Boolean(value)}
}impl From<&str> for Json {fn from(value: &str) -> Self {Json::String(value.to_string())}
}impl From<String> for Json {fn from(value: String) -> Self {Json::String(value)}
}#[macro_export]
macro_rules! impl_from_for_primitives {(  $( $type: ty ) * ) => {$(impl From<$type> for Json {fn from(value: $type) -> Self {Json::Number(value as f64)}})*}
}impl_from_for_primitives!(u8 u16 u32 u64 i8 i16 i32 i64 f32 f64 isize usize);#[macro_export]
macro_rules! json {(null) => {Json::Null};([ $( $element: tt),* ]) => {Json::Array(vec![ $( json!($element)), * ])};({ $( $key:tt : $value:tt ),* }) => {Json::Object(HashMap::from([$(( $key.to_string(), json!($value) )), *]))};($value: tt) => {Json::from($value)};
}#[cfg(test)]
mod tests {use super::*;#[test]fn test_null_json() {let json = json!(null);assert_eq!(json, Json::Null);}#[test]fn test_boolean_number_string_json() {let json = json!(true);assert_eq!(json, Json::Boolean(true));let json = json!(1.0);assert_eq!(json, Json::Number(1.0));let json = json!("hello");assert_eq!(json, Json::String("hello".to_string()));}#[test]fn test_object_json() {let json = json!({"null": null,"name": "hedon","age": 10,"is_student": true,"detail": {"address": "beijing","phone": "1234567890"}});assert_eq!(json,Json::Object(HashMap::from([("null".to_string(), Json::Null),("name".to_string(), Json::String("hedon".to_string())),("age".to_string(), Json::Number(10.0)),("is_student".to_string(), Json::Boolean(true)),("detail".to_string(),Json::Object(HashMap::from([("address".to_string(), Json::String("beijing".to_string())),("phone".to_string(), Json::String("1234567890".to_string()))])))])))}#[test]fn test_array_json() {let json = json!([1, null, "string", true]);assert_eq!(json,Json::Array(vec![Json::Number(1.0),Json::Null,Json::String("string".to_string()),Json::Boolean(true)]))}
}