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 ;
字段属性:header / alias / required / kind / width / format / text /
image / default / note / dropdown / ignore / dynamic。
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的内嵌图片不支持常量内存模式); -
行高在写单元格之前设置,图片按行高自适应缩放。
合并单元格
xlsx 的合并区域只有左上角单元格有值,其余为空。要按业务语义读回,需要开启合并读取
(<mergeCells> 在 <sheetData> 之后,无法边读边取,因此要额外扫一遍工作表 XML,
默认关闭以保证百万行吞吐):
use ;
let reader = open?;
// ① 开启后:左上角的值会回填到整个合并区域,`RowData::merged_at(col)` 可判断某格是否被合并
let mut stream = reader.stream?;
while let Some = stream.next_row?
// ② 整体区域查询(不回填)
let ranges = reader.merge_ranges?;
// MergeRange { first_row, last_row, first_col, last_col },行 1 基、列 0 基
// ③ 导入执行器上等价开关(含合并表头 / 合并内容)
let report = new
.merged
.
.await?;
# Ok::
写出:
use ;
// 大标题 / 多级表头:任意矩形合并(header 样式)
ws.merge_header?; // A1:C1
// 内容行内横向合并(如合计 / 备注),其余列照常写
ws.write_row_with_merges?;
注意事项:
- 写出合并都会推进行游标,不能回退到已写行(常量内存模式的限制);
- 纵向合并(跨行)会由
rust_xlsxwriter以 write-ahead 方式写出,常量内存模式下可用;但 「纵向合并 + 相邻列同时有数据」这种交叉布局在常量内存下无法按行顺序构造,请用WriteOptions::new().in_memory()关闭常量内存,并通过SheetWriter::worksheet()逃生口写; - 合并读取默认关闭;只在确实需要时用
.with_merges()/ImportRunner::merged(true)打开。
表头从第几行开始
导入时表头不一定在第 1 行(上面常有大标题 / 说明行)。用 header_row(0 基)指定,
header_span 支持多行表头(纵向拼接,如 报价(USD) 分两行写):
let runner = new
.header_row // 第 2 行是表头(0 基)
.header_span // 表头占 2 行
.merged; // 配合合并读取,横向合并的表头值会覆盖到每一列
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 ;
let sheet = new
.columns
// 列改写:把「品名」转大写(按表头匹配)
.transform
// 计算列:追加一列「小计」= 单价 × 数量
.computed
.computed;
let mut writer = new;
let mut ws = writer.add_sheet?;
ws.write_headers?; // 表头 = 基础列 + 计算列
ws.write_models?; // 每行自动应用表达式
ws.finish?;
let bytes = writer.save_to_buffer?; // HTTP 直接下载
# Ok::
表达式入参是 [
RowValues]:按表头row.get("列名")/row.text("列名"),或按下标row.at(i)取值。 先从基础列改写(transform),再追加计算列(computed);计算列也能读到前面算出的列。
2)导入:计算列(文件里没有该列也能算出来)
use ;
// 文件里只有「姓」「名」两列,模型里声明了「全名」
let report = new
.computed
.
.await?;
模型只要按同一个表头声明字段即可取到(def.header 必须与模型表头一致):
3)导入模板:默认值 / 示例行表达式
use ;
let spec = new
// 示例行用表达式生成
.sample_expr
// 某列默认值用表达式(示例行里该列为空时填充,每次生成模板重新求值)
.default_expr;
let bytes = build_template?; // 下载给用户填写
# Ok::
行过滤 / CSV 导入 / 读取样式
行过滤:跳过节尾"合计 / 备注"行
use ImportRunner;
let report = new
.row_filter // 返回 false 的行被跳过
.
.await?;
# Ok::
row_filter 也能直接在 [ReadOptions] 上用(ReadOptions::row_filter)。
CSV 导入
CSV 与 xlsx 共用同一套列定义(表头 / 别名 / 必填 / default)、导入计算列、行过滤与模型映射:
use ;
let mut reader = open?; // 或 CsvReader::from_bytes(bytes)
let options = new
.computed
.row_filter;
let report = reader.?;
println!;
# Ok::
支持引号与 "" 转义、跨行引号字段、CRLF / LF、UTF-8 BOM。
(CSV 没有合并单元格 / 内嵌图片 / 样式,这几项在 CSV 链路上为空。)
读取样式(底色 / 字体颜色 / 加粗 / 斜体)
use ;
let reader = open?;
let mut stream = reader.stream?;
while let Some = stream.next_row?
# Ok::
也可以直接查样式表:reader.styles().cell_style(cell.style)(CellStyle { bold, italic, font_color, background },颜色为 0xRRGGBB)。
读取超链接 / 批注 / 数据验证(下拉)
use ;
let reader = open?;
// 整表查询
for link in reader.hyperlinks?
for c in reader.comments?
for v in reader.validations?
for cf in reader.conditional_formats?
// 或随行流式取用(也可在 ImportRunner 的 RowData 上取,便于 from_row / sink 使用)
let mut stream = reader.stream?;
while let Some = stream.next_row?
# Ok::
说明:超链接会解析工作表 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 ;
let mut ws = writer.add_sheet?;
ws.write_text_row?;
ws.write_row_with_links?;
(写批注 rust_xlsxwriter 0.99 未提供公开 API,需要时用 SheetWriter::worksheet() 逃生口。)
无实体(动态表头)导入导出
没有(也不想定义)实体时,表头与字段完全由前端给,框架负责对齐:
导出:表头 + 具名数据,按表头名自动对应数据列
use ;
// 前端传来:表头顺序 + 每行「字段名 → 值」(顺序随便,缺列留空、多余忽略)
let sheet = new.headers;
let rows = vec!;
let bytes = named_xlsx_bytes?; // 或 write_named_xlsx("out.xlsx", &sheet, &rows)
# Ok::
- 想控制列类型 / 格式 / 宽度:
.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 ;
let reader = open?;
let = reader.read_dynamic?;
println!;
for row in &rows
# Ok::
需要类型化时用
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?;
// 大数据量:每个 sheet 独立游标分页,顺序写出(单表仍是常量内存)
runner.export_multi_sheet.await?;
导入模板
use ;
let bytes = build_template?;
生成的工作簿包含:数据 sheet(必填列红字表头 + 示例行 + 下拉验证)、 「填写说明」sheet、若干引用 sheet。
模板还支持(详见下方「列值表达式」与「行过滤 / CSV 导入 / 读取样式」):
.header_group("基本信息", 3):顶层合并表头,生成多级表头模板;.sample_expr(...)/.default_expr("列", ...):用表达式生成示例行 / 列默认值;- 列属性
#[excel(default = "...")]:示例行与导入空值都会兜底填该默认值。
动态表头适配
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。
模型级默认配置:executor_config!
导出中心 / 调度器按名或按类型拿到 runner 时,往往还要重复拼装「合并开关、计算列、批大小」。
用 executor_config! 在链接期登记一次,之后 executor_for::<T>() 的
import_runner() / export_runner()(以及 template() 之外的导出入口)会自动套用:
use ;
executor_config!
// 业务侧零重复配置:
let sheet_bytes = .export_bytes?;
配置项是普通函数或非捕获闭包(退化为 fn 指针;需要捕获状态时写成具名函数 + static)。
按名调度:预览 / 导入 / 导出 / 模板
注册名的字符串调度走 JSON 边界,因此模型需要同时实现 Serialize 与 Deserialize:
use Arc;
use ;
// ① 按名导入:每批模型以 JSON 数组交给 sink
;
let report = commit_json_by_name.await?.unwrap;
// ② 按名导出:JSON 行数组 → xlsx 字节
let rows = json!;
let bytes = export_bytes_by_name?.unwrap;
// ③ 按名取模板
let erased = executor_by_name.unwrap;
let spec = erased.template;
未注册的名字统一返回 Ok(None),方便 Web 层按请求参数路由。
错误与国际化
库内错误统一收敛为 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。