rust_xlsxwriter×Serde终极指南:Rust结构体一键序列化为Excel

原创2026-11-16 23:53:291,995 阅读
文章标签:后端

rust_xlsxwriter×Serde终极指南:Rust结构体一键序列化为Excel

📊 rust_xlsxwriter 是 Rust 生态中创建 Excel XLSX 文件的库,配合 Serde 序列化支持,只需几行代码就能把 Rust 结构体(struct)或结构体数组一键序列化写入 Excel 工作表:字段名自动变成表头,值自动填入下方单元格,还能控制表头样式、数字格式和 Excel 表格外观。本指南带你从启用 feature 到属性宏进阶,完整掌握 Serde 序列化导出 Excel 的最快路径。

为什么 rust_xlsxwriter + Serde 是 Excel 导出组合

传统做法是逐格调用 write_string、write_number 手动填充,列一多代码又长又容易错位。而 rust_xlsxwriter 实现了 Serde 的 serde::Serializer trait(核心实现在 src/serializer.rs),让 Worksheet 直接充当序列化目标:

  • 结构体 → 二维网格:每个字段映射为一列表头,每个实例映射为一行数据;
  • 一次 serialize() 调用:数组或向量数据按行依次写入,无需手写行列索引;
  • 格式跟着结构体走:通过 #[xlsx] 属性把重命名、数字格式、列宽、表格样式直接"焊"在结构体定义上。

完整文档说明在 src/serializer.rs 文件头部,示例代码集中在 examples/ 目录下(如 examples/app_serialize.rs)。

3步启用:开启 serde feature 并写出第一张表

第1步:安装并启用 serde feature

cargo add rust_xlsxwriter -F serde

feature 定义见 Cargo.toml 中的 serde = ["dep:serde", "dep:rust_xlsxwriter_derive"] 一行。

第2步:定义可序列化结构体

use rust_xlsxwriter::{Workbook, XlsxSerialize};
use serde::Serialize;

#[derive(XlsxSerialize, Serialize)]
#[xlsx(header_format = Format::new().set_bold())]
struct Produce {
    #[xlsx(rename = "Item", column_width = 12.0)]
    fruit: &'static str,

    #[xlsx(rename = "Price", num_format = "$0.00")]
    cost: f64,
}

第3步:设置表头、序列化、保存

let mut workbook = Workbook::new();
let worksheet = workbook.add_worksheet();

// 从 (0, 0) 位置开始写入表头
worksheet.set_serialize_headers::<Produce>(0, 0)?;

// 一次序列化整个数组
worksheet.serialize(&items)?;

workbook.save("serialize.xlsx")?;

对应完整示例:examples/doc_xlsxserialize_intro.rs。

如何选择:3 种表头设置方式对比

rust_xlsxwriter 提供三组方法,区别在于"表头信息从哪来"(详见 src/serializer.rs 的文档说明):

方式 方法 结构体需要 适用场景
① 序列化推断 serialize_headers() / serialize_headers_with_format() 仅 Serialize 需要传入一个实例供库推断字段,改动最小的方案
② 反序列化推断 deserialize_headers() / deserialize_headers_with_format() Serialize + Deserialize 只需类型不需实例,可配合 SerializeFieldOptions 自定义表头
③ 属性宏声明 set_serialize_headers() Serialize + XlsxSerialize 格式内联在结构体属性中,代码最少(官方作者主要用法)

💡 选择建议:结构体归你控制 → 用方式③;结构体有 Deserialize → 用方式②省事;结构体是第三方定义且只能 Serialize → 用方式①。

方式②的完整示例(含表头加粗、边框、背景色)见 examples/doc_worksheet_serialize_intro2.rs;方式①的"自定义表头+隐藏表头"进阶用法见 examples/doc_worksheet_serialize_headers_with_options.rs。

#[xlsx] 属性速查表:让输出更精美

XlsxSerialize 支持两类属性,把格式定义"锁"在结构体上(完整说明:src/serializer.rs)。

容器属性(写在 struct 上)

#[derive(XlsxSerialize, Serialize)]
#[xlsx(header_format = Format::new().set_bold())]  // 表头格式
#[xlsx(hide_headers)]        // 隐藏表头行
#[xlsx(table_default)]       // 自动附加默认样式的 Excel 表格
#[xlsx(table_style = TableStyle::Medium10)]  // 指定表格样式
struct Produce { /* ... */ }

给数据区加上 Excel 表格后,自带筛选、隔行底纹等效果,一行属性搞定:examples/doc_worksheet_serialize_table1.rs、examples/doc_xlsxserialize_table_style.rs。

字段属性(写在字段上)

struct Produce {
    #[xlsx(rename = "Item")]          // 重命名表头(不影响其他序列化)
    fruit: &'static str,

    #[xlsx(num_format = "$0.00")]     // 数字格式(货币示例)
    cost: f64,

    #[xlsx(column_width = 12.0)]      // 自动设置列宽
    #[xlsx(value_format = Format::new().set_font_color("#FF0000"))]  // 数据区字体颜色
    fruit2: &'static str,
}

示例文件:examples/doc_xlsxserialize_rename.rs、examples/doc_xlsxserialize_num_format.rs、examples/doc_xlsxserialize_value_format.rs。

常见场景:跳过字段与日期时间

跳过不想导出的字段

比如结构体里有内部 ID 字段不希望出现在 Excel 中,用三种方式之一跳过:

  • Serde 属性:#[serde(skip)](所有序列化都跳过)
  • xlsx 属性:#[xlsx(skip)](仅 Excel 序列化跳过)
  • 运行时:CustomSerializeField::skip()

示例:examples/doc_xlsxserialize_skip.rs、examples/doc_worksheet_serialize_headers_skip1.rs。

序列化日期和时间

支持的时间类型:

  • ExcelDateTime:库自带类型,自动按 Excel 日期数值序列化;
  • chrono 的 NaiveDate / NaiveTime / NaiveDateTime(需 chrono feature);
  • jiff 的 civil 类型(需 jiff feature)。

⚠️ 注意:chrono/jiff 类型默认会序列化为字符串。若要写成 Excel 原生日期(数字+日期格式),需用 Utility::serialize_datetime_to_excel() 转换,或改用 ExcelDateTime。Excel 本身不处理时区,库也不编码时区信息。

示例:examples/doc_worksheet_serialize_datetime1.rs。

避坑指南:Excel 序列化的边界

Excel 是二维网格,序列化能力受此约束(官方说明:src/serializer.rs):

  1. 只支持结构体及其向量:T 或 Vec<T>(T: Serialize);
  2. 不支持 Map / HashMap:无固定 schema,且字段顺序不保证;
  3. #[serde(flatten)] 不可用:flatten 会把固定字段转成动态 map,因此带 flatten 的结构体无法直接序列化(可用 CustomSerializeField::skip() 等手段剔除问题字段);
  4. 嵌套结构体有限制:最好先设计好"数据最终在表格里长什么样",再定义结构体。

碰到无法序列化的数据,还有退路:直接用 Worksheet::write()、write_row()、write_column() 等标准 API 手动写入。

总结:Rust 结构体导出 Excel 的最短路径

需求 推荐做法
快速把结构体数组导出成表 deserialize_headers() + serialize()
结构体可控、想要最少代码 XlsxSerialize 派生 + #[xlsx] 属性
表头要样式/表格/隔行底纹 header_format / table_default / table_style
字段重命名或隐藏列 #[xlsx(rename)] / #[xlsx(skip)]
金额、日期等特殊显示 num_format、value_format、ExcelDateTime

至此,你已经掌握 rust_xlsxwriter 的 Serde 序列化全貌:从一行 cargo add 命令开始,到属性宏精细控制每一列的外观。更多可运行示例可参考 examples/README.md 索引,源码细节随时翻 src/serializer.rs——这是库中实现 Serde 序列化 trait 的核心模块。

登录后查看全文
rust_xlsxwriter