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

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

 

特性	1.x 版本	2.x 版本	说明
核心依赖	依赖于 commons-io 1.x	依赖于 commons-io 2.x	这是最重要的变化之一，2.x 强制要求使用更新的 commons-io。
API 设计	基于 FileItemFactory	基于 流式 API (DiskFileItemFactory 仍存在，但推荐新方式)	2.x 引入了更现代、更灵活的流式处理方式，减少了内存占用。
性能与内存	默认在内存中处理小文件，大文件写入磁盘。	完全流式处理，可以处理任意大小的文件而无需先将内容缓存在内存中。	2.x 在处理大文件时性能更好，内存开销更小，避免了内存溢出。
包名	org.apache.commons.fileupload.*	org.apache.commons.fileupload2.*	这是一个破坏性变更，意味着你不能简单地替换 JAR 文件，需要修改代码中的 import 语句。
Servlet 支持	核心库包含对 Servlet API 的直接支持（如 ServletFileUpload）。	核心库 (fileupload2-core) 与 Servlet 支持 (fileupload2-jakarta) 分离。	2.x 模块化更好，并且为了支持 Jakarta EE 9+（包名从 javax.servlet 变为 jakarta.servlet），提供了单独的模块。
Maven 坐标	commons-fileupload:commons-fileupload:1.x	有两个主要构件： 1. org.apache.commons:commons-fileupload2-core:2.x 2. org.apache.commons:commons-fileupload2-jakarta:2.x	坐标和 GroupId 都发生了变化，需要注意。
功能性增强	基础功能。	支持非阻塞解析（适用于异步 Servlet环境），提供了更细粒度的控制。	2.x 更适合现代 Web 容器和响应式编程模型。

---

核心区别详解

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)：

java

// 1.x 方式
DiskFileItemFactory factory = new DiskFileItemFactory();
ServletFileUpload upload = new ServletFileUpload(factory);
List<FileItem> items = upload.parseRequest(request); // 一次性解析所有内容

for (FileItem item : items) {
    if (item.isFormField()) {
        // 处理普通表单字段
        String fieldName = item.getFieldName();
        String value = item.getString();
    } else {
        // 处理上传的文件
        String fileName = item.getName();
        InputStream fileContent = item.getInputStream();
        // ... 处理流
    }
}

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

java

// 2.x 流式 API 方式 (推荐)
FileUpload upload = FileUpload.builder().get(); // 使用构建器
FileItemIterator iter = upload.getItemIterator(request); // 获取迭代器

while (iter.hasNext()) {
    FileItemStream item = iter.next();
    String name = item.getFieldName();
    InputStream stream = item.openStream();

    if (item.isFormField()) {
        // 处理普通表单字段：直接读取流
        String value = Streams.asString(stream);
        System.out.println("Form field " + name + " with value " + value + " detected.");
    } else {
        // 处理上传的文件：流式处理，不会全部加载到内存
        String fileName = item.getName();
        System.out.println("File field " + name + " with file name " + fileName + " detected.");
        // ... 使用 'stream' 读取文件内容，例如写入磁盘
        // Files.copy(stream, Paths.get("/path/to/save/" + fileName));
    }
}

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

java

// 2.x 方式，但使用类似 1.x 的 API (不推荐，但可行)
DiskFileItemFactory factory = DiskFileItemFactory.builder().get();
FileUpload upload = new FileUpload(factory); // 注意：这里不是 ServletFileUpload
List<FileItem> items = upload.parseRequest(request);

// 后续循环遍历 items 的代码与 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 的优势。

总结

 

方面	结论
直接替换 JAR	不行，包名已改。
无缝升级	不行，必须修改代码和依赖。
推荐升级吗？	推荐，特别是如果你需要处理大文件，或者希望应用更现代、更高效的流式处理 API。2.x 在性能和内存管理上是质的飞跃。
升级复杂度	中等。主要工作量在于修改 import 语句和将原有的基于 List<FileItem> 的代码重构为基于 FileItemIterator 的流式代码。

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