Skip to content

docs: add class and module changes section to FastExcel migration guide (#857) #1041

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Mikkey-f wants to merge 1 commit into
base: main
Choose a base branch
from
+153 −2
Open

docs: add class and module changes section to FastExcel migration guide (#857) #1041

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 48 additions & 2 deletions .github/skills/fastexcel-to-fesod/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -256,7 +256,35 @@ Then continue with the specific import mappings below.
| `import cn.idev.excel.metadata.Head;` | `import org.apache.fesod.sheet.metadata.Head;` |
| `import cn.idev.excel.metadata.property.ExcelContentProperty;` | `import org.apache.fesod.sheet.metadata.property.ExcelContentProperty;` |

### 2i. Wildcard catch-all (apply last)
### 2i. Renamed helper classes (conditional)

Only if the project references these classes directly (rare — they are
mostly internal). Rename the type and update the import together:

| Find (exact import string) | Replace with |
|---------------------------------------------------------|------------------------------------------------------------------|
| `import cn.idev.excel.constant.FastExcelConstants;` | `import org.apache.fesod.sheet.constant.FesodSheetConstants;` |
| `import cn.idev.excel.util.FastExcelTempFileCreationStrategy;` | `import org.apache.fesod.sheet.util.FesodTempFileCreationStrategy;` |
| `import cn.idev.excel.util.BeanMapUtils;` | `import org.apache.fesod.sheet.util.BeanMapUtils;` + rename usages `BeanMapUtils.FastExcelNamingPolicy` → `BeanMapUtils.FesodSheetNamingPolicy` (the nested class was renamed; the import itself stays `BeanMapUtils`) |

### 2j. Utility classes moved to fesod-common (conditional)

FastExcel 1.3 kept these under `cn.idev.excel.util`; Fesod moved them to the
`fesod-common` module. Only apply if the project imports them directly (e.g.
custom converters or strategies):

| Find | Replace with |
|-----------------------------------|-------------------------------------|
| `import cn.idev.excel.util.StringUtils;` | `import org.apache.fesod.common.util.StringUtils;` |
| `import cn.idev.excel.util.IoUtils;` | `import org.apache.fesod.common.util.IoUtils;` |
| `import cn.idev.excel.util.MapUtils;` | `import org.apache.fesod.common.util.MapUtils;` |
| `import cn.idev.excel.util.ListUtils;` | `import org.apache.fesod.common.util.ListUtils;` |
| `import cn.idev.excel.util.BooleanUtils;` | `import org.apache.fesod.common.util.BooleanUtils;` |
| `import cn.idev.excel.util.IntUtils;` | `import org.apache.fesod.common.util.IntUtils;` |
| `import cn.idev.excel.util.MemberUtils;` | `import org.apache.fesod.common.util.MemberUtils;` |
| `import cn.idev.excel.util.PositionUtils;` | `import org.apache.fesod.common.util.PositionUtils;` |

### 2k. Wildcard catch-all (apply LAST)

After all specific replacements above, scan for any remaining wildcard imports:

Expand All @@ -265,7 +293,9 @@ After all specific replacements above, scan for any remaining wildcard imports:
| `import cn.idev.excel.` | `import org.apache.fesod.sheet.` |
| `import org.apache.fesod.excel.` | `import org.apache.fesod.sheet.` |

Apply this only after all the specific rules above, as a safety net.
Apply this only after all the specific rules above (including 2i/2j), as a
safety net. Do NOT let the wildcard rule rewrite `cn.idev.excel.util` to
`org.apache.fesod.sheet.util` — those classes moved to fesod-common (rule 2j).

---

Expand Down Expand Up @@ -345,6 +375,20 @@ This phase prevents encoding-related breakage on Windows locales (for example GB

---

## Phase 6 — New Fesod-only features (OPTIONAL, informational)

Fesod ships features that did not exist in FastExcel 1.3.0. They are NOT part
of the migration — mention them in the summary only if the developer's project
could benefit, without rewriting any existing code:

- `@FreezePane` (`org.apache.fesod.sheet.annotation.write.style`) — freeze rows/columns on write.
- URL image security (`org.apache.fesod.sheet.converters.url`) — `UrlImageFetchPolicy` with `SchemePolicy` and `CidrBlock` guard the URL image converter against SSRF.
- `StringBase64ImageConverter` / `StringPathnameImageConverter` (`org.apache.fesod.sheet.converters.string`) — explicit string-to-image conversion (base64 / file path), alongside the legacy `StringImageConverter`.
- `HeadBuilder` / `DefaultHeadBuilder` (`org.apache.fesod.sheet.metadata`) — fluent No-Bean header construction via `.head(builder -> ...)`.
- `HeaderMergeStrategy` (`org.apache.fesod.sheet.enums`) — `NONE` / `HORIZONTAL_ONLY` / `VERTICAL_ONLY` / `FULL_RECTANGLE` / `AUTO` via `headerMergeStrategy(...)`, superseding `automaticMergeHead`.

---

## Verification

After completing the desired phases, confirm the following:
Expand All @@ -354,6 +398,8 @@ After completing the desired phases, confirm the following:
- No `.java` file contains `import cn.idev.excel.`
- No `.java` file contains `import org.apache.fesod.excel.`
- No `pom.xml` or `build.gradle` references `cn.idev.excel`
- If 2i applied: no `.java` file references `FastExcelConstants`, `FastExcelTempFileCreationStrategy`, or `BeanMapUtils.FastExcelNamingPolicy`; check `.java` files for `FastExcelNamingPolicy` → renamed to `FesodSheetNamingPolicy`
- If 2j applied: no `.java` file contains `cn.idev.excel.util.StringUtils` (or any of the 8 moved utils); check for `import cn.idev.excel.util.` — must be gone (wildcard rule 2k must not have rewritten these to `org.apache.fesod.sheet.util`)

**Must be true after Phase 3 (additional):**

Expand Down
66 changes: 66 additions & 0 deletions website/docs/migration/from-fastexcel.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -214,6 +214,11 @@ After all specific replacements above, scan for any remaining wildcard imports:
| `import cn.idev.excel.` | `import org.apache.fesod.sheet.` |
| `import org.apache.fesod.excel.` | `import org.apache.fesod.sheet.` |

> **Note**: The wildcard rule must **not** be applied to `cn.idev.excel.util.*`
> imports. Those utility classes moved to the `fesod-common` module, not to
> `org.apache.fesod.sheet` — update them to `org.apache.fesod.common.util`
> instead (see Step 4).

### Step 3: Entry class rename (STRONGLY RECOMMENDED)

`FastExcel` and `FastExcelFactory` compile in Fesod but are `@Deprecated` and
Expand Down Expand Up @@ -273,6 +278,67 @@ In Fesod, the naming policy is defined in

If no file references `ByFastExcelCGLIB`, skip this phase entirely.

### Step 4: Class and module changes (check when upgrading)

Beyond the entry classes, a few helper classes were renamed or moved to another
module during the donation, and Fesod ships features that FastExcel 1.3 does
not have. Scan your codebase for the names below and update only the ones you
actually reference.

#### Renamed helper classes

| Before (FastExcel 1.3.0) | After (Fesod) |
|-------------------------------------------------------|-----------------------------------------------------------------|
| `cn.idev.excel.constant.FastExcelConstants` | `org.apache.fesod.sheet.constant.FesodSheetConstants` |
| `cn.idev.excel.util.FastExcelTempFileCreationStrategy` | `org.apache.fesod.sheet.util.FesodTempFileCreationStrategy` |
| `cn.idev.excel.util.BeanMapUtils.FastExcelNamingPolicy` | `org.apache.fesod.sheet.util.BeanMapUtils.FesodSheetNamingPolicy` |

#### Utility classes moved to fesod-common

The following utility classes moved from `cn.idev.excel.util` to
`org.apache.fesod.common.util`. Update their imports if your code uses them
directly (for example in custom converters or strategies). If you already
applied the wildcard rule in Step 2, double-check that these imports were not
rewritten to `org.apache.fesod.sheet.util`:

| Class | Before | After |
|-----------------|----------------------|--------------------------------|
| `StringUtils` | `cn.idev.excel.util` | `org.apache.fesod.common.util` |
| `IoUtils` | `cn.idev.excel.util` | `org.apache.fesod.common.util` |
| `MapUtils` | `cn.idev.excel.util` | `org.apache.fesod.common.util` |
| `ListUtils` | `cn.idev.excel.util` | `org.apache.fesod.common.util` |
| `BooleanUtils` | `cn.idev.excel.util` | `org.apache.fesod.common.util` |
| `IntUtils` | `cn.idev.excel.util` | `org.apache.fesod.common.util` |
| `MemberUtils` | `cn.idev.excel.util` | `org.apache.fesod.common.util` |
| `PositionUtils` | `cn.idev.excel.util` | `org.apache.fesod.common.util` |

#### New Fesod-only features

The following features did not exist in FastExcel 1.3.0. They are worth knowing
about when migrating, but require no action unless you want to use them:

- **`@FreezePane`** (`org.apache.fesod.sheet.annotation.write.style.FreezePane`):
class-level annotation that freezes rows and/or columns when writing a sheet
(`colSplit`, `rowSplit`, `leftmostColumn`, `topRow`).
- **URL image security** (`org.apache.fesod.sheet.converters.url`):
`UrlImageFetchPolicy` (built with `SchemePolicy` and `CidrBlock`) guards the
built-in URL image converter against SSRF. By default only `http`/`https` and
public network addresses are allowed; private networks, hosts and CIDRs can
be allowlisted, and redirects (`maxRedirects`) and image size (`maxImageBytes`)
are capped.
- **String image converters** (`org.apache.fesod.sheet.converters.string`):
`StringBase64ImageConverter` (base64 values, optional `data:` prefix) and
`StringPathnameImageConverter` (local file path) make the string-to-image
conversion explicit, in addition to the legacy `StringImageConverter`.
- **`HeadBuilder` / `DefaultHeadBuilder`** (`org.apache.fesod.sheet.metadata`):
fluent header construction for No-Bean mode, e.g.
`FesodSheet.write(pathname).head(builder -> builder.column("ID", 2).columns("User Info", sub -> sub.column("Name").column("Age")))`.
- **`HeaderMergeStrategy`** (`org.apache.fesod.sheet.enums.HeaderMergeStrategy`):
explicit control over header merging — `NONE`, `HORIZONTAL_ONLY`,
`VERTICAL_ONLY`, `FULL_RECTANGLE`, `AUTO` — set via
`headerMergeStrategy(...)` on the write builder, superseding the boolean
`automaticMergeHead` switch.

---

## Migration Strategies
Expand Down
39 changes: 39 additions & 0 deletions ...e/i18n/zh-cn/docusaurus-plugin-content-docs/current/migration/from-fastexcel.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -197,6 +197,8 @@ implementation 'org.apache.fesod:fesod-sheet:2.0.2-incubating'
| `import cn.idev.excel.` | `import org.apache.fesod.sheet.` |
| `import org.apache.fesod.excel.` | `import org.apache.fesod.sheet.` |

> **注意**：通配符规则**不适用于** `cn.idev.excel.util.*` 的导入。这些工具类迁移到了 `fesod-common` 模块，而不是 `org.apache.fesod.sheet` —— 请改为更新为 `org.apache.fesod.common.util`（参见步骤 4）。

### 步骤 3：重命名入口类（强烈建议）

`FastExcel` 和 `FastExcelFactory` 在 Fesod 中仍然可以编译，但已被标记为 `@Deprecated` 弃用，
Expand Down Expand Up @@ -246,6 +248,43 @@ FastExcel 1.3 曾提供了 `FastExcelFactory` 作为第二个入口类，其 API
如果找到，请替换为 `ByFesodCGLIB`。 在 Fesod 中，命名策略定义在 `org.apache.fesod.sheet.util.BeanMapUtils.FesodSheetNamingPolicy` 中，其 `getTag()`
返回 `ByFesodCGLIB`。 如果没有文件引用 `ByFastExcelCGLIB`，请直接跳过此步骤。

### 步骤 4：类名与模块变更（升级时按需检查）

除了入口类之外，捐赠过程中部分辅助类被重命名或迁移到了其他模块，且 Fesod 还包含一些 FastExcel 1.3 没有的功能。请在代码库中搜索以下名称，仅更新你实际引用到的部分。

#### 已重命名的辅助类

| 修改前（FastExcel 1.3.0） | 修改后（Fesod） |
|-------------------------------------------------------|-----------------------------------------------------------------|
| `cn.idev.excel.constant.FastExcelConstants` | `org.apache.fesod.sheet.constant.FesodSheetConstants` |
| `cn.idev.excel.util.FastExcelTempFileCreationStrategy` | `org.apache.fesod.sheet.util.FesodTempFileCreationStrategy` |
| `cn.idev.excel.util.BeanMapUtils.FastExcelNamingPolicy` | `org.apache.fesod.sheet.util.BeanMapUtils.FesodSheetNamingPolicy` |

#### 迁移到 fesod-common 的工具类

以下工具类已从 `cn.idev.excel.util` 迁移至 `org.apache.fesod.common.util`。如果你的代码直接引用了它们（例如在自定义转换器或策略中），请更新导入路径。如果你在步骤 2 中执行过通配符替换，请复查这些导入没有被误改为 `org.apache.fesod.sheet.util`：

| 类 | 修改前 | 修改后 |
|-----------------|-------------------------|---------------------------------|
| `StringUtils` | `cn.idev.excel.util` | `org.apache.fesod.common.util` |
| `IoUtils` | `cn.idev.excel.util` | `org.apache.fesod.common.util` |
| `MapUtils` | `cn.idev.excel.util` | `org.apache.fesod.common.util` |
| `ListUtils` | `cn.idev.excel.util` | `org.apache.fesod.common.util` |
| `BooleanUtils` | `cn.idev.excel.util` | `org.apache.fesod.common.util` |
| `IntUtils` | `cn.idev.excel.util` | `org.apache.fesod.common.util` |
| `MemberUtils` | `cn.idev.excel.util` | `org.apache.fesod.common.util` |
| `PositionUtils` | `cn.idev.excel.util` | `org.apache.fesod.common.util` |

#### Fesod 新增功能

以下功能在 FastExcel 1.3.0 中不存在。迁移时值得了解，但除非你想使用它们，否则无需任何操作：

- **`@FreezePane`**（`org.apache.fesod.sheet.annotation.write.style.FreezePane`）：类级注解，写入工作表时冻结行和/或列（`colSplit`、`rowSplit`、`leftmostColumn`、`topRow`）。
- **URL 图片安全**（`org.apache.fesod.sheet.converters.url`）：`UrlImageFetchPolicy`（由 `SchemePolicy` 和 `CidrBlock` 构建）为内置的 URL 图片转换器提供 SSRF 防护。默认只允许 `http`/`https` 与公网地址；可通过白名单放行私网、主机和 CIDR，并可限制重定向次数（`maxRedirects`）与图片大小（`maxImageBytes`）。
- **字符串图片转换器**（`org.apache.fesod.sheet.converters.string`）：`StringBase64ImageConverter`（base64 值，可选 `data:` 前缀）与 `StringPathnameImageConverter`（本地文件路径）将字符串转图片的转换显式化，兼容的 `StringImageConverter` 仍然保留。
- **`HeadBuilder` / `DefaultHeadBuilder`**（`org.apache.fesod.sheet.metadata`）：无 Bean 模式下的流式表头构建，例如 `FesodSheet.write(pathname).head(builder -> builder.column("ID", 2).columns("User Info", sub -> sub.column("Name").column("Age")))`。
- **`HeaderMergeStrategy`**（`org.apache.fesod.sheet.enums.HeaderMergeStrategy`）：显式控制表头合并——`NONE`、`HORIZONTAL_ONLY`、`VERTICAL_ONLY`、`FULL_RECTANGLE`、`AUTO`——通过写构建器上的 `headerMergeStrategy(...)` 设置，取代布尔开关 `automaticMergeHead`。

---

## 迁移策略
Expand Down
Loading