# excel-utils-boot-starter **Repository Path**: creekmoon/excel-utils-boot-starter ## Basic Information - **Project Name**: excel-utils-boot-starter - **Description**: 一个符合直觉的导入导出工具类 - **Primary Language**: Java - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2022-01-13 - **Last Updated**: 2026-08-14 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Excel Utils Boot Starter [![Maven Central](https://maven-badges.herokuapp.com/maven-central/cn.creekmoon/excel-utils-boot-starter/badge.svg)](https://mvnrepository.com/artifact/cn.creekmoon/excel-utils-boot-starter) [![License](http://img.shields.io/:license-apache-brightgreen.svg)](http://www.apache.org/licenses/LICENSE-2.0.html) 一个基于 Hutool 的优雅易用的 Excel 导入导出工具,专为 Spring Boot 应用设计。 ## 设计理念 - **易于使用** - 链式调用,三步完成导入导出 - **符合直觉** - API 设计贴近自然语言 - **降低心智负担** - 无需复杂配置,开箱即用 - **功能强大** - 支持多级表头、多 Sheet 页、样式设置、数据验证 ## 快速开始 ### 1. 引入依赖 ```xml cn.creekmoon excel-utils-boot-starter 2.4.1 ``` > ⚠️ 从 2.0.0 版本开始,基于 Spring Boot 3.0 (JDK 17) 开发 ### 2. 大版本升级说明(v2.3.1+) **Breaking Changes:** 从 v2.3.1 开始,导入功能进行了架构升级,以更好地支持 API/JSON 场景: 1. **移除** `TitleReader.rowIndex2msg` - 替代方案:使用 `ImportReport` 获取结构化导入结果 - 影响:直接访问 `reader.rowIndex2msg` 的代码需要迁移到 `reader.getReport()` 2. **Excel 回写行为变化** - 旧版:结果列会为每行写入"导入成功!"或失败原因 - 新版:结果列**默认只写失败原因**,成功行留空(更节省内存,适合大文件) 3. **新增能力** - `readWithReport(options)` - 返回结构化 `ImportReport`,可直接序列化为 JSON - `ImportOptions` - 统一配置入口(fail-fast、错误阈值、数据收集策略等) **迁移示例:** ```java // 旧版(已废弃) reader.rowIndex2msg.get(rowIndex); // ❌ // 新版 ImportReport report = reader.getReport(); report.getRowErrors(); // ✅ 获取行级错误 report.getGlobalErrors(); // ✅ 获取导入全局错误 ``` 详见后续章节:**导入场景 - 场景七:直接返回 JSON 结果(无需 response)** ### 3. 启用工具类 在 Spring Boot 启动类上添加注解: ```java @EnableExcelUtils @SpringBootApplication public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } } ``` ## 导出场景 ### 场景一:基础数据导出 最常见的需求:将用户列表导出为 Excel 文件 ```java @GetMapping("/export/users") public void exportUsers(HttpServletResponse response) { // 准备数据 List users = userService.getAllUsers(); // 三步完成导出 ExcelExport.create() .switchNewSheet(User.class) .addTitle("用户名", User::getUsername) .addTitle("姓名", User::getFullName) .addTitle("邮箱", User::getEmail) .addTitle("注册时间", User::getCreateTime) .write(users) .response(response); } ``` **生成效果:** ``` | 用户名 | 姓名 | 邮箱 | 注册时间 | |----------|----------|------------------|------------------| | zhangsan | 张三 | zhang@email.com | 2024-01-01 10:00 | | lisi | 李四 | li@email.com | 2024-01-02 14:30 | ``` ### 场景二:多级表头导出 业务中经常需要对数据进行分类展示: ```java @GetMapping("/export/sales") public void exportSalesReport(HttpServletResponse response) { List salesData = salesService.getMonthlySales(); ExcelExport.create() .switchNewSheet(SalesData.class) .addTitle("基本信息::销售员", SalesData::getSalesName) .addTitle("基本信息::所属部门", SalesData::getDepartment) .addTitle("业绩数据::本月销售额", SalesData::getCurrentAmount) .addTitle("业绩数据::累计销售额", SalesData::getTotalAmount) .addTitle("排名", SalesData::getRank) .write(salesData) .response(response); } ``` **生成效果:** ``` | 基本信息 | 业绩数据 | | | 销售员 | 所属部门 | 本月销售额 | 累计销售额 | 排名 | |---------|------------|-----------|-----------|------| | 张三 | 华东区 | 50000 | 300000 | 1 | | 李四 | 华南区 | 45000 | 280000 | 2 | ``` ### 场景三:多工作表导出 一个文件包含多个相关数据表: ```java @GetMapping("/export/comprehensive") public void exportComprehensiveReport(HttpServletResponse response) { List students = studentService.getAllStudents(); List teachers = teacherService.getAllTeachers(); ExcelExport excelExport = ExcelExport.create(); // 学生信息表 excelExport.switchNewSheet(Student.class) .addTitle("学号", Student::getStudentNo) .addTitle("姓名", Student::getName) .addTitle("年龄", Student::getAge) .addTitle("专业", Student::getMajor) .write(students); // 教师信息表 excelExport.switchNewSheet(Teacher.class) .addTitle("工号", Teacher::getTeacherNo) .addTitle("姓名", Teacher::getName) .addTitle("学科", Teacher::getSubject) .addTitle("职称", Teacher::getTitle) .write(teachers); excelExport.response(response); } ``` ### 场景四:带样式的数据导出 根据业务规则突出显示重要数据: ```java @GetMapping("/export/financial") public void exportFinancialReport(HttpServletResponse response) { List records = financialService.getMonthlyRecords(); ExcelExport.create() .switchNewSheet(FinancialRecord.class) .addTitle("项目名称", FinancialRecord::getProjectName) // 盈利项目显示绿色 .addTitle("收入金额", FinancialRecord::getIncome, ExcelCellStyle.LIGHT_GREEN, record -> record.getIncome() > 0) // 亏损项目显示橙色 .addTitle("支出金额", FinancialRecord::getExpense, ExcelCellStyle.LIGHT_ORANGE, record -> record.getExpense() > record.getIncome()) // 多条件样式:根据净利润设置不同颜色 .addTitle("净利润", FinancialRecord::getNetProfit, ConditionCellStyle.of(LIGHT_GREEN, r -> r.getNetProfit() > 10000), ConditionCellStyle.of(PALE_BLUE, r -> r.getNetProfit() > 0), ConditionCellStyle.of(LIGHT_ORANGE, r -> r.getNetProfit() <= 0)) .write(records) .response(response); } ``` ## 导入场景 ### 场景一:标准数据导入 最常见的需求:从 Excel 文件导入用户数据 ```java @PostMapping("/import/users") public void importUsers(MultipartFile file, HttpServletResponse response) { ExcelImport.create(file) .switchSheet(0, User::new) .addConvert("用户名", User::setUsername) .addConvert("姓名", User::setFullName) .addConvert("年龄", IntegerConverter::parse, User::setAge) .addConvert("邮箱", User::setEmail) .addConvert("注册时间", DateConverter::parse, User::setCreateTime) .read(user -> { // 处理每一行数据 userService.saveUser(user); log.info("导入用户: {}", user.getUsername()); }) .response(response); } ``` ### 场景二:数据验证与错误处理 实际业务中需要对导入数据进行验证: ```java @PostMapping("/import/products") public void importProducts(MultipartFile file, HttpServletResponse response) { ExcelImport.create(file) .switchSheet(0, Product::new) .addConvert("产品编码", Product::setProductCode) .addConvert("产品名称", Product::setProductName) .addConvert("价格", BigDecimalConverter::parse, Product::setPrice) .addConvert("库存数量", IntegerConverter::parse, Product::setStock) .read(product -> { try { // 业务验证 if (productService.existsByCode(product.getProductCode())) { throw new BusinessException("产品编码已存在"); } if (product.getPrice().compareTo(BigDecimal.ZERO) <= 0) { throw new BusinessException("价格必须大于0"); } productService.saveProduct(product); } catch (Exception e) { log.error("导入产品失败: {}", e.getMessage()); throw e; // 异常会被自动记录到导入结果中 } }) .response(response); } ``` ### 场景三:指定单元格读取 有时需要从固定位置读取特定数据: ```java @PostMapping("/import/config") public void importSystemConfig(MultipartFile file, HttpServletResponse response) { ExcelImport.create(file) .switchSheetAndUseCellReader(0, SystemConfig::new) .addConvert("B1", SystemConfig::setSystemName) // B1 单元格 .addConvert("D1", SystemConfig::setVersion) // D1 单元格 .addConvert(2, 3, IntegerConverter::parse, SystemConfig::setMaxUsers) // 第3行第4列 .read(config -> { systemConfigService.updateConfig(config); }) .response(response); } ``` ### 场景四:导入结果验证与处理 在实际业务中,我们经常需要获取导入结果,进行后续的验证和处理: ```java @PostMapping("/import/users-with-validation") public ResponseEntity importUsersWithValidation(MultipartFile file, HttpServletResponse response) { ExcelImport excelImport = ExcelImport.create(file); // 获取导入结果对象 TitleReaderResult result = excelImport.switchSheet(0, User::new) .addConvert("用户名", User::setUsername) .addConvert("姓名", User::setFullName) .addConvert("年龄", IntegerConverter::parse, User::setAge) .addConvert("邮箱", User::setEmail) .read(); // 不传入Consumer,先获取所有数据 // 获取所有成功解析的数据 List users = result.getAll(); // 对每个用户进行业务验证 for (User user : users) { try { // 业务验证逻辑 if (userService.existsByUsername(user.getUsername())) { result.setResultMsg(user, "用户名已存在"); continue; } if (!isValidEmail(user.getEmail())) { result.setResultMsg(user, "邮箱格式不正确"); continue; } // 保存用户 userService.saveUser(user); result.setResultMsg(user, "导入成功"); } catch (Exception e) { result.setResultMsg(user, "保存失败: " + e.getMessage()); } } // 生成带有验证结果的Excel文件 excelImport.response(response); // 返回导入摘要 ImportSummary summary = new ImportSummary(); summary.setTotalCount(users.size()); summary.setSuccessCount(users.size() - result.getErrorCount().get()); summary.setErrorCount(result.getErrorCount().get()); return ResponseEntity.ok(summary); } ``` ### 场景五:分批处理与进度反馈 对于大数据量导入,可以使用consume方法进行分批处理: ```java @PostMapping("/import/bulk-products") public void importBulkProducts(MultipartFile file, HttpServletResponse response) { ExcelImport excelImport = ExcelImport.create(file); AtomicInteger processedCount = new AtomicInteger(0); AtomicInteger successCount = new AtomicInteger(0); TitleReaderResult result = excelImport.switchSheet(0, Product::new) .addConvert("产品编码", Product::setProductCode) .addConvert("产品名称", Product::setProductName) .addConvert("价格", BigDecimalConverter::parse, Product::setPrice) .read() .consume((rowIndex, product) -> { try { // 业务处理 productService.saveProduct(product); successCount.incrementAndGet(); // 进度反馈(每100条记录输出一次) int processed = processedCount.incrementAndGet(); if (processed % 100 == 0) { log.info("已处理 {} 条记录,成功 {} 条", processed, successCount.get()); } } catch (Exception e) { throw new BusinessException("第" + (rowIndex + 1) + "行处理失败: " + e.getMessage()); } }); // 输出最终统计 log.info("导入完成:总计 {} 条,成功 {} 条,失败 {} 条", processedCount.get(), successCount.get(), result.getErrorCount().get()); excelImport.response(response); } ``` ### 场景六:多工作表导入 从一个文件的多个工作表导入不同类型的数据: ```java @PostMapping("/import/school-data") public void importSchoolData(MultipartFile file, HttpServletResponse response) { ExcelImport excelImport = ExcelImport.create(file); // 导入学生数据(第一个工作表) TitleReaderResult studentResult = excelImport.switchSheet(0, Student::new) .addConvert("学号", Student::setStudentNo) .addConvert("姓名", Student::setName) .addConvert("年龄", IntegerConverter::parse, Student::setAge) .read(student -> studentService.saveStudent(student)); // 导入教师数据(第二个工作表) TitleReaderResult teacherResult = excelImport.switchSheet(1, Teacher::new) .addConvert("工号", Teacher::setTeacherNo) .addConvert("姓名", Teacher::setName) .addConvert("学科", Teacher::setSubject) .read(teacher -> teacherService.saveTeacher(teacher)); // 输出导入摘要 log.info("学生导入:成功 {} 条,失败 {} 条", studentResult.getAll().size(), studentResult.getErrorCount().get()); log.info("教师导入:成功 {} 条,失败 {} 条", teacherResult.getAll().size(), teacherResult.getErrorCount().get()); excelImport.response(response); } ``` ### 场景七:直接返回 JSON 结果(无需 response) **v2.3.1+ 新特性**:很多 API 场景只需要返回导入结果的 JSON,不需要生成 Excel 回写文件。 ```java @PostMapping("/api/import/users") public ResponseEntity> importUsersApi(@RequestParam("file") MultipartFile file) { ExcelImport excelImport = ExcelImport.create(file); // 配置导入选项(针对 API 场景优化) ImportOptions options = ImportOptions.forApi(); // fail-fast + 错误阈值 + 不收集成功数据 // 直接获取结构化报告 ImportReport report = excelImport.switchSheet(0, User::new) .addConvert("用户名", User::setUsername) .addConvert("邮箱", User::setEmail) .addConvert("年龄", IntegerConverter::parse, User::setAge) .readWithReport(options); // 报告会自动序列化为 JSON 返回给前端 return ResponseEntity.ok(report); } ``` **返回的 JSON 结构示例:** ```json { "taskId": "a1b2c3d4-e5f6-7890", "sheetName": "Sheet1", "totalRows": 150, "successRows": 145, "errorRows": 5, "globalErrors": [], "rowErrors": [ { "rowIndex": 23, "message": "[失败!]字段[年龄]解析失败!不支持的数据格式!", "field": null }, { "rowIndex": 45, "message": "[失败!]字段[邮箱]为必填项!", "field": "邮箱" } ], "data": null } ``` **ImportOptions 配置说明:** ```java // 方式1:使用预设(推荐) ImportOptions.forApi(); // API 场景:fail-fast + 错误阈值100 + 不收集成功数据 ImportOptions.forExcelResponse(); // Excel 回写场景:读完整表 + 收集所有错误 ImportOptions.defaults(); // 默认配置 // 方式2:自定义配置 ImportOptions options = new ImportOptions(); options.setFailFastOnTemplateMismatch(true); // 模板不匹配立即停止 options.setMaxErrorRows(50); // 错误超过50行停止 options.setCollectRowErrors(true); // 收集行级错误明细 options.setCollectSuccessData(false); // 不收集成功数据(节省内存) options.setMaxSuccessData(100); // 若收集,最多100条 ``` **模板不匹配时的 fail-fast 示例:** ```java ImportOptions options = new ImportOptions(); options.setFailFastOnTemplateMismatch(true); ImportReport report = excelImport.switchSheet(0, User::new) .addConvert("用户名", User::setUsername) .addConvert("不存在的列", User::setEmail) // 模板不匹配 .readWithReport(options); // 返回的 JSON { "totalRows": 0, "successRows": 0, "errorRows": 0, "globalErrors": ["TEMPLATE_MISMATCH"], "rowErrors": [] } ``` **仍然支持 Excel 回写(兼容旧版):** ```java // 读取 + 返回 JSON ImportReport report = reader.readWithReport(options); // 如果用户需要下载错误文件,仍可调用 response if (report.getErrorRows() > 0) { excelImport.response(response); } ``` > ⚠️ **重要:`readWithReport()` 和 `response()` 的兼容性** > > 如果需要同时使用 `readWithReport()` 和 `response()`,**必须确保** `ImportOptions.collectRowErrors = true`: > > ```java > // ✅ 正确:使用预设配置(推荐) > ImportOptions options = ImportOptions.forExcelResponse(); > report = reader.readWithReport(options); > excelImport.response(response); // ✅ 可以正确写入错误 > > // ✅ 正确:使用默认配置 > report = reader.readWithReport(ImportOptions.defaults()); > excelImport.response(response); // ✅ 可以正确写入错误 > > // ❌ 错误:自定义配置关闭了 collectRowErrors > ImportOptions custom = new ImportOptions(); > custom.setCollectRowErrors(false); // ❌ 关闭错误收集 > report = reader.readWithReport(custom); > excelImport.response(response); // ❌ 无法写入错误到Excel! > ``` > > 如果只需要 **API 返回 JSON**(不需要 response),可以使用 `ImportOptions.forApi()` 以获得更好的性能。 ## 高级特性 ### 样式配置 #### 内置样式 工具提供三种预定义样式: ```java ExcelCellStyle.LIGHT_ORANGE // 浅橙色背景 ExcelCellStyle.PALE_BLUE // 浅蓝色背景 ExcelCellStyle.LIGHT_GREEN // 浅绿色背景 ``` #### 自定义样式 ```java // 创建自定义样式 ExcelCellStyle customStyle = new ExcelCellStyle((workbook, style) -> { style.setFillForegroundColor(IndexedColors.YELLOW.getIndex()); style.setFillPattern(FillPatternType.SOLID_FOREGROUND); // 设置数字格式 style.setDataFormat(workbook.createDataFormat().getFormat("#,##0.00")); }); // 应用样式 .addTitle("金额", Order::getAmount, customStyle, order -> order.getAmount() > 1000) ``` ### 高级配置 #### 启用注解参数说明 ```java @EnableExcelUtils( customExceptions = {BusinessException.class}, // 自定义业务异常 importMaxParallel = 4, // 最大导入并发数 tempFileLifeMinutes = 5 // 临时文件保留时间(分钟) ) ``` #### 数据转换器 系统提供多种内置转换器: - `StringConverter` - 字符串转换(默认) - `IntegerConverter` - 整数转换 - `BigDecimalConverter` - 高精度数字转换 - `DateConverter` - 日期转换 - `LocalDateTimeConverter` - 本地日期时间转换 ### 导入结果处理 #### TitleReaderResult 详解 `TitleReaderResult` 是导入操作的核心结果对象,提供了丰富的方法来处理导入结果: ```java // 四种读取方式 TitleReaderResult result1 = reader.read(); TitleReaderResult result2 = reader.read().consume(user -> process(user)); // 直接处理每行数据 TitleReaderResult result2 = reader.read(user -> process(user)); // 直接处理每行数据 List users = result.getAll(); // 获取所有成功解析的数据 ``` #### consume方法 vs 直接处理的关键区别 **使用consume方法的优势:**自动异常处理和结果记录 ```java // 使用consume - 推荐方式 result.consume(user -> { userService.save(user); // 如果抛异常,会自动记录到结果中 // 成功执行完毕,自动标记为"导入成功!" }); // 直接处理 - 需要手动处理异常 List users = result.getAll(); for (User user : users) { try { userService.save(user); result.setResultMsg(user, "导入成功!"); // 需要手动设置成功消息 } catch (Exception e) { result.setResultMsg(user, e.getMessage()); // 需要手动设置失败消息 result.getErrorCount().incrementAndGet(); // 需要手动增加错误计数 } } ``` **直接处理的适用场景:**需要复杂的业务逻辑判断 ```java List users = result.getAll(); for (User user : users) { if (needsSpecialValidation(user)) { // 复杂的多步骤验证 ValidationResult validation = complexValidation(user); if (validation.isSuccess()) { userService.save(user); result.setResultMsg(user, "特殊验证通过并保存成功"); } else { result.setResultMsg(user, validation.getErrorMessage()); } } else { // 简单保存 userService.save(user); result.setResultMsg(user, "导入成功!"); } } ``` **总结对比:** | 特性 | consume方法 | 直接处理getAll() | |------|------------|------------------| | 异常处理 | 自动捕获并记录 | 需要手动try-catch | | 成功标记 | 自动设置"导入成功!" | 需要手动setResultMsg | | 错误计数 | 自动累加 | 需要手动累加 | | 行号信息 | 自动提供 | 无法获取 | | 错误格式 | 统一格式 | 需要手动格式化 | | 灵活性 | 适合简单处理 | 适合复杂业务逻辑 | | 性能优化 | 逐条处理 | 支持批量操作 | **实际对比示例:** ```java // 方式一:使用consume方法(推荐用于简单业务逻辑) TitleReaderResult result = excelImport.switchSheet(0, User::new) .addConvert("用户名", User::setUsername) .addConvert("年龄", IntegerConverter::parse, User::setAge) .read() .consume(user -> { // 简洁的业务处理,异常会自动被捕获和记录 userService.save(user); // 成功时自动设置"导入成功!"消息 }); // 方式二:直接处理getAll()(适用于复杂业务逻辑) TitleReaderResult result = excelImport.switchSheet(0, User::new) .addConvert("用户名", User::setUsername) .addConvert("年龄", IntegerConverter::parse, User::setAge) .read(); List users = result.getAll(); for (User user : users) { try { // 复杂的业务验证 if (user.getAge() < 18) { result.setResultMsg(user, "年龄不能小于18岁"); continue; } // 批量验证用户名唯一性 if (userService.existsByUsername(user.getUsername())) { result.setResultMsg(user, "用户名已存在"); continue; } userService.save(user); result.setResultMsg(user, "导入成功!"); } catch (Exception e) { result.setResultMsg(user, "保存失败: " + e.getMessage()); result.getErrorCount().incrementAndGet(); } } ``` #### 导入结果文件 调用 `response()` 方法后,系统会自动生成一个包含导入结果的Excel文件: - 在原始数据右侧添加"导入结果"列 - **v2.3.1+ 变化**:默认只显示失败行的原因,成功行留空(节省内存,适合大文件) - 失败的数据会保留原始内容,便于用户修改后重新导入 #### 导入全局错误说明(v2.3.1+) | 全局错误枚举 | 含义 | 何时出现 | |---------|------|---------| | `TEMPLATE_MISMATCH` | 模板不匹配 | Excel 标题列与配置的列不一致 | | `ERROR_LIMIT_REACHED` | 错误阈值触发 | 错误行数达到配置的上限 | | `IMPORT_INTERRUPTED` | 导入中断 | 非预期异常导致读取中断 | **导入结果列内容示例:** ``` | 用户名 | 邮箱 | 年龄 | 导入结果 | |--------|-------------|------|-------------------------------------------| | zhang | z@email.com | 25 | | ← 成功行留空 | li | invalid | abc | [失败!]字段[年龄]解析失败!不支持的数据格式! | | wang | | 30 | [失败!]字段[邮箱]为必填项! | ``` ## 最佳实践 ### 1. 错误处理 ```java // 推荐:使用自定义异常进行业务验证 @EnableExcelUtils(customExceptions = {BusinessException.class}) // 在导入处理中 .read(data -> { if (invalidData(data)) { throw new BusinessException("数据验证失败:" + data.toString()); } saveData(data); }); ``` ## 技术架构 ### 核心执行流程 ```mermaid graph TD A[创建ExcelExport/ExcelImport] --> B[配置Sheet页] B --> C[设置表头/转换器] C --> D[写入/读取数据] D --> E[生成响应文件] subgraph 导出流程 F[switchNewSheet] --> G[addTitle] G --> H[write] H --> I[response] end subgraph 导入流程 J[switchSheet] --> K[addConvert] K --> L[read] L --> M[response] end ```