diff --git a/.github/skills/fastexcel-to-fesod/SKILL.md b/.github/skills/fastexcel-to-fesod/SKILL.md index 39717c0d3..9a68e1498 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 3fbeeeed5..2bfdddef1 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 84e8b1867..cd4ee36f8 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 @@ -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` 弃用， @@ -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`。 + --- ## 迁移策略