Apache Commons FileUpload 1.x 与 2.x 的主要区别

核心区别详解

1. 依赖关系 (Dependencies)

这是升级时遇到的第一个障碍。

• 1.x: 依赖于 commons-io:commons-io:1.4 或更高版本（但仍是 1.x 系列）。

• 2.x: 必须 依赖于 commons-io:commons-io:2.8.0 或更高版本。如果你的项目中还有其他库依赖于 commons-io 1.x，可能会引起冲突。

2. API 设计 (API Design)

这是代码层面需要修改最多的地方。

1.x 典型用法 (基于 Factory)：

2.x 典型用法 (推荐流式 API)：

2.x 兼容 1.x 的用法 (如果你不想大改代码)：

可以直接从 1.x 升级到 2.x 吗？

答案是：不可以直接升级，但可以迁移。 这是一个破坏性升级，需要手动修改代码和依赖配置。

升级/迁移步骤：

1. 更新依赖

   • 移除 commons-fileupload:commons-fileupload:1.x 依赖。

   • 添加 org.apache.commons:commons-fileupload2-core:2.x 依赖。

   • 如果你的项目是 Web 项目，还需要添加 Servlet 支持模块：

     • 对于 Jakarta EE 9+ (Tomcat 10+, Jetty 11+): org.apache.commons:commons-fileupload2-jakarta:2.x

     • 对于 Java EE 8 及以前 (Tomcat 9-): 官方 2.x 未提供 javax.servlet 支持。这是一个关键决策点。你可能需要寻找第三方适配器或考虑升级你的 Servlet 容器。

   • 确保 commons-io 升级到 2.8.0 或更高版本。

2. 修改代码中的 Import 语句

   • 将所有 org.apache.commons.fileupload.* 的 import 语句改为 org.apache.commons.fileupload2.*。

   • 注意：ServletFileUpload 类在核心包中不再存在，它被移到了 -jakarta 模块中，并且 API 也发生了变化。

3. 重构代码逻辑

   • 强烈推荐 使用新的流式 API (FileItemIterator)，这是 2.x 版本性能和内存优势的核心。

   • 如果你希望最小化代码修改，可以暂时使用 DiskFileItemFactory 和 FileUpload.parseRequest(request) 的方式，但这无法充分利用 2.x 的优势。

总结

在决定升级之前，请务必检查你的 Servlet 容器版本，以确定应该使用哪个 Servlet 支持模块（Jakarta 还是继续使用 1.x）。如果无法满足 Jakarta EE 的要求，坚持使用 1.x 可能是一个更稳妥的选择。