Expand description
§excel — 通用 Excel 导入导出工具
对标 Java 生态的 EasyExcel,面向“百万行 + 批量落库 + 单元格图片 + 多 sheet + 动态表头“的真实业务场景。整个工具只依赖纯 Rust 库(无 JVM / 无 Office 组件)。
§能力总览
| 能力 | 实现方式 |
|---|---|
| 百万行读取 | quick-xml SAX 事件流逐行解析,内存与行数无关(SheetStream) |
| 百万行写出 | rust_xlsxwriter 常量内存工作表,边写边落临时文件 |
| 批量落库 | ImportRunner::commit:spawn_blocking 解析 + 有界通道 + 分批事务(BatchSink) |
| 单元格图片 | 标准 drawing 锚点 + WPS DISPIMG;按行对应,图片字节按需读 |
| 多 sheet | 读:SheetSelector::{Name,Names,All};写:ExcelWriter::add_sheet / ExportRunner::export_multi_sheet |
| 动态表头 | 别名 / 模糊匹配 / 归一化(全角、空格、* 必填标记)/ 列序回退(HeaderOptions) |
| 注解式映射 | #[derive(ExcelRow)](excel-macros) |
| 执行器 | #[derive(ExcelExecutor)] 自动注册执行器工厂(inventory 静态收集,零初始化):executor_for::<T> / executor_by_name |
| 导入模板 | 必填红字表头 + 示例行 + 下拉 + 说明 sheet(TemplateSpec) |
| 导出 | 游标分批拉取 + 流式写文件(ExportRunner);CSV 兜底(write::write_csv) |
完整用法与百万行调优见 crate 根目录 README.md。
§最小示例(声明式)
use std::sync::Arc;
use fast_excel::{BatchSink, ExcelError, ExcelReader, ExcelRow, ImportRunner, SheetSelector, ZipSource};
#[derive(ExcelRow, Debug)]
#[excel(sheet = "产品导入")]
struct ProductRow {
#[excel(header = "工厂名称", alias = ["工厂", "厂名"], required)]
factory_name: String,
#[excel(header = "品名", required)]
name: String,
#[excel(header = "MOQ")]
moq: Option<i32>,
}
let report = ImportRunner::new()
.sheets(SheetSelector::All) // 多 sheet 合并导入
.batch_size(500) // 每 500 行一批
.commit(ZipSource::open("products.xlsx")?, db_sink)
.await?;
println!("成功 {} 行,失败 {} 行", report.success_rows, report.error_rows);§落库实现约定
BatchSink::save 拿到的是一批已解析、已校验的行,事务边界由业务侧决定
(推荐“一批一个事务 + insert_many“)。项目内 sea-orm 实体用
Entity::insert_many_with_fill(models, &tx) 即可同时拿到主键生成、审计字段
自动填充与租户注入。
Re-exports§
pub use column::ColumnDef;pub use column::ColumnKind;pub use error::ExcelError;pub use error::Result;pub use expr::CellExpr;pub use expr::RowValues;pub use executor::ErasedExecutor;pub use executor::ExcelExecutor;pub use executor::Executor;pub use executor::ExecutorConfigEntry;pub use executor::ExecutorEntry;pub use executor::JsonBatchSink;pub use executor::commit_json_by_name;pub use executor::executor_by_name;pub use executor::executor_config_entry;pub use executor::executor_entry;pub use executor::executor_for;pub use executor::export_bytes_by_name;pub use executor::identity_import_runner;pub use executor::identity_sheet_options;pub use executor::preview_by_name;pub use executor::registered_executors;pub use executor::registered_names;pub use export::ExportRunner;pub use export::ExportStats;pub use export::Page;pub use header::HeaderAnalysis;pub use header::HeaderMap;pub use header::HeaderOptions;pub use header::MatchKind;pub use header::ResolvedColumn;pub use header::excel_column_name;pub use header::resolve_headers;pub use header::simple_columns;pub use import::BatchConfig;pub use import::BatchSink;pub use import::FnSink;pub use import::ImportPreview;pub use import::ImportProgress;pub use import::ImportReport;pub use import::ImportRunner;pub use import::NoopSink;pub use import::PreviewRow;pub use import::ProgressFn;pub use import::RowError;pub use import::SheetHeader;pub use model::ColumnError;pub use model::DynamicRow;pub use model::ExcelRow;pub use model::RowData;pub use model::RowImage;pub use read::CfRule;pub use read::CellImage;pub use read::CellStyle;pub use read::Comment;pub use read::ComputedColumn;pub use read::ConditionalFormat;pub use read::CsvReader;pub use read::DataValidation;pub use read::EntryReader;pub use read::ExcelReader;pub use read::Hyperlink;pub use read::MergeRange;pub use read::ReadOptions;pub use read::RowFilter;pub use read::SheetInfo;pub use read::SheetSelector;pub use read::SheetStream;pub use read::Styles;pub use read::ZipSource;pub use read::extract_all_images;pub use read::extract_embedded_images;pub use read::extract_images_of_sheet;pub use read::extract_wps_cellimages;pub use read::parse_dispimg_id;pub use task::ExportTaskContext;pub use task::ExportTaskEntry;pub use task::ExportTaskFn;pub use task::ExportTaskFuture;pub use task::ExportTaskKind;pub use task::ExportTaskOutput;pub use task::XLSX_MIME;pub use task::export_task_entry;pub use task::export_task_registered;pub use task::registered_export_tasks;pub use task::run_export_task;pub use task::run_file_task;pub use task::run_rows_task;pub use value::Cell;pub use value::CellValue;pub use value::FromCell;pub use value::IntoCell;pub use write::DynamicExportRunner;pub use write::DynamicSheet;pub use write::ExcelWriter;pub use write::ReferenceSheet;pub use write::SheetOptions;pub use write::SheetWriter;pub use write::TemplateSpec;pub use write::WriteOptions;pub use write::align_row;pub use write::build_template;pub use write::named_xlsx_bytes;pub use write::positional_xlsx_bytes;pub use write::write_csv;pub use write::write_named_xlsx;pub use write::write_positional_xlsx;
Modules§
- column
- 列定义:一个业务字段 = 一列(对标 EasyExcel 的
@ExcelProperty) - error
- 工具内部统一错误类型
- executor
- 执行器:注册一次,全链路通用(预览 / 导入 / 导出 / 模板)
- export
- 导出侧:游标分批拉取 + 流式写出(百万行不进内存)
- expr
- 列值表达式:导出计算列的闭包入参
RowValues与类型别名CellExpr - funcs
- 内置函数方法:在列值表达式(闭包)里直接调用
- header
- 动态表头适配
- import
- 导入侧:解析 → 校验 → 分批落库(可选并发)
- model
- 行模型与声明式映射
- read
- 读侧:流式 xlsx 读取(动态表头 / 多 sheet / 单元格图片)
- task
- 异步导出任务:注册即函数,不再需要「执行器」概念。
- value
- 单元格值模型 + 类型转换(读时
from_cell解析、写时into_cell生成) - write
- 写侧:流式导出(多 sheet / 单元格图片 / 模板生成)
Macros§
- executor_
config - 为某个执行器(按注册名)登记模型级默认配置,让按名/按类型拿到的 runner 自动带上 计算列、合并开关、批大小等,不用在每个调用点重复拼装。
- export_
task - 注册一个异步导出任务(唯一宏:行导出 / 文件导出都用它)。
Derive Macros§
- Excel
Executor #[derive(ExcelExecutor)]派生宏:注册执行器工厂(与ExcelExecutortrait 同名)#[derive(ExcelExecutor)]:把行模型注册成「执行器工厂」- Excel
Row #[derive(ExcelRow)]派生宏(与ExcelRowtrait 同名,不同命名空间)