Skip to content

Commit 5fb72f7

Browse files
bengbengbalabalabengdelei
bengbengbalabalabeng
and
delei
authored
docs: add blog for migration with OpenRewrite (#910)
* docs(blog): add blog for migration with OpenRewrite * fix: correct Apache Fesod to Apache Fesod (Incubating) --------- Co-authored-by: DeleiGuo <delei@apache.org>
1 parent 6374a8c commit 5fb72f7

2 files changed

Lines changed: 428 additions & 0 deletions

File tree

‎website/blog/2026-05-07-migration-from-fastexcel-with-openrewrite.md‎

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
---
2+
title: "Automated Migration from FastExcel 1.3.0 to Apache Fesod (Incubating) with OpenRewrite"
3+
description: Migrate FastExcel 1.3 to Apache Fesod (Incubating) 2.0.1-incubating
4+
authors: [bengbengbalabalabeng]
5+
tags: [migration, fastexcel, fesod]
6+
---
7+
8+
> This article demonstrates how to write a declarative OpenRewrite recipe that migrates your project from `cn.idev.excel:fastexcel:1.3.0` to `org.apache.fesod:fesod-sheet:2.0.1-incubating`, covering both Maven and Gradle builds.
9+
10+
<!--truncate-->
11+
12+
## Background
13+
14+
FastExcel (`cn.idev.excel`) has been donated to the Apache Software Foundation and is now incubating as **Apache Fesod (Incubating)**. The core change is a **Java package path replacement** — the API, annotations, and processing logic remain identical, making this a low-risk, mechanical refactoring.
15+
16+
For the official migration strategy, see: [https://fesod.apache.org/docs/migration/from-fastexcel/](https://fesod.apache.org/docs/migration/from-fastexcel/)
17+
18+
Manually replacing imports file by file is tedious and error-prone. OpenRewrite provides AST-level code transformation capabilities to perform this kind of bulk migration precisely and safely.
19+
20+
## Migration Scope
21+
22+
1. Update Maven/Gradle dependencies
23+
2. Replace deprecated class names with `FesodSheet`
24+
3. Update package imports
25+
26+
## Writing the OpenRewrite Recipe
27+
28+
Create a `rewrite.yml` file in your project root:
29+
30+
```yaml
31+
---
32+
type: specs.openrewrite.org/v1beta/recipe
33+
name: org.apache.fesod.MigrateFastExcelToFesod
34+
displayName: Migrate FastExcel 1.3 to Apache Fesod (Incubating) 2.0.1-incubating
35+
recipeList:
36+
37+
# Step 1: Update Dependencies (Maven & Gradle)
38+
- org.openrewrite.maven.ChangeDependencyGroupIdAndArtifactId:
39+
oldGroupId: cn.idev.excel
40+
oldArtifactId: fastexcel
41+
newGroupId: org.apache.fesod
42+
newArtifactId: fesod-sheet
43+
newVersion: 2.0.1-incubating
44+
- org.openrewrite.gradle.ChangeDependency:
45+
oldGroupId: cn.idev.excel
46+
oldArtifactId: fastexcel
47+
newGroupId: org.apache.fesod
48+
newArtifactId: fesod-sheet
49+
newVersion: 2.0.1-incubating
50+
51+
# Step 2: Package Import Updates
52+
- org.openrewrite.java.ChangePackage:
53+
oldPackageName: cn.idev.excel
54+
newPackageName: org.apache.fesod.sheet
55+
recursive: true
56+
- org.openrewrite.java.ChangePackage:
57+
oldPackageName: org.apache.fesod.excel
58+
newPackageName: org.apache.fesod.sheet
59+
recursive: true
60+
61+
# Step 3: Entry Class Rename
62+
- org.openrewrite.java.ChangeType:
63+
oldFullyQualifiedTypeName: org.apache.fesod.sheet.FastExcel
64+
newFullyQualifiedTypeName: org.apache.fesod.sheet.FesodSheet
65+
- org.openrewrite.java.ChangeType:
66+
oldFullyQualifiedTypeName: org.apache.fesod.sheet.FastExcelFactory
67+
newFullyQualifiedTypeName: org.apache.fesod.sheet.FesodSheet
68+
69+
- org.openrewrite.text.FindAndReplace:
70+
find: ByFastExcelCGLIB
71+
replace: ByFesodCGLIB
72+
filePattern: "**/*.java"
73+
```
74+
75+
### How It Works
76+
77+
The recipe executes steps sequentially in declaration order:
78+
79+
**Step 1 — Update Dependencies**: The first rule updates `pom.xml` for Maven projects; the second rule updates `build.gradle` / `build.gradle.kts` for Gradle projects. If your project uses only one build tool, the other rule is silently skipped.
80+
81+
**Step 2 — Package Import Updates**: `ChangePackage(recursive=true)` covers all sub-packages under `cn.idev.excel` (annotation, read, write, converters, enums, etc.) in a single rule — no need to enumerate each one individually. The second rule handles legacy code that was already partially migrated to `org.apache.fesod.excel`. After this step, imports like `cn.idev.excel.FastExcel` become `org.apache.fesod.sheet.FastExcel` (the `@Deprecated` bridge class in Fesod).
82+
83+
**Step 3 — Entry Class Rename**: Once Step 2 completes, all `FastExcel` and `FastExcelFactory` imports are unified under `org.apache.fesod.sheet`. Only two `ChangeType` rules are needed to rename them to the canonical `FesodSheet` class, automatically updating all call sites (`FastExcel.read()`, `FastExcel.write()`, etc.) and type references (variable declarations, class literals).
84+
85+
**Step 4 — CGLIB String Replacement**: Only affects code that references CGLIB-generated class names at runtime. Most projects don't need this step — the rule is silently skipped if there's no match.
86+
87+
## Adding OpenRewrite to Your Project
88+
89+
### Maven
90+
91+
Add the plugin to `pom.xml`:
92+
93+
```xml
94+
<plugin>
95+
<groupId>org.openrewrite.maven</groupId>
96+
<artifactId>rewrite-maven-plugin</artifactId>
97+
<version>6.38.0</version>
98+
<configuration>
99+
<activeRecipes>
100+
<recipe>org.apache.fesod.MigrateFastExcelToFesod</recipe>
101+
</activeRecipes>
102+
</configuration>
103+
</plugin>
104+
```
105+
106+
### Gradle (Groovy)
107+
108+
Add to `build.gradle`:
109+
110+
```groovy
111+
plugins {
112+
id 'java'
113+
id 'maven-publish'
114+
id 'org.openrewrite.rewrite' version '7.32.2'
115+
}
116+
117+
rewrite {
118+
activeRecipe(
119+
'org.apache.fesod.MigrateFastExcelToFesod',
120+
)
121+
}
122+
```
123+
124+
### Gradle (Kotlin)
125+
126+
Add to `build.gradle.kts`:
127+
128+
```kotlin
129+
plugins {
130+
`java-library`
131+
`maven-publish`
132+
id("org.openrewrite.rewrite") version "7.32.2"
133+
}
134+
135+
rewrite {
136+
activeRecipe(
137+
"org.apache.fesod.MigrateFastExcelToFesod",
138+
)
139+
}
140+
```
141+
142+
## Running the Migration
143+
144+
### Preview Changes
145+
146+
View what the recipe would change without modifying files:
147+
148+
```bash
149+
# Maven
150+
# Output: target/site/rewrite/rewrite.patch
151+
mvn rewrite:dryRun
152+
153+
# Gradle
154+
# Output: build/reports/rewrite/rewrite.patch
155+
gradle rewriteDryRun
156+
```
157+
158+
### Apply Changes
159+
160+
Once satisfied with the preview, apply the changes:
161+
162+
```bash
163+
# Maven
164+
mvn rewrite:run
165+
166+
# Gradle
167+
gradle rewriteRun
168+
```
169+
170+
### Verify
171+
172+
```bash
173+
# Compile check
174+
mvn compile
175+
# or
176+
gradle compileJava
177+
178+
# Run tests
179+
mvn test
180+
# or
181+
gradle test
182+
```
183+
184+
## Before and After
185+
186+
Before migration:
187+
188+
```java
189+
import cn.idev.excel.FastExcel;
190+
import cn.idev.excel.annotation.ExcelProperty;
191+
import cn.idev.excel.read.listener.ReadListener;
192+
193+
FastExcel.write(outputStream, BookData.class)
194+
.sheet("Sheet1")
195+
.doWrite(data());
196+
```
197+
198+
After migration:
199+
200+
```java
201+
import org.apache.fesod.sheet.FesodSheet;
202+
import org.apache.fesod.sheet.annotation.ExcelProperty;
203+
import org.apache.fesod.sheet.read.listener.ReadListener;
204+
205+
FesodSheet.write(outputStream, BookData.class)
206+
.sheet("Sheet1")
207+
.doWrite(data());
208+
```
209+
210+
## References
211+
212+
- Apache Fesod (Incubating) Official Migration Guide: [https://fesod.apache.org/docs/migration/from-fastexcel/](https://fesod.apache.org/docs/migration/from-fastexcel/)
213+
- OpenRewrite Documentation: [https://docs.openrewrite.org/](https://docs.openrewrite.org/)
214+
- OpenRewrite Recipe Reference: [https://docs.openrewrite.org/recipes](https://docs.openrewrite.org/recipes)

0 commit comments

Comments
 (0)