fast-excel 1.0.0

通用 Excel 导入导出工具:流式读写(百万级)、动态表头适配、多 sheet、单元格图片、批量落库(纯 Rust,对标 EasyExcel)
Documentation
//! # 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`](https://docs.rs/inventory) 静态收集,零初始化):[`executor_for::<T>`] / [`executor_by_name`] |
//! | 导入模板 | 必填红字表头 + 示例行 + 下拉 + 说明 sheet([`TemplateSpec`]) |
//! | 导出 | 游标分批拉取 + 流式写文件([`ExportRunner`]);CSV 兜底([`write::write_csv`]) |
//!
//! 完整用法与百万行调优见 crate 根目录 `README.md`。
//!
//! ## 最小示例(声明式)
//!
//! ```no_run
//! 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>,
//! }
//!
//! # async fn demo(db_sink: Arc<dyn BatchSink<ProductRow>>) -> Result<(), ExcelError> {
//! 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);
//! # Ok(()) }
//! ```
//!
//! ## 落库实现约定
//!
//! [`BatchSink::save`] 拿到的是一批已解析、已校验的行,事务边界由业务侧决定
//! (推荐"一批一个事务 + `insert_many`")。项目内 sea-orm 实体用
//! `Entity::insert_many_with_fill(models, &tx)` 即可同时拿到主键生成、审计字段
//! 自动填充与租户注入。

// 让派生宏在 crate 内部(单元测试 / 文档测试)也能用 `::fast_excel::` 路径
extern crate self as fast_excel;

pub mod column;
pub mod error;
pub mod executor;
pub mod export;
pub mod expr;
pub mod funcs;
pub mod header;
pub mod import;
pub mod model;
pub mod read;
pub mod task;
pub mod value;
pub mod write;

pub use column::{ColumnDef, ColumnKind};
pub use error::{ExcelError, Result};
pub use expr::{CellExpr, RowValues};
pub use executor::{
    ErasedExecutor, ExcelExecutor, Executor, ExecutorConfigEntry, ExecutorEntry, JsonBatchSink,
    commit_json_by_name, executor_by_name, executor_config_entry, executor_entry, executor_for,
    export_bytes_by_name, identity_import_runner, identity_sheet_options, preview_by_name,
    registered_executors, registered_names,
};
pub use export::{ExportRunner, ExportStats, Page};
pub use header::{
    HeaderAnalysis, HeaderMap, HeaderOptions, MatchKind, ResolvedColumn, excel_column_name,
    resolve_headers, simple_columns,
};
pub use import::{
    BatchConfig, BatchSink, FnSink, ImportPreview, ImportProgress, ImportReport, ImportRunner,
    NoopSink, PreviewRow, ProgressFn, RowError, SheetHeader,
};
pub use model::{ColumnError, DynamicRow, ExcelRow, RowData, RowImage};
pub use read::{
    CfRule, CellImage, CellStyle, Comment, ComputedColumn, ConditionalFormat, CsvReader,
    DataValidation, EntryReader, ExcelReader, Hyperlink, MergeRange, ReadOptions, RowFilter,
    SheetInfo, SheetSelector, SheetStream, Styles, ZipSource, extract_all_images,
    extract_embedded_images, extract_images_of_sheet, extract_wps_cellimages, parse_dispimg_id,
};
pub use task::{
    ExportTaskContext, ExportTaskEntry, ExportTaskFn, ExportTaskFuture, ExportTaskKind,
    ExportTaskOutput, XLSX_MIME, export_task_entry, export_task_registered, registered_export_tasks,
    run_export_task, run_file_task, run_rows_task,
};
pub use value::{Cell, CellValue, FromCell, IntoCell};
pub use write::{
    DynamicExportRunner, DynamicSheet, ExcelWriter, ReferenceSheet, SheetOptions, SheetWriter,
    TemplateSpec, WriteOptions, align_row, build_template, named_xlsx_bytes,
    positional_xlsx_bytes, write_csv, write_named_xlsx, write_positional_xlsx,
};

/// `#[derive(ExcelRow)]` 派生宏(与 [`ExcelRow`] trait 同名,不同命名空间)
pub use fast_excel_macros::ExcelRow;

/// `#[derive(ExcelExecutor)]` 派生宏:注册执行器工厂(与 [`ExcelExecutor`] trait 同名)
pub use fast_excel_macros::ExcelExecutor;

/// 派生宏生成的 `inventory::submit!` 通过此路径引用;通常无需直接使用
#[doc(hidden)]
pub use ::inventory;

/// 为某个执行器(按注册名)登记**模型级默认配置**,让按名/按类型拿到的 runner 自动带上
/// 计算列、合并开关、批大小等,不用在每个调用点重复拼装。
///
/// 配置项是普通函数 / 非捕获闭包(`fn` 指针),链接期注册:
///
/// ```ignore
/// use fast_excel::executor_config;
///
/// // 只配导入
/// executor_config!("product",
///     import = |r: fast_excel::ImportRunner| r.merged(true).batch_size(500));
///
/// // 同时配导入 + 导出
/// executor_config!("product",
///     import = |r: fast_excel::ImportRunner| r.merged(true),
///     export = |s: fast_excel::SheetOptions| s.computed(
///         fast_excel::ColumnDef::new("导出日期"),
///         |_row| fast_excel::CellValue::Text(fast_excel::funcs::date_fmt(
///             fast_excel::funcs::today(), "%Y-%m-%d")),
///     ));
/// ```
#[macro_export]
macro_rules! executor_config {
    ($name:expr, import = $imp:expr, export = $exp:expr $(,)?) => {
        $crate::__executor_config_submit!($name, $imp, $exp);
    };
    ($name:expr, export = $exp:expr, import = $imp:expr $(,)?) => {
        $crate::__executor_config_submit!($name, $imp, $exp);
    };
    ($name:expr, import = $imp:expr $(,)?) => {
        $crate::__executor_config_submit!($name, $imp, $crate::identity_sheet_options);
    };
    ($name:expr, export = $exp:expr $(,)?) => {
        $crate::__executor_config_submit!($name, $crate::identity_import_runner, $exp);
    };
}

/// `executor_config!` 的内部展开;请勿直接使用
#[doc(hidden)]
#[macro_export]
macro_rules! __executor_config_submit {
    ($name:expr, $imp:expr, $exp:expr) => {
        #[allow(non_upper_case_globals, unused)]
        const _: () = {
            $crate::inventory::submit! {
                $crate::ExecutorConfigEntry {
                    name: $name,
                    import: $imp,
                    export: $exp,
                }
            }
        };
    };
}
/// 注册一个异步导出任务(唯一宏:行导出 / 文件导出都用它)。
///
/// 展开后直接向 `inventory` 提交任务定义,链接期即完成注册:
/// **没有执行器结构体、没有 `install()`、不需要在 `main.rs` 聚合**。
/// 导出中心按 `task_type` 查到函数后直接调用。
///
/// # 形态一:行数据导出(业务只查数据,引擎写 xlsx)
/// ```ignore
/// fast_excel::export_task! {
///     task_type = "factory",
///     sheet_name = "工厂数据",
///     headers = FACTORY_HEADERS,
///     rows = factory_export_rows, // async fn(ExportTaskContext) -> Result<Vec<Vec<String>>, E>
/// }
/// ```
///
/// # 形态二:文件导出(业务自带流式生成,如带图 xlsx)
/// ```ignore
/// fast_excel::export_task! {
///     task_type = "product",
///     mime = fast_excel::XLSX_MIME,
///     file = product_export_file, // async fn(ExportTaskContext) -> Result<(i64, String), E>
/// }
/// ```
///
/// `rows` / `file` 也接受非捕获闭包(如 `|ctx| rows_for(kind, ctx)`),
/// 方便一个模块用同一份逻辑注册多张表。
#[macro_export]
macro_rules! export_task {
    (
        task_type = $task:expr,
        sheet_name = $sheet:expr,
        headers = $headers:expr,
        rows = $rows:expr
        $(,)?
    ) => {
        const _: () = {
            fn __excel_export_task(
                ctx: $crate::ExportTaskContext,
            ) -> $crate::ExportTaskFuture {
                ::std::boxed::Box::pin($crate::run_rows_task(
                    ctx,
                    $task,
                    $sheet,
                    $headers,
                    $rows,
                ))
            }

            $crate::inventory::submit! {
                $crate::ExportTaskEntry {
                    task_type: $task,
                    kind: $crate::ExportTaskKind::Rows {
                        sheet_name: $sheet,
                        headers: $headers,
                    },
                    run: __excel_export_task,
                }
            }
        };
    };
    (
        task_type = $task:expr,
        mime = $mime:expr,
        file = $file:expr
        $(,)?
    ) => {
        const _: () = {
            fn __excel_export_task(
                ctx: $crate::ExportTaskContext,
            ) -> $crate::ExportTaskFuture {
                ::std::boxed::Box::pin($crate::run_file_task(ctx, $mime, $file))
            }

            $crate::inventory::submit! {
                $crate::ExportTaskEntry {
                    task_type: $task,
                    kind: $crate::ExportTaskKind::File { mime: $mime },
                    run: __excel_export_task,
                }
            }
        };
    };
}