fast-excel 1.0.0

通用 Excel 导入导出工具:流式读写(百万级)、动态表头适配、多 sheet、单元格图片、批量落库(纯 Rust,对标 EasyExcel)
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
//! 执行器:注册一次,全链路通用(预览 / 导入 / 导出 / 模板)
//!
//! 业务端只需在行模型上挂 `#[derive(ExcelExecutor)]`(配合 `#[excel(register = "...")]`),
//! 本模块会自动生成该模型的执行器工厂并**静态注册进全局表**(`inventory` 链接期收集,
//! 无需任何启动初始化代码),随后按类型或按注册名统一调用:
//!
//! ```no_run
//! use serde::{Deserialize, Serialize};
//! use fast_excel::{ExcelExecutor, ExcelRow, ZipSource};
//!
//! #[derive(ExcelRow, ExcelExecutor, Serialize, Deserialize)]
//! #[excel(sheet = "产品导入", register = "product")]
//! struct ProductRow {
//!     #[excel(header = "品名", required)]
//!     name: String,
//! }
//!
//! # async fn demo(sink: std::sync::Arc<dyn fast_excel::BatchSink<ProductRow>>) -> Result<(), fast_excel::ExcelError> {
//! let source = ZipSource::open("products.xlsx")?;
//!
//! // ① 按类型调用(编译期保证类型安全)
//! let exec = fast_excel::executor_for::<ProductRow>();
//! let preview = exec.preview(source.clone(), 200)?;
//! let report = exec.commit(source.clone(), sink).await?;
//! let bytes = exec.export_bytes(&products())?;
//!
//! // ② 按注册名字符串调度(Web 层按请求参数路由)
//! let erased = fast_excel::executor_by_name("product").expect("已注册");
//! let json = erased.preview(source, 200)?;
//! # Ok(()) }
//! # fn products() -> Vec<ProductRow> { vec![] }
//! ```

use std::any::type_name;
use std::fmt;
use std::future::Future;
use std::marker::PhantomData;
use std::path::Path;
use std::sync::Arc;

use serde::Serialize;

use crate::column::ColumnDef;
use crate::error::{ExcelError, Result};
use crate::export::{ExportRunner, ExportStats, Page};
use crate::import::{BatchSink, ImportPreview, ImportReport, ImportRunner};
use crate::model::{ExcelRow, RowData};
use crate::read::{SheetSelector, ZipSource};
use crate::write::{SheetOptions, TemplateSpec};

/// 行模型注册契约:`#[derive(ExcelExecutor)]` 生成实现
///
/// 通常不手写;实现该 trait 后即可用 [`executor_for::<T>`] 拿到通用执行器。
pub trait ExcelExecutor: ExcelRow {
    /// 全局注册名(`#[excel(register = "...")]` 指定)
    const EXECUTOR_NAME: &'static str;
}

/// 按类型获取注册模型的通用执行器(自动创建,业务端无需管理工厂)
pub fn executor_for<T: ExcelExecutor>() -> Executor<T> {
    Executor::new(T::EXECUTOR_NAME, T::sheet_name())
}

/// 一个行模型的通用执行器:预览 / 导入 / 导出 / 模板的统一入口
///
/// 所有方法都基于模型自带的列定义与表名自动构造 runner,
/// 需要微调时再通过 [`Executor::import_runner`] / [`Executor::export_runner`] 拿到
/// 可配置的 runner(默认值已经可用,一般不需要)。
#[derive(Clone)]
pub struct Executor<T> {
    /// 注册名(仅用于标识 / 按名调度)
    name: &'static str,
    /// 默认工作表名(来自 `#[excel(sheet = "...")]` 或 `ExcelRow::sheet_name`)
    sheet: Option<&'static str>,
    columns: Vec<ColumnDef>,
    _marker: PhantomData<fn() -> T>,
}

impl<T: ExcelRow> Executor<T> {
    /// 手动构造(未注册模型也能用;注册模型请用 [`executor_for`])
    pub fn new(name: &'static str, sheet: Option<&'static str>) -> Self {
        Self {
            name,
            sheet,
            columns: T::columns(),
            _marker: PhantomData,
        }
    }

    pub fn name(&self) -> &'static str {
        self.name
    }

    pub fn type_name(&self) -> &'static str {
        type_name::<T>()
    }

    pub fn sheet_name(&self) -> Option<&'static str> {
        self.sheet
    }

    pub fn columns(&self) -> &[ColumnDef] {
        &self.columns
    }

    /// 模型名不足时的兜底工作表名
    fn default_sheet(&self) -> String {
        self.sheet.unwrap_or("Sheet1").to_string()
    }

    /// 导入 runner(默认 sheets:单模型 = 按 `sheet` 名,多模型 = `All`)
    ///
    /// 会自动套用 `executor_config!` 注册的模型级配置(合并 / 计算列 / 批大小…)。
    pub fn import_runner(&self) -> ImportRunner {
        let sheets = match self.sheet {
            Some(name) => SheetSelector::Name(name.to_string()),
            None => SheetSelector::All,
        };
        apply_import_config(self.name, ImportRunner::new().sheets(sheets))
    }

    /// 导出 runner(列宽 / 格式 / 图片行高来自列定义;并套用模型级导出配置)
    pub fn export_runner(&self) -> ExportRunner {
        ExportRunner::new(apply_export_config(
            self.name,
            SheetOptions::new(self.default_sheet()).columns(self.columns.clone()),
        ))
    }

    /// 导出 runner(显式指定工作表名)
    pub fn export_runner_for(&self, sheet_name: impl Into<String>) -> ExportRunner {
        ExportRunner::new(apply_export_config(
            self.name,
            SheetOptions::new(sheet_name).columns(self.columns.clone()),
        ))
    }

    /// 导入模板(填入示例行 / 引用列表后交给 [`build_template`](crate::write::build_template))
    pub fn template(&self) -> TemplateSpec {
        TemplateSpec::new(self.columns.clone()).sheet_name(self.default_sheet())
    }
}

impl<T: ExcelRow> Executor<T> {
    /// 校验预览(不落库,只读前 `limit` 行)
    pub fn preview(
        &self,
        source: ZipSource,
        limit: usize,
    ) -> Result<ImportPreview<T>>
    where
        T: Serialize,
    {
        self.import_runner().preview::<T>(source, limit)
    }

    /// 预览转 JSON(按名调度 / HTTP 响应直接返回用)
    pub fn preview_json(
        &self,
        source: ZipSource,
        limit: usize,
    ) -> Result<serde_json::Value>
    where
        T: Serialize,
    {
        let preview = self.preview(source, limit)?;
        serde_json::to_value(&preview).map_err(ExcelError::from)
    }

    /// 正式导入:流式解析 + 分批落库(解析在阻塞线程,落库走异步任务)
    pub async fn commit<S>(&self, source: ZipSource, sink: Arc<S>) -> Result<ImportReport>
    where
        S: BatchSink<T> + ?Sized,
    {
        self.import_runner().commit::<T, S>(source, sink).await
    }

    /// 只解析 + 自定义逐行处理(同步处理,不落库、不攒批)
    pub fn for_each_row<F>(&self, source: ZipSource, on_row: F) -> Result<ImportReport>
    where
        F: FnMut(&RowData<'_>, T) -> std::result::Result<(), Vec<String>>,
    {
        self.import_runner()
            .for_each_row::<T, F>(source, on_row)
    }

    /// 小数据量:写回内存(HTTP 直接下载)
    pub fn export_bytes(&self, rows: &[T]) -> Result<Vec<u8>> {
        self.export_runner().export_bytes(rows)
    }

    /// 小数据量:写文件
    pub fn export_rows<P: AsRef<Path>>(&self, path: P, rows: &[T]) -> Result<u64> {
        self.export_runner().export_rows(path, rows)
    }

    /// 小数据量:一个文件多张工作表(每张独立数据)
    pub fn export_sheets<P: AsRef<Path>>(
        &self,
        path: P,
        named_rows: Vec<(String, Vec<T>)>,
    ) -> Result<ExportStats> {
        let sheets = named_rows
            .into_iter()
            .map(|(name, rows)| {
                (
                    apply_export_config(
                        self.name,
                        SheetOptions::new(name).columns(self.columns.clone()),
                    ),
                    rows,
                )
            })
            .collect();
        self.export_runner().export_sheets(path, sheets)
    }

    /// 游标分批拉取 + 流式写文件(百万行导出推荐)
    pub async fn export_xlsx<P, F, Fut>(&self, path: P, fetch: F) -> Result<ExportStats>
    where
        P: AsRef<Path>,
        F: FnMut(Option<String>) -> Fut,
        Fut: Future<Output = Result<Page<T>>> + Send,
    {
        self.export_runner().export_xlsx(path, fetch).await
    }

    /// 多工作表游标导出:每张表独立分页拉取,顺序写出
    pub async fn export_multi_sheet<P, F, Fut>(
        &self,
        path: P,
        sheets: Vec<String>,
        fetch: F,
    ) -> Result<ExportStats>
    where
        P: AsRef<Path>,
        F: FnMut(usize, Option<String>) -> Fut,
        Fut: Future<Output = Result<Page<T>>> + Send,
    {
        let options: Vec<SheetOptions> = sheets
            .into_iter()
            .map(|name| {
                apply_export_config(
                    self.name,
                    SheetOptions::new(name).columns(self.columns.clone()),
                )
            })
            .collect();
        self.export_runner().export_multi_sheet(path, options, fetch).await
    }
}

#[async_trait::async_trait]
impl<T> ErasedExecutor for Executor<T>
where
    T: ExcelRow + Serialize + serde::de::DeserializeOwned + Sync,
{
    fn name(&self) -> &'static str {
        self.name
    }

    fn type_name(&self) -> &'static str {
        self.type_name()
    }

    fn preview(&self, source: ZipSource, limit: usize) -> Result<serde_json::Value> {
        self.preview_json(source, limit)
    }

    async fn commit_json(
        &self,
        source: ZipSource,
        sink: Arc<dyn JsonBatchSink>,
    ) -> Result<ImportReport> {
        let bridge = Arc::new(JsonBridge::<T> {
            inner: sink,
            _marker: PhantomData,
        });
        self.import_runner().commit::<T, _>(source, bridge).await
    }

    fn export_bytes_json(&self, rows: &serde_json::Value) -> Result<Vec<u8>> {
        let models: Vec<T> = serde_json::from_value(rows.clone())?;
        self.export_runner().export_bytes(&models)
    }

    fn template(&self) -> TemplateSpec {
        Executor::template(self)
    }
}

impl<T> fmt::Debug for Executor<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Executor")
            .field("name", &self.name)
            .field("sheet", &self.sheet)
            .field("model", &type_name::<T>())
            .field("columns", &self.columns.len())
            .finish()
    }
}

// ───────────────────────── 全局注册表(inventory 静态收集) ─────────────────────────

/// 注册表条目:`#[derive(ExcelExecutor)]` 自动提交
///
/// 通过 [`registered_executors`] / [`executor_entry`] 查询,
/// 想要运行时按名拿一个可用的执行器用 [`executor_by_name`]。
#[derive(Debug)]
pub struct ExecutorEntry {
    /// 注册名(`#[excel(register = "...")]`)
    pub name: &'static str,
    /// 模型类型名(调试 / 前端展示用)
    pub type_name: &'static str,
    /// 工厂:创建一个擦除了具体类型的执行器(预览返回 JSON)
    pub make: fn() -> Box<dyn ErasedExecutor>,
}

inventory::collect!(ExecutorEntry);

/// 已注册的全部执行器条目
pub fn registered_executors() -> Vec<&'static ExecutorEntry> {
    inventory::iter::<ExecutorEntry>
        .into_iter()
        .collect()
}

/// 已注册的注册名清单
pub fn registered_names() -> Vec<&'static str> {
    registered_executors()
        .into_iter()
        .map(|e| e.name)
        .collect()
}

/// 按注册名查条目
pub fn executor_entry(name: &str) -> Option<&'static ExecutorEntry> {
    inventory::iter::<ExecutorEntry>
        .into_iter()
        .find(|e| e.name == name)
}

/// 按注册名创建擦除类型的执行器(preview 返回 JSON,适合 Web 层按请求参数路由)
pub fn executor_by_name(name: &str) -> Option<Box<dyn ErasedExecutor>> {
    executor_entry(name).map(|e| (e.make)())
}

/// 按注册名直接预览,返回 JSON;未注册返回 `Ok(None)`
pub fn preview_by_name(
    name: &str,
    source: ZipSource,
    limit: usize,
) -> Result<Option<serde_json::Value>> {
    match executor_by_name(name) {
        Some(exec) => Ok(Some(exec.preview(source, limit)?)),
        None => Ok(None),
    }
}

/// 按注册名导入(JSON 边界);未注册返回 `Ok(None)`
pub async fn commit_json_by_name(
    name: &str,
    source: ZipSource,
    sink: Arc<dyn JsonBatchSink>,
) -> Result<Option<ImportReport>> {
    match executor_by_name(name) {
        Some(exec) => Ok(Some(exec.commit_json(source, sink).await?)),
        None => Ok(None),
    }
}

/// 按注册名导出(JSON 行数组 → xlsx 字节);未注册返回 `Ok(None)`
pub fn export_bytes_by_name(name: &str, rows: &serde_json::Value) -> Result<Option<Vec<u8>>> {
    match executor_by_name(name) {
        Some(exec) => Ok(Some(exec.export_bytes_json(rows)?)),
        None => Ok(None),
    }
}

/// JSON 批次落库:按名调度的 sink(把每批模型以 JSON 数组交给业务)
#[async_trait::async_trait]
pub trait JsonBatchSink: Send + Sync {
    async fn save(&self, rows: Vec<serde_json::Value>)
        -> std::result::Result<usize, ExcelError>;
}

/// 擦除具体类型后的执行器(按名调度用:预览 / 按名导入 / 按名导出 / 模板)
#[async_trait::async_trait]
pub trait ErasedExecutor: Send + Sync {
    fn name(&self) -> &'static str;
    fn type_name(&self) -> &'static str;
    /// 预览前 `limit` 行并转成 JSON
    fn preview(&self, source: ZipSource, limit: usize) -> Result<serde_json::Value>;
    /// 按名导入:解析 source,把每批模型转成 JSON 交给 `sink`
    async fn commit_json(
        &self,
        source: ZipSource,
        sink: Arc<dyn JsonBatchSink>,
    ) -> Result<ImportReport>;
    /// 按名导出:从 JSON 行数组(对象数组)生成 xlsx 字节
    fn export_bytes_json(&self, rows: &serde_json::Value) -> Result<Vec<u8>>;
    /// 按名生成导入模板
    fn template(&self) -> TemplateSpec;
}

/// 把 `JsonBatchSink` 适配成 `BatchSink<T>`
struct JsonBridge<T> {
    inner: Arc<dyn JsonBatchSink>,
    _marker: PhantomData<fn() -> T>,
}

#[async_trait::async_trait]
impl<T> BatchSink<T> for JsonBridge<T>
where
    T: Serialize + Send + Sync + 'static,
{
    async fn save(&self, batch: Vec<T>) -> std::result::Result<usize, ExcelError> {
        let rows: Vec<serde_json::Value> = batch
            .iter()
            .map(serde_json::to_value)
            .collect::<std::result::Result<Vec<_>, _>>()?;
        self.inner.save(rows).await
    }
}

// ───────────────────────── 执行器默认配置(模型级) ─────────────────────────

/// 执行器的**模型级默认配置**(`executor_config!` 链接期注册,按注册名关联)
///
/// 让「导入导出中心」按名拿到 runner 时,自动带上该模型的计算列 / 合并开关 / 批大小等,
/// 不用在每个调用点重复拼装。
pub struct ExecutorConfigEntry {
    pub name: &'static str,
    /// 定制导入 runner(`ImportRunner::merged` / `computed` / `batch_size` …)
    pub import: fn(ImportRunner) -> ImportRunner,
    /// 定制导出工作表配置(`SheetOptions::computed` / `transform` …)
    pub export: fn(SheetOptions) -> SheetOptions,
}

inventory::collect!(ExecutorConfigEntry);

/// 导入配置恒等函数(宏缺省时用)
pub fn identity_import_runner(runner: ImportRunner) -> ImportRunner {
    runner
}

/// 导出配置恒等函数(宏缺省时用)
pub fn identity_sheet_options(sheet: SheetOptions) -> SheetOptions {
    sheet
}

/// 按注册名查配置
pub fn executor_config_entry(name: &str) -> Option<&'static ExecutorConfigEntry> {
    inventory::iter::<ExecutorConfigEntry>()
        .find(|e| e.name == name)
}

fn apply_import_config(name: &str, runner: ImportRunner) -> ImportRunner {
    match executor_config_entry(name) {
        Some(e) => (e.import)(runner),
        None => runner,
    }
}

fn apply_export_config(name: &str, sheet: SheetOptions) -> SheetOptions {
    match executor_config_entry(name) {
        Some(e) => (e.export)(sheet),
        None => sheet,
    }
}