Spring Boot 注解式大文件 Excel 导入工具：excel‑import‑spring‑boot‑starter

背景简介

在中大型系统中，对 Excel 的高效导入与验证往往是瓶颈：数据量大，解析慢，OOM 情况多，需要统一处理逻辑。

基于此，我开源 excel‑import‑spring‑boot‑starter，目标是提供一个支持分段处理、注解驱动、Starter 自动配置、适用于大规模 Excel 导入场景的轻量化方案。

🚀 主要功能亮点

SAX 流式解析 Excel，无需加载全部表格，适合大文件处理（百万行）
注解驱动字段映射 & 校验 （如 @Excel, @NotNull, @Format 等），映射灵活
分段处理策略：支持将 Excel 拆页批量处理，避免事务超时
失败数据收集：异常行可写入 CSV，并可选择上传 MinIO / OSS
Starter 模式零配置接入：单行依赖即可自动注入 ExcelImportService

📦 快速集成示例

xml 复制代码

xml
复制编辑
<dependency>
  <groupId>io.github.tianyulife</groupId>
  <artifactId>excel-import-spring-boot-starter</artifactId>
  <version>2.0.0</version>
</dependency>

定义数据类：

java 复制代码

@Data
public class DemoExcelData {

    @Excel(index = 1)
    private String name;

    @Excel(index = 2)
    @Max(value = 50, message = "年龄不能大于50")
    private Integer age;

    @Excel(index = 3)
    private String gender;

    @Excel(index = 4)
    private String phone;

    @Excel(index = 5)
    private String email;

    @Excel(index = 6)
    private String address;
}

自定义处理器,调用导入：

typescript 复制代码

@Test
public void testMultiThreadImport()  {
    ImportResult<Void> voidImportResult = excelFileImportProcessor.importFile(new File("D:\YCJK\multi-segment-excel-import-spring-boot-starter\src\test\resources\demo_excel_data.xlsx"), new FileImportHandler<DemoExcelData>() {
        /**
         * 批量处理数据，成功的记录 每批次只进行一次和数据库交互操作
         *
         * @param records 成功的记录列表
         */
        @Override
        public void batchProcess(List<DemoExcelData> records) {
            records.forEach(System.out::println);
        }
    });
    if (voidImportResult.isSuccess()) {
        System.out.println("全部成功");
    }
    else {
        System.out.println("失败条数:" + voidImportResult.getFailCount());
        System.out.println("成功条数" + voidImportResult.getSuccessCount());
        System.out.println("失败的文件路径: " + voidImportResult.getFailFile().getAbsolutePath());
    }
}

@Test
public void testImport(){
    SegmentInfo<TransactionSummary> segment = new SegmentInfo<>(
            new FileImportHandler<TransactionSummary>() {
                @Override
                public void batchProcess(List<TransactionSummary> records) {
                    records.forEach(System.out::println);
                }
            }, 8, 9, 11
    );
    SegmentInfo<PayStatementDetail> statementDetailSegmentInfo = new SegmentInfo<>(
            new FileImportHandler<PayStatementDetail>() {
                @Override
                public void batchProcess(List<PayStatementDetail> records) {
 // 保存业务，打印 logs 或发送消费消息  records.forEach(System.out::println);
                }
            }, 14, 15, -1
    );

    List<SegmentInfo<?>> segments = new ArrayList<>();
    segments.add(segment);
    segments.add(statementDetailSegmentInfo);
    File file = new File("C:\Users\12092\Downloads\123.xlsx");
    ImportResult<Map<SegmentInfo<?>, List<Object>>> process = multiSegmentExcelSaxProcessor.process(file, -1, segments);

    if (process.isSuccess()) {
        System.out.println("全部成功");
    }
    else {
        System.out.println("失败条数:" + process.getFailCount());
        System.out.println("成功条数" + process.getSuccessCount());
        System.out.println("失败的文件路径: " + process.getFailFile().getAbsolutePath());
    }

📊 使用场景与优势对比

场景	优势	对比传统 Apache POI
数十万行导入	内存使用低、解析速度快	易出现 OOM
多业务导入模块化	注解 + Handler 解耦业务逻辑	POI 写法嵌套复杂
自动失败上报系统	CSV + 云存储可生成报错表	需额外编写低效逻辑
Spring Boot 集成	Starter 一键启动	无集成封装

🌱 为什么推荐它？

与主流 Excel Starter（如 pig4cloud excel-starter 等）相比，更专注于导入场景，不涉及导出或格式生成；
注解映射灵活，适配多表头、多段落不同结构的复杂 Excel；
项目已发布 Maven Central，支持企业级快速整合。

🚀 立即体验 & 欢迎贡献

GitHub 仓库：github.com/Tianyulife/...
Maven：io.github.tianyulife:excel-import-spring-boot-starter:2.0.0
⭐Star 或 Fork 支持
欢迎提出 Issue、功能建议或 Pull Request！

scss 复制代码

                           ┌────────────┐
                           │  @Excel    │
                           └────┬───────┘
                                │
       ┌────────────────────────┼──────────────────────────┐
       ▼                        ▼                          ▼
┌─────────────┐        ┌─────────────────┐        ┌──────────────────┐
│  基本配置   │        │   格式控制      │        │   BigDecimal配置 │
└────┬────────┘        └────┬────────────┘        └────────┬─────────┘
     │                           │                             │
     ▼                           ▼                             ▼
name, sort, index       dateFormat, separator,         scale, roundingMode
targetAttr, isExport    readConverterExp, cellType
                        height, width, suffix
                        align, defaultValue

       ┌────────────────────────┬──────────────────────────┐
       ▼                        ▼                          ▼
┌──────────────┐       ┌──────────────────┐        ┌─────────────────┐
│   交互提示   │       │    数据处理器    │        │     统计功能    │
└────┬─────────┘       └─────────┬────────┘        └────────┬────────┘
     │                           │                             │
     ▼                           ▼                             ▼
prompt, combo           handler, args                  isStatistics

       ┌──────────────────────────────────────────────┐
       ▼                                              ▼
┌──────────────┐                                ┌──────────────┐
│     Align    │ enum {AUTO, LEFT, CENTER, RIGHT} │
│     Type     │ enum {ALL, EXPORT, IMPORT}        │
│ ColumnType   │ enum {NUMERIC, STRING, IMAGE}     │
└──────────────┘                                └──────────────┘