You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@fesod.apache.org by de...@apache.org on 2026/08/28 16:37:23 UTC

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

This is an automated email from the ASF dual-hosted git repository.

delei pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/fesod.git


The following commit(s) were added to refs/heads/main by this push:
     new 026f216e docs: add class and module changes section to FastExcel migration guide (#857) (#1041)
026f216e is described below

commit 026f216ea925ed6ed5515b05f2aca5d42abf6964
Author: Mikkey-f <16...@qq.com>
AuthorDate: Sat Aug 29 00:37:18 2026 +0800

    docs: add class and module changes section to FastExcel migration guide (#857) (#1041)
---
 .github/skills/fastexcel-to-fesod/SKILL.md         | 50 +++++++++++++++-
 website/docs/migration/from-fastexcel.md           | 66 ++++++++++++++++++++++
 .../current/migration/from-fastexcel.md            | 39 +++++++++++++
 3 files changed, 153 insertions(+), 2 deletions(-)

diff --git a/.github/skills/fastexcel-to-fesod/SKILL.md b/.github/skills/fastexcel-to-fesod/SKILL.md
index 39717c0d..9a68e149 100644
--- a/.github/skills/fastexcel-to-fesod/SKILL.md
+++ b/.github/skills/fastexcel-to-fesod/SKILL.md
@@ -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:
 
@@ -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).
 
 ---
 
@@ -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:
@@ -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):**
 
diff --git a/website/docs/migration/from-fastexcel.md b/website/docs/migration/from-fastexcel.md
index 3fbeeeed..2bfdddef 100644
--- a/website/docs/migration/from-fastexcel.md
+++ b/website/docs/migration/from-fastexcel.md
@@ -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
@@ -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
diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/migration/from-fastexcel.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/migration/from-fastexcel.md
index 9c1c6d24..c6f51d4d 100644
--- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/migration/from-fastexcel.md
+++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/migration/from-fastexcel.md
@@ -214,6 +214,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` 弃用,
@@ -263,6 +265,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`。
+
 ---
 
 ## 迁移策略


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fesod.apache.org
For additional commands, e-mail: commits-help@fesod.apache.org