syn 解析库
核心概念
syn 是 Rust 过程宏开发中最重要的解析库,它将 TokenStream(扁平的 token 序列)解析为结构化的抽象语法树(AST)。有了 syn,过程宏开发者不需要手动遍历 token,而是可以直接操作类型名、字段列表、泛型参数等有语义的数据结构。
syn 提供了 Rust 所有语法结构的解析类型:DeriveInput(派生宏输入)、ItemFn(函数定义)、ItemStruct(结构体定义)、Expr(表达式)等。它还提供了 Parse trait,允许开发者定义自定义的解析规则来处理 DSL 语法。
syn 与 quote 配合使用构成过程宏的标准工作流:syn 解析输入,业务逻辑处理 AST,quote! 生成输出。
// 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 生成");
}核心类型
// === 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 | 路径 | 任何宏 |
解析字段信息
// 从 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)
// 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 解析列表
// 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 这样的分隔列表");
}错误处理
// 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 提供精确的编译时错误信息");
}基本示例
// 展示 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 解析:实现
Parsetrait - 属性参数解析:解析
#[attr(key = value)]中的内容 - 代码分析工具:解析 Rust 源码进行静态分析
注意事项
- 需要
fullfeature 才能解析函数、表达式等完整语法 parse_macro_input!只能在过程宏入口函数中使用- 自定义
Parse实现中要正确处理ParseStream的消耗 - 使用
Spannedtrait 获取语法节点的位置信息 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 和编译性能。