4、派生宏（Derive Macro）：使用syn和quote库实现自定义派生宏，为结构体自动实现Trait

派生宏，说白了就是帮我们自动写代码的「代码生成器」。你想想看，每次给结构体加个字段，就得手动去实现一堆 Trait 方法，是不是很烦？我刚开始写 Rust 时，就经常被这种重复劳动搞得头大。后来学会了自定义派生宏，才真正体会到什么叫「一劳永逸」。

4.1 派生宏的本质

派生宏属于「过程宏」的一种。它接收一个结构体或枚举的 AST（抽象语法树），然后输出一个新的 TokenStream。这个新流里包含了我们要实现的 Trait 方法。

嗯，这里要注意：派生宏只能用在结构体、枚举和联合体上。你不能给一个函数或者一个 impl 块加派生宏。

4.2 项目结构准备

要实现派生宏，我们需要两个 crate：一个用于宏定义，一个用于测试。我个人习惯把宏定义放在单独的 crate 里，名字叫 my_derive，然后在主项目里引用。

my_project/
├── Cargo.toml          # 主项目
├── src/
│   └── main.rs
└── my_derive/
    ├── Cargo.toml      # 宏定义 crate
    └── src/
        └── lib.rs

主项目的 Cargo.toml 要这样写：

[dependencies]
my_derive = { path = "my_derive" }

宏定义 crate 的 Cargo.toml 需要加上 proc-macro 标记：

[lib]
proc-macro = true

[dependencies]
syn = { version = "2.0", features = ["full"] }
quote = "1.0"

4.3 实战：实现一个 ToJson 派生宏

我们来写一个实用的例子：自动为结构体实现 ToJson Trait。这个 Trait 会把结构体转换成 JSON 字符串。

先定义 Trait：

// 在 main.rs 或单独的模块中
pub trait ToJson {
    fn to_json(&self) -> String;
}

然后实现派生宏。这是 my_derive/src/lib.rs 的核心代码：

use proc_macro::TokenStream;
use quote::quote;
use syn::{Data, DeriveInput, Fields, Type};

#[proc_macro_derive(ToJson)]
pub fn derive_to_json(input: TokenStream) -> TokenStream {
    // 解析输入的结构体定义
    let input: DeriveInput = syn::parse(input).unwrap();
    let name = &input.ident;

    // 只处理结构体，忽略枚举
    let fields = match &input.data {
        Data::Struct(data) => &data.fields,
        _ => panic!("ToJson 只能用于结构体"),
    };

    // 提取字段名和类型
    let field_pairs = match fields {
        Fields::Named(fields) => {
            fields.named.iter().map(|f| {
                let field_name = f.ident.as_ref().unwrap();
                let field_type = &f.ty;
                (field_name, field_type)
            }).collect::<Vec<_>>()
        }
        _ => panic!("ToJson 只支持命名字段的结构体"),
    };

    // 生成 JSON 键值对
    let json_pairs = field_pairs.iter().map(|(name, ty)| {
        let key_str = name.to_string();
        quote! {
            format!("\"{}": {}", #key_str, self.#name.to_json())
        }
    });

    // 组装最终的 impl 代码
    let expanded = quote! {
        impl ToJson for #name {
            fn to_json(&self) -> String {
                let mut parts = vec![
                    #(#json_pairs),*
                ];
                format!("{{{}}}", parts.join(", "))
            }
        }
    };

    TokenStream::from(expanded)
}

4.4 使用派生宏

现在我们可以这样用了：

use my_derive::ToJson;

#[derive(ToJson)]
struct Person {
    name: String,
    age: u32,
    email: String,
}

fn main() {
    let p = Person {
        name: "张三".to_string(),
        age: 30,
        email: "zhangsan@example.com".to_string(),
    };
    println!("{}", p.to_json());
    // 输出: {"name": 张三, "age": 30, "email": zhangsan@example.com}
}

嗯，这里有个问题：我们的 to_json 方法递归调用了字段自身的 to_json，但 u32 和 String 并没有实现 ToJson。所以实际使用时，需要为基本类型也实现这个 Trait。

impl ToJson for String {
    fn to_json(&self) -> String {
        format!("\"{}\"", self)
    }
}

impl ToJson for u32 {
    fn to_json(&self) -> String {
        self.to_string()
    }
}

// 其他类型类似...

4.5 处理属性（Attributes）

我曾经在项目中遇到一个需求：某些字段在序列化时要用不同的名字。比如结构体里叫 user_name，但 JSON 里希望是 userName。这就需要用到派生宏的属性了。

我们可以定义一个 #[json(name = "xxx")] 属性：

use syn::{Attribute, Lit, Meta, NestedMeta};

fn extract_json_name(attrs: &[Attribute]) -> Option<String> {
    for attr in attrs {
        if attr.path.is_ident("json") {
            let meta = attr.parse_meta().ok()?;
            if let Meta::List(list) = meta {
                for nested in &list.nested {
                    if let NestedMeta::Meta(Meta::NameValue(nv)) = nested {
                        if nv.path.is_ident("name") {
                            if let Lit::Str(lit) = &nv.lit {
                                return Some(lit.value());
                            }
                        }
                    }
                }
            }
        }
    }
    None
}

然后在生成代码时，优先使用属性指定的名字：

let json_pairs = field_pairs.iter().map(|(name, ty, attrs)| {
    let key_str = extract_json_name(attrs).unwrap_or_else(|| name.to_string());
    quote! {
        format!("\"{}": {}", #key_str, self.#name.to_json())
    }
});

4.6 常见陷阱与调试技巧

问题	原因	解决方案
编译错误：找不到 Trait	派生宏生成的代码引用了未导入的 Trait	在生成的代码中使用完整路径，如 crate::ToJson
属性解析失败	syn 版本不匹配或属性格式错误	检查 syn 版本，使用 parse_meta() 方法
递归调用栈溢出	字段类型没有实现 Trait	为基本类型实现 Trait，或添加类型约束

4.7 调试派生宏

调试派生宏比较麻烦，因为错误信息往往不直观。我推荐两个方法：

1. 使用 cargo expand：安装 cargo-expand 工具，可以查看宏展开后的代码。
2. 打印中间结果：在宏函数里用 eprintln! 打印解析到的信息。

#[proc_macro_derive(ToJson)]
pub fn derive_to_json(input: TokenStream) -> TokenStream {
    let input: DeriveInput = syn::parse(input).unwrap();
    eprintln!("结构体名: {}", input.ident);
    // ... 其他调试信息
}

你想想看，如果没有这些调试手段，光靠猜错误原因，那效率得多低啊。

4.8 性能考量

派生宏是在编译期执行的，所以它的性能影响主要在编译阶段。运行时性能取决于生成的代码质量。我个人建议：

• 避免在宏里做复杂的计算或 IO 操作
• 生成的代码尽量简洁，不要生成不必要的中间变量
• 如果 Trait 方法会被频繁调用，考虑用 #[inline] 标记

说白了，派生宏就是「用编译时间换开发时间」。对于大多数项目来说，这个 trade-off 是非常值得的。

---