afastdata_macro/

lib.rs

//! # afastdata-macro
//!
//! afastdata 序列化框架的 derive 宏，为结构体和枚举自动生成
//! [`AFastSerialize`] 和 [`AFastDeserialize`] trait 的实现。
//!
//! Derive macros for the afastdata serialization framework, automatically generating
//! implementations of [`AFastSerialize`]` and [`AFastDeserialize`] traits for
//! structs and enums.
//!
//! ## 支持的类型 / Supported Types
//!
//! - **命名字段结构体 (Named-field struct)**：逐字段序列化/反序列化
//!   / Field-by-field serialization/deserialization
//! - **元组结构体 (Tuple struct)**：按索引逐字段序列化/反序列化
//!   / Index-based field serialization/deserialization
//! - **单元结构体 (Unit struct)**：生成空实现（不产生任何字节）
//!   / Generates an empty implementation (no bytes produced)
//! - **枚举 (Enum)**：写入变体标签 + 变体字段数据（标签类型可通过 feature 切换）
//!   / Writes a variant tag + variant field data (tag type switchable via features)
//!
//! ## 编码格式 / Encoding Format
//!
//! ### 结构体 / Struct
//!
//! 所有字段按声明顺序依次调用 `to_bytes()` / `from_bytes()`，无额外前缀。
//!
//! All fields call `to_bytes()` / `from_bytes()` in declaration order, with no
//! additional prefix.
//!
//! ### 枚举 / Enum
//!
//! | 编码内容 / Content | 类型 / Type | 说明 / Description |
//! |---|---|---|
//! | 变体索引 / Variant index | `u8`/`u16`/`u32` little-endian | 默认 `u8`，从 0 开始递增；通过 `tag-u16`/`tag-u32` feature 切换 / Default `u8`, starts from 0; switchable via `tag-u16`/`tag-u32` features |
//! | 变体字段 / Variant fields | 逐字段编码 / Field-wise encoding | 仅非 unit 变体 / Only for non-unit variants |
//!
//! ## 泛型支持 / Generic Support
//!
//! 泛型参数会自动添加 `AFastSerialize` 和（对于反序列化）`AFastDeserialize` trait 约束。
//! 如果泛型参数仅用于某些字段，生成的约束可能过于严格，但这保证了实现的正确性。
//!
//! Generic parameters automatically receive `AFastSerialize` and (for deserialization)
//! `AFastDeserialize` trait bounds. If a generic parameter is only used in certain fields,
//! the generated bounds may be overly strict, but this ensures correctness.
//!
//! ## 示例 / Example
//!
//! ```
//! extern crate afastdata;
//! use afastdata::{AFastSerialize, AFastDeserialize};
//!
//! #[derive(AFastSerialize, AFastDeserialize, Debug, PartialEq)]
//! struct Point {
//!     x: i32,
//!     y: i32,
//! }
//!
//! #[derive(AFastSerialize, AFastDeserialize, Debug, PartialEq)]
//! enum Shape {
//!     Circle(f64),
//!     Rectangle { width: f64, height: f64 },
//!     Empty,
//! }
//!
//! // 序列化 / Serialize
//! let point = Point { x: 10, y: 20 };
//! let bytes = point.to_bytes();
//!
//! // 反序列化 / Deserialize
//! let (decoded, _) = Point::from_bytes(&bytes).unwrap();
//! assert_eq!(point, decoded);
//! ```

use proc_macro::TokenStream;
use quote::quote;
use syn::{
    Attribute, Data, DeriveInput, Fields, Index, Lit, LitFloat, LitInt, LitStr, Meta, Path, Token,
    Type, TypePath,
    parse::{Parse, ParseStream},
    parse_macro_input,
    punctuated::Punctuated,
};

/// 返回枚举变体标签的类型和字节大小，基于编译时 feature 配置。
///
/// Returns the enum variant tag type and byte size based on compile-time feature config.
fn tag_type() -> (proc_macro2::TokenStream, usize) {
    if cfg!(feature = "tag-u16") {
        (quote! { u16 }, 2)
    } else if cfg!(feature = "tag-u32") {
        (quote! { u32 }, 4)
    } else {
        (quote! { u8 }, 1)
    }
}

/// 为结构体或枚举生成 [`AFastSerialize`] trait 实现。
///
/// Generates an [`AFastSerialize`] trait implementation for a struct or enum.
///
/// # 生成的代码 / Generated Code
///
/// ## 结构体 / Struct
///
/// 为每个字段调用 `to_bytes()`，并将结果依次追加到字节缓冲区中。
///
/// Calls `to_bytes()` on each field, appending the results to a byte buffer
/// sequentially.
///
/// ```text
/// // 以下为生成代码的示意（非实际代码）
/// // The following is an illustration of generated code (not actual code)
/// impl AFastSerialize for MyStruct {
///     fn to_bytes(&self) -> Vec<u8> {
///         let mut bytes = Vec::new();
///         bytes.extend(AFastSerialize::to_bytes(&self.field1));
///         bytes.extend(AFastSerialize::to_bytes(&self.field2));
///         // ... 依次处理每个字段 / remaining fields processed similarly
///         bytes
///     }
/// }
/// ```
///
/// ## 枚举 / Enum
///
/// 先写入 `u8` 变体索引（从 0 开始），再写入变体的字段数据。
/// Unit 变体只写入索引。可通过 feature 切换为 `u16` 或 `u32`。
///
/// Writes a `u8` variant index (starting from 0), then the variant's field data.
/// Unit variants only write the index. Switchable to `u16` or `u32` via features.
///
/// ```text
/// // 以下为生成代码的示意（非实际代码）
/// // The following is an illustration of generated code (not actual code)
/// impl AFastSerialize for MyEnum {
///     fn to_bytes(&self) -> Vec<u8> {
///         let mut bytes = Vec::new();
///         match self {
///             MyEnum::Variant1 => {
///                 bytes.extend(0u8.to_le_bytes());
///             }
///             MyEnum::Variant2(field) => {
///                 bytes.extend(1u8.to_le_bytes());
///                 bytes.extend(AFastSerialize::to_bytes(field));
///             }
///             // ...
///         }
///         bytes
///     }
/// }
/// ```
///
/// # 泛型 / Generics
///
/// 如果目标类型包含泛型参数，生成的 `impl` 会自动为这些参数添加
/// `AFastSerialize` 约束。
///
/// If the target type contains generic parameters, the generated `impl` automatically
/// adds `AFastSerialize` bounds to those parameters.
///
/// # Panics
///
/// 对 union 类型使用此宏会触发编译 panic。
///
/// Using this macro on a union type will trigger a compile-time panic.
#[proc_macro_derive(AFastSerialize, attributes(afast))]
pub fn derive_serialize(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    let name = &input.ident;
    let generics = &input.generics;

    // 为泛型参数添加 AFastSerialize trait 约束
    // Add AFastSerialize trait bounds to generic parameters
    let mut generics_with_bounds = generics.clone();
    for param in &mut generics_with_bounds.params {
        if let syn::GenericParam::Type(ref mut ty) = *param {
            ty.bounds
                .push(syn::parse_quote!(::afastdata::AFastSerialize));
        }
    }
    let (impl_generics, _, _) = generics_with_bounds.split_for_impl();
    let (_, ty_generics, _) = generics.split_for_impl();

    let expanded = match &input.data {
        Data::Struct(data) => {
            let serialize_body = generate_serialize_fields(&data.fields, quote!(self));
            let marker_ident = syn::Ident::new("__afast_marker__", proc_macro2::Span::call_site());
            let serialize_body_with =
                generate_serialize_fields_with(&data.fields, quote!(self), &marker_ident);
            quote! {
                impl #impl_generics ::afastdata::AFastSerialize for #name #ty_generics {
                    fn to_bytes(&self) -> Vec<u8> {
                        let mut __afast_bytes__ = Vec::new();
                        #(#serialize_body)*
                        __afast_bytes__
                    }
                    fn to_bytes_with(&self, __afast_marker__: &str) -> Vec<u8> {
                        let mut __afast_bytes__ = Vec::new();
                        #(#serialize_body_with)*
                        __afast_bytes__
                    }
                }
            }
        }
        Data::Enum(data) => {
            let (tag_ty, _) = tag_type();
            let mut arms = Vec::new();
            let mut arms_with = Vec::new();
            for (i, variant) in data.variants.iter().enumerate() {
                let variant_name = &variant.ident;

                match &variant.fields {
                    Fields::Unit => {
                        arms.push(quote! {
                            #name::#variant_name => {
                                __afast_bytes__.extend((#i as #tag_ty).to_le_bytes());
                            }
                        });
                        arms_with.push(quote! {
                            #name::#variant_name => {
                                __afast_bytes__.extend((#i as #tag_ty).to_le_bytes());
                            }
                        });
                    }
                    Fields::Unnamed(fields) => {
                        let field_names: Vec<_> = (0..fields.unnamed.len())
                            .map(|i| syn::Ident::new(&format!("__f{}", i), variant_name.span()))
                            .collect();
                        let field_patterns = &field_names;
                        let mut serialize_fields = Vec::new();
                        for (i, f) in fields.unnamed.iter().enumerate() {
                            if !has_skip_attr(&f.attrs).0 {
                                let fname = &field_names[i];
                                serialize_fields.push(quote! {
                                    __afast_bytes__.extend(::afastdata::AFastSerialize::to_bytes(#fname));
                                });
                            }
                        }
                        let mut serialize_fields_with = Vec::new();
                        for (i, f) in fields.unnamed.iter().enumerate() {
                            if has_skip_attr(&f.attrs).0 {
                                continue;
                            }
                            let skip_with = has_skip_with_attr(&f.attrs);
                            let fname = &field_names[i];
                            if let Some((m, _)) = skip_with {
                                serialize_fields_with.push(quote! {
                                    if #m != __afast_marker__ {
                                        __afast_bytes__.extend(::afastdata::AFastSerialize::to_bytes_with(#fname, __afast_marker__));
                                    }
                                });
                            } else {
                                serialize_fields_with.push(quote! {
                                    __afast_bytes__.extend(::afastdata::AFastSerialize::to_bytes_with(#fname, __afast_marker__));
                                });
                            }
                        }
                        arms.push(quote! {
                            #name::#variant_name(#(#field_patterns),*) => {
                                __afast_bytes__.extend((#i as #tag_ty).to_le_bytes());
                                #(#serialize_fields)*
                            }
                        });
                        arms_with.push(quote! {
                            #name::#variant_name(#(#field_patterns),*) => {
                                __afast_bytes__.extend((#i as #tag_ty).to_le_bytes());
                                #(#serialize_fields_with)*
                            }
                        });
                    }
                    Fields::Named(fields) => {
                        let all_field_names: Vec<_> = fields
                            .named
                            .iter()
                            .map(|f| f.ident.as_ref().unwrap())
                            .collect();
                        let non_skip_names: Vec<_> = fields
                            .named
                            .iter()
                            .filter(|f| !has_skip_attr(&f.attrs).0)
                            .map(|f| f.ident.as_ref().unwrap())
                            .collect();
                        let has_skip = non_skip_names.len() < all_field_names.len();
                        let mut serialize_fields = Vec::new();
                        for fname in &non_skip_names {
                            serialize_fields.push(quote! {
                                __afast_bytes__.extend(::afastdata::AFastSerialize::to_bytes(#fname));
                            });
                        }
                        // _with: include all non-skip fields, skip_with matched ones use runtime check
                        let non_skip_fields_with: Vec<_> = fields
                            .named
                            .iter()
                            .filter(|f| !has_skip_attr(&f.attrs).0)
                            .collect();
                        let has_any_skip_with = non_skip_fields_with.len() < all_field_names.len();
                        let non_skip_names_with: Vec<_> = non_skip_fields_with
                            .iter()
                            .map(|f| f.ident.as_ref().unwrap())
                            .collect();
                        let mut serialize_fields_with = Vec::new();
                        for f in &non_skip_fields_with {
                            let fname = f.ident.as_ref().unwrap();
                            let skip_with = has_skip_with_attr(&f.attrs);
                            if let Some((m, _)) = skip_with {
                                serialize_fields_with.push(quote! {
                                    if #m != __afast_marker__ {
                                        __afast_bytes__.extend(::afastdata::AFastSerialize::to_bytes_with(#fname, __afast_marker__));
                                    }
                                });
                            } else {
                                serialize_fields_with.push(quote! {
                                    __afast_bytes__.extend(::afastdata::AFastSerialize::to_bytes_with(#fname, __afast_marker__));
                                });
                            }
                        }
                        if has_skip {
                            arms.push(quote! {
                                #name::#variant_name { #(#non_skip_names),*, .. } => {
                                    __afast_bytes__.extend((#i as #tag_ty).to_le_bytes());
                                    #(#serialize_fields)*
                                }
                            });
                        } else {
                            arms.push(quote! {
                                #name::#variant_name { #(#non_skip_names),* } => {
                                    __afast_bytes__.extend((#i as #tag_ty).to_le_bytes());
                                    #(#serialize_fields)*
                                }
                            });
                        }
                        if has_any_skip_with {
                            arms_with.push(quote! {
                                #name::#variant_name { #(#non_skip_names_with),*, .. } => {
                                    __afast_bytes__.extend((#i as #tag_ty).to_le_bytes());
                                    #(#serialize_fields_with)*
                                }
                            });
                        } else {
                            arms_with.push(quote! {
                                #name::#variant_name { #(#non_skip_names_with),* } => {
                                    __afast_bytes__.extend((#i as #tag_ty).to_le_bytes());
                                    #(#serialize_fields_with)*
                                }
                            });
                        }
                    }
                }
            }

            quote! {
                impl #impl_generics ::afastdata::AFastSerialize for #name #ty_generics {
                    fn to_bytes(&self) -> Vec<u8> {
                        let mut __afast_bytes__ = Vec::new();
                        match self {
                            #(#arms)*
                        }
                        __afast_bytes__
                    }
                    fn to_bytes_with(&self, __afast_marker__: &str) -> Vec<u8> {
                        let mut __afast_bytes__ = Vec::new();
                        match self {
                            #(#arms_with)*
                        }
                        __afast_bytes__
                    }
                }
            }
        }
        Data::Union(_) => panic!("AFastSerialize does not support unions"),
    };

    TokenStream::from(expanded)
}

/// 为结构体或枚举生成 [`AFastDeserialize`] trait 实现。
///
/// Generates an [`AFastDeserialize`] trait implementation for a struct or enum.
///
/// # 生成的代码 / Generated Code
///
/// ## 结构体 / Struct
///
/// 为每个字段依次调用 `from_bytes()`，并使用偏移量追踪已消耗的字节数，
/// 最后构造结构体实例。
///
/// Calls `from_bytes()` on each field sequentially, using an offset to track
/// consumed bytes, then constructs the struct instance.
///
/// ```text
/// // 以下为生成代码的示意（非实际代码）
/// // The following is an illustration of generated code (not actual code)
/// impl AFastDeserialize for MyStruct {
///     fn from_bytes(data: &[u8]) -> Result<(Self, usize), Error> {
///         let mut offset: usize = 0;
///         let (__val, __new_offset) = AFastDeserialize::from_bytes(&data[offset..])?;
///         let field1 = __val;
///         offset += __new_offset;
///         // ... 更多字段 / more fields ...
///         Ok((MyStruct { field1, ... }, offset))
///     }
/// }
/// ```
///
/// ## 枚举 / Enum
///
/// 先读取 `u8` 变体索引，根据索引匹配对应变体，再反序列化该变体的字段。
/// 可通过 feature 切换为 `u16` 或 `u32`。
///
/// First reads the `u8` variant index, matches the corresponding variant by index,
/// then deserializes the variant's fields.
/// Switchable to `u16` or `u32` via features.
///
/// ```text
/// // 以下为生成代码的示意（非实际代码）
/// // The following is an illustration of generated code (not actual code)
/// impl AFastDeserialize for MyEnum {
///     fn from_bytes(data: &[u8]) -> Result<(Self, usize), Error> {
///         let mut offset: usize = 0;
///         let (__tag, __new_offset) = <u8 as AFastDeserialize>::from_bytes(&data[offset..])?;
///         offset += __new_offset;
///         match __tag as usize {
///             0 => Ok((MyEnum::Variant1, offset)),
///             1 => {
///                 let (__val, __new_offset) = AFastDeserialize::from_bytes(&data[offset..])?;
///                 offset += __new_offset;
///                 Ok((MyEnum::Variant2(__val), offset))
///             }
///             v => Err(format!("Unknown variant tag: {} for MyEnum", v)),
///         }
///     }
/// }
/// ```
///
/// # 泛型 / Generics
///
/// 如果目标类型包含泛型参数，生成的 `impl` 会同时添加 `AFastSerialize` 和
/// `AFastDeserialize` 约束。双重约束确保泛型类型在序列化和反序列化两个方向
/// 上都可用。
///
/// If the target type contains generic parameters, the generated `impl` adds both
/// `AFastSerialize` and `AFastDeserialize` bounds. The dual bounds ensure the generic
/// type is available in both serialization and deserialization directions.
///
/// # Panics
///
/// 对 union 类型使用此宏会触发编译 panic。
///
/// Using this macro on a union type will trigger a compile-time panic.
#[proc_macro_derive(AFastDeserialize, attributes(afast))]
pub fn derive_deserialize(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    let name = &input.ident;
    let generics = &input.generics;

    // 为泛型参数添加 AFastSerialize + AFastDeserialize trait 约束
    // Add AFastSerialize + AFastDeserialize trait bounds to generic parameters
    let mut generics_with_bounds = generics.clone();
    for param in &mut generics_with_bounds.params {
        if let syn::GenericParam::Type(ref mut ty) = *param {
            ty.bounds
                .push(syn::parse_quote!(::afastdata::AFastSerialize));
            ty.bounds
                .push(syn::parse_quote!(::afastdata::AFastDeserialize));
        }
    }
    let (impl_generics, _, _) = generics_with_bounds.split_for_impl();
    let (_, ty_generics, _) = generics.split_for_impl();

    let expanded = match &input.data {
        Data::Struct(data) => {
            let (construct, field_desers) =
                generate_deserialize_fields(&data.fields, name, &ty_generics);
            let (construct_with, field_desers_with) = generate_deserialize_fields_with(
                &data.fields,
                name,
                &ty_generics,
                "__afast_marker__",
            );
            quote! {
                impl #impl_generics ::afastdata::AFastDeserialize for #name #ty_generics {
                    fn from_bytes(__afast_data__: &[u8]) -> Result<(Self, usize), ::afastdata::Error> {
                        let mut __afast_offset__: usize = 0;
                        #(#field_desers)*
                        Ok((#construct, __afast_offset__))
                    }
                    fn from_bytes_with(__afast_data__: &[u8], __afast_marker__: &str) -> Result<(Self, usize), ::afastdata::Error> {
                        let mut __afast_offset__: usize = 0;
                        #(#field_desers_with)*
                        Ok((#construct_with, __afast_offset__))
                    }
                }
            }
        }
        Data::Enum(data) => {
            let (tag_ty, _) = tag_type();
            let mut arms = Vec::new();
            let mut arms_with = Vec::new();
            for (i, variant) in data.variants.iter().enumerate() {
                let variant_name = &variant.ident;

                match &variant.fields {
                    Fields::Unit => {
                        arms.push(quote! {
                            #i => {
                                Ok((#name::#variant_name, __afast_offset__))
                            }
                        });
                        arms_with.push(quote! {
                            #i => {
                                Ok((#name::#variant_name, __afast_offset__))
                            }
                        });
                    }
                    Fields::Unnamed(fields) => {
                        let mut field_desers = Vec::new();
                        let mut field_desers_with = Vec::new();
                        let mut field_names = Vec::new();
                        for (i, f) in fields.unnamed.iter().enumerate() {
                            let fname = syn::Ident::new(&format!("__f{}", i), variant_name.span());
                            let ftype = &f.ty;
                            let (skip, default_fn) = has_skip_attr(&f.attrs);
                            if skip {
                                if let Some(func_name) = default_fn.clone() {
                                    match syn::parse_str::<syn::Ident>(&func_name) {
                                        Ok(ident) => {
                                            field_desers.push(quote! {
                                                let #fname: #ftype = #ident();
                                            });
                                            field_desers_with.push(quote! {
                                                let #fname: #ftype = #ident();
                                            });
                                        }
                                        Err(_) => {
                                            field_desers.push(quote! {
                                                compile_error!(concat!("invalid function name in skip: ", #func_name));
                                            });
                                            field_desers_with.push(quote! {
                                                compile_error!(concat!("invalid function name in skip: ", #func_name));
                                            });
                                        }
                                    }
                                } else {
                                    field_desers.push(quote! {
                                        let #fname: #ftype = <#ftype as ::std::default::Default>::default();
                                    });
                                    field_desers_with.push(quote! {
                                        let #fname: #ftype = <#ftype as ::std::default::Default>::default();
                                    });
                                }
                            } else {
                                let validates = parse_validations(&fname, ftype, &f.attrs);
                                field_desers.push(quote! {
                                    let (__val, __new_offset) = ::afastdata::AFastDeserialize::from_bytes(&__afast_data__[__afast_offset__..])?;
                                    let #fname: #ftype = __val;
                                    #(#validates)*
                                    __afast_offset__ += __new_offset;
                                });
                                // _with: check skip_with
                                let skip_with = has_skip_with_attr(&f.attrs);
                                if let Some((m, sw_default)) = skip_with {
                                    let default_expr = if let Some(fn_name) = sw_default {
                                        match syn::parse_str::<syn::Ident>(&fn_name) {
                                            Ok(ident) => quote! { #ident() },
                                            Err(_) => {
                                                quote! { { compile_error!(concat!("invalid function name in skip_with: ", #fn_name)); <#ftype as ::std::default::Default>::default() } }
                                            }
                                        }
                                    } else {
                                        quote! { <#ftype as ::std::default::Default>::default() }
                                    };
                                    field_desers_with.push(quote! {
                                        let #fname: #ftype = if __afast_marker__ == #m {
                                            #default_expr
                                        } else {
                                            let (__val, __new_offset) = ::afastdata::AFastDeserialize::from_bytes_with(&__afast_data__[__afast_offset__..], __afast_marker__)?;
                                            #(#validates)*
                                            __afast_offset__ += __new_offset;
                                            __val
                                        };
                                    });
                                } else {
                                    field_desers_with.push(quote! {
                                        let (__val, __new_offset) = ::afastdata::AFastDeserialize::from_bytes_with(&__afast_data__[__afast_offset__..], __afast_marker__)?;
                                        let #fname: #ftype = __val;
                                        #(#validates)*
                                        __afast_offset__ += __new_offset;
                                    });
                                }
                            }
                            field_names.push(fname);
                        }
                        arms.push(quote! {
                            #i => {
                                #(#field_desers)*
                                Ok((#name::#variant_name(#(#field_names),*), __afast_offset__))
                            }
                        });
                        arms_with.push(quote! {
                            #i => {
                                #(#field_desers_with)*
                                Ok((#name::#variant_name(#(#field_names),*), __afast_offset__))
                            }
                        });
                    }
                    Fields::Named(fields) => {
                        let mut field_desers = Vec::new();
                        let mut field_desers_with = Vec::new();
                        let mut field_names = Vec::new();
                        for f in &fields.named {
                            let fname = f.ident.as_ref().unwrap();
                            let ftype = &f.ty;
                            let (skip, default_fn) = has_skip_attr(&f.attrs);
                            if skip {
                                if let Some(func_name) = default_fn.clone() {
                                    match syn::parse_str::<syn::Ident>(&func_name) {
                                        Ok(ident) => {
                                            field_desers.push(quote! {
                                                let #fname: #ftype = #ident();
                                            });
                                            field_desers_with.push(quote! {
                                                let #fname: #ftype = #ident();
                                            });
                                        }
                                        Err(_) => {
                                            field_desers.push(quote! {
                                                compile_error!(concat!("invalid function name in skip: ", #func_name));
                                            });
                                            field_desers_with.push(quote! {
                                                compile_error!(concat!("invalid function name in skip: ", #func_name));
                                            });
                                        }
                                    }
                                } else {
                                    field_desers.push(quote! {
                                        let #fname: #ftype = <#ftype as ::std::default::Default>::default();
                                    });
                                    field_desers_with.push(quote! {
                                        let #fname: #ftype = <#ftype as ::std::default::Default>::default();
                                    });
                                }
                            } else {
                                let validates = parse_validations(fname, ftype, &f.attrs);
                                field_desers.push(quote! {
                                    let (__val, __new_offset) = ::afastdata::AFastDeserialize::from_bytes(&__afast_data__[__afast_offset__..])?;
                                    let #fname: #ftype = __val;
                                    #(#validates)*
                                    __afast_offset__ += __new_offset;
                                });
                                // _with: check skip_with
                                let skip_with = has_skip_with_attr(&f.attrs);
                                if let Some((m, sw_default)) = skip_with {
                                    let default_expr = if let Some(fn_name) = sw_default {
                                        match syn::parse_str::<syn::Ident>(&fn_name) {
                                            Ok(ident) => quote! { #ident() },
                                            Err(_) => {
                                                quote! { { compile_error!(concat!("invalid function name in skip_with: ", #fn_name)); <#ftype as ::std::default::Default>::default() } }
                                            }
                                        }
                                    } else {
                                        quote! { <#ftype as ::std::default::Default>::default() }
                                    };
                                    field_desers_with.push(quote! {
                                        let #fname: #ftype = if __afast_marker__ == #m {
                                            #default_expr
                                        } else {
                                            let (__val, __new_offset) = ::afastdata::AFastDeserialize::from_bytes_with(&__afast_data__[__afast_offset__..], __afast_marker__)?;
                                            #(#validates)*
                                            __afast_offset__ += __new_offset;
                                            __val
                                        };
                                    });
                                } else {
                                    field_desers_with.push(quote! {
                                        let (__val, __new_offset) = ::afastdata::AFastDeserialize::from_bytes_with(&__afast_data__[__afast_offset__..], __afast_marker__)?;
                                        let #fname: #ftype = __val;
                                        #(#validates)*
                                        __afast_offset__ += __new_offset;
                                    });
                                }
                            }
                            field_names.push(fname);
                        }
                        arms.push(quote! {
                            #i => {
                                #(#field_desers)*
                                Ok((#name::#variant_name { #(#field_names),* }, __afast_offset__))
                            }
                        });
                        arms_with.push(quote! {
                            #i => {
                                #(#field_desers_with)*
                                Ok((#name::#variant_name { #(#field_names),* }, __afast_offset__))
                            }
                        });
                    }
                }
            }

            quote! {
                impl #impl_generics ::afastdata::AFastDeserialize for #name #ty_generics {
                    fn from_bytes(__afast_data__: &[u8]) -> Result<(Self, usize), ::afastdata::Error> {
                        let mut __afast_offset__: usize = 0;
                        let (__afast_tag__, __new_offset) = <#tag_ty as ::afastdata::AFastDeserialize>::from_bytes(&__afast_data__[__afast_offset__..])?;
                        __afast_offset__ += __new_offset;
                        match __afast_tag__ as usize {
                            #(#arms)*
                            v => Err(::afastdata::Error::deserialize(format!("Unknown variant tag: {} for {}", v, ::std::stringify!(#name)))),
                        }
                    }
                    fn from_bytes_with(__afast_data__: &[u8], __afast_marker__: &str) -> Result<(Self, usize), ::afastdata::Error> {
                        let mut __afast_offset__: usize = 0;
                        let (__afast_tag__, __new_offset) = <#tag_ty as ::afastdata::AFastDeserialize>::from_bytes(&__afast_data__[__afast_offset__..])?;
                        __afast_offset__ += __new_offset;
                        match __afast_tag__ as usize {
                            #(#arms_with)*
                            v => Err(::afastdata::Error::deserialize(format!("Unknown variant tag: {} for {}", v, ::std::stringify!(#name)))),
                        }
                    }
                }
            }
        }
        Data::Union(_) => panic!("AFastDeserialize does not support unions"),
    };

    TokenStream::from(expanded)
}

/// 为结构体的字段生成 `to_bytes()` 序列化代码。内部辅助函数。
///
/// Generates `to_bytes()` serialization code for struct fields. Internal helper.
///
/// 跳过所有标记了 `#[afast(skip)]` 的字段。
///
/// Skips all fields marked with `#[afast(skip)]`.
///
/// # 参数 / Parameters
///
/// - `fields`：结构体的字段定义 / The struct's field definitions
/// - `self_prefix`：访问字段时使用的前缀（如 `self` 或变体解构变量）
///   / The prefix used to access fields (e.g., `self` or a variant destructure variable)
///
/// # 返回值 / Returns
///
/// 返回一个 `TokenStream` 列表，每个元素对应一个字段的序列化语句。
///
/// Returns a list of `TokenStream`s, each corresponding to a serialization statement
/// for one field.
///
/// # 生成格式 / Generated Format
///
/// - **命名字段 (Named)**：`__afast_bytes__.extend(AFastSerialize::to_bytes(&self.field_name));`
/// - **元组字段 (Unnamed)**：`__afast_bytes__.extend(AFastSerialize::to_bytes(&self.0));`
/// - **单元字段 (Unit)**：不生成任何代码 / Generates no code
fn generate_serialize_fields(
    fields: &Fields,
    self_prefix: proc_macro2::TokenStream,
) -> Vec<proc_macro2::TokenStream> {
    match fields {
        Fields::Named(named) => named
            .named
            .iter()
            .filter(|f| !has_skip_attr(&f.attrs).0)
            .map(|f| {
                let fname = f.ident.as_ref().unwrap();
                quote! {
                    __afast_bytes__.extend(::afastdata::AFastSerialize::to_bytes(&#self_prefix.#fname));
                }
            })
            .collect(),
        Fields::Unnamed(unnamed) => unnamed
            .unnamed
            .iter()
            .enumerate()
            .filter(|(_, f)| !has_skip_attr(&f.attrs).0)
            .map(|(i, _)| {
                let idx = Index::from(i);
                quote! {
                    __afast_bytes__.extend(::afastdata::AFastSerialize::to_bytes(&#self_prefix.#idx));
                }
            })
            .collect(),
        Fields::Unit => vec![],
    }
}

/// 为结构体的字段生成带 marker 的序列化代码。内部辅助函数。
///
/// Generates marker-aware serialization code for struct fields. Internal helper.
///
/// 跳过 `#[afast(skip)]` 字段，marker 匹配的 `#[afast(skip_with(...))]` 字段在运行时跳过。
///
/// Skips `#[afast(skip)]` fields unconditionally. `#[afast(skip_with(...))]` fields
/// whose marker matches are skipped at runtime.
fn generate_serialize_fields_with(
    fields: &Fields,
    self_prefix: proc_macro2::TokenStream,
    marker: &proc_macro2::Ident,
) -> Vec<proc_macro2::TokenStream> {
    match fields {
        Fields::Named(named) => {
            let mut stmts = Vec::new();
            for f in &named.named {
                if has_skip_attr(&f.attrs).0 {
                    continue;
                }
                let fname = f.ident.as_ref().unwrap();
                let skip_with = has_skip_with_attr(&f.attrs);
                if let Some((m, _)) = skip_with {
                    stmts.push(quote! {
                        if #m != #marker {
                            __afast_bytes__.extend(::afastdata::AFastSerialize::to_bytes_with(&#self_prefix.#fname, #marker));
                        }
                    });
                } else {
                    stmts.push(quote! {
                        __afast_bytes__.extend(::afastdata::AFastSerialize::to_bytes_with(&#self_prefix.#fname, #marker));
                    });
                }
            }
            stmts
        }
        Fields::Unnamed(unnamed) => {
            let mut stmts = Vec::new();
            for (i, f) in unnamed.unnamed.iter().enumerate() {
                if has_skip_attr(&f.attrs).0 {
                    continue;
                }
                let idx = Index::from(i);
                let skip_with = has_skip_with_attr(&f.attrs);
                if let Some((m, _)) = skip_with {
                    stmts.push(quote! {
                        if #m != #marker {
                            __afast_bytes__.extend(::afastdata::AFastSerialize::to_bytes_with(&#self_prefix.#idx, #marker));
                        }
                    });
                } else {
                    stmts.push(quote! {
                        __afast_bytes__.extend(::afastdata::AFastSerialize::to_bytes_with(&#self_prefix.#idx, #marker));
                    });
                }
            }
            stmts
        }
        Fields::Unit => vec![],
    }
}

/// 检查字段是否有 `#[afast(skip)]` 或 `#[afast(skip("fn_name"))]` 属性。
///
/// Checks whether a field has `#[afast(skip)]` or `#[afast(skip("fn_name"))]` attribute.
///
/// 返回值 / Returns:
/// - `(true, None)`：`#[afast(skip)]`，反序列化用 `Default` / uses `Default` for deserialization
/// - `(true, Some("fn"))`：`#[afast(skip("fn"))]`，反序列化用指定函数 / uses specified function
/// - `(false, None)`：无 skip 属性 / no skip attribute
fn has_skip_attr(attrs: &[Attribute]) -> (bool, Option<String>) {
    for attr in attrs {
        if attr.path().is_ident("afast")
            && let Ok(nested) =
                attr.parse_args_with(Punctuated::<Meta, Token![,]>::parse_terminated)
        {
            for meta in nested {
                match meta {
                    Meta::Path(path) if path.is_ident("skip") => {
                        return (true, None);
                    }
                    Meta::List(meta_list) if meta_list.path.is_ident("skip") => {
                        if let Ok(lit_str) = syn::parse2::<LitStr>(meta_list.tokens.clone()) {
                            return (true, Some(lit_str.value()));
                        } else {
                            return (true, None);
                        }
                    }
                    _ => {}
                }
            }
        }
    }
    (false, None)
}

/// 检查字段是否有 `#[afast(skip_with("marker"))]` 或
/// `#[afast(skip_with("marker", "default_fn"))]` 属性。
///
/// Checks whether a field has `#[afast(skip_with("marker"))]` or
/// `#[afast(skip_with("marker", "default_fn"))]` attribute.
///
/// 返回值：`(marker, default_fn)`
/// - `Some(("marker", None))`：`#[afast(skip_with("marker"))]`，反序列化用 Default
/// - `Some(("marker", Some("fn")))`：`#[afast(skip_with("marker", "fn"))]`
/// - `None`：无 skip_with 属性
fn has_skip_with_attr(attrs: &[Attribute]) -> Option<(String, Option<String>)> {
    for attr in attrs {
        if attr.path().is_ident("afast")
            && let Ok(nested) =
                attr.parse_args_with(Punctuated::<Meta, Token![,]>::parse_terminated)
        {
            for meta in nested {
                if let Meta::List(meta_list) = meta
                    && meta_list.path.is_ident("skip_with")
                {
                    let tokens = meta_list.tokens.clone();
                    if let Ok(args) = syn::parse2::<SkipWithArgs>(tokens) {
                        return Some((args.marker.value(), args.default_fn.map(|s| s.value())));
                    }
                    return None;
                }
            }
        }
    }
    None
}

/// `#[afast(skip_with(...))]` 属性的解析结果。
///
/// Parsed representation of the `#[afast(skip_with(...))]` attribute.
///
/// - `marker`：用于匹配的标记字符串 / The marker string used for matching
/// - `default_fn`：可选的默认值生成函数名 / Optional function name for generating default values
struct SkipWithArgs {
    marker: LitStr,
    default_fn: Option<LitStr>,
}

impl Parse for SkipWithArgs {
    /// 解析 `"marker"` 或 `"marker", "default_fn"` 格式的参数。
    ///
    /// Parses arguments in the format `"marker"` or `"marker", "default_fn"`.
    fn parse(input: ParseStream) -> syn::Result<Self> {
        let marker: LitStr = input.parse()?;
        let default_fn = if input.peek(Token![,]) {
            input.parse::<Token![,]>()?;
            Some(input.parse::<LitStr>()?)
        } else {
            None
        };
        Ok(SkipWithArgs { marker, default_fn })
    }
}

/// 范围校验中使用的值，支持整数和浮点数。
///
/// A value used in range validation, supporting both integers and floats.
enum RangeValue {
    /// 整数字面量 / Integer literal
    Int(LitInt),
    /// 浮点字面量 / Float literal
    Float(LitFloat),
}

impl RangeValue {
    /// 将值转换为可用于代码生成的 `TokenStream`。
    ///
    /// Converts the value into a `TokenStream` for code generation.
    fn to_token_stream(&self) -> proc_macro2::TokenStream {
        match self {
            RangeValue::Int(v) => quote! { #v },
            RangeValue::Float(v) => quote! { #v },
        }
    }
}

/// `gt`/`gte`/`lt`/`lte` 范围校验的参数。
///
/// Parameters for `gt`/`gte`/`lt`/`lte` range validation.
///
/// 格式：`(比较值, 错误码, "错误消息")`
///
/// Format: `(comparison_value, error_code, "error message")`
struct Range {
    /// 要比较的阈值 / The threshold value to compare against
    value: RangeValue,
    _comma1: Token![,],
    /// 验证失败时的错误码 / Error code when validation fails
    code: LitInt,
    _comma2: Token![,],
    /// 验证失败时的错误消息 / Error message when validation fails
    msg: LitStr,
}

impl Parse for Range {
    /// 解析 `(value, code, "msg")` 格式的参数，自动识别整数或浮点值。
    ///
    /// Parses arguments in `(value, code, "msg")` format, automatically detecting
    /// integer or float values.
    fn parse(input: ParseStream) -> syn::Result<Self> {
        // 优先尝试解析为浮点数，再尝试整数
        // Try to parse as float first, then as int
        let value = if input.peek(LitFloat) {
            RangeValue::Float(input.parse()?)
        } else {
            RangeValue::Int(input.parse()?)
        };
        Ok(Range {
            value,
            _comma1: input.parse()?,
            code: input.parse()?,
            _comma2: input.parse()?,
            msg: input.parse()?,
        })
    }
}

/// `len` 长度校验的参数。
///
/// Parameters for `len` length validation.
///
/// 格式：`(min, max, 错误码, "错误消息")`
///
/// Format: `(min, max, error_code, "error message")`
struct Length {
    /// 最小长度（含）/ Minimum length (inclusive)
    min: LitInt,
    _comma1: Token![,],
    /// 最大长度（含）/ Maximum length (inclusive)
    max: LitInt,
    _comma2: Token![,],
    /// 验证失败时的错误码 / Error code when validation fails
    code: LitInt,
    _comma3: Token![,],
    /// 验证失败时的错误消息 / Error message when validation fails
    msg: LitStr,
}

impl Parse for Length {
    /// 解析 `(min, max, code, "msg")` 格式的参数。
    ///
    /// Parses arguments in `(min, max, code, "msg")` format.
    fn parse(input: ParseStream) -> syn::Result<Self> {
        Ok(Length {
            min: input.parse()?,
            _comma1: input.parse()?,
            max: input.parse()?,
            _comma2: input.parse()?,
            code: input.parse()?,
            _comma3: input.parse()?,
            msg: input.parse()?,
        })
    }
}

/// `of` 校验中允许的值，支持多种字面量类型。
///
/// An allowed value in `of` validation, supporting multiple literal types.
#[derive(Clone)]
enum ValidateValue {
    /// 整数值 / Integer value
    Int(i64),
    /// 浮点值 / Float value
    Float(f64),
    /// 布尔值 / Boolean value
    Bool(bool),
    /// 字符串值 / String value
    Str(String),
}

impl ValidateValue {
    /// 将值转换为代码生成中使用的 TokenStream。
    ///
    /// Converts the value into a `TokenStream` for code generation.
    ///
    /// 例如 / Example:
    /// - `ValidateValue::Int(42)` → `quote! { 42 }`
    /// - `ValidateValue::Str("hello")` → `quote! { "hello" }`
    fn to_token_stream(&self) -> proc_macro2::TokenStream {
        match self {
            ValidateValue::Int(v) => quote! { #v },

            ValidateValue::Float(v) => {
                // 浮点数通过字符串解析来保持精度
                let v_str = v.to_string();
                v_str.parse().unwrap_or_else(|_| {
                    // 如果字符串解析失败，使用直接值
                    quote! { #v }
                })
            }

            ValidateValue::Bool(v) => quote! { #v },
            ValidateValue::Str(v) => quote! { #v },
        }
    }
}

/// `of` 枚举值校验的参数。
///
/// Parameters for `of` enum-value validation.
///
/// 格式：`([值1, 值2, ...], 错误码, "错误消息")`
///
/// Format: `([val1, val2, ...], error_code, "error message")`
struct OfValidator {
    /// 允许的值列表 / List of allowed values
    allowed_values: Vec<ValidateValue>,
    /// 验证失败时的错误码 / Error code when validation fails
    code: syn::LitInt,
    /// 验证失败时的错误消息 / Error message when validation fails
    msg: syn::LitStr,
}

impl Parse for OfValidator {
    /// 解析 `([val1, val2, ...], code, "msg")` 格式的参数。
    ///
    /// Parses arguments in `([val1, val2, ...], code, "msg")` format.
    fn parse(input: ParseStream) -> syn::Result<Self> {
        let content;
        syn::bracketed!(content in input);

        let mut values = Vec::new();

        if !content.is_empty() {
            loop {
                let lit = content.parse::<Lit>()?;

                let value = match lit {
                    Lit::Int(lit_int) => {
                        let int_value: i64 = lit_int.base10_parse()?;
                        ValidateValue::Int(int_value)
                    }

                    Lit::Float(lit_float) => {
                        let float_value: f64 = lit_float.base10_parse()?;
                        ValidateValue::Float(float_value)
                    }

                    Lit::Bool(lit_bool) => ValidateValue::Bool(lit_bool.value),

                    Lit::Str(lit_str) => ValidateValue::Str(lit_str.value()),

                    _ => {
                        return Err(syn::Error::new_spanned(
                            &lit,
                            "unsupported literal type in 'of' validator; \
                             only int, float, bool, and str literals are supported",
                        ));
                    }
                };

                values.push(value);

                if !content.peek(Token![,]) {
                    break;
                }

                content.parse::<Token![,]>()?;

                if content.is_empty() {
                    break;
                }
            }
        }

        input.parse::<Token![,]>()?;

        let code = input.parse::<syn::LitInt>()?;

        input.parse::<Token![,]>()?;

        let msg = input.parse::<syn::LitStr>()?;

        Ok(OfValidator {
            allowed_values: values,
            code,
            msg,
        })
    }
}

/// 检测字段类型是否为数值类型（i8..i128, u8..u128, f32, f64）。
///
/// Checks whether the field type is a numeric type.
fn is_numeric_type(ty: &Type) -> bool {
    if let Type::Path(TypePath { path, .. }) = ty
        && let Some(segment) = path.segments.last()
    {
        let name = segment.ident.to_string();
        return matches!(
            name.as_str(),
            "i8" | "i16"
                | "i32"
                | "i64"
                | "i128"
                | "u8"
                | "u16"
                | "u32"
                | "u64"
                | "u128"
                | "usize"
                | "f32"
                | "f64"
        );
    }
    false
}

/// 检测字段类型是否为 Option<T>。
///
/// Checks whether the field type is `Option<T>`.
fn is_option_type(ty: &Type) -> bool {
    if let Type::Path(TypePath {
        path: Path { segments, .. },
        ..
    }) = ty
    {
        segments.len() == 1 && segments[0].ident == "Option"
    } else {
        false
    }
}

/// 提取 Option<T> 的内部类型 T。
///
/// Extracts the inner type `T` from `Option<T>`.
fn extract_option_inner(ty: &Type) -> Option<&Type> {
    if let Type::Path(TypePath {
        path: Path { segments, .. },
        ..
    }) = ty
        && segments.len() == 1
        && segments[0].ident == "Option"
        && let syn::PathArguments::AngleBracketed(args) = &segments[0].arguments
        && let Some(syn::GenericArgument::Type(inner)) = args.args.first()
    {
        return Some(inner);
    }
    None
}

/// 检测字段类型是否为可进行比较校验的类型（数值类型或 Option<数值类型>）。
///
/// Checks whether the field type supports comparison validation
/// (numeric type or Option<numeric type>).
fn is_comparable_type(ty: &Type) -> bool {
    if is_numeric_type(ty) {
        return true;
    }
    if let Some(inner) = extract_option_inner(ty) {
        return is_numeric_type(inner);
    }
    false
}

/// 检测字段类型是否为字符串或集合类型（String, &str, Vec<T>, [T; N]）。
///
/// Checks whether the field type is a string or collection type.
fn is_collection_type(ty: &Type) -> bool {
    if let Type::Path(TypePath { path, .. }) = ty
        && let Some(segment) = path.segments.last()
    {
        let name = segment.ident.to_string();
        return matches!(
            name.as_str(),
            "String" | "Vec" | "BTreeSet" | "BTreeMap" | "HashSet" | "HashMap"
        );
    }
    // [T; N] arrays
    if let Type::Array(_) = ty {
        return true;
    }
    // &str
    if let Type::Reference(r) = ty
        && let Type::Path(TypePath { path, .. }) = &*r.elem
        && let Some(segment) = path.segments.last()
    {
        return segment.ident == "str";
    }
    false
}

/// 解析字段上的 `#[afast(...)]` 校验属性，生成校验代码。
///
/// Parses `#[afast(...)]` validation attributes on a field and generates
/// validation code blocks.
///
/// # 参数 / Parameters
///
/// - `field_name`：字段名 / Field name
/// - `field_type`：字段类型 / Field type
/// - `attrs`：字段的属性列表 / Field attributes
///
/// # 返回值 / Returns
///
/// 返回校验语句的 `TokenStream` 列表。
///
/// Returns a list of validation `TokenStream` blocks.
fn parse_validations(
    field_name: &syn::Ident,
    field_type: &Type,
    attrs: &[Attribute],
) -> Vec<proc_macro2::TokenStream> {
    let mut validates = Vec::new();
    for attr in attrs {
        if attr.path().is_ident("afast") {
            let nested = match attr.parse_args_with(Punctuated::<Meta, Token![,]>::parse_terminated)
            {
                Ok(n) => n,
                Err(e) => {
                    validates.push(e.to_compile_error());
                    continue;
                }
            };
            for meta in nested {
                if let Meta::List(meta) = meta {
                    if meta.path.is_ident("gt") {
                        if !is_comparable_type(field_type) {
                            validates.push(
                                    syn::Error::new_spanned(
                                        &meta.path,
                                        format!(
                                            "validation `gt` is only supported on numeric types or Option<numeric>, but field `{}` is not",
                                            field_name
                                        ),
                                    )
                                    .to_compile_error(),
                                );
                            continue;
                        }
                        let inner = match meta.parse_args::<Range>() {
                            Ok(v) => v,
                            Err(e) => {
                                validates.push(e.to_compile_error());
                                continue;
                            }
                        };
                        let cmp_value = inner.value.to_token_stream();
                        let code = match inner.code.base10_parse::<i64>() {
                            Ok(v) => v,
                            Err(e) => {
                                validates.push(
                                    syn::Error::new_spanned(
                                        &inner.code,
                                        format!("invalid error code: {}", e),
                                    )
                                    .to_compile_error(),
                                );
                                continue;
                            }
                        };
                        let err_msg = inner
                            .msg
                            .value()
                            .replace("${field}", &field_name.to_string());
                        if is_option_type(field_type) {
                            validates.push(quote! {
                                    if let Some(ref __val) = #field_name {
                                        if *__val <= #cmp_value {
                                            return Err(::afastdata::Error::validate(#code, #err_msg.to_string()));
                                        }
                                    }
                                });
                        } else {
                            validates.push(quote! {
                                    if #field_name <= #cmp_value {
                                        return Err(::afastdata::Error::validate(#code, #err_msg.to_string()));
                                    }
                                });
                        }
                    } else if meta.path.is_ident("gte") {
                        if !is_comparable_type(field_type) {
                            validates.push(
                                    syn::Error::new_spanned(
                                        &meta.path,
                                        format!(
                                            "validation `gte` is only supported on numeric types (or Option<numeric>), but field `{}` is not",
                                            field_name
                                        ),
                                    )
                                    .to_compile_error(),
                                );
                            continue;
                        }
                        let inner = match meta.parse_args::<Range>() {
                            Ok(v) => v,
                            Err(e) => {
                                validates.push(e.to_compile_error());
                                continue;
                            }
                        };
                        let cmp_value = inner.value.to_token_stream();
                        let code = match inner.code.base10_parse::<i64>() {
                            Ok(v) => v,
                            Err(e) => {
                                validates.push(
                                    syn::Error::new_spanned(
                                        &inner.code,
                                        format!("invalid error code: {}", e),
                                    )
                                    .to_compile_error(),
                                );
                                continue;
                            }
                        };
                        let err_msg = inner
                            .msg
                            .value()
                            .replace("${field}", &field_name.to_string());
                        if is_option_type(field_type) {
                            validates.push(quote! {
                                    if let Some(ref __val) = #field_name {
                                        if *__val < #cmp_value {
                                            return Err(::afastdata::Error::validate(#code, #err_msg.to_string()));
                                        }
                                    }
                                });
                        } else {
                            validates.push(quote! {
                                    if #field_name < #cmp_value {
                                        return Err(::afastdata::Error::validate(#code, #err_msg.to_string()));
                                    }
                                });
                        }
                    } else if meta.path.is_ident("lt") {
                        if !is_comparable_type(field_type) {
                            validates.push(
                                    syn::Error::new_spanned(
                                        &meta.path,
                                        format!(
                                            "validation `lt` is only supported on numeric types (or Option<numeric>), but field `{}` is not",
                                            field_name
                                        ),
                                    )
                                    .to_compile_error(),
                                );
                            continue;
                        }
                        let inner = match meta.parse_args::<Range>() {
                            Ok(v) => v,
                            Err(e) => {
                                validates.push(e.to_compile_error());
                                continue;
                            }
                        };
                        let cmp_value = inner.value.to_token_stream();
                        let code = match inner.code.base10_parse::<i64>() {
                            Ok(v) => v,
                            Err(e) => {
                                validates.push(
                                    syn::Error::new_spanned(
                                        &inner.code,
                                        format!("invalid error code: {}", e),
                                    )
                                    .to_compile_error(),
                                );
                                continue;
                            }
                        };
                        let err_msg = inner
                            .msg
                            .value()
                            .replace("${field}", &field_name.to_string());
                        if is_option_type(field_type) {
                            validates.push(quote! {
                                    if let Some(ref __val) = #field_name {
                                        if *__val >= #cmp_value {
                                            return Err(::afastdata::Error::validate(#code, #err_msg.to_string()));
                                        }
                                    }
                                });
                        } else {
                            validates.push(quote! {
                                    if #field_name >= #cmp_value {
                                        return Err(::afastdata::Error::validate(#code, #err_msg.to_string()));
                                    }
                                });
                        }
                    } else if meta.path.is_ident("lte") {
                        if !is_comparable_type(field_type) {
                            validates.push(
                                    syn::Error::new_spanned(
                                        &meta.path,
                                        format!(
                                            "validation `lte` is only supported on numeric types (or Option<numeric>), but field `{}` is not",
                                            field_name
                                        ),
                                    )
                                    .to_compile_error(),
                                );
                            continue;
                        }
                        let inner = match meta.parse_args::<Range>() {
                            Ok(v) => v,
                            Err(e) => {
                                validates.push(e.to_compile_error());
                                continue;
                            }
                        };
                        let cmp_value = inner.value.to_token_stream();
                        let code = match inner.code.base10_parse::<i64>() {
                            Ok(v) => v,
                            Err(e) => {
                                validates.push(
                                    syn::Error::new_spanned(
                                        &inner.code,
                                        format!("invalid error code: {}", e),
                                    )
                                    .to_compile_error(),
                                );
                                continue;
                            }
                        };
                        let err_msg = inner
                            .msg
                            .value()
                            .replace("${field}", &field_name.to_string());
                        if is_option_type(field_type) {
                            validates.push(quote! {
                                    if let Some(ref __val) = #field_name {
                                        if *__val > #cmp_value {
                                            return Err(::afastdata::Error::validate(#code, #err_msg.to_string()));
                                        }
                                    }
                                });
                        } else {
                            validates.push(quote! {
                                    if #field_name > #cmp_value {
                                        return Err(::afastdata::Error::validate(#code, #err_msg.to_string()));
                                    }
                                });
                        }
                    } else if meta.path.is_ident("len") {
                        let field_is_option = is_option_type(field_type);
                        // For Option<T>, check if inner type is a collection
                        // For non-Option, check directly
                        if field_is_option {
                            // Option<T> is allowed - inner type check is deferred to runtime
                        } else if !is_collection_type(field_type) {
                            validates.push(
                                    syn::Error::new_spanned(
                                        &meta.path,
                                        format!(
                                            "validation `len` is only supported on String, &[u8], Vec<T>, [T; N], or Option<T> wrapping these types, but field `{}` is not",
                                            field_name
                                        ),
                                    )
                                    .to_compile_error(),
                                );
                            continue;
                        }

                        let inner = match meta.parse_args::<Length>() {
                            Ok(v) => v,
                            Err(e) => {
                                validates.push(e.to_compile_error());
                                continue;
                            }
                        };
                        let min_value = match inner.min.base10_parse::<i64>() {
                            Ok(v) => v,
                            Err(e) => {
                                validates.push(
                                    syn::Error::new_spanned(
                                        &inner.min,
                                        format!("invalid min value: {}", e),
                                    )
                                    .to_compile_error(),
                                );
                                continue;
                            }
                        };
                        let max_value = match inner.max.base10_parse::<i64>() {
                            Ok(v) => v,
                            Err(e) => {
                                validates.push(
                                    syn::Error::new_spanned(
                                        &inner.max,
                                        format!("invalid max value: {}", e),
                                    )
                                    .to_compile_error(),
                                );
                                continue;
                            }
                        };
                        let code = match inner.code.base10_parse::<i64>() {
                            Ok(v) => v,
                            Err(e) => {
                                validates.push(
                                    syn::Error::new_spanned(
                                        &inner.code,
                                        format!("invalid error code: {}", e),
                                    )
                                    .to_compile_error(),
                                );
                                continue;
                            }
                        };
                        let err_msg = inner
                            .msg
                            .value()
                            .replace("${field}", &field_name.to_string());
                        // -1 is a sentinel meaning "no limit", so skip range check when either is -1
                        if min_value >= 0 && max_value >= 0 && min_value > max_value {
                            validates.push(
                                    syn::Error::new_spanned(
                                        &meta.path,
                                        format!(
                                            "invalid len validation: min ({}) > max ({}) for field `{}`",
                                            min_value, max_value, field_name
                                        ),
                                    )
                                    .to_compile_error(),
                                );
                            continue;
                        }
                        if min_value < 0 && max_value < 0 {
                            validates.push(
                                    syn::Error::new_spanned(
                                        &meta.path,
                                        format!(
                                            "invalid len validation: both min and max are negative for field `{}`",
                                            field_name
                                        ),
                                    )
                                    .to_compile_error(),
                                );
                            continue;
                        } else if min_value < 0 {
                            let max: usize = match max_value.try_into() {
                                Ok(v) => v,
                                Err(_) => {
                                    validates.push(
                                        syn::Error::new_spanned(
                                            &inner.max,
                                            "value too large for usize",
                                        )
                                        .to_compile_error(),
                                    );
                                    continue;
                                }
                            };
                            if field_is_option {
                                validates.push(quote! {
                                        if let Some(ref __val) = #field_name {
                                            if __val.len() > #max {
                                                return Err(::afastdata::Error::validate(#code, #err_msg.to_string()));
                                            }
                                        }
                                    });
                            } else {
                                validates.push(quote! {
                                        if #field_name.len() > #max {
                                            return Err(::afastdata::Error::validate(#code, #err_msg.to_string()));
                                        }
                                    });
                            }
                        } else if max_value < 0 {
                            let min: usize = match min_value.try_into() {
                                Ok(v) => v,
                                Err(_) => {
                                    validates.push(
                                        syn::Error::new_spanned(
                                            &inner.min,
                                            "value too large for usize",
                                        )
                                        .to_compile_error(),
                                    );
                                    continue;
                                }
                            };
                            if field_is_option {
                                validates.push(quote! {
                                        if let Some(ref __val) = #field_name {
                                            if __val.len() < #min {
                                                return Err(::afastdata::Error::validate(#code, #err_msg.to_string()));
                                            }
                                        }
                                    });
                            } else {
                                validates.push(quote! {
                                        if #field_name.len() < #min {
                                            return Err(::afastdata::Error::validate(#code, #err_msg.to_string()));
                                        }
                                    });
                            }
                        } else {
                            let min: usize = match min_value.try_into() {
                                Ok(v) => v,
                                Err(_) => {
                                    validates.push(
                                        syn::Error::new_spanned(
                                            &inner.min,
                                            "value too large for usize",
                                        )
                                        .to_compile_error(),
                                    );
                                    continue;
                                }
                            };
                            let max: usize = match max_value.try_into() {
                                Ok(v) => v,
                                Err(_) => {
                                    validates.push(
                                        syn::Error::new_spanned(
                                            &inner.max,
                                            "value too large for usize",
                                        )
                                        .to_compile_error(),
                                    );
                                    continue;
                                }
                            };
                            if field_is_option {
                                validates.push(quote! {
                                        if let Some(ref __val) = #field_name {
                                            if !(#min..=#max).contains(&__val.len()) {
                                                return Err(::afastdata::Error::validate(#code, #err_msg.to_string()));
                                            }
                                        }
                                    });
                            } else {
                                validates.push(quote! {
                                        if !(#min..=#max).contains(&#field_name.len()) {
                                            return Err(::afastdata::Error::validate(#code, #err_msg.to_string()));
                                        }
                                    });
                            }
                        }
                    } else if meta.path.is_ident("of") {
                        let inner = match meta.parse_args::<OfValidator>() {
                            Ok(v) => v,
                            Err(e) => {
                                validates.push(e.to_compile_error());
                                continue;
                            }
                        };
                        let allowed_values = inner.allowed_values.clone();
                        let code = match inner.code.base10_parse::<i64>() {
                            Ok(v) => v,
                            Err(e) => {
                                validates.push(
                                    syn::Error::new_spanned(
                                        &inner.code,
                                        format!("invalid error code: {}", e),
                                    )
                                    .to_compile_error(),
                                );
                                continue;
                            }
                        };
                        let err_msg = inner
                            .msg
                            .value()
                            .replace("${field}", &field_name.to_string());
                        let values_tokens: Vec<_> =
                            allowed_values.iter().map(|v| v.to_token_stream()).collect();
                        validates.push(quote! {
                                if !matches!(#field_name, #(#values_tokens)|*) {
                                    return Err(::afastdata::Error::validate(#code, #err_msg.to_string()));
                                }
                            });
                    } else if meta.path.is_ident("func") {
                        let inner = match meta.parse_args::<LitStr>() {
                            Ok(v) => v,
                            Err(e) => {
                                validates.push(e.to_compile_error());
                                continue;
                            }
                        };
                        let ident = match syn::parse_str::<syn::Ident>(&inner.value()) {
                            Ok(v) => v,
                            Err(e) => {
                                validates.push(
                                    syn::Error::new_spanned(
                                        &inner,
                                        format!("invalid function name `{}`: {}", inner.value(), e),
                                    )
                                    .to_compile_error(),
                                );
                                continue;
                            }
                        };
                        let field = field_name.to_string();
                        validates.push(quote! {
                            match #ident(&#field_name, #field) {
                                Ok(()) => {},
                                Err(e) => return Err(e.to_afastdata_error()),
                            }
                        });
                    }
                }
            }
        }
    }
    validates
}

/// 为结构体的字段生成反序列化代码以及构造表达式。内部辅助函数。
///
/// Generates deserialization code for struct fields along with the construction
/// expression. Internal helper.
///
/// # 参数 / Parameters
///
/// - `fields`：结构体的字段定义 / The struct's field definitions
/// - `name`：结构体类型的标识符 / The struct type's identifier
/// - `ty_generics`：类型的泛型参数（用于构造时的 turbofish 语法）
///   / The type's generic parameters (used for turbofish syntax during construction)
///
/// # 返回值 / Returns
///
/// 返回 `(构造表达式, 反序列化语句列表)`：
/// - 构造表达式：用于创建结构体实例的 `TokenStream`
/// - 反序列化语句：每个字段的 `from_bytes()` 调用和偏移量更新
///
/// Returns `(construction_expression, deserialization_statements)`:
/// - Construction expression: A `TokenStream` for creating the struct instance
/// - Deserialization statements: `from_bytes()` calls and offset updates for each field
///
/// # 泛型构造 / Generic Construction
///
/// 使用 `as_turbofish()` 生成正确的泛型语法。例如 `MyStruct::<T>` 而非
/// `MyStruct <T>`（后者会被解析为比较操作）。
///
/// Uses `as_turbofish()` to generate correct generic syntax. For example,
/// `MyStruct::<T>` instead of `MyStruct <T>` (which would be parsed as a
/// comparison operation).
fn generate_deserialize_fields(
    fields: &Fields,
    name: &syn::Ident,
    ty_generics: &syn::TypeGenerics,
) -> (proc_macro2::TokenStream, Vec<proc_macro2::TokenStream>) {
    // 在表达式上下文中使用 turbofish 语法：Name::<T>
    // In expression context, use turbofish syntax: Name::<T>
    let ty_params = ty_generics.as_turbofish();
    match fields {
        Fields::Named(named) => {
            let mut desers = Vec::new();
            let mut field_names = Vec::new();
            for f in &named.named {
                let fname = f.ident.as_ref().unwrap();
                let ftype = &f.ty;
                field_names.push(fname.clone());

                let validates = parse_validations(fname, ftype, &f.attrs);
                let (skip, default) = has_skip_attr(&f.attrs);
                if skip {
                    if let Some(default) = default {
                        match syn::parse_str::<syn::Ident>(&default) {
                            Ok(ident) => {
                                desers.push(quote! {
                                    let #fname: #ftype = #ident();
                                });
                            }
                            Err(_) => {
                                desers.push(quote! {
                                    compile_error!(concat!("invalid function name in skip: ", #default));
                                });
                            }
                        }
                    } else {
                        desers.push(quote! {
                            let #fname: #ftype = #ftype::default();
                        });
                    }
                } else {
                    desers.push(quote! {
                        let (__val, __new_offset) = ::afastdata::AFastDeserialize::from_bytes(&__afast_data__[__afast_offset__..])?;
                        let #fname: #ftype = __val;
                        #(#validates)*
                        __afast_offset__ += __new_offset;
                    });
                }
            }
            let construct = quote! {
                #name #ty_params { #(#field_names),* }
            };
            (construct, desers)
        }
        Fields::Unnamed(unnamed) => {
            let mut desers = Vec::new();
            let mut field_names = Vec::new();
            for (i, f) in unnamed.unnamed.iter().enumerate() {
                let fname = syn::Ident::new(&format!("__f{}", i), name.span());
                let ftype = &f.ty;
                let (skip, default_fn) = has_skip_attr(&f.attrs);
                if skip {
                    if let Some(func_name) = default_fn {
                        match syn::parse_str::<syn::Ident>(&func_name) {
                            Ok(ident) => {
                                desers.push(quote! {
                                    let #fname: #ftype = #ident();
                                });
                            }
                            Err(_) => {
                                desers.push(quote! {
                                    compile_error!(concat!("invalid function name in skip: ", #func_name));
                                });
                            }
                        }
                    } else {
                        desers.push(quote! {
                            let #fname: #ftype = <#ftype as ::std::default::Default>::default();
                        });
                    }
                } else {
                    let validates = parse_validations(&fname, ftype, &f.attrs);
                    desers.push(quote! {
                        let (__val, __new_offset) = ::afastdata::AFastDeserialize::from_bytes(&__afast_data__[__afast_offset__..])?;
                        let #fname: #ftype = __val;
                        #(#validates)*
                        __afast_offset__ += __new_offset;
                    });
                }
                field_names.push(fname);
            }
            let construct = quote! {
                #name #ty_params ( #(#field_names),* )
            };
            (construct, desers)
        }
        Fields::Unit => {
            let construct = quote! { #name #ty_params };
            (construct, vec![])
        }
    }
}

/// 为结构体的字段生成带 marker 的反序列化代码以及构造表达式。内部辅助函数。
///
/// Generates marker-aware deserialization code for struct fields along with the
/// construction expression. Internal helper.
///
/// marker 匹配的 `skip_with` 字段使用默认值或自定义函数填充，不从字节流读取。
///
/// `skip_with` fields whose marker matches are filled with default values or custom
/// functions, without reading from the byte stream.
fn generate_deserialize_fields_with(
    fields: &Fields,
    name: &syn::Ident,
    ty_generics: &syn::TypeGenerics,
    marker: &str,
) -> (proc_macro2::TokenStream, Vec<proc_macro2::TokenStream>) {
    let ty_params = ty_generics.as_turbofish();
    // marker 参数是生成代码中的参数名（如 "__afast_marker__"），不是实际值
    // The marker parameter is the parameter name in generated code, not the actual value
    let marker_ident = syn::Ident::new(marker, proc_macro2::Span::call_site());
    match fields {
        Fields::Named(named) => {
            let mut desers = Vec::new();
            let mut field_names = Vec::new();
            for f in &named.named {
                let fname = f.ident.as_ref().unwrap();
                let ftype = &f.ty;
                field_names.push(fname.clone());

                let (skip, _) = has_skip_attr(&f.attrs);
                if skip {
                    desers.push(quote! {
                        let #fname: #ftype = <#ftype as ::std::default::Default>::default();
                    });
                } else {
                    let skip_with = has_skip_with_attr(&f.attrs);
                    if let Some((m, default_fn)) = skip_with {
                        let default_expr = if let Some(fn_name) = default_fn {
                            match syn::parse_str::<syn::Ident>(&fn_name) {
                                Ok(ident) => quote! { #ident() },
                                Err(_) => {
                                    quote! { { compile_error!(concat!("invalid function name in skip_with: ", #fn_name)); <#ftype as ::std::default::Default>::default() } }
                                }
                            }
                        } else {
                            quote! { <#ftype as ::std::default::Default>::default() }
                        };
                        let validates = parse_validations(fname, ftype, &f.attrs);
                        desers.push(quote! {
                            let #fname: #ftype = if #marker_ident == #m {
                                #default_expr
                            } else {
                                let (__val, __new_offset) = ::afastdata::AFastDeserialize::from_bytes_with(&__afast_data__[__afast_offset__..], #marker_ident)?;
                                #(#validates)*
                                __afast_offset__ += __new_offset;
                                __val
                            };
                        });
                    } else {
                        let validates = parse_validations(fname, ftype, &f.attrs);
                        desers.push(quote! {
                            let (__val, __new_offset) = ::afastdata::AFastDeserialize::from_bytes_with(&__afast_data__[__afast_offset__..], #marker_ident)?;
                            let #fname: #ftype = __val;
                            #(#validates)*
                            __afast_offset__ += __new_offset;
                        });
                    }
                }
            }
            let construct = quote! {
                #name #ty_params { #(#field_names),* }
            };
            (construct, desers)
        }
        Fields::Unnamed(unnamed) => {
            let mut desers = Vec::new();
            let mut field_names = Vec::new();
            for (i, f) in unnamed.unnamed.iter().enumerate() {
                let fname = syn::Ident::new(&format!("__f{}", i), name.span());
                let ftype = &f.ty;
                field_names.push(fname.clone());

                let (skip, _) = has_skip_attr(&f.attrs);
                if skip {
                    desers.push(quote! {
                        let #fname: #ftype = <#ftype as ::std::default::Default>::default();
                    });
                } else {
                    let skip_with = has_skip_with_attr(&f.attrs);
                    if let Some((m, default_fn)) = skip_with {
                        let default_expr = if let Some(fn_name) = default_fn {
                            match syn::parse_str::<syn::Ident>(&fn_name) {
                                Ok(ident) => quote! { #ident() },
                                Err(_) => {
                                    quote! { { compile_error!(concat!("invalid function name in skip_with: ", #fn_name)); <#ftype as ::std::default::Default>::default() } }
                                }
                            }
                        } else {
                            quote! { <#ftype as ::std::default::Default>::default() }
                        };
                        let validates = parse_validations(&fname, ftype, &f.attrs);
                        desers.push(quote! {
                            let #fname: #ftype = if #marker_ident == #m {
                                #default_expr
                            } else {
                                let (__val, __new_offset) = ::afastdata::AFastDeserialize::from_bytes_with(&__afast_data__[__afast_offset__..], #marker_ident)?;
                                #(#validates)*
                                __afast_offset__ += __new_offset;
                                __val
                            };
                        });
                    } else {
                        let validates = parse_validations(&fname, ftype, &f.attrs);
                        desers.push(quote! {
                            let (__val, __new_offset) = ::afastdata::AFastDeserialize::from_bytes_with(&__afast_data__[__afast_offset__..], #marker_ident)?;
                            let #fname: #ftype = __val;
                            #(#validates)*
                            __afast_offset__ += __new_offset;
                        });
                    }
                }
            }
            let construct = quote! {
                #name #ty_params ( #(#field_names),* )
            };
            (construct, desers)
        }
        Fields::Unit => {
            let construct = quote! { #name #ty_params };
            (construct, vec![])
        }
    }
}