fast-excel 1.0.0

通用 Excel 导入导出工具:流式读写(百万级)、动态表头适配、多 sheet、单元格图片、批量落库(纯 Rust,对标 EasyExcel)
Documentation

fast-excel_rs —— 通用 Excel 导入导出工具(Rust 版 EasyExcel)

面向真实业务场景:百万行 + 批量落库 + 单元格图片 + 多 sheet + 动态表头。 纯 Rust(quick-xml + rust_xlsxwriter + zip),不依赖 JVM、Office 组件或外部服务。

本 crate 是独立工具库;采购模块的 Excel 导入 / 导出中心共用它的一套列定义, 保证「模板 / 导出 / 导入校验」三处表头永远一致。

能力对照

能力 EasyExcel 对应 本工具实现
注解式映射 @ExcelProperty #[derive(ExcelRow)] + #[excel(header = "...")]
动态表头适配 表头匹配器 精确 / 别名 / 模糊 / 列序回退(HeaderOptions)
百万行读取 SAX 逐行读 SheetStream:quick-xml 事件流,内存与行数无关
百万行写出 constant_memory ExcelWriter / SheetWriter:边写边落临时文件
分批落库 ReadListener + 手动批 ImportRunner::commit + BatchSink(batch_size 一批一事务)
分页导出 分页查询写 ExportRunner::export_xlsx:游标分页 Page { rows, cursor, done }
单元格图片 图片列 / 自定义转换 读:标准 drawing 锚点 + WPS DISPIMG;写:CellValue::Image
多 sheet 多 sheet() 写 读:SheetSelector::{Name,Names,All};写:ExcelWriter::add_sheet、ExportRunner::export_multi_sheet
合并单元格 合并区域 读:ReadOptions::with_merges 回填值 + MergeRange 暴露区域;写:merge_header / merge_range / write_row_with_merges
表头起始行 表头行配置 导入 header_row(n)(0 基)+ header_span 多行表头;analyze_header 返回 1 基行号
列值表达式 自定义转换 闭包计算列 + 内置函数 [funcs]:导出 SheetOptions::computed / transform;导入 ImportRunner::computed;模板 sample_expr / default_expr
行过滤 跳过脚注行 ImportRunner::row_filter(跳过"合计 / 备注"等表尾行)
CSV 导入 CSV 读取 CsvReader:复用同一套表头适配 / 计算列 / 行过滤 / 模型映射
读取样式 颜色 / 加粗 RowData::cell_style / ExcelReader::styles 取字体颜色、底色、加粗、斜体
超链接/批注 单元格附加信息 读:with_hyperlinks / with_comments / with_validations / with_conditional_formats(含 dxf 颜色);写:write_row_with_links
导入模板 模板导出 TemplateSpec / build_template:必填红字 + 示例行 + 下拉 + 说明 sheet
导入预览 校验后再入库 ImportRunner::preview(只读前 N 行,返回列匹配与行级错误)
执行器注册 注册后全链路复用 #[derive(ExcelExecutor)] + 全局注册表:按类型或按名做预览 / 导入 / 导出 / 模板;executor_config! 登记模型级默认配置
动态表头 无实体导入导出 导入 DynamicRow / ExcelReader::read_dynamic;导出 DynamicSheet + DynamicRow(按表头名对齐)/ align_row
纯文本兜底 — write_csv(UTF-8 BOM,Excel 双击不乱码)

快速开始

1)声明行模型

use fast_excel::{CellImage, ExcelRow};

#[derive(ExcelRow, Debug, Clone)]
#[excel(sheet = "产品导入")]
struct ProductRow {
    #[excel(header = "工厂名称", alias = ["工厂", "厂名"], required)]
    factory: String,
    #[excel(header = "品名", required)]
    name: String,
    #[excel(header = "报价(USD)", kind = "decimal", format = "#,##0.00")]
    price: Option<rust_decimal::Decimal>,
    #[excel(header = "手机号", text)]
    phone: Option<String>,
    #[excel(header = "图片1", image)]
    image1: Option<CellImage>,
}

字段属性:header / alias / required / kind / width / format / text / image / default / note / dropdown / ignore / dynamic。

2)导入:预览 → 分批落库

use std::sync::Arc;
use fast_excel::{BatchSink, ExcelError, ImportRunner, SheetSelector, ZipSource};

// 每批一个事务,业务侧自己决定事务边界
struct ProductSink { /* db: DbConn, ... */ }

#[async_trait::async_trait]
impl BatchSink<ProductRow> for ProductSink {
    async fn save(&self, batch: Vec<ProductRow>) -> Result<usize, ExcelError> {
        let n = batch.len();
        // product::Entity::insert_many_with_fill(models, &tx).await?; tx.commit().await?;
        Ok(n)
    }
}

# async fn demo() -> Result<(), ExcelError> {
let source = ZipSource::open("products.xlsx")?;

// 预览:不落库,只读前 200 行,返回表头匹配 + 行级错误
let preview = ImportRunner::new()
    .sheets(SheetSelector::All)
    .preview::<ProductRow>(source.clone(), 200)?;

// 正式导入:解析在阻塞线程,落库在异步任务,中间有界队列做背压
let report = ImportRunner::new()
    .sheets(SheetSelector::All)
    .batch_size(500)          // 每 500 行一批
    .concurrency(1)           // 批次并发(>1 需业务侧保证批次无序安全)
    .stop_on_error(true)
    .commit(source, Arc::new(ProductSink { /* ... */ }))
    .await?;
# Ok(()) }

3)导出:游标分页 + 流式写

use fast_excel::{ExportRunner, Page, SheetOptions};

# async fn demo(db: sea_orm::DatabaseConnection) -> Result<(), fast_excel::ExcelError> {
let runner = ExportRunner::new(SheetOptions::new("选品数据").columns(ProductRow::columns()));
let stats = runner
    .export_xlsx("uploads/export/products.xlsx", |cursor| {
        let db = db.clone();
        async move {
            let mut q = product::Entity::find()
                .order_by_asc(product::Column::Id)
                .limit(1000);
            if let Some(last_id) = cursor {
                q = q.filter(product::Column::Id.gt(last_id));
            }
            let rows = q.all(&db).await.map_err(|e| fast_excel::ExcelError::Sink(e.to_string()))?;
            let done = rows.len() < 1000;
            let last_id = rows.last().map(|r| r.id.clone());
            let rows = rows.into_iter().map(Into::into).collect();
            Ok(match last_id {
                Some(id) if !done => Page::more(rows, id),
                _ => Page::last(rows),
            })
        }
    })
    .await?;
# Ok(()) }

图片支持

导入:图片直接插在单元格里即可(不需要「文件名 + zip 资料包」那套约定)。

  • Excel 标准 drawing 锚点(xl/drawings/drawingN.xml → xl/media/*);

  • WPS 单元格嵌入图片 =DISPIMG("ID_xxx",1)(xl/cellimages.xml);

  • 图片字节按需读取,只有模型声明了图片列时才读对应列,避免百万行文件把图片全量读进内存;

  • 导出再导入能保住原文件名:写侧把 CellImage::name 写进图片 alt 文本(cNvPr@descr),读侧优先取它,取不到才回退 image1.png。

导出:

use fast_excel::{CellImage, CellValue, SheetOptions, WriteOptions};

let sheet = SheetOptions::new("带图数据")
    .columns(ProductRow::columns())
    .write_options(WriteOptions::default().image_row_height(72.0));
// 行值里放 CellValue::Image(CellImage::new(bytes, "png").named("main.png"))
  • 默认写标准锚点图片(insert_image_fit_to_cell_centered),常量内存模式下可用;

  • WriteOptions::cell_image() 会写 Excel「置于单元格内」图片(随筛选/排序移动); 该方法自动关闭常量内存(rust_xlsxwriter 的内嵌图片不支持常量内存模式);

  • 行高在写单元格之前设置,图片按行高自适应缩放。

合并单元格

xlsx 的合并区域只有左上角单元格有值,其余为空。要按业务语义读回,需要开启合并读取 (<mergeCells> 在 <sheetData> 之后,无法边读边取,因此要额外扫一遍工作表 XML, 默认关闭以保证百万行吞吐):

use fast_excel::{ExcelReader, ReadOptions, SheetSelector};

let reader = ExcelReader::open("merged.xlsx")?;
// ① 开启后:左上角的值会回填到整个合并区域,`RowData::merged_at(col)` 可判断某格是否被合并
let mut stream = reader.stream(
    SheetSelector::First,
    &[],
    ReadOptions::new().with_merges(), // 只想拿区域、不要回填:.merges_exposed_only()
)?;
while let Some(row) = stream.next_row()? {
    // 纵向合并 A2:A4 = "分组A" 时,第 3、4 行的「名称」列同样读到 "分组A"
    println!("{}", row.text_of("名称"));
}
// ② 整体区域查询(不回填)
let ranges = reader.merge_ranges(&SheetSelector::First)?;
// MergeRange { first_row, last_row, first_col, last_col },行 1 基、列 0 基

// ③ 导入执行器上等价开关(含合并表头 / 合并内容)
let report = fast_excel::ImportRunner::new()
    .merged(true)
    .commit::<ProductRow, _>(source, sink)
    .await?;
# Ok::<(), fast_excel::ExcelError>(())

写出:

use fast_excel::{CellValue, SheetOptions};
// 大标题 / 多级表头:任意矩形合并(header 样式)
ws.merge_header(0, 0, 0, 2, "基本信息")?;   // A1:C1
// 内容行内横向合并(如合计 / 备注),其余列照常写
ws.write_row_with_merges(
    &[CellValue::Text("合计".into()), CellValue::Text("1,000".into()), CellValue::Empty],
    &[(1, 2)],                               // B:C 合并
)?;

注意事项:

  • 写出合并都会推进行游标,不能回退到已写行(常量内存模式的限制);
  • 纵向合并(跨行)会由 rust_xlsxwriter 以 write-ahead 方式写出,常量内存模式下可用;但 「纵向合并 + 相邻列同时有数据」这种交叉布局在常量内存下无法按行顺序构造,请用 WriteOptions::new().in_memory() 关闭常量内存,并通过 SheetWriter::worksheet() 逃生口写;
  • 合并读取默认关闭;只在确实需要时用 .with_merges() / ImportRunner::merged(true) 打开。

表头从第几行开始

导入时表头不一定在第 1 行(上面常有大标题 / 说明行)。用 header_row(0 基)指定, header_span 支持多行表头(纵向拼接,如 报价(USD) 分两行写):

let runner = fast_excel::ImportRunner::new()
    .header_row(1)   // 第 2 行是表头(0 基)
    .header_span(2)  // 表头占 2 行
    .merged(true);   // 配合合并读取,横向合并的表头值会覆盖到每一列

ReadOptions::header_row / ReadOptions::header_span 是同一套配置的底层入口; Reader::analyze_header 返回的 header_row 是 1 基(前端展示用)。

列值表达式与内置函数

「表达式」就是业务侧写的 Rust 闭包(箭头函数),不放任何表达式解析引擎 —— 编译期类型安全、 零运行时解析。闭包里可以直接调用 fast_excel::funcs 提供的内置函数方法。

内置函数(fast_excel::funcs):

分类 方法
文本 concat(&[&str])、join(sep, &[&str])、upper、lower、trim、replace_all(s,from,to)、substr(s,start,len)、pad_left(s,width,fill)
金额/数值 money(Decimal)、money_fixed(Decimal)、percent(f64,scale)、round(f64,scale)
日期时间 today()、now()、date_fmt(date,fmt)、datetime_fmt(dt,fmt)、ymd(date)、seconds_of_day(dt)
值/兜底 text(v)、coalesce(&[CellValue])、if_empty(v,fallback)、map_dict(&CellValue, &[(from,to)])
序号 seq(start, step) → Seq(Clone 共享计数),Seq::next() / next_cell()

1)导出:计算列 + 列改写

use fast_excel::{CellValue, ColumnDef, ExcelWriter, SheetOptions, funcs};

let sheet = SheetOptions::new("明细")
    .columns(ProductRow::columns())
    // 列改写:把「品名」转大写(按表头匹配)
    .transform("品名", |row| CellValue::Text(funcs::upper(&row.text("品名"))))
    // 计算列:追加一列「小计」= 单价 × 数量
    .computed(ColumnDef::new("小计"), |row| {
        let price = row.get("单价").and_then(|v| v.to_f64()).unwrap_or(0.0);
        let qty = row.get("数量").and_then(|v| v.to_f64()).unwrap_or(0.0);
        CellValue::Number(funcs::round(price * qty, 2))
    })
    .computed(ColumnDef::new("导出日期"), |_row| {
        CellValue::Text(funcs::date_fmt(funcs::today(), "%Y-%m-%d"))
    });

let mut writer = ExcelWriter::new();
let mut ws = writer.add_sheet(&sheet)?;
ws.write_headers()?;          // 表头 = 基础列 + 计算列
ws.write_models(&rows)?;      // 每行自动应用表达式
ws.finish()?;
let bytes = writer.save_to_buffer()?;   // HTTP 直接下载
# Ok::<(), fast_excel::ExcelError>(())

表达式入参是 [RowValues]:按表头 row.get("列名") / row.text("列名"),或按下标 row.at(i) 取值。 先从基础列改写(transform),再追加计算列(computed);计算列也能读到前面算出的列。

2)导入:计算列(文件里没有该列也能算出来)

use fast_excel::{CellValue, ColumnDef, ImportRunner, funcs};

// 文件里只有「姓」「名」两列,模型里声明了「全名」
let report = ImportRunner::new()
    .computed(ColumnDef::new("全名"), |row| {
        let full = funcs::concat(&[&row.text_of("姓"), &row.text_of("名")]);
        CellValue::Text(full)
    })
    .commit::<PersonRow, _>(source, sink)
    .await?;

模型只要按同一个表头声明字段即可取到(def.header 必须与模型表头一致):

#[derive(ExcelRow)]
struct PersonRow {
    #[excel(header = "姓", required)] last: String,
    #[excel(header = "名")]          first: String,
    #[excel(header = "全名")]         full: String,   // 由表达式计算,文件里没有这列
}

3)导入模板:默认值 / 示例行表达式

use fast_excel::{CellValue, TemplateSpec, build_template, funcs};

let spec = TemplateSpec::new(ProductRow::columns())
    // 示例行用表达式生成
    .sample_expr(|cols| {
        cols.iter().map(|c| match c.header.as_str() {
            "品名" => CellValue::Text("示例品名".into()),
            "数量" => CellValue::Number(100.0),
            _ => CellValue::Empty,
        }).collect()
    })
    // 某列默认值用表达式(示例行里该列为空时填充,每次生成模板重新求值)
    .default_expr("填表日期", || {
        CellValue::Text(funcs::date_fmt(funcs::today(), "%Y-%m-%d"))
    });

let bytes = build_template(&spec)?;   // 下载给用户填写
# Ok::<(), fast_excel::ExcelError>(())

行过滤 / CSV 导入 / 读取样式

行过滤:跳过节尾"合计 / 备注"行

use fast_excel::ImportRunner;

let report = ImportRunner::new()
    .row_filter(|row| row.text_of("品名") != "合计")   // 返回 false 的行被跳过
    .commit::<ProductRow, _>(source, sink)
    .await?;
# Ok::<(), fast_excel::ExcelError>(())

row_filter 也能直接在 [ReadOptions] 上用(ReadOptions::row_filter)。

CSV 导入

CSV 与 xlsx 共用同一套列定义(表头 / 别名 / 必填 / default)、导入计算列、行过滤与模型映射:

use fast_excel::{CellValue, ColumnDef, CsvReader, ReadOptions};

let mut reader = CsvReader::open("products.csv")?;   // 或 CsvReader::from_bytes(bytes)
let options = ReadOptions::new()
    .computed(ColumnDef::new("全名"), |row| {
        CellValue::Text(format!("[{}]", row.text_of("品名")))
    })
    .row_filter(|row| row.text_of("品名") != "合计");

let report = reader.read_into::<ProductRow, _>(&options, |_row, data| {
    // 落库 / 收集(逐行、不攒批)
    Ok(())
})?;
println!("成功 {} 行,跳过 {} 行", report.success_rows, report.skipped_rows);
# Ok::<(), fast_excel::ExcelError>(())

支持引号与 "" 转义、跨行引号字段、CRLF / LF、UTF-8 BOM。 (CSV 没有合并单元格 / 内嵌图片 / 样式,这几项在 CSV 链路上为空。)

读取样式(底色 / 字体颜色 / 加粗 / 斜体)

use fast_excel::{ExcelReader, ReadOptions, SheetSelector};

let reader = ExcelReader::open("marked.xlsx")?;
let mut stream = reader.stream(SheetSelector::First, &ProductRow::columns(), ReadOptions::new())?;
while let Some(row) = stream.next_row()? {
    if let Some(style) = row.cell_style("状态") {
        // 黄色底 = 待确认
        if style.background == Some(0xFF_FF00) {
            println!("第 {} 行待确认", row.row_index);
        }
    }
}
# Ok::<(), fast_excel::ExcelError>(())

也可以直接查样式表:reader.styles().cell_style(cell.style)(CellStyle { bold, italic, font_color, background },颜色为 0xRRGGBB)。

读取超链接 / 批注 / 数据验证(下拉)

use fast_excel::{ExcelReader, ReadOptions, SheetSelector};

let reader = ExcelReader::open("with-links.xlsx")?;

// 整表查询
for link in reader.hyperlinks(&SheetSelector::First)? {
    println!("{}{} → {:?}", link.row, link.col, link.href());
}
for c in reader.comments(&SheetSelector::First)? {
    println!("批注 {}:{}({})", c.row, c.text, c.author.as_deref().unwrap_or("匿名"));
}
for v in reader.validations(&SheetSelector::First)? {
    if v.is_list() {
        println!("下拉选项:{:?}", v.items); // 内联列表 ["官网","内部","其他"]
    }
}
for cf in reader.conditional_formats(&SheetSelector::First)? {
    for rule in &cf.rules {
        println!("条件格式 {}: {} {:?}", rule.kind, rule.operator.as_deref().unwrap_or(""), rule.formulas);
    }
}

// 或随行流式取用(也可在 ImportRunner 的 RowData 上取,便于 from_row / sink 使用)
let mut stream = reader.stream(
    SheetSelector::First,
    &ProductRow::columns(),
    ReadOptions::new()
        .with_hyperlinks()
        .with_comments()
        .with_validations()
        .with_conditional_formats(),
)?;
while let Some(row) = stream.next_row()? {
    if let Some(link) = row.link_at(0) {
        let _ = link.href();
    }
    let _ = row.comment_at(0);
    let _ = row.validation_at(0);
    let _ = row.conditional_format_at(0);
    let _ = row.cell_style("品名"); // 底色 / 字体颜色 / 加粗
}
# Ok::<(), fast_excel::ExcelError>(())

说明:超链接会解析工作表 rels 拿外部目标(URL / 文件);批注同时支持经典批注 (comments*.xml)与线程批注(threadedComments,回复按 parentId 并入父批注文本, 作者取自 persons 表);数据验证的 formula1 若为区域引用则不解析成选项(保留在 formula); 条件格式给出规则(type/operator/formulas/dxfId),颜色用 reader.styles().dxf_style(rule.dxf_id.unwrap_or(0)) 取(返回 CellStyle)。 超链接 / 数据验证 / 条件格式读取都需要额外扫一遍工作表 XML,默认关闭。

写出超链接:

use fast_excel::{CellValue, SheetOptions};

let mut ws = writer.add_sheet(&SheetOptions::new("链接"))?;
ws.write_text_row(["名称", "网址"])?;
ws.write_row_with_links(
    &[CellValue::Text("官网".into()), CellValue::Empty],
    &[(1, "https://example.com".to_string(), Some("打开".to_string()))],
)?;

(写批注 rust_xlsxwriter 0.99 未提供公开 API,需要时用 SheetWriter::worksheet() 逃生口。)

无实体(动态表头)导入导出

没有(也不想定义)实体时,表头与字段完全由前端给,框架负责对齐:

导出:表头 + 具名数据,按表头名自动对应数据列

use fast_excel::{CellValue, DynamicRow, DynamicSheet, named_xlsx_bytes};

// 前端传来:表头顺序 + 每行「字段名 → 值」(顺序随便,缺列留空、多余忽略)
let sheet = DynamicSheet::new("选品结果").headers(["品名", "数量", "备注"]);
let rows = vec![DynamicRow {
    entries: vec![
        ("备注".into(), CellValue::Text("急".into())),
        ("品名".into(), CellValue::Text("甲".into())),
        ("数量".into(), CellValue::Number(3.0)),
    ],
}];
let bytes = named_xlsx_bytes(&sheet, &rows)?;      // 或 write_named_xlsx("out.xlsx", &sheet, &rows)
# Ok::<(), fast_excel::ExcelError>(())
  • 想控制列类型 / 格式 / 宽度:.columns(fast_excel::simple_columns(["品名","数量"])) 或直接传 Vec<ColumnDef>;
  • 已经按位置排好:用 positional_xlsx_bytes(&sheet, &rows)(rows: Vec<Vec<CellValue>>);
  • 百万行:DynamicExportRunner::new(sheet).export_named(path, |cursor| …)(游标分页,与 ExportRunner 同样的背压)。

导入:任意文件 → 表头 + 逐行「表头 → 值」

use fast_excel::{ExcelReader, ReadOptions, SheetSelector};

let reader = ExcelReader::open("任意.xlsx")?;
let (headers, rows) = reader.read_dynamic(&SheetSelector::First, ReadOptions::new())?;
println!("表头:{headers:?}");
for row in &rows {
    println!("{}", row.text(&headers[0]));
}
# Ok::<(), fast_excel::ExcelError>(())

需要类型化时用 DynamicRow 逐行读(DynamicRow::get(header) / row.into::<…>() 自行转换); CSV 链路同样支持:CsvReader::parse_all::<DynamicRow>(…)。 对齐函数可单独用:fast_excel::align_row(&headers, &entries)。

百万级要点

环节 做法 内存
读取 quick-xml SAX 逐行,next_row() 一次一行 ≈ 单行
解析并发 spawn_blocking 解析 + 有界 mpsc 通道背压 ≈ queue_batches × batch_size 行
落库 BatchSink::save(batch),一批一事务;concurrency 控制批并发 由业务侧决定
写出 constant_memory 工作表,只能按行号递增写 ≈ 单行缓冲
导出拉取 游标分页 Page,queue_pages 控制预取页数 ≈ queue_pages × page_size 行

注意事项:

  • 常量内存模式只能顺序写行(SheetWriter 用 row_cursor 强制推进,避免静默丢行);

  • 拉取失败时不会留下半截导出文件(自动删除),避免「能下载但内容不全」;

  • 行级错误默认跳过并记录(max_errors 截断),continue_on_row_error(false) 可改成首错中断。

多工作表

// 小数据量:一次写多个 sheet
runner.export_sheets("out.xlsx", vec![
    (SheetOptions::new("汇总").columns(ProductRow::columns()), summary_rows),
    (SheetOptions::new("明细").columns(ProductRow::columns()), detail_rows),
])?;

// 大数据量:每个 sheet 独立游标分页,顺序写出(单表仍是常量内存)
runner.export_multi_sheet("out.xlsx", sheet_options, |sheet_index, cursor| async move {
    // 按 sheet_index 拉不同的筛选条件
    # unimplemented!()
}).await?;

导入模板

use fast_excel::{build_template, ColumnDef, ReferenceSheet, TemplateSpec};

let bytes = build_template(&TemplateSpec::new(ProductRow::columns())
    .sheet_name("产品导入")
    .title("产品导入模板")
    .note("图片直接粘贴到单元格")
    .sample_row(vec![/* 示例行 */])
    .reference(ReferenceSheet::new("工厂列表", vec!["工厂名称".into(), "短码".into()])
        .rows(vec![vec!["工厂A".into(), "A".into()]])))?;

生成的工作簿包含:数据 sheet(必填列红字表头 + 示例行 + 下拉验证)、 「填写说明」sheet、若干引用 sheet。

模板还支持(详见下方「列值表达式」与「行过滤 / CSV 导入 / 读取样式」):

  • .header_group("基本信息", 3):顶层合并表头,生成多级表头模板;
  • .sample_expr(...) / .default_expr("列", ...):用表达式生成示例行 / 列默认值;
  • 列属性 #[excel(default = "...")]:示例行与导入空值都会兜底填该默认值。

动态表头适配

HeaderOptions 的匹配顺序(可在 ImportRunner / ReadOptions 上调整):

  1. 精确:归一化后一致(去空白、全角转半角、去 * 必填标记);
  2. 别名:命中 ColumnDef::aliases;
  3. 模糊:互相包含,取差异最小(如 报价(USD)(含税) 命中 报价(USD));
  4. 列序回退:显式开启后,表头缺失时按声明顺序落到第 N 列。

analyze_header / analyze_all_headers 可只做预检,把「匹配到哪些列、缺哪些必填列、 多出哪些列」返回给前端确认。

执行器(推荐):注册一次,全链路通用

不想每次手拼 ImportRunner / ExportRunner 的,给行模型挂一个派生宏即可。 宏自动创建执行器工厂并静态注册进全局表(inventory 链接期收集,零初始化), 业务端既不用管理工厂,也不用写任何注册代码:

use fast_excel::{ExcelExecutor, ExcelRow, ZipSource};
use serde::Serialize;

#[derive(ExcelRow, ExcelExecutor, Serialize)]
#[excel(sheet = "产品导入", register = "product")]
struct ProductRow {
    #[excel(header = "品名", required)]
    name: String,
    // ...
}

# async fn demo(sink: std::sync::Arc<dyn fast_excel::BatchSink<ProductRow>>) -> Result<(), fast_excel::ExcelError> {
let source = ZipSource::open("products.xlsx")?;

// ① 按类型:编译期类型安全,一个入口覆盖全部
let exec = fast_excel::executor_for::<ProductRow>();
let preview = exec.preview(source.clone(), 200)?;        // 校验预览
let report = exec.commit(source.clone(), sink).await?;   // 分批落库
let bytes = exec.export_bytes(&[])?;                     // 导出到内存(HTTP 下载)
exec.export_xlsx("out.xlsx", /* 游标分页闭包 */ |cursor| async move { todo!() }).await?;

// ② 按注册名:字符串调度(Web 层按请求参数路由到不同模型)
let json = fast_excel::preview_by_name("product", source, 200)?;
println!("已注册执行器:{:?}", fast_excel::registered_names());
# Ok(()) }
  • register = "name" 是全局注册名,必填;模型需实现 Serialize(按名预览返回 JSON);
  • 需要微调默认行为时,用 exec.import_runner() / exec.export_runner() 拿到切好的 runner 再改;
  • 全部能力:preview / preview_json / commit / for_each_row / export_bytes / export_rows / export_sheets / export_xlsx / export_multi_sheet / template。

模型级默认配置:executor_config!

导出中心 / 调度器按名或按类型拿到 runner 时,往往还要重复拼装「合并开关、计算列、批大小」。 用 executor_config! 在链接期登记一次,之后 executor_for::<T>() 的 import_runner() / export_runner()(以及 template() 之外的导出入口)会自动套用:

use fast_excel::{CellValue, ColumnDef, executor_config, funcs};

executor_config! {
    "product",
    // 导入:自动开合并读取、批大小 500
    import = |r: fast_excel::ImportRunner| r.merged(true).batch_size(500),
    // 导出:自动追加「导出日期」计算列
    export = |s: fast_excel::SheetOptions| s.computed(
        ColumnDef::new("导出日期"),
        |_row| CellValue::Text(funcs::date_fmt(funcs::today(), "%Y-%m-%d")),
    ),
}

// 业务侧零重复配置:
let sheet_bytes = fast_excel::executor_for::<ProductRow>().export_bytes(&rows)?;

配置项是普通函数或非捕获闭包(退化为 fn 指针;需要捕获状态时写成具名函数 + static)。

按名调度:预览 / 导入 / 导出 / 模板

注册名的字符串调度走 JSON 边界,因此模型需要同时实现 Serialize 与 Deserialize:

use std::sync::Arc;
use fast_excel::{JsonBatchSink, commit_json_by_name, export_bytes_by_name, ExcelError};

// ① 按名导入:每批模型以 JSON 数组交给 sink
struct MySink;
#[async_trait::async_trait]
impl JsonBatchSink for MySink {
    async fn save(&self, rows: Vec<serde_json::Value>) -> Result<usize, ExcelError> {
        // 业务侧自行落库;rows 是 [{ "name": "...", "qty": 1 }, ...]
        Ok(rows.len())
    }
}
let report = commit_json_by_name("product", source, Arc::new(MySink)).await?.unwrap();

// ② 按名导出:JSON 行数组 → xlsx 字节
let rows = serde_json::json!([{ "name": "螺丝", "qty": 100 }]);
let bytes = export_bytes_by_name("product", &rows)?.unwrap();

// ③ 按名取模板
let erased = fast_excel::executor_by_name("product").unwrap();
let spec = erased.template();

未注册的名字统一返回 Ok(None),方便 Web 层按请求参数路由。

错误与国际化

库内错误统一收敛为 ExcelError,ExcelError::code() 给出 excel_* key; 业务侧实现 From<ExcelError> for AppError 时可按 @excel_xxx:原始信息 拼接, 由全局 i18n 中间件按 Accept-Language / x-locale 翻译,和业务错误走同一条链路。

测试

cargo test -p fast-excel                                                   # 单测 + 往返 + 文档测试
cargo test -p fast-excel --test roundtrip -- --ignored --nocapture         # 100 万行流式压力测试
cargo bench -p fast-excel                                                  # 读写吞吐基准(criterion)

stress_one_million_rows_streaming 会真实写出 100 万行 xlsx 再逐行读回, 验证「边写边落盘 + SAX 逐行读」不随行数增长内存,默认不参与 CI。