syn 解析库 ​

核心概念 ​

syn 是 Rust 过程宏开发中最重要的解析库,它将 TokenStream(扁平的 token 序列)解析为结构化的抽象语法树(AST)。有了 syn,过程宏开发者不需要手动遍历 token,而是可以直接操作类型名、字段列表、泛型参数等有语义的数据结构。

syn 提供了 Rust 所有语法结构的解析类型:DeriveInput(派生宏输入)、ItemFn(函数定义)、ItemStruct(结构体定义)、Expr(表达式)等。它还提供了 Parse trait,允许开发者定义自定义的解析规则来处理 DSL 语法。

syn 与 quote 配合使用构成过程宏的标准工作流:syn 解析输入,业务逻辑处理 AST,quote! 生成输出。

rust
// syn 的典型使用方式(过程宏 crate 中)
//
// use syn::{parse_macro_input, DeriveInput};
//
// #[proc_macro_derive(MyMacro)]
// pub fn my_macro(input: TokenStream) -> TokenStream {
//     // parse_macro_input! 将 TokenStream 解析为 DeriveInput
//     let input = parse_macro_input!(input as DeriveInput);
//     
//     // 现在可以访问结构化的信息
//     let name = &input.ident;         // 类型名
//     let generics = &input.generics;  // 泛型参数
//     let data = &input.data;          // 字段/变体数据
//     
//     // ... 生成代码 ...
//     todo!()
// }

fn main() {
    println!("syn 将 TokenStream 解析为结构化的 AST");
    println!("标准工作流:syn 解析 → 逻辑处理 → quote 生成");
}

核心类型 ​

rust
// === DeriveInput:派生宏的输入 ===
//
// pub struct DeriveInput {
//     pub attrs: Vec<Attribute>,    // 属性列表
//     pub vis: Visibility,          // 可见性
//     pub ident: Ident,             // 类型名
//     pub generics: Generics,       // 泛型参数
//     pub data: Data,               // 数据(Struct/Enum/Union)
// }

// === Data:类型数据 ===
//
// pub enum Data {
//     Struct(DataStruct),   // 结构体
//     Enum(DataEnum),       // 枚举
//     Union(DataUnion),     // 联合体
// }

// === Fields:字段列表 ===
//
// pub enum Fields {
//     Named(FieldsNamed),       // struct Foo { x: i32 }
//     Unnamed(FieldsUnnamed),   // struct Foo(i32)
//     Unit,                     // struct Foo;
// }

// === Field:单个字段 ===
//
// pub struct Field {
//     pub attrs: Vec<Attribute>,   // 字段属性
//     pub vis: Visibility,         // 字段可见性
//     pub ident: Option<Ident>,    // 字段名(元组结构体为 None)
//     pub ty: Type,                // 字段类型
// }

// === ItemFn:函数定义 ===
//
// pub struct ItemFn {
//     pub attrs: Vec<Attribute>,
//     pub vis: Visibility,
//     pub sig: Signature,    // 函数签名
//     pub block: Box<Block>, // 函数体
// }

fn main() {
    println!("DeriveInput 是派生宏最常用的解析目标");
    println!("ItemFn 是属性宏处理函数时的解析目标");
}
解析类型对应的 Rust 结构常用于
DeriveInput结构体/枚举/联合体定义派生宏
ItemFn函数定义属性宏
ItemStruct结构体定义函数宏
ItemEnum枚举定义函数宏
Expr表达式函数宏
Type类型表达式任何宏
Path路径任何宏

解析字段信息 ​

rust
// 从 DeriveInput 提取字段信息是最常见的操作
//
// use syn::{parse_macro_input, DeriveInput, Data, Fields, Field};
//
// fn extract_named_fields(input: &DeriveInput) -> Vec<&Field> {
//     match &input.data {
//         Data::Struct(data) => {
//             match &data.fields {
//                 Fields::Named(fields) => {
//                     fields.named.iter().collect()
//                 }
//                 Fields::Unnamed(fields) => {
//                     fields.unnamed.iter().collect()
//                 }
//                 Fields::Unit => vec![],
//             }
//         }
//         Data::Enum(data) => {
//             // 枚举的每个变体也可以有字段
//             let mut all_fields = vec![];
//             for variant in &data.variants {
//                 match &variant.fields {
//                     Fields::Named(fields) => {
//                         all_fields.extend(fields.named.iter());
//                     }
//                     Fields::Unnamed(fields) => {
//                         all_fields.extend(fields.unnamed.iter());
//                     }
//                     Fields::Unit => {}
//                 }
//             }
//             all_fields
//         }
//         Data::Union(_) => vec![],
//     }
// }
//
// // 典型用法
// let input = parse_macro_input!(input as DeriveInput);
// let fields = extract_named_fields(&input);
// for field in fields {
//     let name = &field.ident;
//     let ty = &field.ty;
//     println!("字段: {:?}, 类型: {:?}", name, ty);
// }

fn main() {
    println!("提取字段信息是过程宏最常见的操作");
}

自定义解析(Parse trait) ​

rust
// syn 的 Parse trait 允许定义自定义的解析规则
// 用于函数式过程宏中的 DSL 解析
//
// use syn::parse::{Parse, ParseStream};
// use syn::{Token, Ident, LitStr, Expr};
//
// // 定义自定义语法结构
// // 目标语法: route GET "/users" => handler_fn
// struct RouteDefinition {
//     method: Ident,
//     path: LitStr,
//     handler: Ident,
// }
//
// impl Parse for RouteDefinition {
//     fn parse(input: ParseStream) -> syn::Result<Self> {
//         let method: Ident = input.parse()?;       // 解析方法名
//         let path: LitStr = input.parse()?;         // 解析路径字符串
//         input.parse::<Token![=>]>()?;               // 解析 => 符号
//         let handler: Ident = input.parse()?;        // 解析处理函数名
//         
//         Ok(RouteDefinition { method, path, handler })
//     }
// }
//
// // 在过程宏中使用
// #[proc_macro]
// pub fn route(input: TokenStream) -> TokenStream {
//     let def = parse_macro_input!(input as RouteDefinition);
//     // 使用解析结果...
//     todo!()
// }

// === ParseStream 常用方法 ===
//
// input.parse::<Ident>()?        // 解析标识符
// input.parse::<LitStr>()?       // 解析字符串字面量
// input.parse::<LitInt>()?       // 解析整数字面量
// input.parse::<Token![=]>()?    // 解析 = 符号
// input.parse::<Token![=>]>()?   // 解析 => 符号
// input.parse::<Token![,]>()?    // 解析逗号
// input.parse::<Expr>()?         // 解析表达式
// input.parse::<Type>()?         // 解析类型
//
// input.peek(Token![,])          // 窥视下一个 token 是否是逗号
// input.is_empty()               // 是否已经解析完所有 token
// input.lookahead1()             // 查看下一个 token 用于错误报告

fn main() {
    println!("Parse trait 让自定义 DSL 解析变得简单");
}

Punctuated 解析列表 ​

rust
// syn::punctuated::Punctuated 用于解析分隔符分隔的列表
//
// use syn::punctuated::Punctuated;
// use syn::{Expr, Token};
//
// // 解析逗号分隔的表达式列表
// let args: Punctuated<Expr, Token![,]> = 
//     input.parse_terminated(Expr::parse, Token![,])?;
//
// // 遍历
// for expr in &args {
//     // 处理每个表达式
// }
//
// // 常见的 Punctuated 用法
// Punctuated<Field, Token![,]>    // 逗号分隔的字段
// Punctuated<Expr, Token![,]>     // 逗号分隔的表达式
// Punctuated<Type, Token![+]>     // + 分隔的 trait bound
// Punctuated<Ident, Token![,]>    // 逗号分隔的标识符

fn main() {
    println!("Punctuated 处理 a, b, c 这样的分隔列表");
}

错误处理 ​

rust
// syn 提供了精确的错误报告机制
//
// use syn::Error;
// use syn::spanned::Spanned;
//
// // 从特定的语法节点创建错误(错误指向该节点的源码位置)
// let err = Error::new_spanned(&field.ty, "不支持此字段类型");
//
// // 从 Span 创建错误
// let err = Error::new(ident.span(), "无效的标识符");
//
// // 将错误转换为编译错误
// return err.to_compile_error().into();
//
// // 合并多个错误
// let mut errors = Error::new(span1, "第一个错误");
// errors.combine(Error::new(span2, "第二个错误"));
// return errors.to_compile_error().into();

// === 用 Result 处理解析错误 ===
//
// fn process(input: &DeriveInput) -> syn::Result<TokenStream2> {
//     match &input.data {
//         Data::Struct(data) => {
//             // 正常处理
//             Ok(quote! { ... })
//         }
//         _ => {
//             Err(Error::new_spanned(
//                 &input.ident,
//                 "此宏只支持结构体"
//             ))
//         }
//     }
// }
//
// #[proc_macro_derive(MyMacro)]
// pub fn my_macro(input: TokenStream) -> TokenStream {
//     let input = parse_macro_input!(input as DeriveInput);
//     match process(&input) {
//         Ok(tokens) => tokens.into(),
//         Err(err) => err.to_compile_error().into(),
//     }
// }

fn main() {
    println!("syn::Error 提供精确的编译时错误信息");
}

基本示例 ​

rust
// 展示 syn 解析后的数据结构使用方式

// 模拟 syn 解析 DeriveInput 后的数据访问模式
// (实际中这些信息由 syn::parse_macro_input! 提供)

#[derive(Debug)]
struct FieldInfo {
    name: String,
    type_name: String,
    is_public: bool,
}

#[derive(Debug)]
struct StructInfo {
    name: String,
    fields: Vec<FieldInfo>,
    has_generics: bool,
}

// 模拟从 DeriveInput 提取信息
fn analyze_struct() -> StructInfo {
    // 模拟解析结果
    StructInfo {
        name: "User".to_string(),
        fields: vec![
            FieldInfo { name: "name".into(), type_name: "String".into(), is_public: true },
            FieldInfo { name: "age".into(), type_name: "u32".into(), is_public: true },
            FieldInfo { name: "email".into(), type_name: "Option<String>".into(), is_public: false },
        ],
        has_generics: false,
    }
}

// 模拟代码生成
fn generate_builder(info: &StructInfo) -> String {
    let mut code = String::new();
    
    // Builder 结构体
    code.push_str(&format!("struct {}Builder {{\n", info.name));
    for field in &info.fields {
        code.push_str(&format!("    {}: Option<{}>,\n", field.name, field.type_name));
    }
    code.push_str("}\n\n");
    
    // setter 方法
    code.push_str(&format!("impl {}Builder {{\n", info.name));
    for field in &info.fields {
        code.push_str(&format!(
            "    fn {}(mut self, val: {}) -> Self {{\n        self.{} = Some(val);\n        self\n    }}\n",
            field.name, field.type_name, field.name
        ));
    }
    code.push_str("}\n");
    
    code
}

fn main() {
    let info = analyze_struct();
    println!("结构体信息: {:#?}\n", info);
    
    let generated = generate_builder(&info);
    println!("生成的代码:\n{}", generated);
}

常见问题 ​

问题一:syn 的 features 怎么配置?

syn 默认只包含 derive 和 parsing feature。如果需要解析完整的 Rust 语法(函数、表达式等),需要启用 full feature:syn = { version = "2", features = ["full"] }。只需要 DeriveInput 的话不用 full。

问题二:parse_macro_input! 和 syn::parse 有什么区别?

parse_macro_input! 是一个便利宏,解析失败时自动返回编译错误。syn::parse::<T>(input) 返回 Result,可以自定义错误处理。在过程宏入口通常用 parse_macro_input!,在内部函数中用 syn::parse。

问题三:怎么解析属性(#[...])中的内容?

用 field.attrs 获取属性列表,然后用 attr.parse_args::<T>() 或 attr.parse_nested_meta() 解析属性内容。serde 等库用这种方式解析 #[serde(rename = "...")] 等辅助属性。

问题四:syn 2.x 和 1.x 有什么重要区别?

syn 2.x 重写了属性解析 API(parse_nested_meta 替代了 NestedMeta),改进了错误信息,减少了编译时间。新项目应直接使用 syn 2.x。

适用场景 ​

  • 派生宏输入解析:DeriveInput 解析结构体/枚举定义
  • 属性宏输入解析:ItemFn、ItemStruct 等
  • 自定义 DSL 解析:实现 Parse trait
  • 属性参数解析:解析 #[attr(key = value)] 中的内容
  • 代码分析工具:解析 Rust 源码进行静态分析

注意事项 ​

  • 需要 full feature 才能解析函数、表达式等完整语法
  • parse_macro_input! 只能在过程宏入口函数中使用
  • 自定义 Parse 实现中要正确处理 ParseStream 的消耗
  • 使用 Spanned trait 获取语法节点的位置信息
  • syn 2.x 的属性解析 API 与 1.x 不兼容
  • 错误处理优先用 syn::Error 而非 panic!

总结 ​

syn 是过程宏开发的核心解析库,将 TokenStream 解析为结构化的 AST。DeriveInput 是派生宏最常用的解析目标,包含类型名、泛型、字段等完整信息。Parse trait 允许定义自定义的 DSL 解析规则。Punctuated 处理分隔符分隔的列表。syn::Error 提供精确的编译时错误报告。syn 与 quote 配合构成过程宏的标准开发模式:syn 解析输入为 AST,业务逻辑处理 AST 提取信息,quote! 将结果转换回 TokenStream 输出。syn 2.x 是当前版本,改进了属性解析 API 和编译性能。