If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/alibaba/easyexcel shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 4 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Concentrated ownership — top contributor handles 66% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live alibaba/easyexcel repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/alibaba/easyexcel.

What it runs against: a local clone of alibaba/easyexcel — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in alibaba/easyexcel | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 586 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of alibaba/easyexcel. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/alibaba/easyexcel.git
#   cd easyexcel
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of alibaba/easyexcel and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "alibaba/easyexcel(\\.git)?\\b" \\
  && ok "origin remote is alibaba/easyexcel" \\
  || miss "origin remote is not alibaba/easyexcel (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "easyexcel-core/src/main/java/com/alibaba/excel/EasyExcel.java" \\
  && ok "easyexcel-core/src/main/java/com/alibaba/excel/EasyExcel.java" \\
  || miss "missing critical file: easyexcel-core/src/main/java/com/alibaba/excel/EasyExcel.java"
test -f "easyexcel-core/src/main/java/com/alibaba/excel/analysis/ExcelAnalyserImpl.java" \\
  && ok "easyexcel-core/src/main/java/com/alibaba/excel/analysis/ExcelAnalyserImpl.java" \\
  || miss "missing critical file: easyexcel-core/src/main/java/com/alibaba/excel/analysis/ExcelAnalyserImpl.java"
test -f "easyexcel-core/src/main/java/com/alibaba/excel/analysis/v07/XlsxSaxAnalyser.java" \\
  && ok "easyexcel-core/src/main/java/com/alibaba/excel/analysis/v07/XlsxSaxAnalyser.java" \\
  || miss "missing critical file: easyexcel-core/src/main/java/com/alibaba/excel/analysis/v07/XlsxSaxAnalyser.java"
test -f "easyexcel-core/src/main/java/com/alibaba/excel/analysis/v03/XlsSaxAnalyser.java" \\
  && ok "easyexcel-core/src/main/java/com/alibaba/excel/analysis/v03/XlsSaxAnalyser.java" \\
  || miss "missing critical file: easyexcel-core/src/main/java/com/alibaba/excel/analysis/v03/XlsSaxAnalyser.java"
test -f "easyexcel-core/src/main/java/com/alibaba/excel/ExcelReader.java" \\
  && ok "easyexcel-core/src/main/java/com/alibaba/excel/ExcelReader.java" \\
  || miss "missing critical file: easyexcel-core/src/main/java/com/alibaba/excel/ExcelReader.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 586 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~556d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/alibaba/easyexcel"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

EasyExcel is a Java library that parses and generates Excel files (both .xls and .xlsx) with minimal memory overhead through custom SAX-based parsing for OOXML files. Unlike Apache POI which loads entire sheets into memory, EasyExcel rewrites the .xlsx parsing layer to stream data directly, enabling a 3MB Excel file to consume only a few MB instead of 100MB+. Single Maven module: easyexcel-core contains the main logic under src/main/java/com/alibaba/excel/. Core entry points are EasyExcel.java (facade), ExcelReader.java/ExcelWriter.java (APIs), and ExcelAnalyserImpl.java (parsing engine). Separate handler chains for v03 (.xls) under analysis/v03/handlers/ and custom rewritten v07+ (.xlsx) parsing under analysis/.

Java backend developers and data engineers who process large Excel files (100MB+) in batch ETL pipelines, reporting systems, or data import workflows where POI's memory consumption causes OutOfMemoryErrors. Also used by developers needing simple fluent API for Excel I/O without wrestling with POI's complexity.

Production-ready but in maintenance mode. The project has 47k+ GitHub stars, CI/CD via GitHub Actions, and is actively used at Alibaba scale. However, the README explicitly states EasyExcel is transitioning to 'maintenance mode' — bug fixes only, no new features planned. Last activity suggests stable but not actively developed.

Moderate risk due to maintenance-mode status: no new features will be added, and community migration to alternatives is being encouraged. Dependency on Apache POI (for .xls v03 support) means inheriting POI's own maintenance concerns. Single organization (Alibaba) maintains this, though open contributions are accepted. Breaking changes unlikely given stability focus, but long-term evolution is limited.

Minimal active development. The GitHub Actions CI/CD pipelines (ci.yml, release.yml) are set up but indicate stable-state maintenance. No evidence of major refactors or feature branches in the file list. Recent work is likely bug fixes and dependency updates, not architectural changes.

git clone https://github.com/alibaba/easyexcel.git
cd easyexcel
mvn clean install
# Core module built to easyexcel-core/target/easyexcel-core-*.jar

Daily commands: EasyExcel is a library, not a runnable app. Use via Maven: add dependency to pom.xml, then call EasyExcel.read(file).sheet().doRead() in your application. See examples/ subdirectory (if present) or official docs at https://easyexcel.opensource.alibaba.com/docs/current/

• easyexcel-core/src/main/java/com/alibaba/excel/EasyExcel.java — Main public API entry point; all read/write operations start here—essential for understanding the library's surface contract.
• easyexcel-core/src/main/java/com/alibaba/excel/analysis/ExcelAnalyserImpl.java — Core SAX-based Excel parsing engine; handles both XLS and XLSX format analysis and memory-efficient streaming.
• easyexcel-core/src/main/java/com/alibaba/excel/analysis/v07/XlsxSaxAnalyser.java — XLSX-specific SAX parser implementation; critical for modern Office file format support and large file handling.
• easyexcel-core/src/main/java/com/alibaba/excel/analysis/v03/XlsSaxAnalyser.java — XLS (binary format) SAX parser; handles legacy Excel format parsing with record-based streaming.
• easyexcel-core/src/main/java/com/alibaba/excel/ExcelReader.java — Fluent API builder for configuring and executing read operations; required reading for customizing parse behavior.
• easyexcel-core/src/main/java/com/alibaba/excel/ExcelWriter.java — Fluent API builder for configuring and executing write operations; essential for export functionality.
• easyexcel-core/src/main/java/com/alibaba/excel/context — Context objects holding read/write state and metadata; foundational for understanding execution flow.

Add Support for a New Data Type or Format

1. Create a converter implementing the TypeConverter interface in easyexcel-support to handle custom type conversions (e.g., custom objects, enums). (easyexcel-core/src/main/java/com/alibaba/excel/annotation/ExcelProperty.java (review converterClazz parameter))
2. Register the converter in the ExcelProperty annotation or GlobalConfiguration for automatic discovery. (easyexcel-core/src/main/java/com/alibaba/excel/context (add to context initialization))
3. Test the converter with read/write operations using ExcelReader/ExcelWriter. (easyexcel-core/src/main/java/com/alibaba/excel/EasyExcel.java (use read() or write()))

Add a Custom Cell Handler or Tag Handler

1. For XLSX: extend AbstractXlsxTagHandler and override startTag()/endTag() to process specific XML elements. (easyexcel-core/src/main/java/com/alibaba/excel/analysis/v07/handlers/AbstractXlsxTagHandler.java)
2. For XLS: extend AbstractXlsRecordHandler and override doProcess() to handle binary record types. (easyexcel-core/src/main/java/com/alibaba/excel/analysis/v03/handlers/AbstractXlsRecordHandler.java)
3. Register the handler in XlsxSaxAnalyser (v07) or XlsSaxAnalyser (v03) handler registry. (easyexcel-core/src/main/java/com/alibaba/excel/analysis/v07/XlsxSaxAnalyser.java or easyexcel-core/src/main/java/com/alibaba/excel/analysis/v03/XlsSaxAnalyser.java)

Add Custom Read Listener for Event Processing

1. Implement the ReadListener interface (or extend a base listener) to define onReadCell() and onReadFinished() callbacks. (easyexcel-core/src/main/java/com/alibaba/excel/EasyExcel.java (review registerReadListener()))
2. Pass the listener to ExcelReader via registerReadListener() or ExcelReaderSheetBuilder.registerReadListener(). (easyexcel-core/src/main/java/com/alibaba/excel/ExcelReader.java)
3. The listener receives callbacks for each row as the SAX parser emits events from XlsxSaxAnalyser or XlsSaxAnalyser. (easyexcel-core/src/main/java/com/alibaba/excel/analysis/ExcelAnalyserImpl.java (invokes listener callbacks))

Add Custom Cache Strategy for Large Files

1. Implement the ReadCache interface with put()/get()/remove() methods for storing parsed shared strings. (easyexcel-core/src/main/java/com/alibaba/excel/cache/ReadCache.java)
2. Create a ReadCacheSelector that returns your cache based on file size or configuration. (easyexcel-core/src/main/java/com/alibaba/excel/cache/selector/ReadCacheSelector.java)
3. Configure the cache selector in ExcelReaderBuilder.readCacheSelector() before reading. (easyexcel-core/src/main/java)

SAX parsing quirks: .xlsx parsing is heavily optimized for memory; if you need POI's full object model (e.g., cell styling details), you'll lose EasyExcel's memory advantage. No automatic schema validation: EasyExcel trusts input format; corrupt Excel files may cause cryptic parsing errors rather than clear validation messages. Listener callbacks are single-threaded: do not parallelize data processing inside listener callbacks without external synchronization. Cache backend: EHCache is used for sheet metadata caching but configuration is opaque; large workbooks with many sheets may hit cache limits silently.

• SAX (Simple API for XML) Parsing — EasyExcel's core innovation is rewriting POI's OOXML parsing to use SAX streaming instead of DOM; allows processing Excel files larger than heap without buffering entire sheets
• Record Handler Pattern (Chain of Responsibility) — The v03 (.xls) layer uses AbstractXlsRecordHandler subclasses (BofRecordHandler, EofRecordHandler, etc.) to handle each binary record type; understanding this pattern is key to extending v03 support
• OOXML (Office Open XML) Structure — Modern Excel files (.xlsx) are ZIP archives containing XML; EasyExcel optimizes by streaming the XML layer via SAX instead of decompressing/buffering the entire archive
• Memory-Mapped I/O and Streaming Parsers — EasyExcel avoids heap memory bloat by parsing Excel files in one-pass streaming fashion; critical for processing multi-gigabyte files on constrained JVMs
• Listener Pattern (Observer) — EasyExcel uses event-driven callbacks (ReadListener interface) to notify application code as rows are parsed; allows async/batched processing without loading entire sheet
• Type Coercion and Cell Format Handling — Excel cells have implicit types (Date, Number, Formula); EasyExcel must infer and convert these during streaming parsing without access to full schema metadata
• Cache-Aside Pattern (EHCache Integration) — EasyExcel caches sheet metadata and shared strings via EHCache to avoid reparsing during multi-sheet workbook reads; affects concurrency and memory tuning

• apache/poi — Parent dependency used by EasyExcel for .xls v03 SAX parsing and OOXML utilities; understanding POI's RecordHandler chain is essential for modifying v03 parsing
• alibaba/easyexcel-spring — Official Spring Boot integration for EasyExcel; provides @ExcelProperty annotation and auto-configuration if you need to integrate EasyExcel with Spring controllers
• alibaba/easyexcel-test — Alibaba's test suite and example repository (if separate); contains real-world Excel files and integration tests for EasyExcel
• x1r/pzip — Alternative lightweight ZIP handler; relevant because EasyExcel internally decompresses .xlsx (which is ZIP); understanding ZIP streaming may help optimize further

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for CSV parsing in CsvExcelReadExecutor

The CSV reading functionality (easyexcel-core/src/main/java/com/alibaba/excel/analysis/csv/CsvExcelReadExecutor.java) appears to lack dedicated test coverage. Given that easyexcel supports CSV as a file format alongside XLS/XLSX, adding tests would ensure CSV parsing handles edge cases (empty cells, special characters, quoted fields, different delimiters) correctly and maintain parity with the existing v03/v07 Excel format tests.

• [ ] Create easyexcel-core/src/test/java/com/alibaba/excel/analysis/csv/ directory
• [ ] Add CsvExcelReadExecutorTest.java with test cases for: basic CSV parsing, special characters, quoted fields, empty rows/columns, different encodings
• [ ] Add sample CSV test files to easyexcel-core/src/test/resources/
• [ ] Verify tests pass and achieve >80% code coverage for CsvExcelReadExecutor

Implement handler tests for v03 XLS record handlers

The v03 XLS format has 15+ record handlers (BlankRecordHandler, BoolErrRecordHandler, FormulaRecordHandler, etc. in easyexcel-core/src/main/java/com/alibaba/excel/analysis/v03/handlers/) but likely lack unit test coverage. These handlers are critical for correctly parsing legacy XLS files. Adding focused unit tests would catch regressions when refactoring and document expected behavior for each record type.

• [ ] Create easyexcel-core/src/test/java/com/alibaba/excel/analysis/v03/handlers/ directory
• [ ] Add unit tests for high-risk handlers: FormulaRecordHandler, SstRecordHandler, MergeCellsRecordHandler, and HyperlinkRecordHandler
• [ ] Use mock objects to test handler interactions with AbstractXlsRecordHandler
• [ ] Add test cases for error conditions (null records, malformed data)

Add integration tests for large file handling and memory optimization

The README emphasizes '解决大文件内存溢出' (solving large file memory overflow), but there's no visible test suite validating this core feature. The docs/LARGEREAD.md file suggests large-file reading is documented, but test coverage is needed. Add integration tests that read multi-MB Excel files and verify memory consumption stays below configured thresholds.

• [ ] Create easyexcel-core/src/test/java/com/alibaba/excel/integration/LargeFileTest.java
• [ ] Generate test Excel files (10MB, 100MB+) with large row counts in easyexcel-core/src/test/resources/
• [ ] Add tests verifying memory usage with ExcelReader using batch read listeners
• [ ] Add tests comparing memory consumption between streaming vs. non-streaming modes
• [ ] Document expected memory behavior in test comments referencing docs/LARGEREAD.md

• Add integration tests for CSV reading via CsvExcelReadExecutor.java — the CSV parsing path lacks clear test coverage and would benefit from standardized round-trip tests (read CSV → verify data types → write back).
• Document the memory profiling methodology: create a /docs/MEMORY_PROFILE.md explaining how to benchmark EasyExcel vs POI using JProfiler or YourKit on 100MB+ files, since README claims 3M→few MB but provides no reproducible benchmark code.
• Implement IgnorableXlsRecordHandler (already stubbed in codebase) to skip record types like hyperlinks or embedded objects — currently these are parsed but ignored, wasting cycles on large files with rich formatting.

The EasyExcel codebase has moderate security concerns, primarily centered on dependency management and XML/file processing vulnerabilities. The main risks are: (1) Apache POI's known vulnerabilities related to XXE and ZIP bombs, (2) lack of input validation and resource limits for file processing, (3) potential XXE vulnerabilities in XLSX parsing, and (4) the project's transition to maintenance mode which may slow security updates. The absence of explicit version pinning for critical dependencies increases risk. Recommended actions include: pinning all dependency versions to patched releases, implementing strict file validation and size limits, securing XML parsers against XXE, and considering alternative libraries if requiring active security support.

• High · Dependency on Apache POI with Known Vulnerabilities — easyexcel-core/pom.xml - poi and poi-ooxml dependencies. The project depends on org.apache.poi:poi and org.apache.poi:poi-ooxml without explicitly pinned versions. Apache POI has a history of security vulnerabilities including XXE (XML External Entity) injection, ZIP bomb attacks, and remote code execution vulnerabilities. Without version constraints, the build may pull vulnerable versions. Fix: Pin Apache POI to the latest stable version with security patches. Implement input validation and consider using XXE-safe XML parsing configurations. Review the parent pom.xml for version management and ensure versions are explicitly set to patched releases (e.g., 5.2.x or later).
• High · Unrestricted File Upload/Processing Risk — easyexcel-core/src/main/java/com/alibaba/excel/analysis/v07/XlsxSaxAnalyser.java and CSV parser modules. EasyExcel is designed to process Excel files with SAX-based parsing for large files. Without proper file validation, size limits, or resource consumption controls, this could be exploited for denial-of-service attacks via malformed or compressed Excel files (zip bombs), or XXE attacks through embedded XML. Fix: Implement strict file validation: enforce maximum file size limits, validate ZIP structure before processing, disable external entity resolution in XML parsers, implement timeout mechanisms for processing, and add resource consumption monitoring to prevent DoS attacks.
• Medium · Ehcache Dependency Without Version Pinning — easyexcel-core/pom.xml - ehcache dependency. The ehcache dependency is included without an explicitly pinned version in the provided pom.xml snippet. Ehcache has had security vulnerabilities in the past. Using a version-unpinned dependency increases the risk of pulling vulnerable releases. Fix: Pin ehcache to a known secure version. Review parent pom.xml (../pom.xml) to verify if versions are defined there. Regularly update dependencies and monitor security advisories.
• Medium · Potential XXE Vulnerability in XML Processing — easyexcel-core/src/main/java/com/alibaba/excel/analysis/v07/handlers/ (AbstractXlsxTagHandler.java and related files). The project processes XLSX files which are ZIP archives containing XML. The handlers in analysis/v07/handlers/ process XML content. If XML parsing is not properly configured to disable external entity resolution, XXE attacks could occur. Fix: Ensure all XML parsers (SAXParser, XMLReader, etc.) have XXE protections enabled: disable DTD processing, disable external entity resolution, and use secure parser configurations. Configure parsers with: XMLConstants.ACCESS_EXTERNAL_DTD="" and XMLConstants.ACCESS_EXTERNAL_SCHEMA="".
• Medium · Maintenance Mode - Limited Security Updates — README.md and project governance. The README indicates EasyExcel is entering maintenance mode with reduced active development. This means slower security patches and potentially deprecated dependency versions that won't be updated regularly. Fix: For production use, consider evaluating alternative, actively maintained libraries. If continuing to use EasyExcel, implement additional security controls, perform regular security audits, and maintain a dependency update schedule.
• Low · commons-csv Dependency Security — easyexcel-core/pom.xml - commons-csv dependency. The commons-csv dependency is included without explicit version pinning. While Apache Commons CSV is generally secure, unversioned dependencies can lead to unexpected behavior changes or security fixes being applied without testing. Fix: Pin commons-csv to an explicit version. Review the parent pom.xml for version management strategy and ensure all dependencies have defined versions.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.