# alibaba/easyexcel architecture

> Architecture diagram of the GitHub repository alibaba/easyexcel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alibaba/easyexcel
- Repository: https://github.com/alibaba/easyexcel

## Overview

EasyExcel is a Java library for streaming Excel/CSV reading and generating spreadsheets. The principal workflows are application code configuring a read or write through the public API, then receiving row callbacks or writing supplied data to an output. The tree also shows format-specific readers, template/fill support, converters, and customizable write handlers. The README documents the basic read/write workflows; sampled source supports selected parser and handler relationships. Several subsystems are represented by their existing directories because their implementation files were not sampled.

Main entry points: [`easyexcel-core/src/main/java/com/alibaba/excel/analysis/v07/handlers/CellTagHandler.java`](https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/analysis/v07/handlers/CellTagHandler.java) (XLSX cell parser), [`easyexcel-core/src/main/java/com/alibaba/excel/analysis/ExcelAnalyserImpl.java`](https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/analysis/ExcelAnalyserImpl.java) (Read analyser), [`easyexcel-core/src/main/java/com/alibaba/excel/write/ExcelBuilderImpl.java`](https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/write/ExcelBuilderImpl.java) (Write builder), [`easyexcel-core/src/main/java/com/alibaba/excel/write/handler/context/CellWriteHandlerContext.java`](https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/write/handler/context/CellWriteHandlerContext.java) (Cell write context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_api["Read/write API<br/>[EasyExcel.java]"]
  node_reader["Reader builder"]
  node_writer["Writer API<br/>[ExcelWriter.java]"]
end

subgraph group_read["Reading"]
  node_analyser["Read analyser"]
  node_csvread["CSV reader"]
  node_xlsread["XLS reader"]
  node_xlsrecords["XLS record handlers"]
  node_xlsxread["XLSX reader"]
  node_xlsxcell["XLSX cell parser"]
  node_sharedstrings["Shared strings"]
  node_cache[("Read cache<br/>[ReadCache.java]")]
  node_readprocessor["Read event processor"]
  node_listeners["Read listeners"]
end

subgraph group_write["Writing"]
  node_writerbuilder["Write builder"]
  node_writecontext["Write context<br/>[WriteContext.java]"]
  node_writeholders["Workbook and sheet state"]
  node_fill["Template fill"]
  node_writehandlers["Write handlers"]
  node_cellhandler["Cell handler contract"]
  node_cellcontext["Cell write context"]
  node_fillstyle["Fill style handler"]
  node_chain["Handler execution chain"]
  node_writecore["Write context contract<br/>[WriteContext.java]"]
end

subgraph group_model["Data and conversion"]
  node_metadata["Cell and head metadata<br/>[Cell.java]"]
  node_celldata["Read/write cell data<br/>[WriteCellData.java]"]
  node_converters["Type converters"]
  node_formattypes["Cell type mapping"]
  node_xmlconstants["Excel XML constants"]
end

node_app(("Application"))

node_app -->|"configures"| node_api
node_app -->|"builds reader"| node_reader
node_app -->|"writes data"| node_writer
node_xlsxcell -->|"uses tags"| node_xmlconstants
node_xlsxcell -->|"maps cell type"| node_formattypes
node_xlsxcell -->|"creates cell data"| node_celldata
node_xlsxcell -->|"looks up strings"| node_cache
node_sharedstrings -->|"uses cache"| node_cache
node_xlsrecords -->|"handles records"| node_xlsread
node_cellcontext -->|"carries context"| node_writecore
node_cellcontext -->|"supports style fill"| node_fillstyle
node_fillstyle -->|"creates cell style"| node_writeholders
node_cellhandler -->|"accepts context"| node_cellcontext
node_chain -->|"dispatches handlers"| node_cellhandler
node_writecore -->|"exposes holders"| node_writeholders
node_writer -.->|"delegates writing"| node_writerbuilder
node_reader -.->|"starts analysis"| node_analyser
node_analyser -.->|"selects format reader"| node_csvread
node_analyser -.->|"selects format reader"| node_xlsread
node_analyser -.->|"selects format reader"| node_xlsxread
node_readprocessor -.->|"dispatches events"| node_listeners
node_writerbuilder -.->|"uses write context"| node_writecore
node_writehandlers -.->|"provides handlers"| node_cellhandler
node_writerbuilder -.->|"supports template fill"| node_fill
node_converters -.->|"converts values"| node_celldata

click node_api "https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/EasyExcel.java"
click node_reader "https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/read/builder/ExcelReaderBuilder.java"
click node_writer "https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/ExcelWriter.java"
click node_analyser "https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/analysis/ExcelAnalyserImpl.java"
click node_csvread "https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/analysis/csv/CsvExcelReadExecutor.java"
click node_xlsread "https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/analysis/v03/XlsSaxAnalyser.java"
click node_xlsrecords "https://github.com/alibaba/easyexcel/tree/master/easyexcel-core/src/main/java/com/alibaba/excel/analysis/v03/handlers"
click node_xlsxread "https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/analysis/v07/XlsxSaxAnalyser.java"
click node_xlsxcell "https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/analysis/v07/handlers/CellTagHandler.java"
click node_sharedstrings "https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/analysis/v07/handlers/sax/SharedStringsTableHandler.java"
click node_cache "https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/cache/ReadCache.java"
click node_readprocessor "https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/read/processor/DefaultAnalysisEventProcessor.java"
click node_listeners "https://github.com/alibaba/easyexcel/tree/master/easyexcel-core/src/main/java/com/alibaba/excel/read/listener"
click node_writerbuilder "https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/write/ExcelBuilderImpl.java"
click node_writecontext "https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/context/WriteContext.java"
click node_writeholders "https://github.com/alibaba/easyexcel/tree/master/easyexcel-core/src/main/java/com/alibaba/excel/write/metadata/holder"
click node_fill "https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/write/executor/ExcelWriteFillExecutor.java"
click node_writehandlers "https://github.com/alibaba/easyexcel/tree/master/easyexcel-core/src/main/java/com/alibaba/excel/write/handler"
click node_cellhandler "https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/write/handler/CellWriteHandler.java"
click node_cellcontext "https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/write/handler/context/CellWriteHandlerContext.java"
click node_fillstyle "https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/write/handler/impl/FillStyleCellWriteHandler.java"
click node_chain "https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/write/handler/chain/CellHandlerExecutionChain.java"
click node_metadata "https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/metadata/Cell.java"
click node_celldata "https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/metadata/data/WriteCellData.java"
click node_converters "https://github.com/alibaba/easyexcel/tree/master/easyexcel-core/src/main/java/com/alibaba/excel/converters"
click node_formattypes "https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/enums/CellDataTypeEnum.java"
click node_writecore "https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/context/WriteContext.java"
click node_xmlconstants "https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/constant/ExcelXmlConstants.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_reader,node_writer toneBlue
class node_analyser,node_csvread,node_xlsread,node_xlsrecords,node_xlsxread,node_xlsxcell,node_sharedstrings,node_cache,node_readprocessor,node_listeners toneAmber
class node_writerbuilder,node_writecontext,node_writeholders,node_fill,node_writehandlers,node_cellhandler,node_cellcontext,node_fillstyle,node_chain,node_writecore toneMint
class node_metadata,node_celldata,node_converters,node_formattypes,node_xmlconstants toneRose
class node_app toneIndigo
```

## Components

### Public API

- [Read/write API](https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/EasyExcel.java): `easyexcel-core/src/main/java/com/alibaba/excel/EasyExcel.java`
- [Reader builder](https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/read/builder/ExcelReaderBuilder.java): `easyexcel-core/src/main/java/com/alibaba/excel/read/builder/ExcelReaderBuilder.java`
- [Writer API](https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/ExcelWriter.java): `easyexcel-core/src/main/java/com/alibaba/excel/ExcelWriter.java`

### Reading

- [Read analyser](https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/analysis/ExcelAnalyserImpl.java): `easyexcel-core/src/main/java/com/alibaba/excel/analysis/ExcelAnalyserImpl.java`
- [CSV reader](https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/analysis/csv/CsvExcelReadExecutor.java): `easyexcel-core/src/main/java/com/alibaba/excel/analysis/csv/CsvExcelReadExecutor.java`
- [XLS reader](https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/analysis/v03/XlsSaxAnalyser.java): `easyexcel-core/src/main/java/com/alibaba/excel/analysis/v03/XlsSaxAnalyser.java`
- [XLS record handlers](https://github.com/alibaba/easyexcel/tree/master/easyexcel-core/src/main/java/com/alibaba/excel/analysis/v03/handlers): `easyexcel-core/src/main/java/com/alibaba/excel/analysis/v03/handlers`
- [XLSX reader](https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/analysis/v07/XlsxSaxAnalyser.java): `easyexcel-core/src/main/java/com/alibaba/excel/analysis/v07/XlsxSaxAnalyser.java`
- [XLSX cell parser](https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/analysis/v07/handlers/CellTagHandler.java): `easyexcel-core/src/main/java/com/alibaba/excel/analysis/v07/handlers/CellTagHandler.java`
- [Shared strings](https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/analysis/v07/handlers/sax/SharedStringsTableHandler.java): `easyexcel-core/src/main/java/com/alibaba/excel/analysis/v07/handlers/sax/SharedStringsTableHandler.java`
- [Read cache](https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/cache/ReadCache.java): `easyexcel-core/src/main/java/com/alibaba/excel/cache/ReadCache.java`
- [Read event processor](https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/read/processor/DefaultAnalysisEventProcessor.java): `easyexcel-core/src/main/java/com/alibaba/excel/read/processor/DefaultAnalysisEventProcessor.java`
- [Read listeners](https://github.com/alibaba/easyexcel/tree/master/easyexcel-core/src/main/java/com/alibaba/excel/read/listener): `easyexcel-core/src/main/java/com/alibaba/excel/read/listener`

### Writing

- [Write builder](https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/write/ExcelBuilderImpl.java): `easyexcel-core/src/main/java/com/alibaba/excel/write/ExcelBuilderImpl.java`
- [Write context](https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/context/WriteContext.java): `easyexcel-core/src/main/java/com/alibaba/excel/context/WriteContext.java`
- [Workbook and sheet state](https://github.com/alibaba/easyexcel/tree/master/easyexcel-core/src/main/java/com/alibaba/excel/write/metadata/holder): `easyexcel-core/src/main/java/com/alibaba/excel/write/metadata/holder`
- [Template fill](https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/write/executor/ExcelWriteFillExecutor.java): `easyexcel-core/src/main/java/com/alibaba/excel/write/executor/ExcelWriteFillExecutor.java`
- [Write handlers](https://github.com/alibaba/easyexcel/tree/master/easyexcel-core/src/main/java/com/alibaba/excel/write/handler): `easyexcel-core/src/main/java/com/alibaba/excel/write/handler`
- [Cell handler contract](https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/write/handler/CellWriteHandler.java): `easyexcel-core/src/main/java/com/alibaba/excel/write/handler/CellWriteHandler.java`
- [Cell write context](https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/write/handler/context/CellWriteHandlerContext.java): `easyexcel-core/src/main/java/com/alibaba/excel/write/handler/context/CellWriteHandlerContext.java`
- [Fill style handler](https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/write/handler/impl/FillStyleCellWriteHandler.java): `easyexcel-core/src/main/java/com/alibaba/excel/write/handler/impl/FillStyleCellWriteHandler.java`
- [Handler execution chain](https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/write/handler/chain/CellHandlerExecutionChain.java): `easyexcel-core/src/main/java/com/alibaba/excel/write/handler/chain/CellHandlerExecutionChain.java`
- [Write context contract](https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/context/WriteContext.java): `easyexcel-core/src/main/java/com/alibaba/excel/context/WriteContext.java`

### Data and conversion

- [Cell and head metadata](https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/metadata/Cell.java): `easyexcel-core/src/main/java/com/alibaba/excel/metadata/Cell.java`
- [Read/write cell data](https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/metadata/data/WriteCellData.java): `easyexcel-core/src/main/java/com/alibaba/excel/metadata/data/WriteCellData.java`
- [Type converters](https://github.com/alibaba/easyexcel/tree/master/easyexcel-core/src/main/java/com/alibaba/excel/converters): `easyexcel-core/src/main/java/com/alibaba/excel/converters`
- [Cell type mapping](https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/enums/CellDataTypeEnum.java): `easyexcel-core/src/main/java/com/alibaba/excel/enums/CellDataTypeEnum.java`
- [Excel XML constants](https://github.com/alibaba/easyexcel/blob/master/easyexcel-core/src/main/java/com/alibaba/excel/constant/ExcelXmlConstants.java): `easyexcel-core/src/main/java/com/alibaba/excel/constant/ExcelXmlConstants.java`

### Other components

- **Application**

## Connections

- Application → Read/write API: configures (evidence: `README.md`)
- Application → Reader builder: builds reader (evidence: `README.md`)
- Application → Writer API: writes data (evidence: `README.md`)
- XLSX cell parser → Excel XML constants: uses tags (evidence: `easyexcel-core/src/main/java/com/alibaba/excel/analysis/v07/handlers/CellTagHandler.java`)
- XLSX cell parser → Cell type mapping: maps cell type (evidence: `easyexcel-core/src/main/java/com/alibaba/excel/analysis/v07/handlers/CellTagHandler.java`)
- XLSX cell parser → Read/write cell data: creates cell data (evidence: `easyexcel-core/src/main/java/com/alibaba/excel/analysis/v07/handlers/CellTagHandler.java`)
- XLSX cell parser → Read cache: looks up strings (evidence: `easyexcel-core/src/main/java/com/alibaba/excel/analysis/v07/handlers/CellTagHandler.java`)
- Shared strings → Read cache: uses cache (evidence: `easyexcel-core/src/main/java/com/alibaba/excel/analysis/v07/handlers/sax/SharedStringsTableHandler.java`)
- XLS record handlers → XLS reader: handles records
- Cell write context → Write context contract: carries context (evidence: `easyexcel-core/src/main/java/com/alibaba/excel/write/handler/context/CellWriteHandlerContext.java`)
- Cell write context → Fill style handler: supports style fill (evidence: `easyexcel-core/src/main/java/com/alibaba/excel/write/handler/context/CellWriteHandlerContext.java`)
- Fill style handler → Workbook and sheet state: creates cell style (evidence: `easyexcel-core/src/main/java/com/alibaba/excel/write/handler/impl/FillStyleCellWriteHandler.java`)
- Cell handler contract → Cell write context: accepts context (evidence: `easyexcel-core/src/main/java/com/alibaba/excel/write/handler/CellWriteHandler.java`)
- Handler execution chain → Cell handler contract: dispatches handlers (evidence: `easyexcel-core/src/main/java/com/alibaba/excel/write/handler/chain/CellHandlerExecutionChain.java`)
- Write context contract → Workbook and sheet state: exposes holders (evidence: `easyexcel-core/src/main/java/com/alibaba/excel/context/WriteContext.java`)
- Writer API → Write builder: delegates writing
- Reader builder → Read analyser: starts analysis
- Read analyser → CSV reader: selects format reader
- Read analyser → XLS reader: selects format reader
- Read analyser → XLSX reader: selects format reader
- Read event processor → Read listeners: dispatches events
- Write builder → Write context contract: uses write context
- Write handlers → Cell handler contract: provides handlers (evidence: `easyexcel-core/src/main/java/com/alibaba/excel/write/handler/chain/CellHandlerExecutionChain.java`)
- Write builder → Template fill: supports template fill
- Type converters → Read/write cell data: converts values
