Skip to main content

fast_excel/
executor.rs

1//! 执行器:注册一次,全链路通用(预览 / 导入 / 导出 / 模板)
2//!
3//! 业务端只需在行模型上挂 `#[derive(ExcelExecutor)]`(配合 `#[excel(register = "...")]`),
4//! 本模块会自动生成该模型的执行器工厂并**静态注册进全局表**(`inventory` 链接期收集,
5//! 无需任何启动初始化代码),随后按类型或按注册名统一调用:
6//!
7//! ```no_run
8//! use serde::{Deserialize, Serialize};
9//! use fast_excel::{ExcelExecutor, ExcelRow, ZipSource};
10//!
11//! #[derive(ExcelRow, ExcelExecutor, Serialize, Deserialize)]
12//! #[excel(sheet = "产品导入", register = "product")]
13//! struct ProductRow {
14//!     #[excel(header = "品名", required)]
15//!     name: String,
16//! }
17//!
18//! # async fn demo(sink: std::sync::Arc<dyn fast_excel::BatchSink<ProductRow>>) -> Result<(), fast_excel::ExcelError> {
19//! let source = ZipSource::open("products.xlsx")?;
20//!
21//! // ① 按类型调用(编译期保证类型安全)
22//! let exec = fast_excel::executor_for::<ProductRow>();
23//! let preview = exec.preview(source.clone(), 200)?;
24//! let report = exec.commit(source.clone(), sink).await?;
25//! let bytes = exec.export_bytes(&products())?;
26//!
27//! // ② 按注册名字符串调度(Web 层按请求参数路由)
28//! let erased = fast_excel::executor_by_name("product").expect("已注册");
29//! let json = erased.preview(source, 200)?;
30//! # Ok(()) }
31//! # fn products() -> Vec<ProductRow> { vec![] }
32//! ```
33
34use std::any::type_name;
35use std::fmt;
36use std::future::Future;
37use std::marker::PhantomData;
38use std::path::Path;
39use std::sync::Arc;
40
41use serde::Serialize;
42
43use crate::column::ColumnDef;
44use crate::error::{ExcelError, Result};
45use crate::export::{ExportRunner, ExportStats, Page};
46use crate::import::{BatchSink, ImportPreview, ImportReport, ImportRunner};
47use crate::model::{ExcelRow, RowData};
48use crate::read::{SheetSelector, ZipSource};
49use crate::write::{SheetOptions, TemplateSpec};
50
51/// 行模型注册契约:`#[derive(ExcelExecutor)]` 生成实现
52///
53/// 通常不手写;实现该 trait 后即可用 [`executor_for::<T>`] 拿到通用执行器。
54pub trait ExcelExecutor: ExcelRow {
55    /// 全局注册名(`#[excel(register = "...")]` 指定)
56    const EXECUTOR_NAME: &'static str;
57}
58
59/// 按类型获取注册模型的通用执行器(自动创建,业务端无需管理工厂)
60pub fn executor_for<T: ExcelExecutor>() -> Executor<T> {
61    Executor::new(T::EXECUTOR_NAME, T::sheet_name())
62}
63
64/// 一个行模型的通用执行器:预览 / 导入 / 导出 / 模板的统一入口
65///
66/// 所有方法都基于模型自带的列定义与表名自动构造 runner,
67/// 需要微调时再通过 [`Executor::import_runner`] / [`Executor::export_runner`] 拿到
68/// 可配置的 runner(默认值已经可用,一般不需要)。
69#[derive(Clone)]
70pub struct Executor<T> {
71    /// 注册名(仅用于标识 / 按名调度)
72    name: &'static str,
73    /// 默认工作表名(来自 `#[excel(sheet = "...")]` 或 `ExcelRow::sheet_name`)
74    sheet: Option<&'static str>,
75    columns: Vec<ColumnDef>,
76    _marker: PhantomData<fn() -> T>,
77}
78
79impl<T: ExcelRow> Executor<T> {
80    /// 手动构造(未注册模型也能用;注册模型请用 [`executor_for`])
81    pub fn new(name: &'static str, sheet: Option<&'static str>) -> Self {
82        Self {
83            name,
84            sheet,
85            columns: T::columns(),
86            _marker: PhantomData,
87        }
88    }
89
90    pub fn name(&self) -> &'static str {
91        self.name
92    }
93
94    pub fn type_name(&self) -> &'static str {
95        type_name::<T>()
96    }
97
98    pub fn sheet_name(&self) -> Option<&'static str> {
99        self.sheet
100    }
101
102    pub fn columns(&self) -> &[ColumnDef] {
103        &self.columns
104    }
105
106    /// 模型名不足时的兜底工作表名
107    fn default_sheet(&self) -> String {
108        self.sheet.unwrap_or("Sheet1").to_string()
109    }
110
111    /// 导入 runner(默认 sheets:单模型 = 按 `sheet` 名,多模型 = `All`)
112    ///
113    /// 会自动套用 `executor_config!` 注册的模型级配置(合并 / 计算列 / 批大小…)。
114    pub fn import_runner(&self) -> ImportRunner {
115        let sheets = match self.sheet {
116            Some(name) => SheetSelector::Name(name.to_string()),
117            None => SheetSelector::All,
118        };
119        apply_import_config(self.name, ImportRunner::new().sheets(sheets))
120    }
121
122    /// 导出 runner(列宽 / 格式 / 图片行高来自列定义;并套用模型级导出配置)
123    pub fn export_runner(&self) -> ExportRunner {
124        ExportRunner::new(apply_export_config(
125            self.name,
126            SheetOptions::new(self.default_sheet()).columns(self.columns.clone()),
127        ))
128    }
129
130    /// 导出 runner(显式指定工作表名)
131    pub fn export_runner_for(&self, sheet_name: impl Into<String>) -> ExportRunner {
132        ExportRunner::new(apply_export_config(
133            self.name,
134            SheetOptions::new(sheet_name).columns(self.columns.clone()),
135        ))
136    }
137
138    /// 导入模板(填入示例行 / 引用列表后交给 [`build_template`](crate::write::build_template))
139    pub fn template(&self) -> TemplateSpec {
140        TemplateSpec::new(self.columns.clone()).sheet_name(self.default_sheet())
141    }
142}
143
144impl<T: ExcelRow> Executor<T> {
145    /// 校验预览(不落库,只读前 `limit` 行)
146    pub fn preview(
147        &self,
148        source: ZipSource,
149        limit: usize,
150    ) -> Result<ImportPreview<T>>
151    where
152        T: Serialize,
153    {
154        self.import_runner().preview::<T>(source, limit)
155    }
156
157    /// 预览转 JSON(按名调度 / HTTP 响应直接返回用)
158    pub fn preview_json(
159        &self,
160        source: ZipSource,
161        limit: usize,
162    ) -> Result<serde_json::Value>
163    where
164        T: Serialize,
165    {
166        let preview = self.preview(source, limit)?;
167        serde_json::to_value(&preview).map_err(ExcelError::from)
168    }
169
170    /// 正式导入:流式解析 + 分批落库(解析在阻塞线程,落库走异步任务)
171    pub async fn commit<S>(&self, source: ZipSource, sink: Arc<S>) -> Result<ImportReport>
172    where
173        S: BatchSink<T> + ?Sized,
174    {
175        self.import_runner().commit::<T, S>(source, sink).await
176    }
177
178    /// 只解析 + 自定义逐行处理(同步处理,不落库、不攒批)
179    pub fn for_each_row<F>(&self, source: ZipSource, on_row: F) -> Result<ImportReport>
180    where
181        F: FnMut(&RowData<'_>, T) -> std::result::Result<(), Vec<String>>,
182    {
183        self.import_runner()
184            .for_each_row::<T, F>(source, on_row)
185    }
186
187    /// 小数据量:写回内存(HTTP 直接下载)
188    pub fn export_bytes(&self, rows: &[T]) -> Result<Vec<u8>> {
189        self.export_runner().export_bytes(rows)
190    }
191
192    /// 小数据量:写文件
193    pub fn export_rows<P: AsRef<Path>>(&self, path: P, rows: &[T]) -> Result<u64> {
194        self.export_runner().export_rows(path, rows)
195    }
196
197    /// 小数据量:一个文件多张工作表(每张独立数据)
198    pub fn export_sheets<P: AsRef<Path>>(
199        &self,
200        path: P,
201        named_rows: Vec<(String, Vec<T>)>,
202    ) -> Result<ExportStats> {
203        let sheets = named_rows
204            .into_iter()
205            .map(|(name, rows)| {
206                (
207                    apply_export_config(
208                        self.name,
209                        SheetOptions::new(name).columns(self.columns.clone()),
210                    ),
211                    rows,
212                )
213            })
214            .collect();
215        self.export_runner().export_sheets(path, sheets)
216    }
217
218    /// 游标分批拉取 + 流式写文件(百万行导出推荐)
219    pub async fn export_xlsx<P, F, Fut>(&self, path: P, fetch: F) -> Result<ExportStats>
220    where
221        P: AsRef<Path>,
222        F: FnMut(Option<String>) -> Fut,
223        Fut: Future<Output = Result<Page<T>>> + Send,
224    {
225        self.export_runner().export_xlsx(path, fetch).await
226    }
227
228    /// 多工作表游标导出:每张表独立分页拉取,顺序写出
229    pub async fn export_multi_sheet<P, F, Fut>(
230        &self,
231        path: P,
232        sheets: Vec<String>,
233        fetch: F,
234    ) -> Result<ExportStats>
235    where
236        P: AsRef<Path>,
237        F: FnMut(usize, Option<String>) -> Fut,
238        Fut: Future<Output = Result<Page<T>>> + Send,
239    {
240        let options: Vec<SheetOptions> = sheets
241            .into_iter()
242            .map(|name| {
243                apply_export_config(
244                    self.name,
245                    SheetOptions::new(name).columns(self.columns.clone()),
246                )
247            })
248            .collect();
249        self.export_runner().export_multi_sheet(path, options, fetch).await
250    }
251}
252
253#[async_trait::async_trait]
254impl<T> ErasedExecutor for Executor<T>
255where
256    T: ExcelRow + Serialize + serde::de::DeserializeOwned + Sync,
257{
258    fn name(&self) -> &'static str {
259        self.name
260    }
261
262    fn type_name(&self) -> &'static str {
263        self.type_name()
264    }
265
266    fn preview(&self, source: ZipSource, limit: usize) -> Result<serde_json::Value> {
267        self.preview_json(source, limit)
268    }
269
270    async fn commit_json(
271        &self,
272        source: ZipSource,
273        sink: Arc<dyn JsonBatchSink>,
274    ) -> Result<ImportReport> {
275        let bridge = Arc::new(JsonBridge::<T> {
276            inner: sink,
277            _marker: PhantomData,
278        });
279        self.import_runner().commit::<T, _>(source, bridge).await
280    }
281
282    fn export_bytes_json(&self, rows: &serde_json::Value) -> Result<Vec<u8>> {
283        let models: Vec<T> = serde_json::from_value(rows.clone())?;
284        self.export_runner().export_bytes(&models)
285    }
286
287    fn template(&self) -> TemplateSpec {
288        Executor::template(self)
289    }
290}
291
292impl<T> fmt::Debug for Executor<T> {
293    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
294        f.debug_struct("Executor")
295            .field("name", &self.name)
296            .field("sheet", &self.sheet)
297            .field("model", &type_name::<T>())
298            .field("columns", &self.columns.len())
299            .finish()
300    }
301}
302
303// ───────────────────────── 全局注册表(inventory 静态收集) ─────────────────────────
304
305/// 注册表条目:`#[derive(ExcelExecutor)]` 自动提交
306///
307/// 通过 [`registered_executors`] / [`executor_entry`] 查询,
308/// 想要运行时按名拿一个可用的执行器用 [`executor_by_name`]。
309#[derive(Debug)]
310pub struct ExecutorEntry {
311    /// 注册名(`#[excel(register = "...")]`)
312    pub name: &'static str,
313    /// 模型类型名(调试 / 前端展示用)
314    pub type_name: &'static str,
315    /// 工厂:创建一个擦除了具体类型的执行器(预览返回 JSON)
316    pub make: fn() -> Box<dyn ErasedExecutor>,
317}
318
319inventory::collect!(ExecutorEntry);
320
321/// 已注册的全部执行器条目
322pub fn registered_executors() -> Vec<&'static ExecutorEntry> {
323    inventory::iter::<ExecutorEntry>
324        .into_iter()
325        .collect()
326}
327
328/// 已注册的注册名清单
329pub fn registered_names() -> Vec<&'static str> {
330    registered_executors()
331        .into_iter()
332        .map(|e| e.name)
333        .collect()
334}
335
336/// 按注册名查条目
337pub fn executor_entry(name: &str) -> Option<&'static ExecutorEntry> {
338    inventory::iter::<ExecutorEntry>
339        .into_iter()
340        .find(|e| e.name == name)
341}
342
343/// 按注册名创建擦除类型的执行器(preview 返回 JSON,适合 Web 层按请求参数路由)
344pub fn executor_by_name(name: &str) -> Option<Box<dyn ErasedExecutor>> {
345    executor_entry(name).map(|e| (e.make)())
346}
347
348/// 按注册名直接预览,返回 JSON;未注册返回 `Ok(None)`
349pub fn preview_by_name(
350    name: &str,
351    source: ZipSource,
352    limit: usize,
353) -> Result<Option<serde_json::Value>> {
354    match executor_by_name(name) {
355        Some(exec) => Ok(Some(exec.preview(source, limit)?)),
356        None => Ok(None),
357    }
358}
359
360/// 按注册名导入(JSON 边界);未注册返回 `Ok(None)`
361pub async fn commit_json_by_name(
362    name: &str,
363    source: ZipSource,
364    sink: Arc<dyn JsonBatchSink>,
365) -> Result<Option<ImportReport>> {
366    match executor_by_name(name) {
367        Some(exec) => Ok(Some(exec.commit_json(source, sink).await?)),
368        None => Ok(None),
369    }
370}
371
372/// 按注册名导出(JSON 行数组 → xlsx 字节);未注册返回 `Ok(None)`
373pub fn export_bytes_by_name(name: &str, rows: &serde_json::Value) -> Result<Option<Vec<u8>>> {
374    match executor_by_name(name) {
375        Some(exec) => Ok(Some(exec.export_bytes_json(rows)?)),
376        None => Ok(None),
377    }
378}
379
380/// JSON 批次落库:按名调度的 sink(把每批模型以 JSON 数组交给业务)
381#[async_trait::async_trait]
382pub trait JsonBatchSink: Send + Sync {
383    async fn save(&self, rows: Vec<serde_json::Value>)
384        -> std::result::Result<usize, ExcelError>;
385}
386
387/// 擦除具体类型后的执行器(按名调度用:预览 / 按名导入 / 按名导出 / 模板)
388#[async_trait::async_trait]
389pub trait ErasedExecutor: Send + Sync {
390    fn name(&self) -> &'static str;
391    fn type_name(&self) -> &'static str;
392    /// 预览前 `limit` 行并转成 JSON
393    fn preview(&self, source: ZipSource, limit: usize) -> Result<serde_json::Value>;
394    /// 按名导入:解析 source,把每批模型转成 JSON 交给 `sink`
395    async fn commit_json(
396        &self,
397        source: ZipSource,
398        sink: Arc<dyn JsonBatchSink>,
399    ) -> Result<ImportReport>;
400    /// 按名导出:从 JSON 行数组(对象数组)生成 xlsx 字节
401    fn export_bytes_json(&self, rows: &serde_json::Value) -> Result<Vec<u8>>;
402    /// 按名生成导入模板
403    fn template(&self) -> TemplateSpec;
404}
405
406/// 把 `JsonBatchSink` 适配成 `BatchSink<T>`
407struct JsonBridge<T> {
408    inner: Arc<dyn JsonBatchSink>,
409    _marker: PhantomData<fn() -> T>,
410}
411
412#[async_trait::async_trait]
413impl<T> BatchSink<T> for JsonBridge<T>
414where
415    T: Serialize + Send + Sync + 'static,
416{
417    async fn save(&self, batch: Vec<T>) -> std::result::Result<usize, ExcelError> {
418        let rows: Vec<serde_json::Value> = batch
419            .iter()
420            .map(serde_json::to_value)
421            .collect::<std::result::Result<Vec<_>, _>>()?;
422        self.inner.save(rows).await
423    }
424}
425
426// ───────────────────────── 执行器默认配置(模型级) ─────────────────────────
427
428/// 执行器的**模型级默认配置**(`executor_config!` 链接期注册,按注册名关联)
429///
430/// 让「导入导出中心」按名拿到 runner 时,自动带上该模型的计算列 / 合并开关 / 批大小等,
431/// 不用在每个调用点重复拼装。
432pub struct ExecutorConfigEntry {
433    pub name: &'static str,
434    /// 定制导入 runner(`ImportRunner::merged` / `computed` / `batch_size` …)
435    pub import: fn(ImportRunner) -> ImportRunner,
436    /// 定制导出工作表配置(`SheetOptions::computed` / `transform` …)
437    pub export: fn(SheetOptions) -> SheetOptions,
438}
439
440inventory::collect!(ExecutorConfigEntry);
441
442/// 导入配置恒等函数(宏缺省时用)
443pub fn identity_import_runner(runner: ImportRunner) -> ImportRunner {
444    runner
445}
446
447/// 导出配置恒等函数(宏缺省时用)
448pub fn identity_sheet_options(sheet: SheetOptions) -> SheetOptions {
449    sheet
450}
451
452/// 按注册名查配置
453pub fn executor_config_entry(name: &str) -> Option<&'static ExecutorConfigEntry> {
454    inventory::iter::<ExecutorConfigEntry>()
455        .find(|e| e.name == name)
456}
457
458fn apply_import_config(name: &str, runner: ImportRunner) -> ImportRunner {
459    match executor_config_entry(name) {
460        Some(e) => (e.import)(runner),
461        None => runner,
462    }
463}
464
465fn apply_export_config(name: &str, sheet: SheetOptions) -> SheetOptions {
466    match executor_config_entry(name) {
467        Some(e) => (e.export)(sheet),
468        None => sheet,
469    }
470}