easyexcel-read

EasyExcel 数据读取（Read）

官方文档：https://easyexcel.opensource.alibaba.com/docs/current/quickstart/read 官方示例：https://github.com/alibaba/easyexcel/blob/master/easyexcel-test/src/test/java/com/alibaba/easyexcel/test/demo/read/ReadTest.java 当前版本：com.alibaba:easyexcel:4.0.3（Apache-2.0，仓库已归档，仅做 Bug 修复）

本技能专注于 "读取 Excel 数据" 场景。当用户需要解析 .xlsx/.xls 文件（导入数据、批量入库、对账文件解析、用户上传）时，应当使用本技能。

Capability Boundaries

✅ 强项

1. 监听器模式（流式，大文件不 OOM）
2. 同步读取（小文件一次性返回 List）
3. 多 Sheet 读取（全部 / 部分）
4. 多行表头支持（headRowNumber）
5. 自定义转换器（日期/数字/枚举）
6. 异常处理（行级容错）
7. 额外信息读取（批注/超链接/合并单元格）
8. 公式和单元格原始类型
9. 不创建对象的读（直接得 Map）
10. Web 上传文件读取

⚠️ 限制

1. 监听器不能被 Spring 管理（必须 new，且字段需要用构造方法传入 Spring Bean）
2. 一个 sheet 不能重复读取（多次读取需重新构造 reader）
3. 03 版多 sheet 一次性传入避免重复解析
4. headRowNumber 不指定时会按 @ExcelProperty#value() 表头数量推断
5. doReadSync() 不推荐大数据量

❌ Out of Scope（不该用本技能的场景，请改用其它技能）

1. 按预制模板填充 → 不适用本技能，使用 easyexcel-fill
2. 程序化生成 Excel → 不适用本技能，使用 easyexcel-write
3. CSV 文件 → 不适用本技能，自行使用 commons-csv / OpenCSV（EasyExcel 也支持 CSV，需 excelType(CSV)）
4. Word/PPT → 不适用本技能，使用 Apache POI

Data Privacy

本技能不收集、存储或传输任何用户数据。所有代码示例仅用于本地开发参考。

When to use this skill

• 用户说"读取 Excel"、"解析 Excel"、"导入 Excel"、"上传 Excel"
• 用户上传 .xlsx 文件，要求把数据读为 Java 对象或 Map
• 业务上有"批量入库"、"对账文件解析"、"动态列读取"等需求
• 需要读取批注/超链接/合并单元格等额外信息

Quick Start

典型调用方式（4 种写法）：

// 写法 1：JDK8+ PageReadListener（since 3.0.0-beta1，最简洁）
EasyExcel.read(fileName, DemoData.class, new PageReadListener<DemoData>(dataList -> {
    for (DemoData data : dataList) {
        log.info("读取到数据: {}", JSON.toJSONString(data));
    }
})).sheet().doRead();

// 写法 2：匿名 ReadListener
EasyExcel.read(fileName, DemoData.class, new ReadListener<DemoData>() {
    @Override public void invoke(DemoData data, AnalysisContext context) { /* 每行回调 */ }
    @Override public void doAfterAllAnalysed(AnalysisContext context) { /* 全部完成 */ }
}).sheet().doRead();

// 写法 3：自定义 ReadListener
EasyExcel.read(fileName, DemoData.class, new DemoDataListener()).sheet().doRead();

// 写法 4：ExcelReader（一个文件一个 reader）
try (ExcelReader excelReader = EasyExcel.read(fileName, DemoData.class,
        new DemoDataListener()).build()) {
    ReadSheet readSheet = EasyExcel.readSheet(0).build();
    excelReader.read(readSheet);
}

官方原文："PageReadListener 默认每次会读取100条数据 然后返回过来 直接调用使用数据就行"

Workflow

Step 1. 确认场景 — 数据规模、是否包含额外信息、是否有 DTO Step 2. 定义数据模型 — 编写 DTO/VO，标注 @ExcelProperty 等注解 Step 3. 选择读取方式 — 监听器（流式）/ 同步（小文件）/ 不创建对象 Step 4. 实现 ReadListener — 注入 DAO（构造方法）；处理 invoke / doAfterAllAnalysed / onException / invokeHead / extra Step 5. 执行读取 — doRead() 或 excelReader.read(readSheet) Step 6. 验证输出 — 检查行数、转换异常、批注/超链接捕获

Critical: 模式选择决策

数据规模？
├── < 1000 行 + 一次性返回 → 同步模式：doReadSync()
├── < 1 万行 + 简单处理 → PageReadListener
├── > 1 万行 + 入库 → ReadListener + 批量入库（每 2000 行）
└── 不需要对象 + 动态列 → ReadListener<Map<Integer, String>>

需要额外信息？
├── 批注 → extraRead(CellExtraTypeEnum.COMMENT)
├── 超链接 → extraRead(CellExtraTypeEnum.HYPERLINK)
└── 合并单元格 → extraRead(CellExtraTypeEnum.MERGE)

需要多 Sheet？
├── 全部 → doReadAll()
└── 部分 → ExcelReader.read(readSheet1, readSheet2, ...)

Critical: 标准监听器模板

@Slf4j
public class DemoDataListener implements ReadListener<DemoData> {
    /**
     * 官方原文："DemoDataListener 不能被spring管理，要每次读取excel都要new"
     */
    private static final int BATCH_COUNT = 100;
    private List<DemoData> cachedDataList =
        ListUtils.newArrayListWithExpectedSize(BATCH_COUNT);
    private DemoDAO demoDAO;

    public DemoDataListener() {
        demoDAO = new DemoDAO();
    }

    /**
     * 官方原文："如果使用了spring,请使用这个构造方法。
     *            每次创建Listener的时候需要把spring管理的类传进来"
     */
    public DemoDataListener(DemoDAO demoDAO) {
        this.demoDAO = demoDAO;
    }

    @Override
    public void invoke(DemoData data, AnalysisContext context) {
        log.info("解析到一条数据:{}", JSON.toJSONString(data));
        cachedDataList.add(data);
        if (cachedDataList.size() >= BATCH_COUNT) {
            saveData();
            cachedDataList = ListUtils.newArrayListWithExpectedSize(BATCH_COUNT);
        }
    }

    @Override
    public void doAfterAllAnalysed(AnalysisContext context) {
        saveData();  // ⚠️ 处理最后一批
        log.info("所有数据解析完成！");
    }

    private void saveData() {
        log.info("{}条数据，开始存储数据库！", cachedDataList.size());
        demoDAO.save(cachedDataList);
        log.info("存储数据库成功！");
    }
}

// 持久层（官方原文："如果是mybatis,尽量别直接调用多次insert,
//            自己写一个mapper里面新增一个方法batchInsert"）
public class DemoDAO {
    public void save(List<DemoData> list) {
        // mybatis batchInsert
    }
}

Reference Library（按需加载）

详细代码与注释已拆分到 references/。按场景加载：

API & 基础模式

• references/api/4-read-modes.md — 4 种基础读取模式（最简 / 列下标 / 多 Sheet / 日期数字转换）
• references/api/key-classes.md — Key Classes / Methods 速查

场景化（多行头 / 同步 / 表头 / 额外信息 / 公式 / 异常 / 不创建对象 / Web 上传）

• references/scenarios/multi-header-sync-header-extra.md — 多行头、同步读取、表头数据、额外信息
• references/scenarios/formula-celltype-exception-noobj.md — 公式 / 单元格类型 / 异常处理 / 不创建对象
• references/scenarios/web-upload.md — Web 上传读取

故障排查

• references/troubleshooting/gotchas.md — 12 条常见错误与正确做法

References

• 官方文档：https://easyexcel.opensource.alibaba.com/docs/current/quickstart/read
• 官方示例：https://github.com/alibaba/easyexcel/blob/master/easyexcel-test/src/test/java/com/alibaba/easyexcel/test/demo/read/ReadTest.java
• Web 示例：https://github.com/alibaba/easyexcel/blob/master/easyexcel-test/src/test/java/com/alibaba/easyexcel/test/demo/web/WebTest.java
• 项目主页：https://easyexcel.opensource.alibaba.com/
• GitHub：https://github.com/alibaba/easyexcel
• API 参考：https://easyexcel.opensource.alibaba.com/docs/current/api/