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 |
| 导入模板 | 模板导出 | TemplateSpec / build_template:必填红字 + 示例行 + 下拉 + 说明 sheet |
| 导入预览 | 校验后再入库 | ImportRunner::preview(只读前 N 行,返回列匹配与行级错误) |
| 执行器注册 | 注册后全链路复用 | #[derive(ExcelExecutor)] + 全局注册表:预览 / 导入 / 导出 / 模板一条龙(按类型或按名字符串) |
| 纯文本兜底 | — | write_csv(UTF-8 BOM,Excel 双击不乱码) |
快速开始
1)声明行模型
use ;
字段属性:header / alias / required / kind / width / format / text /
image / default / note / dropdown / ignore。
2)导入:预览 → 分批落库
use Arc;
use ;
// 每批一个事务,业务侧自己决定事务边界
# async
3)导出:游标分页 + 流式写
use ;
# async
图片支持
导入:图片直接插在单元格里即可(不需要「文件名 + 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 ;
let sheet = new
.columns
.write_options;
// 行值里放 CellValue::Image(CellImage::new(bytes, "png").named("main.png"))
-
默认写标准锚点图片(
insert_image_fit_to_cell_centered),常量内存模式下可用; -
WriteOptions::cell_image()会写 Excel「置于单元格内」图片(随筛选/排序移动); 该方法自动关闭常量内存(rust_xlsxwriter的内嵌图片不支持常量内存模式); -
行高在写单元格之前设置,图片按行高自适应缩放。
百万级要点
| 环节 | 做法 | 内存 |
|---|---|---|
| 读取 | 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?;
// 大数据量:每个 sheet 独立游标分页,顺序写出(单表仍是常量内存)
runner.export_multi_sheet.await?;
导入模板
use ;
let bytes = build_template?;
生成的工作簿包含:数据 sheet(必填列红字表头 + 示例行 + 下拉验证)、 「填写说明」sheet、若干引用 sheet。
动态表头适配
HeaderOptions 的匹配顺序(可在 ImportRunner / ReadOptions 上调整):
- 精确:归一化后一致(去空白、全角转半角、去
*必填标记); - 别名:命中
ColumnDef::aliases; - 模糊:互相包含,取差异最小(如
报价(USD)(含税)命中报价(USD)); - 列序回退:显式开启后,表头缺失时按声明顺序落到第 N 列。
analyze_header / analyze_all_headers 可只做预检,把「匹配到哪些列、缺哪些必填列、
多出哪些列」返回给前端确认。
执行器(推荐):注册一次,全链路通用
不想每次手拼 ImportRunner / ExportRunner 的,给行模型挂一个派生宏即可。
宏自动创建执行器工厂并静态注册进全局表(inventory 链接期收集,零初始化),
业务端既不用管理工厂,也不用写任何注册代码:
use ;
use Serialize;
# async
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。
错误与国际化
库内错误统一收敛为 ExcelError,ExcelError::code() 给出 excel_* key;
业务侧实现 From<ExcelError> for AppError 时可按 @excel_xxx:原始信息 拼接,
由全局 i18n 中间件按 Accept-Language / x-locale 翻译,和业务错误走同一条链路。
测试
stress_one_million_rows_streaming 会真实写出 100 万行 xlsx 再逐行读回,
验证「边写边落盘 + SAX 逐行读」不随行数增长内存,默认不参与 CI。