122 lines
4.1 KiB
Markdown
122 lines
4.1 KiB
Markdown
|
# Proposal: Replace Apache POI with Alibaba EasyExcel
|
|||
|
|
|
|||
|
|
## Summary
|
|||
|
|
|
|||
|
|
将若依框架中的 Apache POI 替换为 Alibaba EasyExcel，以解决大文本量 Excel 导入导出时的内存占用和性能问题。当前使用 POI 的 SXSSFWorkbook 虽然支持流式写入，但在处理大量数据时仍然存在性能瓶颈，且不支持真正的流式读取。
|
|||
|
|
|
|||
|
|
## Motivation
|
|||
|
|
|
|||
|
|
### 问题分析
|
|||
|
|
|
|||
|
|
1. **当前 POI 实现的限制**：
|
|||
|
|
- `ExcelUtil.java:112` - `sheetSize` 硬编码为 65536，这是 Excel 2003 的限制
|
|||
|
|
- `ExcelUtil.java:1682` - 使用 SXSSFWorkbook 进行流式写入，但内存优化有限
|
|||
|
|
- `ExcelUtil.java:325-525` - `importExcel` 方法一次性加载整个 Sheet 到内存，无法处理大文件
|
|||
|
|
- POI 的 DOM 解析模式导致大文件内存占用过高
|
|||
|
|
|
|||
|
|
2. **业务需求**：
|
|||
|
|
- 需要支持导入导出超过 10 万行数据
|
|||
|
|
- 需要支持单元格内容超过 32767 字符（POI STRING 类型限制）
|
|||
|
|
- 需要降低内存占用，避免 OOM
|
|||
|
|
|
|||
|
|
3. **EasyExcel 优势**：
|
|||
|
|
- 基于 SAX 解析，真正的流式读写
|
|||
|
|
- 内存占用仅与行数据大小相关，与文件大小无关
|
|||
|
|
- API 设计简洁，注解驱动
|
|||
|
|
- 官方维护活跃，社区成熟
|
|||
|
|
|
|||
|
|
## Proposed Solution
|
|||
|
|
|
|||
|
|
### 技术方案
|
|||
|
|
|
|||
|
|
1. **保持 API 兼容性**：
|
|||
|
|
- 保留 `@Excel` 和 `@Excels` 注解接口
|
|||
|
|
- 保留 `ExcelUtil<T>` 的公共方法签名
|
|||
|
|
- 保留 `ExcelHandlerAdapter` 接口（适配 EasyExcel 的写处理器）
|
|||
|
|
|
|||
|
|
2. **核心实现变更**：
|
|||
|
|
- 使用 `EasyExcel.write()` 替代 POI 的 Workbook/Sheet 操作
|
|||
|
|
- 使用 `EasyExcel.read()` 替代 POI 的 Workbook 解析
|
|||
|
|
- 实现自定义的 `HeadGenerator` 和 `ContentStyleStrategy` 以支持样式
|
|||
|
|
|
|||
|
|
3. **依赖变更**：
|
|||
|
|
- 移除 `poi-ooxml` 依赖
|
|||
|
|
- 添加 `easyexcel` 依赖（版本 3.3.4，支持 Spring Boot 3）
|
|||
|
|
|
|||
|
|
### 影响范围
|
|||
|
|
|
|||
|
|
**修改的文件**：
|
|||
|
|
- `ruoyi-common/pom.xml` - 更新依赖
|
|||
|
|
- `ruoyi-common/src/main/java/com/ruoyi/common/utils/poi/ExcelUtil.java` - 重写实现
|
|||
|
|
- `ruoyi-common/src/main/java/com/ruoyi/common/annotation/Excel.java` - 调整注解属性
|
|||
|
|
- `ruoyi-common/src/main/java/com/ruoyi/common/utils/poi/ExcelHandlerAdapter.java` - 适配新接口
|
|||
|
|
|
|||
|
|
**无需修改的文件**（向后兼容）：
|
|||
|
|
- 所有 Controller 层代码（13 个文件使用 ExcelUtil）
|
|||
|
|
- 实体类上的 `@Excel` 注解
|
|||
|
|
|
|||
|
|
## Alternatives Considered
|
|||
|
|
|
|||
|
|
### 方案 1：升级 POI 版本
|
|||
|
|
- **优点**：代码改动最小
|
|||
|
|
- **缺点**：无法从根本上解决内存问题，POI 的架构限制依然存在
|
|||
|
|
|
|||
|
|
### 方案 2：使用 Hutool 的 Excel 工具
|
|||
|
|
- **优点**：API 简洁
|
|||
|
|
- **缺点**：底层仍使用 POI，内存问题未解决
|
|||
|
|
|
|||
|
|
### 方案 3：使用 EasyExcel（选定方案）
|
|||
|
|
- **优点**：真正的流式处理，内存占用低，社区成熟
|
|||
|
|
- **缺点**：需要适配现有注解和 API
|
|||
|
|
|
|||
|
|
## Compatibility Notes
|
|||
|
|
|
|||
|
|
### 破坏性变更
|
|||
|
|
|
|||
|
|
1. **样式支持**：EasyExcel 的样式支持有限，以下功能可能需要简化：
|
|||
|
|
- 合并单元格（`needMerge`）
|
|||
|
|
- 图片插入（`ColumnType.IMAGE`）
|
|||
|
|
- 数据验证（`combo`, `comboReadDict`）
|
|||
|
|
- 自定义颜色（`headerBackgroundColor`, `color` 等）
|
|||
|
|
|
|||
|
|
2. **Sheet 分割**：EasyExcel 自动处理大文件，无需手动分割 Sheet
|
|||
|
|
|
|||
|
|
3. **统计行**：`isStatistics` 需要通过监听器实现
|
|||
|
|
|
|||
|
|
### 保留的功能
|
|||
|
|
|
|||
|
|
- ✅ 注解驱动配置
|
|||
|
|
- ✅ 字典类型转换（`dictType`）
|
|||
|
|
- ✅ 表达式转换（`readConverterExp`）
|
|||
|
|
- ✅ 日期格式化（`dateFormat`）
|
|||
|
|
- ✅ 导入/导出模板生成
|
|||
|
|
- ✅ 字段筛选（`includeFields`, `excludeFields`）
|
|||
|
|
|
|||
|
|
## Success Criteria
|
|||
|
|
|
|||
|
|
1. **性能指标**：
|
|||
|
|
- 导出 10 万行数据，内存占用 < 500MB
|
|||
|
|
- 导入 100MB Excel 文件，内存占用 < 200MB
|
|||
|
|
|
|||
|
|
2. **功能完整性**：
|
|||
|
|
- 所有现有 Controller 的导入导出功能正常工作
|
|||
|
|
- 支持超过 65536 行数据
|
|||
|
|
|
|||
|
|
3. **兼容性**：
|
|||
|
|
- 现有实体类注解无需修改
|
|||
|
|
- 现有业务代码无需修改
|
|||
|
|
|
|||
|
|
## Timeline
|
|||
|
|
|
|||
|
|
阶段划分（具体任务见 tasks.md）：
|
|||
|
|
1. 依赖更新与环境准备
|
|||
|
|
2. 核心 ExcelUtil 重写
|
|||
|
|
3. 注解与接口适配
|
|||
|
|
4. 集成测试与验证
|
|||
|
|
5. 文档更新
|
|||
|
|
|
|||
|
|
## Related Changes
|
|||
|
|
|
|||
|
|
- 无前置依赖
|
|||
|
|
- 可能影响：所有使用 Excel 导入导出的模块
|