Skip to main content

Crate fast_excel

Crate fast_excel 

Source
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::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§

ExcelExecutor
#[derive(ExcelExecutor)] 派生宏:注册执行器工厂(与 ExcelExecutor trait 同名) #[derive(ExcelExecutor)]:把行模型注册成「执行器工厂」
ExcelRow
#[derive(ExcelRow)] 派生宏(与 ExcelRow trait 同名,不同命名空间)