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
<p>List<FileItem> 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 能“反向生成响应”，其实它只是上传过程的中间产物。下载必须手动构造响应头并输出流：
立即学习“Java免费学习笔记（深入）”；
- 设
Content-Type：用URLConnection.guessContentTypeFromName(fileName)或查 MIME 表 - 设
Content-Disposition：含attachment; filename*=UTF-8''...才能正确处理中文名 - 用
response.getOutputStream()写文件，别用getWriter()（字符流会破坏二进制） - 大文件务必加
response.setBufferSize()并分块写，避免内存堆积
Spring Boot 项目里要不要手动集成 Commons FileUpload
不用。Spring MVC 的 MultipartFile 底层默认就用了 commons-fileupload（或 StandardServletMultipartResolver），你只需要配置：
spring.servlet.multipart.max-file-size=10MBspring.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。 
