核心概念
commons-fileupload 是 Apache 组织下的一个开源项目，它依赖于另一个库 commons-io，它的工作原理基于 HTTP 协议中的一个标准部分：multipart/form-data。
（图片来源网络，侵删）
当你在 HTML 表单中设置 enctype="multipart/form-data" 并选择一个文件提交时，浏览器会将表单数据（包括普通文本字段和文件内容）打包成一个特殊的“多部分”请求体发送到服务器。
commons-fileupload 的作用就是：
- 解析 这个复杂的
multipart请求体。 - 将请求体中的普通字段（如 username, description）和文件字段（文件名、内容、类型等）分离开来。
- 提供一个易于使用的 API 来获取这些信息，并将文件内容保存到服务器的指定位置。
准备工作：添加 Maven 依赖
在你的 pom.xml 文件中添加 commons-fileupload 和 commons-io 的依赖。commons-io 是 commons-fileupload 的一个可选依赖，但强烈建议一起使用，因为它提供了很多实用的 I/O 工具类。
<dependencies>
<!-- Servlet API 依赖 -->
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>javax.servlet-api</artifactId>
<version>4.0.1</version>
<scope>provided</scope>
</dependency>
<!-- Apache Commons FileUpload -->
<dependency>
<groupId>commons-fileupload</groupId>
<artifactId>commons-fileupload</artifactId>
<version>1.4</version> <!-- 使用较新的稳定版本 -->
</dependency>
<!-- Apache Commons IO (强烈推荐) -->
<dependency>
<groupId>commons-io</groupId>
<artifactId>commons-io</artifactId>
<version>2.11.0</version>
</dependency>
</dependencies>
前端页面 (HTML)
我们需要一个支持文件上传的 HTML 表单，关键点：
（图片来源网络，侵删）
<form>标签必须有method="post"。<form>标签必须有enctype="multipart/form-data"，这是告诉浏览器以特殊格式发送数据的关键。<input>标签必须是type="file"。
创建一个 upload.html 文件：
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">文件上传示例</title>
</head>
<body>
<h1>上传文件</h1>
<form action="upload" method="post" enctype="multipart/form-data">
<!-- 普通文本字段 -->
<label for="username">用户名:</label>
<input type="text" id="username" name="username"><br><br>
<!-- 文件选择字段 -->
<label for="file">选择文件:</label>
<input type="file" id="file" name="file"><br><br>
<input type="submit" value="上传">
</form>
</body>
</html>
注意：<input name="file"> 中的 name="file" 将与后端代码中用来获取文件的 key 对应。
后端处理 (Servlet)
这是核心部分,我们将创建一个 Servlet 来接收和处理上传的请求。
1 在 web.xml 中配置 Servlet
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd"
version="4.0">
<servlet>
<servlet-name>FileUploadServlet</servlet-name>
<servlet-class>com.example.FileUploadServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>FileUploadServlet</servlet-name>
<url-pattern>/upload</url-pattern>
</servlet-mapping>
</web-app>
2 编写 FileUploadServlet.java
这个 Servlet 的 doPost 方法将包含所有文件上传的逻辑。
（图片来源网络，侵删）
package com.example;
import org.apache.commons.fileupload.FileItem;
import org.apache.commons.fileupload.disk.DiskFileItemFactory;
import org.apache.commons.fileupload.servlet.ServletFileUpload;
import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.File;
import java.io.IOException;
import java.io.PrintWriter;
import java.util.List;
@WebServlet("/upload") // 如果使用注解方式，可以省略 web.xml 的配置
public class FileUploadServlet extends HttpServlet {
// 上传文件存储目录
private static final String UPLOAD_DIRECTORY = "upload";
// 设置上传文件的最大尺寸，这里是 5MB
private static final int MEMORY_THRESHOLD = 1024 * 1024 * 5;
// 设置最大上传文件尺寸，这里是 10MB
private static final int MAX_FILE_SIZE = 1024 * 1024 * 10;
// 设置请求的最大尺寸，这里是 10MB
private static final int MAX_REQUEST_SIZE = 1024 * 1024 * 10;
protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
// 1. 检查是否为 multipart 请求
if (!ServletFileUpload.isMultipartContent(request)) {
// 如果不是，则停止处理
PrintWriter writer = response.getWriter();
writer.println("Error: 表单必须包含 enctype=multipart/form-data");
writer.flush();
return;
}
// 配置上传参数
DiskFileItemFactory factory = new DiskFileItemFactory();
// 设置内存临界值 - 超过后将产生临时文件存储于临时目录
factory.setSizeThreshold(MEMORY_THRESHOLD);
// 设置临时存储目录
factory.setRepository(new File(System.getProperty("java.io.tmpdir")));
ServletFileUpload upload = new ServletFileUpload(factory);
// 设置最大文件上传值
upload.setFileSizeMax(MAX_FILE_SIZE);
// 设置最大请求值 (包含文件和表单数据)
upload.setSizeMax(MAX_REQUEST_SIZE);
// 构造临时路径来上传文件，这里的路径是 Web 应用的根目录下的 upload 文件夹
String uploadPath = getServletContext().getRealPath("") + File.separator + UPLOAD_DIRECTORY;
File uploadDir = new File(uploadPath);
if (!uploadDir.exists()) {
uploadDir.mkdir();
}
try {
// 解析请求的内容提取文件数据
@SuppressWarnings("unchecked")
List<FileItem> formItems = upload.parseRequest(request);
if (formItems != null && formItems.size() > 0) {
for (FileItem item : formItems) {
// 处理不在表单中的字段
if (item.isFormField()) {
String name = item.getFieldName();
String value = item.getString("UTF-8"); // 指定编码，防止中文乱码
System.out.println("普通字段 - " + name + ": " + value);
// 你可以将用户名存入 request 域
request.setAttribute("username", value);
} else {
// 处理表单中上传的文件
String fileName = new File(item.getName()).getName();
String filePath = uploadPath + File.separator + fileName;
File storeFile = new File(filePath);
// 在控制台输出上传文件的路径
System.out.println("文件存储在: " + filePath);
// 保存文件到硬盘
item.write(storeFile);
request.setAttribute("message", "文件 " + fileName + " 上传成功!");
}
}
}
} catch (Exception ex) {
request.setAttribute("message", "错误信息: " + ex.getMessage());
}
// 跳转到消息显示页面
getServletContext().getRequestDispatcher("/message.jsp").forward(request, response);
}
}
3 代码解释
- 检查请求类型：
ServletFileUpload.isMultipartContent(request)是一个关键检查，确保我们处理的是一个包含文件上传的请求。 DiskFileItemFactory：这是用于创建FileItem对象的工厂。setSizeThreshold：设置内存缓冲区大小，如果上传的文件很小，它会直接读入内存，如果文件大小超过这个阈值，剩余的部分会被写入到临时文件中，以避免内存溢出。setRepository：设置临时文件的存储目录，通常是系统默认的临时目录。
ServletFileUpload：这是核心类，负责解析multipart请求。setFileSizeMax：限制单个文件的大小。- `
