Files
ccdi/openspec/changes/replace-poi-with-easyexcel/tasks.md
2026-01-27 17:55:53 +08:00

4.4 KiB
Raw Blame History

Tasks: Replace Apache POI with Alibaba EasyExcel

依赖更新与环境准备

  • 1.1 更新 pom.xml,添加 easyexcel.version 属性(版本 3.3.4
  • 1.2 更新 ruoyi-common/pom.xml,保留 poi-ooxml 依赖,添加 easyexcel 依赖
  • 1.3 验证依赖解析成功:mvn dependency:tree
  • 1.4 备份现有的 ExcelUtil.java 文件到 excel/ 目录(保留参考)

注解与接口适配

  • 2.1 更新 Excel.java 注解:

    • 2.1.1 移除 POI 类型的 importHorizontalAlignment, IndexedColors
    • 2.1.2 使用字符串替代(align, headerBackgroundColor 等)
    • 2.1.3 调整颜色属性为字符串表示
    • 2.1.4 更新 Javadoc 注释
  • 2.2 更新 ExcelHandlerAdapter.java 接口:

    • 2.2.1 保留原有方法签名
    • 2.2.2 添加 EasyExcel CellWorkbook 类型适配说明
  • 2.3 验证注解编译无误

核心 ExcelUtil 重写

  • 3.1 创建新的 ExcelUtil.java 基础结构:

    • 3.1.1 保留泛型类定义 ExcelUtil<T>
    • 3.1.2 保留现有公共方法签名
    • 3.1.3 移除 POI 相关的私有字段和方法
  • 3.2 实现导出功能:

    • 3.2.1 exportExcel(HttpServletResponse, List<T>, String, String) - 主入口
    • 3.2.2 exportExcel(HttpServletResponse, List<T>, String) - 简化版
    • 3.2.3 exportExcel() - 返回文件名版本
    • 3.2.4 importTemplateExcel() - 生成导入模板
  • 3.3 实现导入功能:

    • 3.3.1 importExcel(InputStream) - 默认标题行
    • 3.3.2 importExcel(InputStream, int titleNum) - 自定义标题行
    • 3.3.3 importExcel(String sheetName, InputStream, int titleNum) - 指定 Sheet
  • 3.4 实现 EasyExcel 集成组件:

    • 3.4.1 ExcelStyleHandler - 样式处理器(基于 @Excel 注解)
    • 3.4.2 ReadListener - 读取监听器(内置在 importExcel 中)
  • 3.5 实现辅助功能:

    • 3.5.1 字典类型转换(dictType
    • 3.5.2 表达式转换(readConverterExp
    • 3.5.3 字段筛选(showColumn, hideColumn
    • 3.5.4 日期格式化(dateFormat- EasyExcel 自动处理
    • 3.5.5 自定义处理器(handler- 需要进一步适配

集成测试与验证

  • 4.1 单元测试:

    • 4.1.1 测试基本导出功能(少量数据)
    • 4.1.2 测试大数据量导出10 万行)
    • 4.1.3 测试基本导入功能
    • 4.1.4 测试大文件导入100MB
    • 4.1.5 测试超长文本单元格
    • 4.1.6 测试样式应用
    • 4.1.7 测试字典转换
    • 4.1.8 测试字段筛选
  • 4.2 现有功能集成测试:

    • 4.2.1 测试 SysUserController 导入导出
    • 4.2.2 测试 SysRoleController 导入导出
    • 4.2.3 测试 SysDictDataController 导入导出
    • 4.2.4 测试 SysPostController 导入导出
    • 4.2.5 测试 SysConfigController 导入导出
    • 4.2.6 测试 SysOperlogController 导入导出
    • 4.2.7 测试 SysLogininforController 导入导出
    • 4.2.8 测试 SysJobController 导入导出
    • 4.2.9 测试 SysJobLogController 导入导出
  • 4.3 性能验证:

    • 4.3.1 使用 VisualVM 监控导出 10 万行数据的内存占用
    • 4.3.2 使用 VisualVM 监控导入 100MB 文件的内存占用
    • 4.3.3 记录并对比迁移前后的性能指标

文档更新

  • 5.1 更新 openspec/project.md

    • 5.1.1 添加 EasyExcel 到技术栈
    • 5.1.2 更新项目约定中的 Excel 处理说明
  • 5.2 创建 API 文档:

    • 5.2.1 记录 ExcelUtil 公共方法的使用方式
    • 5.2.2 记录 @Excel 注解的所有属性说明
    • 5.2.3 提供迁移指南(如果 API 有变化)
  • 5.3 更新 CLAUDE.md(如需要):

    • 5.3.1 添加 Excel 相关的开发约定

依赖关系

1. 依赖更新
    ↓
2. 注解适配
    ↓
3. ExcelUtil 重写
    ↓
4. 集成测试
    ↓
5. 文档更新

并行任务

以下任务可以并行执行:

  • 2.1-2.3(注解适配)可与 3.1-3.2ExcelUtil 基础结构)并行
  • 4.1(单元测试)可与 4.2(集成测试)部分并行

验收标准

所有任务完成后,必须满足:

  1. 编译通过,无依赖错误
  2. 所有现有 Controller 的导入导出功能正常
  3. 导出 10 万行数据内存占用 < 500MB
  4. 导入 100MB 文件内存占用 < 200MB
  5. 现有实体类注解无需修改