Java常用文件上传下载类库与Apache Commons

Apache Commons FileUpload仅解析multipart请求，不处理下载或文件系统操作；完整上传需自行实现存储、校验等逻辑，并注意乱码、流重复读、临时文件清理及大小限制。

Apache Commons FileUpload 是 Java 中处理文件上传最成熟、最广泛使用的库，但它本身不负责下载，也不直接操作文件系统——它只解析 HTTP 请求中的 multipart 数据。如果你在项目里混用 commons-io 或 commons-lang，那只是补足工具链，不是替代方案。

为什么不能只靠 commons-fileupload 实现完整上传流程

它只做一件事：把 HttpServletRequest 里的二进制流拆成字段和文件项。后续的存储、校验、重命名、路径生成、数据库记录，全得你自己写。常见翻车点包括：

• 没调用 item.isFormField() 就直接 item.getString()，导致中文乱码或 NPE
• 用 item.getInputStream() 读完一次后再次调用，返回空流（流不可重复读）
• 临时文件没清理，DiskFileItemFactory.setRepository() 指向的目录磁盘爆满
• 没限制 setSizeMax() 和 setFileSizeMax()，被恶意大文件打挂服务

ServletFileUpload upload = new ServletFileUpload(new DiskFileItemFactory());
upload.setFileSizeMax(10 * 1024 * 1024); // 单文件 ≤10MB
upload.setSizeMax(50 * 1024 * 1024);      // 整个请求 ≤50MB
List items = upload.parseRequest(request);
for (FileItem item : items) {
if (item.isFormField()) {
String value = item.getString("UTF-8"); // 必须指定编码
} else {
String fileName = Paths.get(item.getName()).getFileName().toString();
try (InputStream in = item.getInputStream();
FileOutputStream out = new FileOutputStream("/upload/" + fileName)) {
IOUtils.copy(in, out); // 这里需要 commons-io
}
}
}

commons-io 在上传下载中真正起作用的几个函数

它不参与协议解析，但大幅降低 I/O 操作出错概率。重点用好这几个：

• IOUtils.copy(InputStream, OutputStream)：自动处理缓冲和异常，比手写 while 循环安全
• FilenameUtils.getName(String)：比 new File(path).getName() 更可靠，不依赖本地文件系统语义
• IOUtils.toByteArray(InputStream)：适合小文件内存处理，但别对 >10MB 文件用，会 OOM
• FileUtils.copyInputStreamToFile(InputStream, File)：封装了流关闭和目录创建，比裸写 FileOutputStream 少三行易错代码

下载时千万别用 commons-fileupload

它完全不提供下载能力。常见错误是误以为 FileItem 能“反向生成响应”，其实它只是上传过程的中间产物。下载必须手动构造响应头并输出流：

• 设 Content-Type：用 URLConnection.guessContentTypeFromName(fileName) 或查 MIME 表
• 设 Content-Disposition：含 attachment; filename*=UTF-8''... 才能正确处理中文名
• 用 response.getOutput

  

  Stream() 写文件，别用 getWriter()（字符流会破坏二进制）
• 大文件务必加 response.setBufferSize() 并分块写，避免内存堆积

Spring Boot 项目里要不要手动集成 Commons FileUpload

不用。Spring MVC 的 MultipartFile 底层默认就用了 commons-fileupload（或 StandardServletMultipartResolver），你只需要配置：

• spring.servlet.multipart.max-file-size=10MB
• spring.servlet.multipart.max-request-size=50MB
• spring.servlet.multipart.location=/tmp/upload（确保该目录可写）

然后 Controller 直接接收：

@PostMapping("/upload")
public String handle(@RequestParam("file") MultipartFile file) {
    if (!file.isEmpty()) {
        file.transferTo(Paths.get("/data/", file.getOriginalFilename()).toFile());
    }
    return "ok";
}

这时候 commons-fileupload 是透明的，你只需关注业务逻辑。除非要深度定制解析行为（比如跳过某些字段、动态改临时目录），否则没必要碰底层 API。