diff --git a/website/blog/2026-05-07-migration-from-fastexcel-with-openrewrite.md b/website/blog/2026-05-07-migration-from-fastexcel-with-openrewrite.md new file mode 100644 index 000000000..f6979d06c --- /dev/null +++ b/website/blog/2026-05-07-migration-from-fastexcel-with-openrewrite.md @@ -0,0 +1,214 @@ +--- +title: "Automated Migration from FastExcel 1.3.0 to Apache Fesod (Incubating) with OpenRewrite" +description: Migrate FastExcel 1.3 to Apache Fesod 2.0.1-incubating +authors: [bengbengbalabalabeng] +tags: [migration, fastexcel, fesod] +--- + +> 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. + + + +## Background + +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. + +For the official migration strategy, see: [https://fesod.apache.org/docs/migration/from-fastexcel/](https://fesod.apache.org/docs/migration/from-fastexcel/) + +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. + +## Migration Scope + +1. Update Maven/Gradle dependencies +2. Replace deprecated class names with `FesodSheet` +3. Update package imports + +## Writing the OpenRewrite Recipe + +Create a `rewrite.yml` file in your project root: + +```yaml +--- +type: specs.openrewrite.org/v1beta/recipe +name: org.apache.fesod.MigrateFastExcelToFesod +displayName: Migrate FastExcel 1.3 to Apache Fesod 2.0.1-incubating +recipeList: + + # Step 1: Update Dependencies (Maven & Gradle) + - org.openrewrite.maven.ChangeDependencyGroupIdAndArtifactId: + oldGroupId: cn.idev.excel + oldArtifactId: fastexcel + newGroupId: org.apache.fesod + newArtifactId: fesod-sheet + newVersion: 2.0.1-incubating + - org.openrewrite.gradle.ChangeDependency: + oldGroupId: cn.idev.excel + oldArtifactId: fastexcel + newGroupId: org.apache.fesod + newArtifactId: fesod-sheet + newVersion: 2.0.1-incubating + + # Step 2: Package Import Updates + - org.openrewrite.java.ChangePackage: + oldPackageName: cn.idev.excel + newPackageName: org.apache.fesod.sheet + recursive: true + - org.openrewrite.java.ChangePackage: + oldPackageName: org.apache.fesod.excel + newPackageName: org.apache.fesod.sheet + recursive: true + + # Step 3: Entry Class Rename + - org.openrewrite.java.ChangeType: + oldFullyQualifiedTypeName: org.apache.fesod.sheet.FastExcel + newFullyQualifiedTypeName: org.apache.fesod.sheet.FesodSheet + - org.openrewrite.java.ChangeType: + oldFullyQualifiedTypeName: org.apache.fesod.sheet.FastExcelFactory + newFullyQualifiedTypeName: org.apache.fesod.sheet.FesodSheet + + - org.openrewrite.text.FindAndReplace: + find: ByFastExcelCGLIB + replace: ByFesodCGLIB + filePattern: "**/*.java" +``` + +### How It Works + +The recipe executes steps sequentially in declaration order: + +**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. + +**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). + +**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). + +**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. + +## Adding OpenRewrite to Your Project + +### Maven + +Add the plugin to `pom.xml`: + +```xml + + org.openrewrite.maven + rewrite-maven-plugin + 6.38.0 + + + org.apache.fesod.MigrateFastExcelToFesod + + + +``` + +### Gradle (Groovy) + +Add to `build.gradle`: + +```groovy +plugins { + id 'java' + id 'maven-publish' + id 'org.openrewrite.rewrite' version '7.32.2' +} + +rewrite { + activeRecipe( + 'org.apache.fesod.MigrateFastExcelToFesod', + ) +} +``` + +### Gradle (Kotlin) + +Add to `build.gradle.kts`: + +```kotlin +plugins { + `java-library` + `maven-publish` + id("org.openrewrite.rewrite") version "7.32.2" +} + +rewrite { + activeRecipe( + "org.apache.fesod.MigrateFastExcelToFesod", + ) +} +``` + +## Running the Migration + +### Preview Changes + +View what the recipe would change without modifying files: + +```bash +# Maven +# Output: target/site/rewrite/rewrite.patch +mvn rewrite:dryRun + +# Gradle +# Output: build/reports/rewrite/rewrite.patch +gradle rewriteDryRun +``` + +### Apply Changes + +Once satisfied with the preview, apply the changes: + +```bash +# Maven +mvn rewrite:run + +# Gradle +gradle rewriteRun +``` + +### Verify + +```bash +# Compile check +mvn compile +# or +gradle compileJava + +# Run tests +mvn test +# or +gradle test +``` + +## Before and After + +Before migration: + +```java +import cn.idev.excel.FastExcel; +import cn.idev.excel.annotation.ExcelProperty; +import cn.idev.excel.read.listener.ReadListener; + +FastExcel.write(outputStream, BookData.class) + .sheet("Sheet1") + .doWrite(data()); +``` + +After migration: + +```java +import org.apache.fesod.sheet.FesodSheet; +import org.apache.fesod.sheet.annotation.ExcelProperty; +import org.apache.fesod.sheet.read.listener.ReadListener; + +FesodSheet.write(outputStream, BookData.class) + .sheet("Sheet1") + .doWrite(data()); +``` + +## References + +- Apache Fesod Official Migration Guide: [https://fesod.apache.org/docs/migration/from-fastexcel/](https://fesod.apache.org/docs/migration/from-fastexcel/) +- OpenRewrite Documentation: [https://docs.openrewrite.org/](https://docs.openrewrite.org/) +- OpenRewrite Recipe Reference: [https://docs.openrewrite.org/recipes](https://docs.openrewrite.org/recipes) diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-blog/2026-05-07-migration-from-fastexcel-with-openrewrite.md b/website/i18n/zh-cn/docusaurus-plugin-content-blog/2026-05-07-migration-from-fastexcel-with-openrewrite.md new file mode 100644 index 000000000..5aecc6fad --- /dev/null +++ b/website/i18n/zh-cn/docusaurus-plugin-content-blog/2026-05-07-migration-from-fastexcel-with-openrewrite.md @@ -0,0 +1,214 @@ +--- +title: "使用 OpenRewrite 从 FastExcel 1.3.0 自动迁移到 Apache Fesod (Incubating)" +description: 将 FastExcel 1.3 迁移至 Apache Fesod 2.0.1-incubating +authors: [bengbengbalabalabeng] +tags: [migration, fastexcel, fesod] +--- + +> 本文介绍如何利用 OpenRewrite 编写声明式迁移配置，将项目从 `cn.idev.excel:fastexcel:1.3.0` 迁移至 `org.apache.fesod:fesod-sheet:2.0.1-incubating`，适用于 Maven 与 Gradle 项目。 + + + +## 背景 + +FastExcel（`cn.idev.excel`）已捐赠给 Apache 软件基金会，孵化为 **Apache Fesod (Incubating)**。迁移的核心变化是 **Java 包路径替换**——API、注解和处理逻辑完全一致，属于低风险的机械重构。 + +官方迁移策略参考：[https://fesod.apache.org/docs/migration/from-fastexcel/](https://fesod.apache.org/docs/migration/from-fastexcel/) + +手动逐文件替换 import 既耗时又容易遗漏。OpenRewrite 提供了 AST 级别的代码变换能力，能精确、安全地完成这类批量迁移。 + +## 迁移范围 + +1. 更新 Maven/Gradle 依赖 +2. 将已废弃的类名替换为 `FesodSheet` +3. 更新包导入 + +## 编写 OpenRewrite Recipe + +在项目根目录创建文件 `rewrite.yml`： + +```yaml +--- +type: specs.openrewrite.org/v1beta/recipe +name: org.apache.fesod.MigrateFastExcelToFesod +displayName: Migrate FastExcel 1.3 to Apache Fesod 2.0.1-incubating +recipeList: + + # 步骤 1：更新依赖 (Maven & Gradle) + - org.openrewrite.maven.ChangeDependencyGroupIdAndArtifactId: + oldGroupId: cn.idev.excel + oldArtifactId: fastexcel + newGroupId: org.apache.fesod + newArtifactId: fesod-sheet + newVersion: 2.0.1-incubating + - org.openrewrite.gradle.ChangeDependency: + oldGroupId: cn.idev.excel + oldArtifactId: fastexcel + newGroupId: org.apache.fesod + newArtifactId: fesod-sheet + newVersion: 2.0.1-incubating + + # 步骤 2：更新包导入 + - org.openrewrite.java.ChangePackage: + oldPackageName: cn.idev.excel + newPackageName: org.apache.fesod.sheet + recursive: true + - org.openrewrite.java.ChangePackage: + oldPackageName: org.apache.fesod.excel + newPackageName: org.apache.fesod.sheet + recursive: true + + # 步骤 3：重命名入口类 + - org.openrewrite.java.ChangeType: + oldFullyQualifiedTypeName: org.apache.fesod.sheet.FastExcel + newFullyQualifiedTypeName: org.apache.fesod.sheet.FesodSheet + - org.openrewrite.java.ChangeType: + oldFullyQualifiedTypeName: org.apache.fesod.sheet.FastExcelFactory + newFullyQualifiedTypeName: org.apache.fesod.sheet.FesodSheet + + - org.openrewrite.text.FindAndReplace: + find: ByFastExcelCGLIB + replace: ByFesodCGLIB + filePattern: "**/*.java" +``` + +### 执行逻辑解析 + +Recipe 按声明顺序依次执行，分为四个步骤： + +**Step 1 — 更新依赖**：Maven 项目触发第一条规则修改 `pom.xml`；Gradle 项目触发第二条规则修改 `build.gradle` / `build.gradle.kts`。如果项目只使用其中一种构建工具，另一条规则自动跳过，不会报错。 + +**Step 2 — 更新包导入**：`ChangePackage(recursive=true)` 一条规则覆盖 `cn.idev.excel` 下所有子包（annotation、read、write、converters、enums 等），无需逐个枚举。第二条规则处理已部分迁移到 `org.apache.fesod.excel` 的遗留代码。这一步会将 `cn.idev.excel.FastExcel` 的 import 改为 `org.apache.fesod.sheet.FastExcel`（Fesod 中的 `@Deprecated` 桥接类）。 + +**Step 3 — 重命名入口类**：Step 2 完成后，所有 `FastExcel` 和 `FastExcelFactory` 的 import 已统一指向 `org.apache.fesod.sheet` 包。此时只需两条 `ChangeType` 规则，将它们改为正式的 `FesodSheet` 类，同时自动处理所有调用点（`FastExcel.read()`、`FastExcel.write()` 等）和类型引用（变量声明、类字面量）。 + +**Step 4 — CGLIB 字符串替换**：仅对引用了 CGLIB 生成类名的代码生效，多数项目不需要此步骤，不匹配则自动跳过。 + +## 在项目中引入 OpenRewrite + +### Maven 项目 + +在 `pom.xml` 中添加插件： + +```xml + + org.openrewrite.maven + rewrite-maven-plugin + 6.38.0 + + + org.apache.fesod.MigrateFastExcelToFesod + + + +``` + +### Gradle (Groovy) + +在 `build.gradle` 中引入： + +```groovy +plugins { + id 'java' + id 'maven-publish' + id 'org.openrewrite.rewrite' version '7.32.2' +} + +rewrite { + activeRecipe( + 'org.apache.fesod.MigrateFastExcelToFesod', + ) +} +``` + +### Gradle (Kotlin) + +```kotlin +plugins { + `java-library` + `maven-publish` + id("org.openrewrite.rewrite") version "7.32.2" +} + +rewrite { + activeRecipe( + "org.apache.fesod.MigrateFastExcelToFesod", + ) +} +``` + +## 执行迁移 + +### 预览变更 + +先查看 Recipe 会产生哪些修改，不实际改动文件： + +```bash +# Maven +# 默认输出路径：target/site/rewrite/rewrite.patch +mvn rewrite:dryRun + +# Gradle +# 默认输出路径：build/reports/rewrite/rewrite.patch +gradle rewriteDryRun +``` + +输出会列出所有即将修改的文件和具体变更内容。 + +### 执行迁移 + +确认无误后，执行实际修改： + +```bash +# Maven +mvn rewrite:run + +# Gradle +gradle rewriteRun +``` + +### 验证 + +```bash +# 编译检查 +mvn compile +# 或 +gradle compileJava + +# 运行测试 +mvn test +# 或 +gradle test +``` + +## 迁移效果示例 + +迁移前： + +```java +import cn.idev.excel.FastExcel; +import cn.idev.excel.annotation.ExcelProperty; +import cn.idev.excel.read.listener.ReadListener; + +FastExcel.write(outputStream, BookData.class) + .sheet("Sheet1") + .doWrite(data()); +``` + +迁移后： + +```java +import org.apache.fesod.sheet.FesodSheet; +import org.apache.fesod.sheet.annotation.ExcelProperty; +import org.apache.fesod.sheet.read.listener.ReadListener; + +FesodSheet.write(outputStream, BookData.class) + .sheet("Sheet1") + .doWrite(data()); +``` + +## 参考 + +- Apache Fesod 官方迁移指南：[https://fesod.apache.org/docs/migration/from-fastexcel/](https://fesod.apache.org/docs/migration/from-fastexcel/) +- OpenRewrite 官方文档：[https://docs.openrewrite.org/](https://docs.openrewrite.org/) +- OpenRewrite Recipe 参考：[https://docs.openrewrite.org/recipes](https://docs.openrewrite.org/recipes)