# AutoPOI wraps Apache POI so an Excel export is one call and an annotation

> AutoPOI is a Java library from the JeecgBoot project that puts a layer of annotations and utility classes over Apache POI, so an entity with an Excel annotation can be exported or imported in a few lines. It ships three artifacts for plain Java, Spring Boot 2 and Spring Boot 3, and a template expression language for Word and Excel templates.

**jeecgboot/autopoi** — AutoPOI is an intelligent wrapper around POI that simplifies API usage.  AutoPOI是对POI的智能化封装，简化API使用，通过极简代码实现Excel导入导出和Word模板导出，帮助无基础用户轻松自动化处理文档。

- Repository: https://github.com/jeecgboot/autopoi
- Website: http://www.jeecg.com
- Stars: 553 · Forks: 229
- Language: Java
- License: Apache-2.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/jeecgboot-autopoi

## The premise: a POI wrapper for people who have not used POI

AutoPOI is described as an intelligent wrapper around POI that simplifies API usage, and the stated goal is that a person who has never touched POI can quickly implement Excel import and export, Word template export, in as few as five lines of code.

That framing is worth taking seriously because it dictates the whole API shape. Apache POI is powerful and sprawling, and its two APIs, HSSF for the older xls format and XSSF for xlsx, differ enough that even experienced users end up writing wrapper code of their own. AutoPOI is that wrapper, published as a library so that everybody does not have to write it.

The four design points the README lists are, translated from the Chinese, design that is refined and simple to use, an interface set that is rich and simple to extend, many default values so that you write less and do more, and support for AbstractView so that web export is straightforward.

The repository is a Maven multi-module project under the jeecgboot organisation, with a homepage of jeecg.com, and the group id is org.jeecgframework. The topics name both poi and easypoi, and the description also names easyexcel, so the lineage runs through the EasyPOI and EasyExcel projects.

The primary language is Java, the licence is Apache-2.0, the default branch is master, and the last push was on 2026-10-12. The recent releases listed are 2.0.4 from 2026-07-09, v1.4.18 from 2025-10-09 with the note that it moves fully to Spring Boot 3, and 1.4.14 from 2025-07-31. The README's own version line says the current latest is 2.0.5 with a release date of 2026-07-09, which is one patch ahead of the newest tag in the list, so the numbers are not perfectly aligned.

## Three entry classes, and what each one covers

The library exposes three utility classes, and they are the entire surface a user has to learn.

ExcelExportUtil handles Excel export, both the ordinary export and the template export. ExcelImportUtil handles Excel import. WordExportUtil handles Word export, and the README is specific about its limits: it supports docx only, because POI has an image bug in the older doc version and that format is therefore not supported for now.

That restriction is the kind of detail that only appears in documentation written by someone who hit it, and it has a practical consequence. A Word template export feature that quietly produces nothing for .doc inputs would be much worse than one that says so.

The three classes map onto three different jobs. An ordinary export takes a list of objects and writes a spreadsheet with generated column headers from the annotations. A template export takes a template file and a map of data and fills it in, which is how you produce a fixed-layout document. An import takes a file or a stream and returns a list of entities, optionally with validation.

Around those three, the library adds the pieces that make them usable in a web application. There are Spring MVC views, so an export endpoint is a controller method returning a ModelAndView rather than a hand-written response writer. There is a validation layer on import, which filters rows that break the rules and appends the error information back into an Excel file.

There is also a dictionary mechanism, which in this ecosystem means resolving a code to a display label at export time and back to a code at import time, either against a data dictionary entry identified by dicCode or against a database table identified by dictTable with a dicCode field and a dicText field naming the column to display. That is a feature aimed squarely at Chinese enterprise systems, where a column stores a code and the user sees a label, and it is one of the things that makes this library different from a general POI wrapper.

## Three Maven artifacts, because the servlet namespace split is real

The dependency configuration is where a Java developer starts, and the README gives three separate dependency blocks.

For a plain Java project with no Spring:

```xml
<dependency>
 <groupId>org.jeecgframework</groupId>
 <artifactId>autopoi</artifactId>
 <version>2.0.5</version>
</dependency>
```

For Spring Boot 2.x, the artifact is autopoi-spring-boot-2-starter, and for Spring Boot 3.x it is autopoi-spring-boot-3-starter, each with the same 2.0.5 version. The reason for the split is named directly in the project description: the 2.x starter is compatible with javax.servlet and the 3.x starter with jakarta.servlet.

That split is the Jakarta EE namespace migration showing up in a dependency tree. When the servlet APIs were renamed from javax to jakarta, a library that implements a servlet view had to be rebuilt against the new packages, and rather than shipping one artifact with reflection or a compatibility layer, this project ships two. For a team upgrading Boot 2 to Boot 3 that is the kind of detail that decides whether the upgrade is a version bump or a fortnight.

The version_info style of pinning is not used here; the README gives literal 2.0.5 coordinates, which means a project that copies them is on a fixed patch release rather than on a range.

The five modules listed in the README are autopoi-parent, the parent POM, autopoi itself for the import and export tooling, and the two Spring Boot starters.

## The template expression language, and the annotation vocabulary

Two mechanisms cover most of what the library does, and they are quite different in style.

The template expression language is a set of markers embedded in a template document. The list in the README is worth reading in full because it is a small DSL. Space separates parts of an expression. A ternary is written {{test ? obj:obj2}}. The prefix n: marks a cell as numeric, written {{n:}}. The prefix le: gives a length, used inside an if or else, for example {{le:() > 8 ? obj1 : obj2}}. The prefix fd: formats a date, {{fd:(obj;yyyy-MM-dd)}}, and fn: formats a number, {{fn:(obj;###.00)}}. The prefix fe: iterates over data and creates a row, !fe: iterates without creating a row, and $fe: shifts the current row down by the size of the collection and inserts there. The prefix !if: deletes the current column, {{!if:(test)}}. And a single quote marks a literal value, so '1' outputs 1 rather than being interpreted.

The annotation vocabulary is the other half, and it is what makes the export calls one line. The example entity uses an ExcelTarget at class level to name the export target, an Excel annotation on each field for the column name, order number and merge behaviour, an ExcelEntity annotation on a field to declare a nested entity relation with an id, and an ExcelCollection on a list field to export a collection as rows.

Given that annotation set, the basic export is:

Three arguments: the export parameters, the class, and the list. Adding an index column to the output is params.setAddIndex(true) on the same object.

The import side mirrors it. You set the number of title rows and head rows on ImportParams, optionally the sheet number, and pass a file and the entity class:

```Java
	ImportParams params = new ImportParams();
	List<Map<String,Object>> list = ExcelImportUtil.importExcel(new File(
			"d:/tt.xls"), Map.class, params);
```

That last one is the Map import, which is the exception to the annotation-first design: it returns maps instead of typed objects and needs no entity class, and the README notes that a custom key requires implementing the IExcelDataHandler interface.

## XLS versus XLSX, and the optional dependencies that keep the tree small

The README has a short section comparing the two Excel formats, and it is the kind of guidance you only get from someone who has exported enough spreadsheets to care.

Exporting to XLS is two to three times faster than exporting to XLSX. Exporting to XLS produces a file two to three times larger than XLSX, or more. And the practical choice depends on balancing network speed against local speed.

The trade is therefore explicit: the old binary format is faster to write and larger on the wire, while the newer zip-based format is slower and smaller. For a user on a slow connection downloading a large export, XLSX wins despite being slower to produce. For a server generating many exports, XLS wins on CPU. That is a decision the library leaves to you, which is right, but it means the format parameter is a real choice rather than a default to accept.

The optional dependency arrangement is the other thing to notice. The README says that the SAX import uses the xercesImpl package, which may cause odd problems, and that Word export uses poi-scratchpad, and that both have been made optional packages. So the base artifact does not drag in an XML parser implementation known to misbehave, nor the scratchpad layer Word export needs. You add them when you need them.

The repository root also carries a Chinese-language note on upgrading to POI 5, another on the packaging build, plus deploy.bat and install.bat scripts and a docs/ directory. The presence of a POI 5 upgrade note in the root tells you the underlying POI version was a major one at some point, which is the kind of migration that produces exactly the kind of compatibility work the two Spring Boot starters represent.

Word export is built on poi-scratchpad and supports only docx, and it uses the same template mechanism as the Excel template export, with the template expression language described above applying to the placeholders in the Word document.

## Where AutoPOI is the wrong choice

Three limits, and the first is about the cost of the abstraction.

The first is that you are choosing an ecosystem, not just a library. AutoPOI is part of the JeecgBoot world, and while the plain autopoi artifact has no Spring dependency, the parts that make it pleasant, the dictionary resolution, the MVC export views, the validation results written back into Excel, all assume a JeecgBoot-style application with a data dictionary and a particular entity layout. Using it in an unrelated Spring application gets you the POI convenience and little else, and you are then paying for a dependency whose ecosystem you have not adopted.

The second is the format and version churn. The underlying POI has had a major version bump that the repository documents, the library has had its own major version bumps, and the recent release list shows a jump from the 1.4.x line to 2.0.x with a separate Spring Boot 3 line appearing in between. The v1.4.18 release note says it moves fully to Spring Boot 3, and then 2.0.x follows. For a library whose job is to sit on top of POI, the churn in POI itself is passed straight through to you.

The third is what the wrapper does not do. The list of features stops at import, export, templates, validation and the MVC views. There is no charting, no pivot tables, no formula evaluation, no streaming for very large files beyond the SAX import, and no document merge. If your requirement is generating a workbook with formulas that Excel recalculates, or a pivot summary, or a chart, you are back to using POI directly for that part, at which point you have two libraries doing the same job.

The alternative approach is to use Apache POI directly, or to use EasyExcel, which the topics list names and which takes a different approach to the same problem with a streaming model built around a listener interface. The difference in approach is that AutoPOI optimises for the smallest possible amount of code, which is the right trade for an internal enterprise system where a report is written once and read by a colleague, while EasyExcel optimises for memory use on very large files, which is the right trade for a data export that must handle millions of rows. The same annotation-driven idea appears in both, so the migration between them is mostly a change of import and of the export call signature.

## Conclusion

Adopt AutoPOI if your Java service needs Excel import and export and you want annotations on your entities rather than hand-built column lists, because the export call takes the class and the data and works out the rest, and the three separate artifacts mean you pick the starter that matches your servlet namespace. Do not adopt it if you need Word export of the older doc format, since the README states that doc is not supported because POI has an image bug in that version, and do not assume the latest version number in the README matches the newest tag, because the README says 2.0.5 while the tagged releases list stops at 2.0.4. Verify first that the artifactId matches your Spring Boot major version, javax.servlet or jakarta.servlet, that the export format you need is the one your users can open, since the README says XLS exports two to three times faster and two to three times larger than XLSX, and that the optional SAX and poi-scratchpad dependencies are present if you use streaming import or Word export.

## FAQ

### What is AutoPOI and what does it simplify?

It is a Java library that wraps Apache POI so that Excel import, Excel export and Word template export can be done in as few as five lines of code by someone who has not used POI. It offers rich but extensible interfaces, many default values, and AbstractView support so web export is straightforward.

### Which Maven dependency should I use for AutoPOI?

Use org.jeecgframework artifact autopoi-spring-boot-2-starter for Spring Boot 2.x, autopoi-spring-boot-3-starter for Spring Boot 3.x, or plain autopoi for a Java project with no Spring, each at version 2.0.5. The two starters differ because the 2.x one is compatible with javax.servlet and the 3.x one with jakarta.servlet.

### Does AutoPOI support Word documents in the old doc format?

No. Word export supports docx only, because the older doc version has an image bug in POI and is therefore not supported for now. Word export uses the poi-scratchpad package, which is an optional dependency you add yourself.

### How do I export Excel from an entity in AutoPOI?

Annotate the class with ExcelTarget, put Excel annotations with a name and order number on the fields, add ExcelEntity for nested objects and ExcelCollection for lists, then call ExcelExportUtil.exportExcel with an ExportParams object, the entity class and your list. Setting setAddIndex(true) on the params adds an index column.

### What template expressions does AutoPOI support?

Space separates expression parts, a ternary is written {{test ? obj:obj2}}, n: marks a numeric cell, le: gives a length for use in a condition, fd: formats a date, fn: formats a number, fe: iterates and creates rows, !fe: iterates without creating rows, $fe: shifts rows down and inserts, !if: deletes the current column, and single quotes mark literal values.

### Should I export XLS or XLSX with AutoPOI?

The README says XLS export is two to three times faster than XLSX and produces a file two to three times larger or more, so the choice depends on balancing network speed against local speed. XLSX is smaller on the wire, XLS is cheaper to produce on the server.

## Sources

- [jeecgboot/autopoi on GitHub](https://github.com/jeecgboot/autopoi)
- [License: Apache-2.0](https://github.com/jeecgboot/autopoi/blob/master/LICENSE)
- [Project website](http://www.jeecg.com)
- [README](https://github.com/jeecgboot/autopoi/blob/master/README.md)
- [Releases](https://github.com/jeecgboot/autopoi/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jeecgboot-autopoi