fast-excel 1.0.0

通用 Excel 导入导出工具:流式读写(百万级)、动态表头适配、多 sheet、单元格图片、批量落库(纯 Rust,对标 EasyExcel)
Documentation
//! 执行器:注册宏 + 全局注册表 + 通用入口(消费者视角)
//!
//! 本文件模拟"业务端"使用 `#[derive(ExcelExecutor)]`:
//! 不管理任何工厂,注册 + 调度全靠宏与全局表。

use std::path::PathBuf;
use std::sync::{Arc, Mutex};

use fast_excel::{
    ColumnDef, ExcelError, ExcelExecutor, ExcelReader, ExcelRow, Executor, JsonBatchSink, NoopSink,
    SheetSelector, ZipSource, build_template, commit_json_by_name, executor_by_name,
    executor_entry, executor_for, export_bytes_by_name, preview_by_name, registered_executors,
    registered_names,
};
use serde::{Deserialize, Serialize};

#[derive(ExcelRow, ExcelExecutor, Serialize, Deserialize, Debug, Clone, PartialEq)]
#[excel(sheet = "产品", register = "product")]
struct Product {
    #[excel(header = "品名", required)]
    name: String,
    #[excel(header = "数量")]
    qty: Option<i32>,
}

#[derive(ExcelRow, ExcelExecutor, Serialize, Deserialize, Debug, Clone, PartialEq)]
#[excel(sheet = "订单", register = "order")]
struct Order {
    #[excel(header = "订单号", required)]
    no: String,
}

fn temp_path(name: &str) -> PathBuf {
    let mut p = std::env::temp_dir();
    p.push(format!("excel-executor-{}-{name}", std::process::id()));
    p
}

fn products() -> Vec<Product> {
    vec![
        Product { name: "螺丝".into(), qty: Some(100) },
        Product { name: "螺母".into(), qty: None },
    ]
}

#[test]
fn test_register_and_discover() {
    // 注册表自动收集(inventory 链接期),无需任何初始化
    let names = registered_names();
    assert!(names.contains(&"product"), "缺 product:{names:?}");
    assert!(names.contains(&"order"), "缺 order:{names:?}");

    let entry = executor_entry("product").expect("product 应已注册");
    assert_eq!(entry.name, "product");
    assert_eq!(entry.type_name, "Product");

    let all = registered_executors();
    assert_eq!(all.len(), 2, "恰好两个模型注册:{:?}", all);
}

#[test]
fn test_executor_for_uses_model_defaults() {
    let exec = executor_for::<Product>();
    assert_eq!(exec.name(), "product");
    assert_eq!(exec.sheet_name(), Some("产品"));
    assert_eq!(exec.columns().len(), 2);

    // 派生态生成的内置关联函数
    assert_eq!(Product::executor().name(), "product");

    // 手动构造(未注册模型也能用)
    let manual = Executor::<Product>::new("custom", None);
    assert_eq!(manual.name(), "custom");
    assert_eq!(manual.sheet_name(), None);
}

#[test]
fn test_preview_by_type_and_by_name() {
    let path = temp_path("preview.xlsx");
    let exec = executor_for::<Product>();
    exec.export_rows(&path, &products()).unwrap();

    let source = ZipSource::open(&path).unwrap();
    // 类型化预览
    let preview = exec.preview(source.clone(), 10).unwrap();
    assert_eq!(preview.total_rows, 2);
    assert_eq!(preview.error_rows, 0);
    assert_eq!(preview.rows[0].data.as_ref().unwrap().name, "螺丝");

    // 按名预览 → JSON(Web 层用)
    let json = preview_by_name("product", source, 10)
        .unwrap()
        .expect("product 已注册");
    let total = json.get("totalRows").and_then(|v| v.as_u64()).unwrap();
    assert_eq!(total, 2, "JSON 预览行数:{json}");
}

#[tokio::test]
async fn test_commit_via_executor() {
    let path = temp_path("commit.xlsx");
    executor_for::<Product>().export_rows(&path, &products()).unwrap();

    let report = executor_for::<Product>()
        .commit(ZipSource::open(&path).unwrap(), Arc::new(NoopSink))
        .await
        .unwrap();
    assert_eq!(report.success_rows, 2, "{report:?}");
    assert_eq!(report.error_rows, 0);
}

#[test]
fn test_export_and_template_via_executor() {
    // 导出到内存 → 读回
    let bytes = executor_for::<Product>().export_bytes(&products()).unwrap();
    let reader = ExcelReader::from_bytes(bytes).unwrap();
    let mut stream = reader
        .stream(
            SheetSelector::First,
            &Product::columns(),
            fast_excel::ReadOptions::new(),
        )
        .unwrap();
    let mut count = 0;
    while let Some(row) = stream.next_row().unwrap() {
        Product::from_row(&row).unwrap();
        count += 1;
    }
    assert_eq!(count, 2);

    // 模板
    let spec = executor_for::<Product>().template();
    assert_eq!(spec.sheet_name, "产品");
    let template_bytes = build_template(&spec).unwrap();
    assert!(!template_bytes.is_empty());
}

#[test]
fn test_erased_executor_by_name() {
    let path = temp_path("erased.xlsx");
    executor_for::<Product>().export_rows(&path, &products()).unwrap();

    let erased = executor_by_name("product").expect("product 已注册");
    assert_eq!(erased.name(), "product");
    assert!(erased.type_name().contains("Product"));

    // 手动构造路径(未注册模型也能用)
    let manual = Executor::<Product>::new("x", None);
    assert_eq!(manual.name(), "x");
    assert_eq!(manual.columns().len(), 2);
}

#[test]
fn test_missing_name_returns_none() {
    assert!(executor_entry("not-exists").is_none());
    assert!(executor_by_name("not-exists").is_none());
}

// ── 模型级默认配置(executor_config!) ──

fast_excel::executor_config! {
    "product",
    import = |r: fast_excel::ImportRunner| r.merged(true).batch_size(77),
    export = |s: fast_excel::SheetOptions| s.computed(
        fast_excel::ColumnDef::new("标签"),
        |row| fast_excel::CellValue::Text(format!("{}#{}", row.text("品名"), row.text("数量"))),
    ),
}

#[test]
fn test_executor_config_applies_model_defaults() {
    let runner = executor_for::<Product>().import_runner();
    assert!(runner.read.read_merges, "应套用 merged(true)");
    assert_eq!(runner.batch.batch_size, 77);

    // 未登记的模型不受影响
    let order = executor_for::<Order>().import_runner();
    assert!(!order.read.read_merges);
    assert_eq!(order.batch.batch_size, 500);
}

#[test]
fn test_executor_config_applies_export_column() {
    let exec = executor_for::<Product>();
    let bytes = exec.export_bytes(&products()).unwrap();
    let reader = fast_excel::ExcelReader::from_bytes(bytes).unwrap();
    let mut defs = Product::columns();
    defs.push(ColumnDef::new("标签"));
    let mut stream = reader
        .stream(SheetSelector::First, &defs, fast_excel::ReadOptions::new())
        .unwrap();
    let row = stream.next_row().unwrap().unwrap();
    assert_eq!(row.text_of("标签"), "螺丝#100", "导出的计算列应由模型级配置自动加上");
}

// ── 按名调度:导入 / 导出(JSON 边界) ──

/// 收集 JSON 批次的 sink
struct CollectSink(Arc<Mutex<Vec<serde_json::Value>>>);

#[async_trait::async_trait]
impl JsonBatchSink for CollectSink {
    async fn save(&self, rows: Vec<serde_json::Value>) -> std::result::Result<usize, ExcelError> {
        let n = rows.len();
        self.0.lock().unwrap().extend(rows);
        Ok(n)
    }
}

#[tokio::test]
async fn test_commit_and_export_by_name() {
    let path = temp_path("by-name.xlsx");
    executor_for::<Product>()
        .export_rows(&path, &products())
        .unwrap();

    // 按名导入 → JSON 批次
    let collected = Arc::new(Mutex::new(Vec::new()));
    let sink: Arc<dyn JsonBatchSink> = Arc::new(CollectSink(collected.clone()));
    let report = commit_json_by_name("product", ZipSource::open(&path).unwrap(), sink)
        .await
        .unwrap()
        .expect("product 已注册");
    assert_eq!(report.success_rows, 2, "{report:?}");
    assert_eq!(collected.lock().unwrap().len(), 2);

    // 按名导出(JSON 行数组 → xlsx)
    let rows = serde_json::json!([{ "name": "螺丝", "qty": 100 }]);
    let bytes = export_bytes_by_name("product", &rows)
        .unwrap()
        .expect("product 已注册");
    assert!(!bytes.is_empty());

    // 未注册返回 None
    let none = commit_json_by_name(
        "not-exists",
        ZipSource::open(&path).unwrap(),
        Arc::new(CollectSink(Arc::new(Mutex::new(Vec::new())))),
    )
    .await
    .unwrap();
    assert!(none.is_none());
    assert!(export_bytes_by_name("not-exists", &rows).unwrap().is_none());

    let _ = std::fs::remove_file(&path);
}