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、リポジトリはアーカイブ済みで、バグ修正のみ）

このスキルは、**「Excel データの読み取り」**に特化しています。ユーザーが .xlsx／.xls ファイルの解析（データのインポート、一括登録、照合ファイルの解析、ユーザーによるアップロード）を必要とする場合は、このスキルを使用してください。

対応範囲

✅ 得意なこと

1. リスナーモード（ストリーミング、大きなファイルでも OOM を回避）
2. 同期読み取り（小さなファイルを一度に List として返す）
3. 複数シートの読み取り（すべて／一部）
4. 複数行のヘッダーに対応（headRowNumber）
5. カスタムコンバーター（日付／数値／列挙型）
6. 例外処理（行単位のエラー許容）
7. 追加情報の読み取り（コメント／ハイパーリンク／結合セル）
8. 数式とセルの元の型
9. オブジェクトを作成しない読み取り（Map を直接取得）
10. Web アップロードファイルの読み取り

⚠️ 制限事項

1. リスナーは Spring で管理できません（必ず new で作成し、フィールドにはコンストラクター経由で Spring Bean を渡す必要があります）
2. 同じシートを繰り返し読み取ることはできません（複数回読み取る場合は reader を再構築する必要があります）
3. 03 版では、複数シートを一度に渡して重複解析を避けてください
4. headRowNumber を指定しない場合、@ExcelProperty#value() のヘッダー数から推定されます
5. doReadSync() は大量データには推奨されません

❌ 対象外（このスキルを使わない場面では、ほかのスキルを使用してください）

1. 事前定義済みテンプレートへの入力 → このスキルは不適切です。easyexcel-fill を使用してください
2. プログラムによる Excel の生成 → このスキルは不適切です。easyexcel-write を使用してください
3. CSV ファイル → このスキルは不適切です。commons-csv／OpenCSV を使用してください（EasyExcel も CSV に対応していますが、excelType(CSV) が必要です）
4. Word／PPT → このスキルは不適切です。Apache POI を使用してください

データのプライバシー

このスキルはユーザーデータを収集、保存、送信しません。すべてのコード例はローカル開発の参考用です。

このスキルを使用する場面

• ユーザーが「Excel を読み取る」「Excel を解析する」「Excel をインポートする」「Excel をアップロードする」と言った場合
• ユーザーが .xlsx ファイルをアップロードし、データを Java オブジェクトまたは Map として読み取るよう求めた場合
• 「一括登録」「照合ファイルの解析」「動的列の読み取り」などの業務要件がある場合
• コメント／ハイパーリンク／結合セルなどの追加情報を読み取る必要がある場合

クイックスタート

典型的な呼び出し方（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 件のデータを読み取り、返します。そのまま呼び出してデータを使用できます」

ワークフロー

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. 出力を検証 — 行数、変換例外、コメント／ハイパーリンクの取得を確認

重要：モード選択の判断

数据规模？
├── < 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, ...)

重要：標準リスナーテンプレート

@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
    }
}

リファレンスライブラリ（必要に応じて読み込み）

詳細なコードとコメントは references/ に分割されています。シナリオに応じて読み込んでください。

API と基本モード

• references/api/4-read-modes.md — 4 種類の基本的な読み取りモード（最小構成／列インデックス／複数シート／日付・数値変換）
• references/api/key-classes.md — 主要なクラス／メソッドのクイックリファレンス

シナリオ別（複数行ヘッダー／同期／ヘッダー／追加情報／数式／例外／オブジェクトを作成しない方式／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 項目

参考資料

• 公式ドキュメント：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/