Java上传文件代码|全流程解析与实战示例

覆盖Spring Boot、Servlet原生、Apache Commons FileUpload三大主流方案|含断点续传、分片上传、安全校验与性能调优

一、文件上传核心原理与流程

1.1 HTTP文件上传机制

文件上传依赖HTTP的multipart/form-data编码格式。当表单包含<input type="file">时,浏览器将自动采用该编码方式,将文件内容按边界(boundary)分隔,以二进制流形式发送至服务器。

请求头关键特征:

  • Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
  • Content-Length标识总字节数

服务器端解析流程:读取原始请求体 → 按boundary切分段 → 提取元信息(文件名、MIME类型、字段名)→ 解析二进制内容 → 存储至目标路径。

1.2 核心组件与依赖关系

Java中文件上传涉及以下关键组件:

组件作用典型实现
ServletInputStream原始请求体输入流javax.servlet.ServletRequest
MultipartResolver解析multipart请求CommonsMultipartResolver、StandardServletMultipartResolver
Part单个上传项(文件/字段)javax.servlet.http.Part
FileItemApache Commons FileUpload的抽象org.apache.commons.fileupload.FileItem

1.3 上传流程时序图(文字描述)

① 客户端构建请求

浏览器生成boundary分隔符,将每个文件及表单字段封装为独立part,头部含Content-Disposition(含name、filename)与Content-Type。

② 服务器接收请求

Web容器(Tomcat/Jetty)将请求体解析为MultipartHttpServletRequest或原始HttpServletRequest流。

③ 解析multipart数据

调用解析器(如ServletFileUpload)遍历每个part,提取文件流与元数据。

④ 安全校验与存储

校验文件大小、类型、内容(魔数校验)→ 生成唯一文件名 → 写入目标路径(本地/云存储)。

⑤ 返回结果

返回JSON响应(如{code:200, url:"/files/abc.pdf"}),前端更新UI。

二、原生Servlet API上传方案(无框架依赖)

2.1 基础配置要求

需在Servlet 3.0+中启用@MultipartConfig注解:

@WebServlet("/upload")
@MultipartConfig(
  fileSizeThreshold = 1024 * 1024, // 超过1MB暂存至临时目录
  maxFileSize = 10 * 1024 * 1024,  // 单文件上限10MB
  maxRequestSize = 50 * 1024 * 1024 // 请求总上限50MB
)
public class FileUploadServlet extends HttpServlet {
  protected void doPost(HttpServletRequest request, HttpServletResponse response)
    throws ServletException, IOException {
    // 处理逻辑
  }
}

2.2 完整上传代码示例

protected void doPost(HttpServletRequest request, HttpServletResponse response)
  throws ServletException, IOException {
  String uploadDir = getServletContext().getRealPath("/uploads");
  File dir = new File(uploadDir);
  if (!dir.exists()) dir.mkdirs();
  for (Part part : request.getParts()) {
    String fileName = Paths.get(part.getSubmittedFileName()).getFileName().toString();
    // 安全校验:过滤路径遍历
    if (fileName.contains("..") || fileName.isEmpty()) continue;
    // 生成唯一文件名(避免覆盖)
    String uniqueName = UUID.randomUUID().toString() + "_" + fileName;
    // 写入文件(避免内存溢出)
    try (InputStream input = part.getInputStream();
         FileOutputStream output = new FileOutputStream(new File(dir, uniqueName))) {
      byte[] buffer = new byte[8192];
      int bytesRead;
      while ((bytesRead = input.read(buffer)) != -1) {
        output.write(buffer, 0, bytesRead);
      }
    }
  }
  response.setContentType("application/json");
  response.getWriter().write("{\"code\":200,\"msg\":\"上传成功\"}");
}

2.3 客户端表单示例

<form action="upload" method="post" enctype="multipart/form-data">
  <input type="file" name="file" multiple>
  <button type="submit">上传</button>
</form>

2.4 关键注意事项

  • 路径遍历攻击防护:使用Paths.get(...).getFileName()过滤../路径
  • 临时文件清理:Servlet容器会自动清理fileSizeThreshold以下的临时文件
  • 大文件处理:避免part.write()导致内存溢出,改用流式写入

三、Spring Boot上传方案(推荐)

3.1 依赖配置

Spring Boot 2.x+默认启用StandardServletMultipartResolver,无需额外依赖。若需使用Apache Commons解析器,添加:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- 可选:支持 CommonsMultipartResolver -->
<dependency>
  <groupId>commons-fileupload</groupId>
  <artifactId>commons-fileupload</artifactId>
  <version>1.5</version>
</dependency>

3.2 全局配置

在application.yml中设置上传限制:

spring:
  servlet:
    multipart:
      max-file-size: 20MB      # 单文件最大
      max-request-size: 100MB  # 请求总大小
      file-size-threshold: 1MB # 触发临时文件阈值

3.3 控制器代码示例

@RestController
public class FileUploadController {
  @PostMapping("/upload")
  public ResponseEntity<Map<String, Object>> upload(@RequestParam("file") MultipartFile file) {
    Map<String, Object> result = new HashMap<>();
    try {
      // 校验文件大小
      if (file.isEmpty()) {
        throw new IllegalArgumentException("文件为空");
      }
      // 校验文件类型(基于扩展名与MIME类型双重验证)
      String originalFilename = file.getOriginalFilename();
      String ext = StringUtils.getFilenameExtension(originalFilename);
      String contentType = file.getContentType();
      // 白名单校验
      Set<String> allowedExts = Set.of("jpg", "png", "pdf", "doc", "docx");
      if (!allowedExts.contains(ext.toLowerCase())) {
        throw new IllegalArgumentException("不支持的文件类型");
      }
      // 魔数校验(以PDF为例)
      if ("pdf".equals(ext.toLowerCase())) {
        byte[] header = new byte[8];
        file.getInputStream().read(header);
        String magic = new String(Arrays.copyOf(header, 4));
        if (!"%PDF".equals(magic)) {
          throw new IllegalArgumentException("文件内容与扩展名不匹配");
        }
      }
      // 生成安全路径
      String uploadDir = "/var/www/uploads";
      File dir = new File(uploadDir);
      if (!dir.exists()) dir.mkdirs();
      // 生成唯一文件名(避免覆盖)
      String safeName = UUID.randomUUID().toString() + "." + ext;
      Path filePath = Paths.get(uploadDir, safeName);
      // 异步写入避免阻塞(生产环境建议使用异步线程池)
      file.transferTo(filePath);
      result.put("code", 200);
      result.put("url", "/uploads/" + safeName);
      result.put("fileName", originalFilename);
    } catch (Exception e) {
      result.put("code", 500);
      result.put("msg", "上传失败:" + e.getMessage());
    }
    return ResponseEntity.ok(result);
  }
}

3.4 高级技巧:支持多文件上传

@PostMapping("/multi-upload")
public ResponseEntity<Map<String, Object>> uploadMultiple(
    @RequestParam("files") List<MultipartFile> files) {
  // 处理逻辑同上,循环遍历files
  ...
}

3.5 断点续传实现思路

基于Content-Range请求头实现分片上传:

  1. 前端分片:使用File API的slice()方法将大文件切分为固定大小(如2MB)的块
  2. 上传分片:每个分片携带chunkIndex、totalChunks、fileMd5参数
  3. 服务端合并:接收所有分片后按序合并,校验MD5一致性

四、Apache Commons FileUpload方案

4.1 依赖与配置

需手动配置解析器,适用于传统Web应用:

<dependency>
  <groupId>commons-fileupload</groupId>
  <artifactId>commons-fileupload</artifactId>
  <version>1.5</version>
</dependency>
<dependency>
  <groupId>commons-io</groupId>
  <artifactId>commons-io</artifactId>
  <version>2.11.0</version>
</dependency>

4.2 完整实现示例

protected void doPost(HttpServletRequest request, HttpServletResponse response)
  throws ServletException, IOException {
  DiskFileItemFactory factory = new DiskFileItemFactory();
  factory.setSizeThreshold(1024 * 1024); // 1MB内存缓存
  factory.setRepository(new File(System.getProperty("java.io.tmpdir")));
  ServletFileUpload upload = new ServletFileUpload(factory);
  upload.setSizeMax(100 * 1024 * 1024); // 100MB上限
  String uploadDir = getServletContext().getRealPath("/uploads");
  File dir = new File(uploadDir);
  if (!dir.exists()) dir.mkdirs();
  try {
    List<FileItem> items = upload.parseRequest(request);
    for (FileItem item : items) {
      if (item.isFormField()) {
        // 普通表单字段
        String fieldName = item.getFieldName();
        String value = item.getString();
      } else {
        // 文件字段
        String fileName = Paths.get(item.getName()).getFileName().toString();
        if (fileName.contains("..")) continue;
        String uniqueName = UUID.randomUUID().toString() + "_" + fileName;
        File uploadedFile = new File(dir, uniqueName);
        item.write(uploadedFile);
      }
    }
    response.getWriter().write("{\"code\":200}");
  } catch (Exception e) {
    response.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR, e.getMessage());
  }
}

4.3 与Servlet API对比

特性Servlet APICommons FileUpload
兼容性Servlet 3.0+所有Servlet版本
临时文件管理容器自动管理需手动配置
进度监听需自定义监听器内置ProgressListener
大文件处理流式处理更安全支持流式与内存处理

五、安全防护与最佳实践

5.1 关键安全措施

  • 文件类型校验:结合扩展名、MIME类型、魔数(Magic Number)三重验证
  • 文件名安全:禁止使用原始文件名,改用UUID或哈希值
  • 路径安全:文件存储路径需在Web根目录之外,通过Servlet映射访问
  • 权限控制:上传接口需登录态校验(如JWT Token)
  • 病毒扫描:集成ClamAV等工具对上传文件实时扫描

5.2 魔数校验参考表

文件类型魔数(Hex)描述
JPEGFFD8FF文件头三字节
PNG89504E47前8字节
PDF25504446%PDF
DOCX504B0304ZIP格式
GIF47494638GIF8

5.3 存储路径安全方案

避免直接暴露上传目录:

  1. 将文件存储于/var/www/protected/(不在Web根目录)
  2. 通过专门Servlet映射访问:
@WebServlet("/download/*")
public class DownloadServlet extends HttpServlet {
  protected void doGet(HttpServletRequest req, HttpServletResponse resp)
    throws ServletException, IOException {
    String fileName = req.getPathInfo().substring(1); // 去掉"/"
    // 校验文件合法性
    File file = new File("/var/www/protected", fileName);
    if (!file.exists() || !file.isFile()) {
      resp.sendError(404);
      return;
    }
    // 流式下载
    resp.setContentType(getServletContext().getMimeType(fileName));
    resp.setHeader("Content-Disposition", "attachment; filename=\"" + fileName + "\"");
    Files.copy(file.toPath(), resp.getOutputStream());
  }
}

六、常见错误排查指南

6.1 典型异常与解决方案

413 Request Entity Too Large
500 Internal Server Error
文件名乱码
空指针异常

原因:服务器拒绝超大请求体

解决:

  • Tomcat:server.tomcat.max-http-post-size=10485760
  • Nginx:client_max_body_size 20m;
  • Spring Boot:spring.servlet.multipart.max-request-size

原因:文件写入权限不足或路径不存在

解决:

  • 检查目标目录权限:chmod 755 /var/www/uploads
  • 确保路径存在:new File(path).mkdirs()
  • 使用绝对路径避免相对路径解析错误

原因:浏览器与服务器编码不一致

解决:

  • Servlet API:item.getString("UTF-8")
  • Commons FileUpload:new DiskFileItemFactory().setHeaderEncoding("UTF-8")
  • Spring Boot:spring.servlet.multipart.charset=UTF-8

原因:请求未包含文件字段或表单缺失enctype

解决:

  • 表单必须添加enctype="multipart/form-data"
  • 检查前端上传字段名与后端参数名一致(如@RequestParam("file"))
  • 使用file.isEmpty()前置校验

七、性能优化与高级技巧

7.1 大文件上传优化

  • 分片上传:将大文件拆分为2-10MB块,并行上传提升吞吐量
  • 进度跟踪:通过WebSocket或轮询返回进度(需服务端记录已上传块)
  • 断点续传:客户端保存已上传块MD5,断开后续传未完成部分
  • 压缩传输:对文本类文件(PDF/DOCX)启用GZIP压缩

7.2 异步处理方案

避免阻塞主线程:

@PostMapping("/async-upload")
public ResponseEntity<Map<String, Object>> asyncUpload(@RequestParam("file") MultipartFile file) {
  String taskId = UUID.randomUUID().toString();
  taskExecutor.execute(() -> {
    // 后台处理:校验、存储、通知
  });
  return ResponseEntity.ok(Map.of("code", 202, "taskId", taskId));
}

7.3 云存储集成(以阿里云OSS为例)

String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
String accessKeyId = "yourAK";
String accessKeySecret = "yourSK";
String bucketName = "your-bucket";
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
try (InputStream input = file.getInputStream()) {
  ossClient.putObject(bucketName, "uploads/" + fileName, input);
} finally {
  ossClient.shutdown();
}

八、网友高频问题解答

Q1:为什么上传后文件变为空?

答:常见于使用file.transferTo()后关闭了输入流。解决方案:

  • 确保MultipartFile未被重复读取
  • 避免在try-with-resources中手动关闭流
  • 检查磁盘空间是否充足(df -h)

Q2:如何限制用户只能上传图片?

答:前端+后端双重校验:

// 前端
<input type="file" accept="image/*">
// 后端
String contentType = file.getContentType();
if (!contentType.startsWith("image/")) {
  throw new IllegalArgumentException("仅支持图片格式");
}

Q3:上传到服务器后无法访问?

答:检查以下三点:

  1. 文件是否存储在Web可访问目录(如/static/)
  2. 是否通过Web服务器(Nginx/Apache)映射静态资源路径
  3. 防火墙是否放行对应端口

Q4:如何防止文件覆盖?

答:采用以下任一方案:

  • 生成唯一文件名:UUID + "." + ext
  • 添加时间戳:System.currentTimeMillis() + "_" + fileName
  • 使用哈希值:DigestUtils.md5Hex(file.getInputStream()) + "." + ext