apache/fesod/fastexcel-to-fesod-2

FastExcel 1.3 → Apache Fesod Migration Skill

Background

FastExcel (cn.idev.excel:fastexcel:1.3.0) was donated to the Apache Software Foundation and reborn as Apache Fesod (Incubating). The latest stable release is 2.0.1-incubating.

Key facts that affect how this migration works:

• cn.idev.excel.FastExcel and cn.idev.excel.FastExcelFactory are renamed,

but Fesod ships `@Deprecated` bridge subclasses at org.apache.fesod.sheet.FastExcel and org.apache.fesod.sheet.FastExcelFactory so existing call sites compile after a package-only swap.

• The only hard breaking change is the Java package prefix:

any *.excel.* imports must move to *.sheet.*. In practice, both of these are common and must be handled:

• cn.idev.excel.* → org.apache.fesod.sheet.*
• org.apache.fesod.excel.* → org.apache.fesod.sheet.*
• The CGLIB naming tag changed from ByFastExcelCGLIB → ByFesodCGLIB.

This only matters if the project inspects generated class names at runtime.

• All annotation names, method signatures, and processing logic are identical.

The official Fesod migration doc recommends a three-phase gradual approach; this skill implements all three phases in one pass, but each phase is clearly labelled so the developer can stop after Phase 1 or Phase 2 if needed.

Phase 1 — Dependency swap (REQUIRED, zero code changes)

This phase alone is sufficient to make the project compile and run on Fesod with deprecation warnings. It is always safe to stop here first and run tests.

1a. Maven — single-module project

In pom.xml, find the FastExcel dependency block:

<dependency>
    <groupId>cn.idev.excel</groupId>
    <artifactId>fastexcel</artifactId>
    <version>...</version>
</dependency>

Replace it with:

<dependency>
    <groupId>org.apache.fesod</groupId>
    <artifactId>fesod-sheet</artifactId>
    <version>2.0.1-incubating</version>
</dependency>

Also remove the FastExcel version property if it exists, e.g.:

<fastexcel.version>1.3.0</fastexcel.version>

1b. Gradle

In build.gradle (or build.gradle.kts), replace:

// Groovy DSL
implementation 'cn.idev.excel:fastexcel:1.3.0'

with:

implementation 'org.apache.fesod:fesod-sheet:2.0.1-incubating'

Kotlin DSL:

implementation("org.apache.fesod:fesod-sheet:2.0.1-incubating")

Phase 2 — Package import rename (REQUIRED for compilation)

After swapping the dependency, any import under *.excel.* can be unresolved. Apply the following substitutions to every .java file in the project.

Process the table top-to-bottom (most specific first) to avoid partial replacements.

2x. Scope guardrails (IMPORTANT)

To avoid accidental regressions, apply replacements only in migration-relevant code.

• ✅ Safe targets:
• import ... lines under cn.idev.excel.* / org.apache.fesod.excel.*
• static call sites such as FastExcel.read( / FastExcel.write( / FastExcelFactory.*(
• ❌ Do not bulk-replace whole files or whole repositories for FastExcel text.
• ❌ Do not modify business literals unless explicitly requested:
• @ExcelProperty("...") labels
• sheet names / file names / i18n text
• controller response strings
• ❌ Do not rewrite comments/Javadoc as part of mechanical migration.

If you use scripted replacement, constrain the pattern to imports and call expressions, then review diffs before running tests.

2a0. Pre-migrated namespace cleanup (very common)

Some repositories are already partially migrated and use org.apache.fesod.excel.* while still depending on older artifacts. After moving to fesod-sheet, these imports must be rewritten to org.apache.fesod.sheet.*.

Apply this explicit replacement before the detailed mapping table:

Then continue with the specific import mappings below.

2a. Core entry classes

Note: After this phase, FastExcel.read(...) and FastExcelFactory.writerSheet(...)

still compile — they resolve to the @Deprecated bridge classes in Fesod.

Phase 3 replaces them with the canonical FesodSheet class.

2b. Read API

2c. Write API

2d. Write handlers

2e. Annotations

2f. Converters