MCPInstall

easyexcel-read

by full-stack-skillsData & Databases

基于 Alibaba EasyExcel（com.alibaba:easyexcel:4.0.3）的 Excel 数据读取技能。覆盖监听器模式（ReadListener/AnalysisEventListener/PageReadListener）、同步读取（doReadSync）、多 Sheet 读取、@ExcelProperty(index/name)匹配、多行表头（headRowNumber）、日期数字自定义转换器（@DateTimeFormat/@NumberFormat/Converter）、监听器异常处理（onException + ExcelDataConvertException）、额外信息读取（批注/超链接/合并单元格，extraRead + CellExtra）、公式和单元格类型（CellData ）、不创建对象的读（ReadListener ）、Web 上传读取（MultipartFile→InputStream）。当用户需要解析 Excel（导入数据/批量入库/对账文件/用户上传/Excel 转对象/Excel 转 Map）时使用此技能，不适用于按预制模板填充（改用 easyexcel-fill）、不适用于程序化生成 Excel（改用 easyexcel-write）。

Installs
71
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/full-stack-skills/java-skills --skill easyexcel-read
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads easyexcel-read automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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

FAQ

What does the easyexcel-read skill do?

基于 Alibaba EasyExcel（com.alibaba:easyexcel:4.0.3）的 Excel 数据读取技能。覆盖监听器模式（ReadListener/AnalysisEventListener/PageReadListener）、同步读取（doReadSync）、多 Sheet 读取、@ExcelProperty(index/name)匹配、多行表头（headRowNumber）、日期数字自定义转换器（@DateTimeFormat/@NumberFormat/Converter）、监听器异常处理（onException + ExcelDataConvertException）、额外信息读取（批注/超链接/合并单元格，extraRead + CellExtra）、公式和单元格类型（CellData ）、不创建对象的读（ReadListener ）、Web 上传读取（MultipartFile→InputStream）。当用户需要解析 Excel（导入数据/批量入库/对账文件/用户上传/Excel 转对象/Excel 转 Map）时使用此技能，不适用于按预制模板填充（改用 easyexcel-fill）、不适用于程序化生成 Excel（改用 easyexcel-write）。

How do I install easyexcel-read?

Run npx skills add https://github.com/full-stack-skills/java-skills --skill easyexcel-read in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/easyexcel-read/ (personal) or .claude/skills/easyexcel-read/ (project).

Which AI agents can use easyexcel-read?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is easyexcel-read safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains easyexcel-read?

It is published by full-stack-skills in full-stack-skills/java-skills. It has 71 recorded installs.

More from full-stack-skills/java-skills

View all →

java-development-manual

full-stack-skills/java-skills

Java开发手册规约集合，基于阿里巴巴Java开发手册（嵩山版）。 涵盖7大维度：编程规约、异常日志、单元测试、安全规约、MySQL数据库、工程结构、设计规约。 当用户需要：(1) 编写或审查Java代码 (2) 检查命名/代码规范 (3) 处理异常和日志 (4) 编写单元测试 (5) 安全编码 (6) 数据库设计 (7) 工程架构设计时使用此skill。 触发词：Java规范、阿里规约、代码规范、开发手册、编程规约、异常处理、单元测试、安全、MySQL、工程结构、设计模式。

Backend & APIs119 installs

mybatis-plus-patterns

full-stack-skills/java-skills

Open the skill to read its SKILL.md instructions.

Backend & APIs114 installs

java-code-comments

full-stack-skills/java-skills

Provides comprehensive guidance for adding Java code comments following industry standards and best practices. This skill helps add class-level comments, method-level comments, and field-level comments to Java code. Use when the user wants to add comments to Java code, needs to document Java classes/methods/fields, wants to improve code documentation, or needs to generate JavaDoc comments. This skill covers Controller, Service, ServiceImpl, Mapper, Model, Entity, BO (Business Object), DTO, VO, and other common Java component types. The skill follows a systematic workflow: scan codebase, identify components, create todo list, and add comments in order (class comments → method comments → field comments).

Backend & APIs112 installs

java-conventions

full-stack-skills/java-skills

统一 Java 项目编码规范与注释规范（SLF4J+Lombok 日志、Bean Lombok 注解选择、判空 Objects/Optional、工具类优先级 Spring→Apache Commons→Hutool→Guava、复杂逻辑用设计模式/简单逻辑不拆分、Controller/Service/ServiceImpl/Mapper 注释一致性）。当需要“按 Java 规范重构/Review/补全注释/统一日志/统一工具类使用/补全 JavaDoc”时使用。

Backend & APIs108 installs

mybatis-patterns

full-stack-skills/java-skills

Open the skill to read its SKILL.md instructions.

Backend & APIs102 installs

redis-redisson-patterns

full-stack-skills/java-skills

Redis + Redisson 缓存与分布式锁技能。覆盖缓存Key命名规范、过期时间设置原则、RedisTemplate序列化选择(JSON vs JDK vs String)、Redisson分布式锁三大模式(watchDog/tryLock 有leaseTime/无leaseTime 决策)、缓存穿透(布隆/空值缓存)/击穿(互斥锁)/雪崩(随机TTL)防护、Caffeine vs Redis选择决策。 纠正 LLM：不设过期时间、StringRedisTemplate和RedisTemplate混用、Redisson锁不 try-finally unlock、看门狗在指定 leaseTime 时不生效。

Data & Databases100 installs

Popular data & databases skills

View category →

supabase-postgres-best-practices

supabase/agent-skills

Postgres best practices maintained by Supabase, for Postgres running anywhere. Load this skill BEFORE writing or changing anything that lives in a Postgres database: creating or altering tables and columns (including choosing column types), schema design, migrations and declarative schema files, RLS policies and the tests that verify them, indexes, triggers, database functions, queues and scheduled jobs (pgcron, pgmq), vector/semantic search (pgvector), and restoring dumps (pgrestore) or importing data. Also load it when diagnosing slow queries, high CPU, timeouts, EXPLAIN plans, connection exhaustion, locking, bloat, or rows visible to the wrong user or tenant. This is not just a performance guide — schema, migration, security, and SQL authoring tasks need these rules too, even for a one-column change or a single query.

OfficialData & Databases462.2K installs

prisma-client-api

prisma/skills

Prisma Client API reference covering model queries, filters, operators, and client methods. Use when writing database queries, using CRUD operations, filtering data, or configuring Prisma Client. Triggers on "prisma query", "findMany", "create", "update", "delete", "$transaction".

OfficialData & Databases393.5K installs

prisma-database-setup

prisma/skills

Deprecated compatibility name for prisma-orm-setup. Use only when a user or existing integration explicitly invokes prisma-database-setup; otherwise select prisma-orm-setup.

OfficialData & Databases392.3K installs

prisma-cli

prisma/skills

Prisma ORM 7 CLI reference for existing Prisma 7 applications or explicitly selected Prisma 7 workflows. Covers prisma init, generate, migrate, db, dev, studio, and mcp. For setup, connection repair, or Prisma 8, use prisma-orm-setup; not the Prisma Platform CLI.

OfficialData & Databases390.8K installs

prisma-postgres

prisma/skills

Deprecated compatibility name for prisma-postgres-setup. Use only when a user or existing integration explicitly invokes prisma-postgres; otherwise select prisma-postgres-setup.

OfficialData & Databases384.4K installs

prisma-driver-adapter-implementation

prisma/skills

Required reference for Prisma ORM 7 SQL driver adapter work. Use when implementing or modifying adapters, adding database drivers, or touching SqlDriverAdapter, Transaction, savepoint, result mapping, or DriverAdapterError behavior. Covers current transaction lifecycle, optional savepoint hooks, original database-error preservation, and verification.

OfficialData & Databases378.9K installs