Skip to content

Apache上传下载 ​

[TOC]

概述 ​

在 Java Web 应用中,文件传输包含客户端向服务端上传二进制文件与服务端向客户端下发文件流两个方向。原生 Servlet API 面向常规文本表单设计,直接处理大文件二进制流、分界符解析、临时磁盘缓存及流式读写时代码繁琐且容易引发内存溢出。Apache 提供的 commons-fileupload 与 commons-io 组合是 Java Servlet 生态中最经典的文件传输技术栈,二者各司其职,完整覆盖从 HTTP 报文拆包到磁盘与网络流传输的全链路。

文件传输痛点 ​

原生 HttpServletRequest 与 HttpServletResponse 在处理文件传输时存在三类典型瓶颈:

  1. 常规表单解析失效:浏览器上传文件必须将请求头 Content-Type 设置为 multipart/form-data,请求体不再是 key=value&key2=value2 形式的键值对字符串,而是由边界符分隔的二进制多段报文。此时 request.getParameter() 无法解析任何表单字段,均返回 null。

  2. 大文件内存溢出风险:如果直接将 request.getInputStream() 全部读入内存字节数组再切分边界,高并发或大文件上传场景会瞬间耗尽 JVM 堆内存,必须具备基于阈值的“内存缓存 + 临时文件落盘”切换能力与临时文件回收能力。

  3. 二进制响应与路径处理繁琐:文件下载需要手动处理 MIME 类型推断、不同浏览器对中文文件名的编码规范、大文件缓冲区循环拷贝以及输入/输出流的安全关闭,纯 JDK I/O 样板代码冗长且容易遗漏资源释放或路径安全校验。

技术栈协作架构 ​

commons-fileupload 与 commons-io 并非平行的两个工具包,而是紧密耦合的上下游协作关系:

  • commons-fileupload(协议解析层):负责解析符合 RFC 1867 / RFC 7578 规范的 multipart/form-data 请求体,将原始字节流拆解为结构化的普通表单字段与上传文件项,同时提供请求总大小、单文件大小校验以及上传进度回调能力。
  • commons-io(底层 I/O 与文件支撑层):作为 commons-fileupload 的核心底层依赖,提供延迟落盘输出流、临时文件跟踪回收器等存储基础设施;在文件下载与落盘环节,开发者也直接调用其流拷贝工具与文件名安全处理工具。

image-20261120222746275

一次完整的文件传输链路中,两个库的职责划分如下:

传输方向commons-fileupload 职责commons-io 职责
文件上传校验请求类型、按边界符切分请求体、封装 FileItem 或 FileItemStream、限制文件体积与回调上传进度提供 DeferredFileOutputStream 控制内存与磁盘切换、通过 FileCleaningTracker 回收临时文件、借助 FilenameUtils 剥离客户端路径
文件下载不参与下载流程使用 IOUtils 将服务器本地文件流高效拷贝至 ServletOutputStream,配合 FileUtils 完成文件读取与元数据校验

commons-fileupload 与 Servlet 3.0 Part 对比 ​

自 Servlet 3.0 起,容器原生提供了 @MultipartConfig 注解与 Part 接口用于文件上传。在真实工程选型与老项目维护中,commons-fileupload 仍被广泛使用(Tomcat 内部对 Part 的底层解析同样基于重打包后的 commons-fileupload 代码),二者定位差异如下:

对比维度Apache commons-fileuploadServlet 3.0 原生 Part
依赖与兼容性需引入独立 JAR,兼容 Servlet 2.x 至 6.x 各版本零第三方依赖,要求 Servlet 3.0 及以上容器
解析模式同时支持传统临时存储模式与零临时文件的流式解析模式仅提供基于 Part 的常规解析模式,无原生无落盘流式迭代器
进度监听内置 ProgressListener 接口,可直接追踪已读取字节数规范未提供原生进度监听接口,需自行包装输入流实现
参数读取冲突一旦开始解析请求体,统一从解析结果提取普通字段与文件容器托管解析后,允许继续通过 request.getParameter() 获取普通字段
框架集成长期作为 Spring MVC 经典解析器 CommonsMultipartResolver 的底层实现对应 Spring MVC StandardServletMultipartResolver(Spring 6 / Boot 3 默认)

环境搭建 ​

引入 commons-fileupload 时,最容易出错的环节是 Servlet 规范包名与版本的对应关系。

javax.servlet 与 jakarta.servlet 版本差异 ​

Servlet 5.0(Tomcat 10.0)开始,规范包名由 javax.servlet.* 迁移至 jakarta.servlet.*。commons-fileupload 因此分裂为两个大版本分支,不可混用:

依赖分支适用容器与规范Maven 坐标 artifactId核心包路径
1.x 系列(1.5)Tomcat 9 及以下(javax.servlet)commons-fileuploadorg.apache.commons.fileupload.servlet
2.x 系列(2.0.0-M2+)Tomcat 10.0(jakarta.servlet 5)commons-fileupload2-jakarta-servlet5org.apache.commons.fileupload2.jakarta.servlet5
2.x 系列(2.0.0-M2+)Tomcat 10.1+ / 11(jakarta.servlet 6)commons-fileupload2-jakarta-servlet6org.apache.commons.fileupload2.jakarta.servlet6

commons-fileupload 1.5 修复了早期版本(1.4 及以前)存在的多部分请求头数量无限制导致的拒绝服务漏洞(CVE-2023-24998),在 javax.servlet 项目中应至少使用 1.5 版本。

Maven 依赖配置 ​

基于 Tomcat 9(javax.servlet)的标准 Maven 依赖配置如下:

xml
<!-- Servlet API(由 Tomcat 容器在运行时提供) -->
<dependency>
  <groupId>javax.servlet</groupId>
  <artifactId>javax.servlet-api</artifactId>
  <version>4.0.1</version>
  <scope>provided</scope>
</dependency>

<!-- Apache Commons FileUpload 1.x(适配 javax.servlet) -->
<dependency>
  <groupId>commons-fileupload</groupId>
  <artifactId>commons-fileupload</artifactId>
  <version>1.5</version>
</dependency>

<!-- Apache Commons IO(显式声明统一版本,避免旧版传递依赖冲突) -->
<dependency>
  <groupId>commons-io</groupId>
  <artifactId>commons-io</artifactId>
  <version>2.16.1</version>
</dependency>

若项目运行在 Tomcat 10.1 及以上(jakarta.servlet 6)环境,则替换为 2.x 模块化坐标:

xml
<!-- Apache Commons FileUpload 2.x(适配 Jakarta Servlet 6 / Tomcat 10.1+) -->
<dependency>
  <groupId>org.apache.commons</groupId>
  <artifactId>commons-fileupload2-jakarta-servlet6</artifactId>
  <version>2.0.0-M2</version>
</dependency>

<!-- Apache Commons IO(FileUpload 2.x 核心依赖) -->
<dependency>
  <groupId>commons-io</groupId>
  <artifactId>commons-io</artifactId>
  <version>2.16.1</version>
</dependency>

手动导入 JAR ​

未使用构建工具的传统 Java Web 工程(如直接基于 WEB-INF/lib 部署)需手动准备以下两个 JAR 包,并确保它们在打包部署时一并输出到 WEB-INF/lib 目录:

  1. commons-fileupload-1.5.jar(提供 multipart/form-data 解析核心类)。

  2. commons-io-2.16.1.jar(提供临时文件存储与流拷贝支持;缺少该 JAR 会在实例化 DiskFileItemFactory 时抛出 NoClassDefFoundError)。

multipart/form-data 协议 ​

在 Web 应用中,向服务器上传文件时,浏览器与服务器之间的通信必须遵循 multipart/form-data 协议规范(主要由 RFC 1867 和 RFC 7578 定义)。理解该协议的原始报文结构、边界切分机制以及底层的流式状态机解析原理,是掌握 commons-fileupload 技术栈的核心前提。

协议背景 ​

在常规的 Web 表单提交中,默认的编码类型(enctype)为 application/x-www-form-urlencoded。该编码方式会将表单数据拼接为 key1=value1&key2=value2 的字符串,并对非 ASCII 字符及特殊符号进行百分号编码(URL Encoding,如 %XX)。

这种设计在处理文件上传时存在严重缺陷:

  1. 二进制膨胀与损耗:将图片、音视频等二进制文件进行 URL 编码或 Base64 编码,会导致数据体积急剧膨胀(如 Base64 增加约 33% 体积,URL 编码在极端情况下可达 3 倍),显著消耗网络带宽与服务器 CPU 资源。

  2. 多载荷混杂局限:常规编码无法在单一 HTTP 请求中同时传输文本参数、多个不同类型的文件以及各自独立的元数据(如文件名、媒体类型 MIME)。

为了解决这些问题,RFC 1867 引入了 multipart/form-data 媒体类型。它允许客户端在单个 HTTP 请求体中划分多个独立的载荷段(Part),每个段拥有独立的头部描述(描述字段名、文件名、内容类型)与原始二进制数据,各段之间通过特定的“边界分隔符”进行物理隔离,从而实现零编码损耗的高效传输。

HTTP 请求报文结构 ​

一个标准的 multipart/form-data 请求由 HTTP 请求头、边界定义、多个独立数据段(Part)以及结束分界符构成。其关键要素如下:

  1. Content-Type 声明与 Boundary 定义:

    请求头必须指定 Content-Type: multipart/form-data; boundary=...。

    boundary(分界符参数)是由客户端浏览器随机生成的唯一字符串(RFC 2046 规定其长度不超过 70 个字符,且不应在内容主体中出现),用于在报文中划分不同的数据段。

  2. 数据段分界规则:

    • 起始/中间分界符:每个数据段的开头为 -- 加上 boundary 字符串,后接换行符 \r\n,形如 --${boundary}\r\n。

    • 段内头部(Part Headers):紧跟分界符之后,包含该段的元数据。

    • Content-Disposition: form-data; name="字段名"(若为文件段,还包含 filename="文件名")。

    • Content-Type: 媒体类型(如 image/png、application/octet-stream,若省略则普通文本字段默认为 text/plain)。

    • 空行分隔:头部描述与段主体内容之间必须有且仅有一个空行(即 \r\n\r\n)。

    • 段主体(Part Body):原始的二进制或文本数据。

    • 结束分界符:所有数据段传输完毕后,最后一行必须为 -- 加上 boundary 再加上 --,形如 --${boundary}--\r\n,标志请求体结束。

示例: 原始 HTTP 上传报文 ​

以下是一个包含普通文本字段 username 和文件上传字段 avatar 的原始 TCP 字节流报文:

http
// 1. 请求行与头部信息,指定多部分类型及边界标识符
POST /upload HTTP/1.1
Host: localhost:8080
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Length: 326

// 2. 第一段:普通文本表单字段(用户名)
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="username"

admin

// 3. 第二段:文件表单字段(文件名与类型)
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="avatar"; filename="avatar.txt"
Content-Type: text/plain

Hello, multipart file upload content!

// 4. 结束分界符:附加双连字符后缀
------WebKitFormBoundary7MA4YWxkTrZu0gW--

状态机解析机制 ​

由于 HTTP 请求体可能包含数百兆甚至数吉字节的文件,服务器绝不能将整个报文一次性读入内存,而必须采用流式分块扫描(Streaming Tokenization)。

commons-fileupload 底层基于有限状态机(Finite State Machine, FSM)对输入流进行逐字节匹配:

image-20261120222816444

解析状态流转步骤如下:

  1. 寻找初始边界(Preamble 阶段):

    解析器读取 request.getInputStream(),跳过边界符前的任何前导空白或前导文本(Preamble),直到匹配到第一个边界符 --${boundary}\r\n。状态转移至“解析段头部”。

  2. 解析段头部(Read Part Headers 阶段):

    按行读取字节,直到遇到连续的 \r\n\r\n。

    解析每一行 Header,提取 Content-Disposition 中的 name 和 filename,以及 Content-Type。

    如果检测到 filename 属性,则标识当前 Part 为文件项;否则为普通表单字段。状态转移至“读取段主体”。

  3. 读取段主体(Read Part Body 阶段):

    在缓冲区中滑动扫描边界标志字节序列 \r\n--${boundary}。

    在未扫描到该序列前,持续将读取的字节流输出至目标存储(内存缓冲区或临时文件)。

    由于边界符可能被分割在两个缓冲区块的交界处,解析器内部使用滑动窗口算法(如 Boyer-Moore 算法变种)进行匹配。

  4. 遇到边界分界符(Check Boundary 阶段):

    当扫描到 \r\n--${boundary} 后,紧接着读取后续的两个字符:

    • 如果后续为 \r\n,说明当前段结束且后续还有新数据段。状态重置为“解析段头部”,循环处理下一段。
    • 如果后续为 --,说明已到达结束分界符(Epilogue 阶段),停止流式读取,关闭输入流。

RFC 7578 核心约束 ​

在实现和解析 multipart/form-data 时,需遵循 RFC 7578 的关键约束与安全规范:

  1. 字符集规范:

    各数据段头部的字符集必须为 UTF-8。传统 RFC 2231 中的 filename*=UTF-8''... 格式在 RFC 7578 中被废弃,标准推荐直接在 filename="..." 中使用 UTF-8 编码字符串,或在段头部声明 Content-Type: text/plain; charset=utf-8。

  2. 同名多文件支持:

    表单中可能存在同名多选文件上传(如 <input type="file" name="files" multiple>),此时同一个 name="files" 会连续出现多个 Part,每个 Part 包含不同的 filename。解析器必须支持同名 Key 的迭代收集。

  3. 无传输编码(No Transfer Encoding):

    RFC 7578 明确禁止在单个数据段中使用 Content-Transfer-Encoding(如 Base64 或 Quoted-Printable)。每个 Part 的主体必须直接以原始二进制流的形式传输。

API: FileItemStream【待补充】 ​

API: FileItemIterator【待补充】 ​

DiskFileItemFactory 临时存储 ​

在传统解析模式下,服务端读取 multipart/form-data 请求体时无法预知客户端最终会发送多少字节的数据。如果将所有上传内容无条件缓存在 JVM 堆内存中,并发上传大文件会迅速引发 OutOfMemoryError;如果将所有几字节的普通表单字段也全部写入磁盘,又会产生大量无谓的磁盘 I/O。DiskFileItemFactory 通过分级阈值存储与延迟落盘切换解决了速度与内存安全之间的矛盾,并配合临时文件跟踪器闭环管理磁盘空间回收。

分级存储模型 ​

commons-fileupload 通过抽象工厂接口 FileItemFactory 将“请求报文解析”与“数据存储策略”解耦。ServletFileUpload 在解析每个数据段时,只负责调用工厂创建 FileItem 实例,而具体数据存放在内存还是磁盘,完全由工厂实现类 DiskFileItemFactory 决定。

DiskFileItemFactory 内部维护两个核心存储策略参数:

  1. 内存缓冲区阈值(sizeThreshold):控制单个表单项允许驻留在内存中的最大字节数,默认值为 10 KB(10240 字节)。普通文本字段与极小文件直接保存在内存中,避免磁盘 I/O 开销;一旦数据体积超过该阈值,立即转存至磁盘临时目录。

  2. 临时文件目录(repository):指定超过阈值的数据段落盘存放的目录。默认值为 null,运行时自动回退至 JVM 系统属性 java.io.tmpdir 指向的临时目录(在 Tomcat 环境下通常被重定向至 $CATALINA_BASE/temp)。

在生产环境中,建议显式指定应用专属的临时目录,而不是依赖系统默认的 /tmp 目录:

  • 避免权限与清理冲突:操作系统定时任务(如 Linux systemd-tmpfiles)可能定期清理 /tmp 下的文件,导致长耗时上传任务中途丢失临时文件。
  • 优化落盘移动性能:将临时目录与最终业务存储目录置于同一文件系统分区下,后续持久化文件时可直接执行原子重命名(renameTo),避免跨分区全量字节拷贝。

DeferredFileOutputStream ​

DiskFileItemFactory 创建的 DiskFileItem 并非自行维护内存数组与文件流的切换逻辑,而是直接委托给 commons-io 提供的 DeferredFileOutputStream。该类继承自 ThresholdingOutputStream,专门实现“先写内存、超限无缝切盘”的透明输出流。

image-20261120222847869

当解析器将某个数据段的原始字节不断写入 DiskFileItem 的输出流时,DeferredFileOutputStream 的内部流转分为四个阶段:

  1. 初始内存缓冲:输出流实例化时,不会在磁盘上创建任何文件,而是内部初始化一个 ByteArrayOutputStream 作为当前活动输出流,此时 isInMemory() 返回 true。

  2. 写入前阈值预检:每次调用 write(...) 写入数据前,父类 ThresholdingOutputStream 都会校验 已写入字节数 + 本次待写入字节数 > sizeThreshold 是否成立。若未超限,字节直接追加至内存缓冲区。

  3. 触发阈值落盘切换:一旦预检发现即将突破阈值,流内部自动回调 thresholdReached() 方法:

    • 在 repository 目录下真正创建物理临时文件;
    • 打开指向该临时文件的 FileOutputStream;
    • 将此前暂存在 ByteArrayOutputStream 中的所有历史字节一次性刷写到磁盘文件;
    • 将当前活动输出流指针切换为该 FileOutputStream,并将原内存缓冲区引用置为 null 以便垃圾回收。
  4. 后续直写磁盘:切换完成后,当前数据段剩余的全部字节直接写入磁盘文件,不再经过堆内存缓冲,isInMemory() 随之返回 false。

若将 sizeThreshold 设置为 0,则任何非空上传项在写入第一个字节时即会触发落盘,完全不占用堆内存缓冲区;反之,若在内存充裕且以中小文件为主的场景适当调大阈值(如 64 KB 或 128 KB),可显著降低服务器磁盘 IOPS 压力。

临时文件生命周期 ​

只有当数据段体积超过 sizeThreshold 时,DiskFileItem 才会在临时目录生成物理文件,命名格式遵循:

text
upload_<JVM全局唯一UID>_<8位递增序号>.tmp

围绕该临时文件,存在三种典型的结束路径:

  1. 持久化迁移:业务层调用 FileItem 的落盘方法将上传文件保存至目标目录时,若数据位于磁盘,底层优先尝试通过操作系统文件重命名(renameTo)直接移动该 .tmp 文件,时间复杂度为 O(1)O(1);若临时目录与目标目录跨磁盘分区导致重命名失败,则自动退化为字节流拷贝,拷贝完成后再删除原临时文件。

  2. 显式主动清理:业务处理完毕、发生校验拦截(如非法后缀名、文件过大)或捕获异常中断时,应在 finally 代码块中显式调用 FileItem 的删除方法,立即释放已生成的磁盘临时文件。

  3. 被动兜底回收:若业务代码遗漏显式清理,或请求在解析中途因客户端断连而异常中止,残留的 .tmp 文件将长期滞留磁盘,最终导致磁盘空间耗尽。为此需要引入自动跟踪回收机制作为兜底保障。

FileCleaningTracker ​

为了防止遗漏清理导致临时文件泄漏,commons-io 提供了 FileCleaningTracker 组件。它不依赖已被现代 JDK 废弃的 finalize() 方法,而是基于 Java 引用队列与虚引用(PhantomReference)实现非阻塞的异步文件清理。

image-20261120222913592

将 FileCleaningTracker 绑定至 DiskFileItemFactory 后,自动回收流程按以下顺序运作:

  1. 创建即登记:每当 DiskFileItemFactory 创建一个新的 DiskFileItem 实例时,会预先确定其对应的临时文件对象,并以该 DiskFileItem 实例作为被监控对象(Marker),封装为一个继承自 PhantomReference 的内部跟踪节点注册到 ReferenceQueue 中。

  2. 后台守护监听:FileCleaningTracker 内部维护一个名为 Reaper 的后台守护线程,持续阻塞等待 ReferenceQueue 中的回收通知。

  3. GC 触发删除:HTTP 请求处理结束后,DiskFileItem 不再被任何业务对象强引用。当 JVM 执行垃圾回收时,回收器会将对应的虚引用节点放入 ReferenceQueue。Reaper 线程立即被唤醒,从队列取出跟踪节点,并自动删除关联的磁盘 .tmp 文件(若文件此前已被移动或显式删除,则安全忽略)。

FileCleanerCleanup ​

FileCleaningTracker 默认处于未启用状态,且其内部的 Reaper 线程一旦启动便会持续运行。在 Servlet 容器(如 Tomcat)支持热部署或卸载 Web 应用的场景下,如果直接手动 new FileCleaningTracker() 却未在应用销毁时终止该线程,存活的 Reaper 线程会持续持有当前应用的 WebappClassLoader 引用,从而引发严重的类加载器内存泄漏(Metaspace OOM)。

commons-fileupload 专门提供了实现了 ServletContextListener 接口的 FileCleanerCleanup 监听器,将回收线程与 Web 应用生命周期严格绑定:

  1. 容器启动阶段:监听器在 contextInitialized() 中创建全局唯一的 FileCleaningTracker 实例,并将其存入 ServletContext 属性域中供全应用共享。

  2. 容器卸载阶段:应用停止或重新部署时,监听器在 contextDestroyed() 中调用跟踪器的退出指令,通知 Reaper 线程在清理完剩余队列后安全终止,彻底断开对类加载器的引用。

示例: 临时存储与自动清理配置 ​

在基于 javax.servlet 的 Web 项目中,首先需在 web.xml 中注册 FileCleanerCleanup 监听器:

xml
<!-- 注册临时文件清理监听器,随容器启动创建并在卸载时安全终止回收线程 -->
<listener>
  <listener-class>org.apache.commons.fileupload.servlet.FileCleanerCleanup</listener-class>
</listener>

随后在构建 DiskFileItemFactory 时,配置独立的临时目录、自定义内存阈值,并从 ServletContext 中提取监听器托管的 FileCleaningTracker 实例完成绑定:

java
import java.io.File;
import javax.servlet.ServletContext;
import org.apache.commons.fileupload.disk.DiskFileItemFactory;
import org.apache.commons.fileupload.servlet.FileCleanerCleanup;
import org.apache.commons.io.FileCleaningTracker;

// 1. 构建工厂实例并指定内存缓冲区阈值与临时存储目录
public DiskFileItemFactory createFactory(ServletContext servletContext) {
  // 2. 创建并确保独立的临时目录存在,避免与系统目录混用
  File repository = new File(servletContext.getRealPath("/WEB-INF/temp"));
  if (!repository.exists()) {
    repository.mkdirs();
  }

  // 3. 实例化磁盘文件项工厂,设置 16KB 内存阈值与临时目录
  DiskFileItemFactory factory = new DiskFileItemFactory();
  factory.setSizeThreshold(16 * 1024);
  factory.setRepository(repository);

  // 4. 从应用上下文获取由监听器托管的临时文件跟踪器并绑定到工厂
  FileCleaningTracker tracker = FileCleanerCleanup.getFileCleaningTracker(servletContext);
  factory.setFileCleaningTracker(tracker);

  return factory;
}

即使配置了 FileCleaningTracker,高并发上传场景下仍建议在业务逻辑的 finally 块中主动调用 FileItem 的删除方法。自动回收依赖 JVM 的垃圾回收时机,属于兜底防泄漏手段;主动删除则能确保临时磁盘空间在请求结束瞬间立即可用。

x 与 2.x 工厂构建差异 ​

在适配 Jakarta Servlet(Tomcat 10+)的 commons-fileupload2 中,工厂的构建方式与底层文件 API 均进行了现代化重构:

对比维度commons-fileupload 1.xcommons-fileupload2 2.x
实例化方式构造方法配合 setSizeThreshold / setRepository建造者模式 DiskFileItemFactory.builder()
路径类型传统 java.io.FileNIO java.nio.file.Path
清理监听器FileCleanerCleanupJakartaFileCleaner

在 commons-fileupload2 中配置临时存储工厂的典型写法如下:

java
import java.nio.file.Path;
import java.nio.file.Paths;
import org.apache.commons.fileupload2.core.DiskFileItemFactory;

// 1. 2.x 版本采用建造者模式与 NIO Path API 构建工厂实例
Path tempDir = Paths.get(servletContext.getRealPath("/WEB-INF/temp"));

// 2. 通过链式调用配置内存缓冲区大小与临时目录路径
DiskFileItemFactory factory = DiskFileItemFactory.builder()
  .setBufferSize(16 * 1024)
  .setPath(tempDir)
  .get();

API: FileItemFactory【待补充】 ​

API: DiskFileItemFactory【待补充】 ​

API: DeferredFileOutputStream【待补充】 ​

API: FileCleaningTracker【待补充】 ​

API: FileCleanerCleanup【待补充】 ​

ServletFileUpload 请求解析 ​

ServletFileUpload 是 commons-fileupload 传统解析模式的核心入口,负责将原生 HttpServletRequest 中的二进制输入流按边界符完整拆解,并委托 FileItemFactory 封装为内存或磁盘承载的 FileItem 集合。通过该组件,开发者无需直接操作原始字节流,即可统一完成请求合法性校验、体积与数量限制、编码解码、进度回调及异常分类处理。

解析执行流程 ​

ServletFileUpload 继承自核心解析抽象类 FileUpload(其父类为 FileUploadBase)。为了使底层解析引擎与具体的 Servlet 或 Portlet 规范解耦,ServletFileUpload 在接收到 HttpServletRequest 后,会先通过适配器将其包装为通用的 ServletRequestContext,再交由父类执行完整的报文解析。

image-20261120222947293

一次完整的请求解析按以下顺序执行:

  1. 前置类型校验:在启动解析前,先校验当前请求是否为 POST 方法且请求头 Content-Type 以 multipart/ 开头。若客户端以普通 application/x-www-form-urlencoded 方式提交请求,直接拦截返回,避免后续解析抛出无效内容类型异常。

  2. 上下文适配与总长度预检:解析器将 HttpServletRequest 封装为 ServletRequestContext,并检查请求头中的 Content-Length。若已配置请求总体积上限且 Content-Length 明确超限,底层立即触发快速失败(Fail-Fast),在尚未读取请求体前直接中止。

  3. 流式拆包与项创建:解析器内部创建基于状态机的 FileItemIterator 逐段扫描请求体。每扫描到一个新的 Part,就调用绑定的 DiskFileItemFactory 创建一个 FileItem 实例,并将该段的原始字节写入 FileItem 内部的输出流(由 DeferredFileOutputStream 自动决定暂存内存还是切换落盘)。

  4. 结果汇总返回:所有数据段全部读取完毕后,解析器将所有 FileItem 实例汇总为有序列表(List<FileItem>)或按字段名分组的映射表(Map<String, List<FileItem>>)返回给业务层。

HTTP 请求输入流(ServletInputStream)只能被顺序消费一次。一旦调用 parseRequest() 开始读取请求体,流指针即到达末尾,此时无法再重复调用解析方法,也无法通过 request.getParameter() 获取表单参数;所有普通文本字段与上传文件必须统一从解析返回的 FileItem 集合中提取。

FileItem ​

解析完成后,请求体中的每一个数据段(无论文本还是二进制文件)都会被统一抽象为一个 FileItem 对象。业务层在遍历结果集时,必须先区分该表单项的类型,再执行对应的提取或落盘逻辑。

普通表单字段 ​

当浏览器提交的表单项不包含 filename 属性(如文本框、单选框、隐藏域)时,对应的 FileItem 被标记为普通表单字段。

  • 判断依据:通过表单项类型判定方法返回 true 识别。
  • 数据提取:由于文本字段体积通常远小于 DiskFileItemFactory 的内存阈值,其字节一般直接驻留在内存数组中。读取时必须显式传入字符集名称(如 UTF-8)将其解码为字符串;若表单中存在复选框等同名的多值字段,解析结果中会包含多个同名 FileItem,需自行归集。

上传文件项 ​

当数据段的 Content-Disposition 头部包含 filename 属性时,对应的 FileItem 被标记为文件项。处理文件项时需重点关注以下边界细节:

  • 空文件框判断:在 HTML 表单中,即使用户未在 <input type="file"> 控件中选择任何文件,浏览器仍会提交一个带有空文件名("")且字节数为 0 的文件段。业务层必须检查原始文件名是否为空字符串或仅包含空白字符,过滤无效的空上传项。
  • 客户端路径差异:部分老旧浏览器或特定 HTTP 客户端在 filename 中携带完整的本地绝对路径(如 C:\Users\demo\avatar.png),落盘前需借助 FilenameUtils 提取纯文件名,严禁直接拼接服务器存储路径。
  • 持久化与清理:调用落盘方法持久化数据时,若临时数据已在磁盘且与目标目录处于同一分区,底层直接通过文件重命名完成 O(1)O(1) 迁移;无论业务处理成功还是中途抛出校验异常,均应在 finally 块中主动删除临时数据,避免等待 GC 才释放磁盘空间。

字符编码处理 ​

在 multipart/form-data 上传过程中,中文乱码通常发生在两个完全独立的环节,任何一处配置缺失都会导致乱码,二者必须分别治理。

报文头部编码 ​

每个数据段的 Content-Disposition 头部承载了字段名(name)与原始文件名(filename)。当上传中文文件名时,浏览器按页面编码(通常为 UTF-8)直接将原始字节写入段头部。若未在 ServletFileUpload 上显式指定头部编码,解析器会尝试回退使用 request.getCharacterEncoding();若请求头未声明字符集,则默认按平台或 ISO-8859-1 解码,导致获取到的中文文件名变为乱码。在 ServletFileUpload 实例上显式设置 UTF-8 头部编码即可彻底解决文件名乱码。

字段正文编码 ​

普通表单字段的值位于数据段正文(Part Body)中,而非请求头部。即使在解析前调用了 request.setCharacterEncoding("UTF-8") 并配置了解析器的头部编码,当调用无参的文本读取方法获取普通字段值时,底层仍默认采用 ISO-8859-1 字符集进行字节到字符串的转换。因此,提取普通表单字段的值时,**必须调用带字符集参数的重载方法显式指定 UTF-8**。

乱码发生位置受影响内容正确配置方式
Part 头部上传文件的原始中文文件名、中文字段名解析前在 ServletFileUpload 实例上配置头部编码为 UTF-8
Part 正文普通文本输入框提交的中文参数值读取 FileItem 字符串值时显式传入 UTF-8 字符集

上传体积与数量限制 ​

若不对上传请求的体积和段数量设防,恶意客户端只需构造超大请求或包含数万个空表单项的报文,即可耗尽服务器磁盘空间或 CPU 资源(哈希碰撞与对象分配压力)。ServletFileUpload 提供三个维度的原生限制配置,默认均为 -1(表示不限制),生产环境必须全部显式设定合理上限。

单文件体积限制 ​

控制单个文件项允许上传的最大字节数(fileSizeMax)。解析器在流式读取每个文件段时实时累计当前项的已读字节数,一旦超出设定上限立即中断流读取并抛出单文件超限异常,防止单个超大文件撑爆临时目录。

请求总体积限制 ​

控制整次 HTTP 请求体(所有文件与普通字段及边界符之和)允许的最大字节数(sizeMax)。该限制具备双重校验机制:首先在解析前预检请求头 Content-Length 实现即时拦截;若客户端采用 Transfer-Encoding: chunked 分块传输导致缺少 Content-Length,则在读取输入流的过程中动态累计总字节数并在超限时立即中止。

文件项数量限制 ​

自 commons-fileupload 1.5 版本起新增文件项总数上限配置(fileCountMax),专门用于修复 CVE-2023-24998 拒绝服务漏洞。在早期版本中,攻击者即使受限于请求总大小,仍可在几兆字节的请求体中塞入数万个极小的伪造 Part,导致服务端创建海量临时文件与 FileItem 对象而宕机。通过限定单次请求允许包含的最大表单项数量,可有效阻断此类攻击。

FileUploadException ​

commons-fileupload 定义了层次清晰的受检异常体系,根异常为 FileUploadException。业务层不应笼统捕获顶层 Exception,而应按具体异常子类向客户端返回准确的 HTTP 状态码(如 413 Payload Too Large 或 400 Bad Request)与可读提示。

image-20261120223015929

常见核心异常子类及其触发场景如下:

异常子类触发场景建议 HTTP 响应状态码
SizeLimitExceededException整次请求总字节数超过 sizeMax 限制413 Payload Too Large
FileSizeLimitExceededException单个上传文件字节数超过 fileSizeMax 限制413 Payload Too Large
FileCountLimitExceededException请求内表单项总数超过 fileCountMax 限制(1.5+)400 Bad Request
InvalidContentTypeException请求头不是合法的 multipart/form-data 或缺少 boundary415 Unsupported Media Type
IOFileUploadException读取网络输入流中途发生客户端断连、超时等底层 I/O 异常400 Bad Request / 408 Request Timeout

ProgressListener ​

对于数十兆以上的文件上传,用户往往需要前端展示实时传输进度条。ServletFileUpload 内部在包装底层输入流时,通过装饰器流 ProgressNotifier 持续追踪已从网络读取的字节数,并定期回调开发者注册的 ProgressListener 接口。

回调方法会实时传入三个状态值:累计已读取字节数、请求总内容长度(若客户端使用分块传输未知长度则为 -1)以及当前正在解析的第几个表单项。

使用进度监听时需特别注意回调频次节流:底层输入流每次读取缓冲区(默认几 KB)都会触发一次回调。如果在回调中直接写入数据库、打印日志或高频写入分布式 Session,会制造严重的性能瓶颈。工程实践中通常在监听器内部记录上一次上报的字节里程碑(例如每传输满 1 MB 或进度变化超过 1%),仅在跨越阈值时更新进度状态(如写入 HttpSession 或 Redis,供前端通过轮询或 SSE 获取)。

java
// 1. 定义带节流控制的上传进度监听器,避免高频写入会话引发性能损耗
public class ThrottledProgressListener implements ProgressListener {

  // 2. 记录上一次触发进度更新时的兆字节计数
  private long lastMegaBytes = -1;

  // 3. 底层每读取一批字节即回调该方法,传入已读字节数、总长度与当前项序号
  @Override
  public void update(long pBytesRead, long pContentLength, int pItems) {
    long megaBytes = pBytesRead / (1024 * 1024);
    if (megaBytes == lastMegaBytes) {
      return;
    }
    lastMegaBytes = megaBytes;

    // 4. 仅在每累计传输满 1MB 时计算百分比并更新进度状态
    if (pContentLength > 0) {
      int percent = (int) ((pBytesRead * 100) / pContentLength);
      System.out.println("正在解析第 " + pItems + " 项,进度: " + percent + "%");
    }
  }
}

示例: 传统模式文件上传 ​

以下完整示例演示了基于 javax.servlet 与 commons-fileupload 1.5 的标准服务端上传处理流程,涵盖请求校验、临时目录与自动清理绑定、体积/数量限制、中文编码处理、进度监听、分级异常反馈以及 finally 主动临时文件回收:

java
package com.example.upload;

import java.io.File;
import java.io.IOException;
import java.util.List;
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 org.apache.commons.fileupload.FileItem;
import org.apache.commons.fileupload.FileUploadBase.FileSizeLimitExceededException;
import org.apache.commons.fileupload.FileUploadBase.SizeLimitExceededException;
import org.apache.commons.fileupload.FileUploadException;
import org.apache.commons.fileupload.disk.DiskFileItemFactory;
import org.apache.commons.fileupload.servlet.FileCleanerCleanup;
import org.apache.commons.fileupload.servlet.ServletFileUpload;
import org.apache.commons.io.FilenameUtils;

@WebServlet("/upload")
public class UploadServlet extends HttpServlet {

  // 1. 处理 multipart/form-data 文件上传请求
  @Override
  protected void doPost(HttpServletRequest req, HttpServletResponse resp)
      throws ServletException, IOException {
    resp.setContentType("text/plain;charset=UTF-8");

    // 2. 校验请求类型,非 multipart 请求直接拒绝解析
    if (!ServletFileUpload.isMultipartContent(req)) {
      resp.setStatus(HttpServletResponse.SC_BAD_REQUEST);
      resp.getWriter().write("请求类型必须为 multipart/form-data");
      return;
    }

    // 3. 配置临时存储工厂并绑定监听器托管的临时文件跟踪器
    DiskFileItemFactory factory = new DiskFileItemFactory();
    factory.setSizeThreshold(16 * 1024);
    factory.setFileCleaningTracker(
        FileCleanerCleanup.getFileCleaningTracker(getServletContext()));

    // 4. 构建核心解析器,配置编码、体积上限与文件数量上限
    ServletFileUpload upload = new ServletFileUpload(factory);
    upload.setHeaderEncoding("UTF-8");
    upload.setFileSizeMax(5 * 1024 * 1024L);
    upload.setSizeMax(20 * 1024 * 1024L);
    upload.setFileCountMax(10L);
    upload.setProgressListener(new ThrottledProgressListener());

    List<FileItem> items = null;
    try {
      // 5. 执行请求解析,获取包含所有普通字段与文件项的列表
      items = upload.parseRequest(req);

      File saveDir = new File(getServletContext().getRealPath("/WEB-INF/uploads"));
      if (!saveDir.exists()) {
        saveDir.mkdirs();
      }

      // 6. 遍历所有表单项,区分普通文本字段与上传文件项
      for (FileItem item : items) {
        if (item.isFormField()) {
          String fieldName = item.getFieldName();
          String value = item.getString("UTF-8");
          System.out.println("普通字段: " + fieldName + " = " + value);
        } else {
          String rawName = item.getName();
          if (rawName == null || rawName.trim().isEmpty()) {
            continue;
          }

          // 7. 剥离客户端潜在路径信息后将文件持久化落盘
          String safeName = FilenameUtils.getName(rawName);
          File targetFile = new File(saveDir, safeName);
          item.write(targetFile);
        }
      }

      resp.getWriter().write("文件上传成功");
    } catch (FileSizeLimitExceededException e) {
      // 8. 捕获单文件超限与请求总大小超限,返回明确的状态码与提示
      resp.setStatus(HttpServletResponse.SC_REQUEST_ENTITY_TOO_LARGE);
      resp.getWriter().write("单个文件大小超出 5MB 限制");
    } catch (SizeLimitExceededException e) {
      resp.setStatus(HttpServletResponse.SC_REQUEST_ENTITY_TOO_LARGE);
      resp.getWriter().write("本次上传总大小超出 20MB 限制");
    } catch (FileUploadException e) {
      resp.setStatus(HttpServletResponse.SC_BAD_REQUEST);
      resp.getWriter().write("请求解析失败: " + e.getMessage());
    } catch (Exception e) {
      throw new ServletException("文件保存异常", e);
    } finally {
      // 9. 无论成功或异常,均显式清理已生成的临时文件释放磁盘空间
      if (items != null) {
        for (FileItem item : items) {
          item.delete();
        }
      }
    }
  }
}

x 与 2.x 调用差异 ​

在迁移至 Jakarta Servlet(Tomcat 10+)对应的 commons-fileupload2 时,解析器类命名、字符集类型以及异常类体系均进行了重构:

对比维度commons-fileupload 1.xcommons-fileupload2 2.x
核心解析类ServletFileUploadJakartaServletFileUpload / JakartaServletDiskFileUpload
字符集参数字符串编码名称(如 "UTF-8")java.nio.charset.Charset(如 StandardCharsets.UTF_8)
文件落盘目标java.io.Filejava.nio.file.Path
异常体系基类独立受检异常 FileUploadException继承自 IOException 的 FileUploadException,超限子类更名为 FileUploadSizeException 等

在 commons-fileupload2 中,解析与落盘调用简化为强类型与 NIO 风格:

java
import java.nio.charset.StandardCharsets;
import java.nio.file.Path;
import java.util.List;
import org.apache.commons.fileupload2.core.DiskFileItem;
import org.apache.commons.fileupload2.core.DiskFileItemFactory;
import org.apache.commons.fileupload2.jakarta.servlet6.JakartaServletDiskFileUpload;

// 1. 2.x 版本通过 JakartaServletDiskFileUpload 直接解析为强类型 DiskFileItem
JakartaServletDiskFileUpload upload = new JakartaServletDiskFileUpload(factory);
upload.setHeaderCharset(StandardCharsets.UTF_8);
upload.setFileSizeMax(5 * 1024 * 1024L);

// 2. 读取普通字段与落盘均全面切换为 Charset 与 NIO Path
List<DiskFileItem> items = upload.parseRequest(req);
for (DiskFileItem item : items) {
  if (item.isFormField()) {
    String value = item.getString(StandardCharsets.UTF_8);
  } else {
    item.write(Path.of("/data/uploads", item.getName()));
  }
}

API: ServletFileUpload【待补充】 ​

API: FileItem【待补充】 ​

API: ProgressListener【待补充】 ​

API: FileUploadException【待补充】 ​

FileItemIterator 流式解析 ​

传统 parseRequest() 模式虽然使用便捷,但在处理大文件上传、高并发中转代理或直传云端对象存储(如 OSS、S3、MinIO)场景时,会带来额外的本地磁盘写放大与临时目录容量风险。commons-fileupload 提供的流式解析 API(以 FileItemIterator 与 FileItemStream 为核心)彻底绕过了临时文件缓冲层,允许业务代码直接从底层网络输入流中按段拉取原始字节,实现真正的零临时文件、恒定低内存文件上传处理。

传统模式性能瓶颈 ​

在 DiskFileItemFactory 驱动的传统解析模式下,一次大于内存阈值的大文件上传在服务器本地会经历两轮完整的磁盘或网络 I/O:

  1. 双重 I/O 写放大:解析器必须先将整个请求体读取完毕并写入临时目录的 .tmp 文件,随后业务代码才能拿到 List<FileItem>,再将临时文件拷贝或上传至最终存储目标(例如跨分区磁盘、NFS 或远端对象存储),导致吞吐量减半、磁盘 IOPS 翻倍。

  2. 首字节处理延迟:在最后一个字节到达服务器并完成落盘之前,parseRequest() 一直处于阻塞状态。即使客户端上传了一个不符合业务规则的文件,服务端也往往要等到请求接收大半甚至全部落盘后才能在业务层校验拦截。

  3. 临时磁盘容量枯竭:高并发上传数百兆视频或压缩包时,即便最终目标在云端对象存储,应用服务器的本地临时磁盘仍可能被并发 .tmp 文件瞬间打满。

两种解析模式的架构差异如下:

对比维度传统解析模式(FileItem)流式解析模式(FileItemIterator)
是否需要工厂必须配置 DiskFileItemFactory不需要任何 FileItemFactory 实例
本地临时文件超过阈值即生成 .tmp 临时文件零临时文件,全程直接消费网络流
内存占用模型小文件驻留堆内存,大文件切盘缓冲仅维持极小的滑动窗口缓冲区(默认约 4 KB)
数据访问顺序全部解析完毕后可随机反复读取任意字段严格单向顺序消费,按 HTTP 报文到达次序处理
提前获知文件大小落盘完成后可精确获取单文件总字节数读取流之前无法预知当前文件的精确总字节数
典型适用场景常规表单、中小文件、需随机读取元数据后再保存文件大文件上传、网关代理转发、边上传边计算哈希/直传对象存储

零临时文件流式架构 ​

实际上,传统模式中的 parseRequest() 在底层正是基于 FileItemIterator 构建的:传统模式替开发者遍历迭代器,把每个数据段的流拷贝进 DiskFileItemFactory 创建的 FileItem 中。而流式解析模式将这个控制权直接交还给业务层。

image-20261120223042259

流式架构的核心运作方式为按需拉取(Pull Model):

  1. 跳过存储工厂:实例化无参的 ServletFileUpload 即可开启流式解析,底层不再创建 DiskFileItem 与 DeferredFileOutputStream,也不涉及 FileCleaningTracker 回收逻辑。

  2. 包装底层网络流:调用迭代器入口方法后,解析器将 HttpServletRequest 的原始输入流逐层包装——外层挂载用于统计总字节数的 LimitedInputStream 与用于回调进度的 ProgressNotifier,内层交由 MultipartStream 维护固定大小的滑动缓冲区扫描分界符。

  3. 直连目标输出通道:每当迭代器定位到一个新的数据段头部,业务层直接获取指向该段主体的逻辑输入流,在循环中将字节一边从 Socket 读出、一边实时写入目标存储(如本地最终文件、对象存储分片上传流、加密流或消息摘要流),全程不落地任何中间 .tmp 文件。

FileItemIterator ​

FileItemIterator 承担“报文边界推进器”的职责,以懒加载方式按顺序迭代 HTTP 请求体中的每一个数据段。

  • 懒解析推进:获取迭代器对象时,解析器并未读取整个请求体,仅校验了请求头与总长度上限;只有当业务层主动推进迭代步骤时,底层的 MultipartStream 才会向前扫描到下一个分界符,并解析出该段的头部元数据。
  • 保留原生安全防线:虽然绕过了 DiskFileItemFactory,但配置在 ServletFileUpload 上的头部编码(headerEncoding)、请求总大小上限(sizeMax)、单文件大小上限(fileSizeMax)、表单项总数上限(fileCountMax)以及 ProgressListener 在流式模式下依然完整生效。

FileItemStream ​

FileItemStream 代表当前正在扫描的某一个表单数据段,它并不是缓存在内存中的数据快照,而是挂载在底层 HTTP 输入流上的一个实时切片窗口。

使用 FileItemStream 时必须严格遵守三个流式约束:

  1. 单向推进与即时失效:同一时刻仅允许消费当前这一个 FileItemStream 打开的输入流。一旦业务层再次调用 FileItemIterator 的推进方法进入下一段,前一个 FileItemStream 对应的切片流会被立即标记关闭,底层指针自动跳过前一段尚未读完的剩余字节,无法回头重新读取。

  2. 前端表单字段顺序依赖:由于服务端只能按字节到达顺序依次读取,如果保存文件时需要依赖其他普通文本参数(例如业务分类 bizType、归属目录 folderId 或校验令牌),前端 HTML 表单或 FormData 必须将这些普通文本字段排列在 <input type="file"> 之前,确保服务端先提取到元数据再开始处理紧随其后的文件流。

  3. 无预知文件长度:在文件流尚未扫描到结束边界符之前,服务端不可能知道该文件一共有多少字节,因此 FileItemStream 不提供获取文件总大小的方法。若对接某些要求预先声明内容长度的对象存储接口,需由前端在前置普通字段中传入文件大小,或采用分片上传接口流式推送。

对于普通文本字段与文件项,打开流后的消费方式有所不同:

  • 普通文本字段:借助 commons-fileupload 内置工具类 Streams 将短小的字符流按 UTF-8 直接解码为字符串。
  • 上传文件项:使用 commons-io 的 IOUtils 将当前段的 InputStream 流式拷贝至最终输出流,大文件场景应优先选用支持超过 2 GB 计数的长整型拷贝方法。

流式消费边界与异常解包 ​

流式解析在异常处理与资源关闭上与传统模式存在显著差异,忽略这些细节容易导致状态码误判或流提前损坏:

  1. 体积超限异常的二次包装:在传统模式中,parseRequest() 内部完成了全部字节读取,单文件或总请求体积超限会直接抛出 FileSizeLimitExceededException 或 SizeLimitExceededException。但在流式模式下,读取动作发生在业务层操作 InputStream 的过程中,而标准 InputStream.read() 的方法签名只允许抛出 IOException。因此,当流式读取中途触发体积超限时,commons-fileupload 1.x 会将具体的 FileUploadException 包装在一个继承自 IOException 的 FileUploadIOException 中抛出。业务层捕获该异常后,必须调用 getCause() 解包,才能准确识别超限类型并返回 413 Payload Too Large。

  2. 仅关闭切片流,严禁关闭底层请求流:每次通过 try-with-resources 关闭 FileItemStream 返回的输入流是安全且推荐的——它关闭的只是当前段的逻辑切片包装流(ItemInputStream),并不会关闭底层的 ServletInputStream,后续数据段仍可正常继续读取。切勿手动关闭 request.getInputStream(),否则会立即破坏后续所有数据段的解析。

  3. 半成品清理:由于流式上传是边收边写最终目标文件,一旦读取中途因客户端断连或触发体积超限抛出异常,目标路径下可能残留只写了一半的损坏文件。生产代码在捕获异常时应同步删除该未完成的目标文件。

示例: 零临时文件流式上传 ​

以下完整示例展示了基于 javax.servlet 与 commons-fileupload 1.5 的流式文件上传处理,全程不实例化 DiskFileItemFactory,直接将上传流写入最终目录并妥善解包流式超限异常:

java
package com.example.upload;

import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
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 org.apache.commons.fileupload.FileItemIterator;
import org.apache.commons.fileupload.FileItemStream;
import org.apache.commons.fileupload.FileUploadBase.FileSizeLimitExceededException;
import org.apache.commons.fileupload.FileUploadBase.FileUploadIOException;
import org.apache.commons.fileupload.FileUploadBase.SizeLimitExceededException;
import org.apache.commons.fileupload.FileUploadException;
import org.apache.commons.fileupload.servlet.ServletFileUpload;
import org.apache.commons.fileupload.util.Streams;
import org.apache.commons.io.FilenameUtils;
import org.apache.commons.io.IOUtils;

@WebServlet("/stream-upload")
public class StreamingUploadServlet extends HttpServlet {

  // 1. 采用零临时文件流式 API 处理大文件上传请求
  @Override
  protected void doPost(HttpServletRequest req, HttpServletResponse resp)
      throws ServletException, IOException {
    resp.setContentType("text/plain;charset=UTF-8");

    // 2. 校验请求类型,非 multipart 请求直接拦截
    if (!ServletFileUpload.isMultipartContent(req)) {
      resp.setStatus(HttpServletResponse.SC_BAD_REQUEST);
      resp.getWriter().write("请求类型必须为 multipart/form-data");
      return;
    }

    // 3. 无需创建 DiskFileItemFactory,直接实例化解析器并配置编码与体积限制
    ServletFileUpload upload = new ServletFileUpload();
    upload.setHeaderEncoding("UTF-8");
    upload.setFileSizeMax(50 * 1024 * 1024L);
    upload.setSizeMax(200 * 1024 * 1024L);
    upload.setFileCountMax(10L);

    File saveDir = new File(getServletContext().getRealPath("/WEB-INF/uploads"));
    if (!saveDir.exists()) {
      saveDir.mkdirs();
    }

    try {
      // 4. 获取拉取式数据段迭代器,按 HTTP 报文到达顺序逐段处理
      FileItemIterator iter = upload.getItemIterator(req);
      while (iter.hasNext()) {
        FileItemStream item = iter.next();
        String fieldName = item.getFieldName();

        // 5. 打开当前段专属输入流,必须在下一次 iter.hasNext() 前完成消费并关闭
        try (InputStream in = item.openStream()) {
          if (item.isFormField()) {
            String value = Streams.asString(in, "UTF-8");
            System.out.println("普通字段: " + fieldName + " = " + value);
          } else {
            String rawName = item.getName();
            if (rawName == null || rawName.trim().isEmpty()) {
              continue;
            }

            // 6. 跳过本地临时文件,直接将网络字节流拷贝至最终目标输出流
            String safeName = FilenameUtils.getName(rawName);
            File targetFile = new File(saveDir, safeName);
            try (OutputStream out = new FileOutputStream(targetFile)) {
              IOUtils.copyLarge(in, out);
            }
          }
        }
      }

      resp.getWriter().write("流式上传成功");
    } catch (FileUploadIOException e) {
      // 7. 流式读取中途触发的体积超限会被包装为 FileUploadIOException,需解包判定原因
      Throwable cause = e.getCause();
      if (cause instanceof FileSizeLimitExceededException
          || cause instanceof SizeLimitExceededException) {
        resp.setStatus(HttpServletResponse.SC_REQUEST_ENTITY_TOO_LARGE);
        resp.getWriter().write("上传文件体积超出限制");
      } else {
        resp.setStatus(HttpServletResponse.SC_BAD_REQUEST);
        resp.getWriter().write("流式解析中断: " + e.getMessage());
      }
    } catch (FileUploadException e) {
      resp.setStatus(HttpServletResponse.SC_BAD_REQUEST);
      resp.getWriter().write("请求头解析失败: " + e.getMessage());
    }
  }
}

x 与 2.x 流式调用差异 ​

在适配 Jakarta Servlet 的 commons-fileupload2 中,流式接口的命名更贴合输入流语义,同时彻底消除了 1.x 中令人困扰的 FileUploadIOException 异常二次包装问题:

对比维度commons-fileupload 1.xcommons-fileupload2 2.x
迭代器接口FileItemIteratorFileItemInputIterator
流式数据项接口FileItemStreamFileItemInput
获取切片输入流openStream()getInputStream()
流式超限异常包装在 FileUploadIOException 中,需 getCause() 解包FileUploadException 直接继承 IOException,可直接捕获具体超限子类

commons-fileupload2 中的流式解析典型写法如下:

java
import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import org.apache.commons.fileupload2.core.FileItemInput;
import org.apache.commons.fileupload2.core.FileItemInputIterator;
import org.apache.commons.fileupload2.jakarta.servlet6.JakartaServletFileUpload;

// 1. 2.x 版本直接构建无工厂的 JakartaServletFileUpload 进行流式解析
JakartaServletFileUpload<?, ?> upload = new JakartaServletFileUpload<>();
upload.setHeaderCharset(StandardCharsets.UTF_8);
upload.setFileSizeMax(50 * 1024 * 1024L);

// 2. 通过 FileItemInputIterator 与 FileItemInput 逐段拉取原始输入流
FileItemInputIterator iter = upload.getItemIterator(req);
while (iter.hasNext()) {
  FileItemInput item = iter.next();
  try (InputStream in = item.getInputStream()) {
    if (item.isFormField()) {
      String value = new String(in.readAllBytes(), StandardCharsets.UTF_8);
    } else {
      Files.copy(in, Path.of("/data/uploads", item.getName()));
    }
  }
}

API: FileItemIterator【待补充】 ​

API: FileItemStream【待补充】 ​

API: IOUtils【待补充】 ​

API: FilenameUtils【待补充】 ​

上传存储安全 ​

文件上传接口允许外部不可信用户直接向服务器文件系统写入二进制数据,是 Java Web 应用中最容易引发高危漏洞的攻击面之一。未设防的落盘逻辑可能导致路径穿越覆盖系统关键文件、上传 JSP 木马触发远程代码执行(WebShell RCE)、恶意 SVG/HTML 引发存储型 XSS,或因海量文件堆积在同一目录导致服务器文件系统性能崩溃。生产环境的上传持久化不能依赖单一校验,而必须围绕“输入清洗、类型核验、存储隔离、目录打散”构建完整的纵深防御链路。

image-20261120223106486

路径穿越防护 ​

HTTP 请求中 Content-Disposition 头部携带的 filename 字段完全由客户端控制,攻击者可利用抓包工具将其篡改为包含相对路径跳转符或绝对路径的恶意字符串(例如 ../../../../tomcat/webapps/ROOT/shell.jsp 或 C:\Windows\win.ini)。如果服务端直接将客户端原始文件名与存储根目录拼接落盘,就会触发典型的路径穿越(Path Traversal)漏洞,将恶意文件写入预期目录之外的任意可写位置。

防御路径穿越必须采用“输入剥离 + 规范化边界断言”的双重校验:

  1. 剥离路径前缀与空字节:借助 commons-io 的 FilenameUtils 从原始文件名中截取最后一个路径分隔符(同时兼容 Unix / 与 Windows \)之后的纯文件名,并过滤其中可能存在的空字节(\0),防止底层 C 文件系统接口触发截断绕过。

  2. 规范化路径边界校验:在拼接出最终落盘路径后,必须先将其转换为消除 .、.. 与符号链接差异的规范化绝对路径(Path.toAbsolutePath().normalize() 或 File.getCanonicalPath()),再严格断言目标路径位于隔离根目录之内(targetPath.startsWith(normalizedBase))。任何越界路径一律立即中断并抛出安全异常。

文件名重命名 ​

即使完成了路径剥离,也绝不应直接使用客户端上传的原始文件名作为磁盘上的物理文件名,原因在于:

  1. 同名覆盖风险:不同用户上传相同名称的文件(如 avatar.jpg、简历.pdf)会导致后者直接覆盖前者的数据。

  2. 解析歧义与畸形字符:包含空格、中文、分号、多重扩展名(如 payload.jsp;.jpg)或操作系统保留字(如 Windows 下的 CON、AUX)的文件名,在不同操作系统与 Web 代理层(Nginx、Tomcat)之间容易引发解析差异漏洞。

标准的工程实践是将逻辑展示名与物理存储名彻底解耦:

  • 磁盘物理存储名:由服务端基于随机算法(如无连字符的 UUID 或雪花算法 ID)重新生成全局唯一文件名,仅拼接经过白名单校验的纯小写安全扩展名(例如 9f8e7d6c5b4a432189abcdef01234567.png)。
  • 业务展示文件名:经过转义清洗后的用户原始文件名仅作为元数据保存在数据库表中,展示列表或触发下载时再从数据库读取并还原给用户。

文件类型校验 ​

客户端在 multipart 请求段头中声明的 Content-Type(例如 image/jpeg)以及文件名后缀均属于客户端可控输入,只需修改请求报文即可轻易伪造,服务端绝不能仅凭 FileItem 解析出的内容类型放行文件。

扩展名白名单 ​

文件后缀校验必须坚持白名单策略,严禁使用黑名单(如仅禁止 .jsp、.exe)。黑名单极易被遗漏的等效可执行后缀或大小写变体绕过(例如 .jspx、.jspf、.Jsp、Windows 下自动忽略末尾点号或空格的 .jsp.)。

服务端应结合业务场景明确维护允许上传的最小集合(如头像上传仅允许 jpg、jpeg、png、webp),提取纯文件名中的最后一段扩展名并统一转为小写(Locale.ROOT)后执行精确匹配。

文件魔数校验 ​

仅校验扩展名无法阻止攻击者将恶意脚本(如 JSP 代码或可执行程序)改名为 .png 上传。不同格式的二进制文件在其头部前若干字节通常具有固定的特征标识,称为文件魔数(Magic Number)。

常见文件格式的十六进制魔数对照如下:

文件格式典型扩展名起始魔数(Hex)ASCII 特征说明
JPEG.jpg / .jpegFF D8 FFSOI 起始标记及段头
PNG.png89 50 4E 47 0D 0A 1A 0A含 PNG 标识及换行检测字节
GIF.gif47 49 46 38GIF8(GIF87a / GIF89a)
PDF.pdf25 50 44 46%PDF
ZIP / Office.zip / .docx / .xlsx50 4B 03 04PK..(OpenXML 文档本质为 ZIP 归档)

在流式上传或读取 FileItem 输入流时,检测魔数需要预先读取流的前若干字节。为了不破坏后续落盘数据的完整性,必须先将原始输入流包装为 BufferedInputStream,在读取前标记起始位置(mark),读取足够字节比对魔数通过后调用 reset() 将流指针归位,再执行完整流拷贝。

对于更复杂的文档或复合格式识别(如区分 .docx、.xlsx 与普通 .zip),可引入 Apache Tika 等内容探测库结合 ZIP 内部结构进行深度校验。

二次渲染与 XSS 防护 ​

即便文件头部匹配合法图片魔数,攻击者仍可能构造“图片马”(在合法 JPEG 的 EXIF 注释区或 PNG 数据块尾部夹带脚本代码),或上传包含 <script> 标签的 .svg 矢量图。当浏览器直接访问这类静态文件时,可能触发存储型 XSS 甚至脚本执行。

高安全场景下应追加以下防护手段:

  1. 图片二次重编码:对用户上传的图片通过 ImageIO 或缩略图库解码为内存像素矩阵后重新编码输出,可彻底剥离非像素区的 EXIF 元数据与隐藏恶意载荷。

  2. 禁止内联解析高危文档:不将 .html、.htm、.svg、.xml 加入开放静态直链白名单;若业务确需支持上传,必须在下载或访问响应中强制附带 Content-Disposition: attachment 与 X-Content-Type-Options: nosniff,禁止浏览器进行 MIME 嗅探和内联脚本渲染。

隔离存储 ​

将上传文件直接保存在 Tomcat 应用部署目录内(例如 webapps/app/uploads/)是 Java Web 开发中最常见也最危险的反模式,存在两个致命缺陷:

  1. WebShell 执行漏洞:Tomcat 默认会将 webapps 目录下所有 .jsp 文件交由 JspServlet 编译为 Java 类并执行。一旦其他校验环节出现疏漏,攻击者上传的脚本落盘在应用公开目录中即可直接通过 URL 触发远程代码执行。

  2. 部署覆盖丢数据:重新打包发布 WAR 文件或重启容器清理展开目录时,应用目录内的全部用户上传文件会被直接清空。

生产环境必须遵循执行环境与存储目录物理隔离原则:

  1. 独立外部存储目录:将文件持久化到应用部署目录之外的专用数据分区(如 /data/app-uploads/),或直接托管至独立的分布式对象存储(如 OSS、S3、MinIO)。若受限于小型部署环境暂存应用内,也至少应置于受 Servlet 规范保护、禁止客户端直接 URL 访问的 /WEB-INF/ 目录下,并通过鉴权下载 Servlet 中转输出。

  2. 动静分离与禁用脚本执行:若使用 Nginx 对外部存储目录提供静态文件访问,需独立配置静态资源域名(避免与主站共享 Cookie 引发同源安全风险),并在 Nginx 层面显式关闭该目录的动态脚本转发与代理能力。

  3. 操作系统最小权限:运行 Tomcat 的系统账号不应为 root;为上传存储目录及其生成的文件移除执行权限(例如文件权限设为 0640),确保即使文件被篡改也无法被操作系统作为可执行程序运行。

目录打散 ​

当业务持续运行、上传文件数量达到数十万乃至数百万级时,如果将所有文件平铺存放在同一个文件夹下,不仅会导致人工运维与目录遍历极度缓慢,还会触发文件系统性能急剧退化(部分传统文件系统对单目录内的文件数或子目录数存在硬性上限,且目录检索与 inode 锁竞争开销陡增)。通过多级子目录将文件分散存储(即目录打散)是必不可少的存储结构设计。

image-20261120223126481

日期分层目录 ​

按上传时间构建层级路径,常见格式为 年/月/日/(如 /data/uploads/2026/11/20/<uuid>.png)。

  • 优势:路径语义直观,极其便于按时间窗口执行冷热数据迁移、增量备份或定时清理过期临时业务文件。
  • 局限:如果系统在特定促销活动或高峰日单日上传量达数百万级,当日目录仍会出现局部文件过度集中的热点问题,此时可在日期目录之下再结合小时或哈希目录做二级打散。

哈希多级目录 ​

对服务端重命名后的随机文件名(如 UUID)计算哈希值,利用位运算截取低位十六进制字符构建固定深度的目录树:

  1. 取 hashCode() 的低 4 位(hash & 0xF)映射为第一级目录(0~f,共 16 个子目录)。

  2. 无符号右移 4 位再取低 4 位((hash >>> 4) & 0xF)映射为第二级目录(0~f,共 16 个子目录)。

两级十六进制打散即可稳定生成 16×16=25616 \times 16 = 256 个均匀分布的叶子目录;若文件规模达亿级,可按字节截取(hash & 0xFF)扩展为 256×256=65536256 \times 256 = 65536 个目录。使用位掩码与无符号右移 >>> 能保证即使 hashCode() 为负数(包括 Integer.MIN_VALUE),计算出的目录索引也始终落在合法的非负范围内。

示例: 安全落盘工具类 ​

以下工具类整合了路径剥离、扩展名白名单、基于 BufferedInputStream 的流式魔数校验、UUID 重命名、两级十六进制哈希目录打散以及规范化路径边界校验,可直接嵌入传统模式(传入 item.getInputStream())或流式模式(传入 item.openStream())的持久化环节:

java
package com.example.upload;

import java.io.BufferedInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Locale;
import java.util.Map;
import java.util.UUID;
import org.apache.commons.io.FilenameUtils;
import org.apache.commons.io.IOUtils;

// 1. 安全文件落盘工具,串联路径剥离、白名单、魔数校验、重命名与目录打散
public class SafeUploadStorage {

  private static final Map<String, byte[]> ALLOWED_MAGIC = createMagicTable();

  private static Map<String, byte[]> createMagicTable() {
    Map<String, byte[]> map = new HashMap<>();
    map.put("jpg", new byte[]{(byte) 0xFF, (byte) 0xD8, (byte) 0xFF});
    map.put("png", new byte[]{(byte) 0x89, 0x50, 0x4E, 0x47});
    map.put("pdf", new byte[]{0x25, 0x50, 0x44, 0x46});
    return Collections.unmodifiableMap(map);
  }

  // 2. 执行完整校验并将上传流安全持久化至隔离根目录
  public Path store(InputStream rawIn, String rawName, Path baseDir) throws IOException {
    // 3. 剥离客户端路径前缀与空字节,提取并规范化小写扩展名
    String cleanName = FilenameUtils.getName(rawName == null ? "" : rawName.replace("\0", ""));
    String ext = FilenameUtils.getExtension(cleanName).toLowerCase(Locale.ROOT);
    byte[] expectedMagic = ALLOWED_MAGIC.get(ext);
    if (expectedMagic == null) {
      throw new SecurityException("不支持的文件扩展名: " + ext);
    }

    // 4. 包装为可回退缓冲流,读取头部魔数校验真实类型后重置流指针
    BufferedInputStream bin = new BufferedInputStream(rawIn);
    bin.mark(expectedMagic.length);
    byte[] header = new byte[expectedMagic.length];
    int read = IOUtils.read(bin, header);
    if (read < expectedMagic.length || !Arrays.equals(header, expectedMagic)) {
      throw new SecurityException("文件内容与扩展名不匹配");
    }
    bin.reset();

    // 5. 生成随机存储名,并按哈希低位计算两级十六进制打散目录
    String storedName = UUID.randomUUID().toString().replace("-", "") + "." + ext;
    int hash = storedName.hashCode();
    String dirA = Integer.toHexString(hash & 0xF);
    String dirB = Integer.toHexString((hash >>> 4) & 0xF);

    // 6. 解析规范化目标路径并校验边界,阻断任何路径穿越企图
    Path normalizedBase = baseDir.toAbsolutePath().normalize();
    Path targetPath = normalizedBase.resolve(dirA).resolve(dirB).resolve(storedName).normalize();
    if (!targetPath.startsWith(normalizedBase)) {
      throw new SecurityException("检测到非法存储路径穿越");
    }

    // 7. 创建打散子目录并执行流式落盘
    Files.createDirectories(targetPath.getParent());
    Files.copy(bin, targetPath);
    return targetPath;
  }
}

API: FilenameUtils【待补充】 ​

API: FileUtils【待补充】 ​

Servlet 文件下载 ​

在 Java Web 应用中,静态资源通常可以直接由 Tomcat 默认的 DefaultServlet 或前置 Nginx 提供访问;但在涉及权限校验、隔离目录读取(如 /WEB-INF/ 或应用外独立分区)、数据库展示名还原、下载次数统计或强制另存为等业务场景时,必须通过业务 Servlet 接管下载请求。与上传流程不同,文件下载不涉及 commons-fileupload,而是由 Servlet 响应头控制协议语义,并结合 commons-io 完成大文件的低内存流式下发。

下载执行流程 ​

一次完整的 Servlet 文件下载需要严格遵循“先校验、再设头、最后写流”的执行顺序。在任何字节写入响应体之前,必须先确认用户权限与目标文件合法性;一旦响应缓冲区开始向客户端刷写字节,HTTP 状态行与响应头即进入已提交状态(isCommitted() == true),届时再修改响应头或返回 404 / 403 错误状态码将直接失效或抛出异常。

image-20261120223155181

标准下载链路分为五个步骤:

  1. 鉴权与参数解析:拦截下载请求并校验当前会话的访问权限,提取请求参数中的文件标识(推荐传入业务主键 ID,由服务端查库映射物理存储路径与原始展示文件名)。

  2. 物理路径安全校验:对目标路径执行规范化与隔离根目录边界断言,确认文件存在且为常规可读文件;若校验失败,立即返回 400、403 或 404 并终止执行。

  3. 配置 HTTP 响应头:依次声明响应体的媒体类型(Content-Type)、禁止 MIME 嗅探标记(X-Content-Type-Options)、文件总字节数(Content-Length)以及下载处置方式与编码后的文件名(Content-Disposition)。

  4. 流式拷贝响应体:打开本地磁盘文件输入流,借助 commons-io 的 IOUtils 按固定缓冲区循环读取字节并写入 HttpServletResponse 提供的二进制输出流(ServletOutputStream)。

  5. 局部资源释放:在 try-with-resources 中关闭服务端打开的本地文件输入流,而 ServletOutputStream 的生命周期交由 Servlet 容器统一收尾。

HTTP 响应头配置 ​

浏览器收到服务端返回的二进制字节流后,究竟是在标签页中直接渲染预览、弹出另存为对话框、正确显示中文文件名还是精确渲染下载进度条,完全取决于服务端配置的 HTTP 响应头。

Content-Type ​

Content-Type 用于告知浏览器响应体的 MIME 类型(例如 image/png、application/pdf)。

  • 动态推断与兜底:服务端可通过 ServletContext 根据文件名后缀查询容器内置的 MIME 映射表(对应 Tomcat conf/web.xml 中的 <mime-mapping>)。对于未注册的冷门或自定义后缀,统一回退为通用二进制流 application/octet-stream。
  • 禁止浏览器内容嗅探:部分浏览器在遇到未知类型或特定文本片段时,会忽略 Content-Type 自行猜测内容格式并尝试将其当作 HTML 或脚本执行。生产环境的下载接口必须同时附加 X-Content-Type-Options: nosniff,强制浏览器严格遵守服务端声明的媒体类型。

Content-Disposition ​

Content-Disposition 决定客户端如何处置响应载荷,核心取值分为两类:

处置指令浏览器行为典型适用场景
inline优先在浏览器窗口内直接渲染打开,无法渲染时才回退为下载图片预览、在线查看 PDF 合同、音视频播放
attachment强制触发浏览器的文件保存对话框,禁止直接内联渲染报表导出、安装包分发、用户上传的不可信附件

当下载文件名包含中文、空格或特殊符号时,由于 HTTP/1.1 协议规范要求响应头值仅允许 ISO-8859-1(ASCII 子集)字符,直接拼接原始中文字符串会导致乱码甚至容器抛出非法字符异常。早期项目常采用 new String(name.getBytes("UTF-8"), "ISO-8859-1") 或根据 User-Agent 区分 IE/Firefox 的硬编码兼容方案,但这种做法在现代多端浏览器中极易产生编码分歧。

现代跨浏览器标准方案是遵循 RFC 5987 / RFC 6266,在同一条 Content-Disposition 响应头中同时提供 ASCII 回退名与标准 UTF-8 扩展名:

  1. filename="...":仅保留安全 ASCII 字符作为老旧客户端的兜底名称,并过滤双引号与换行符(\r、\n)以防止 HTTP 响应头注入(CRLF Injection)。

  2. filename*=UTF-8''...:遵循 字符集'语言标签'百分号编码值 语法(中间两个单引号表示省略语言标签),现代主流浏览器(Chrome、Edge、Firefox、Safari)均会优先解析该字段。

使用 JDK 的 URLEncoder.encode(name, "UTF-8") 生成百分号编码时,该方法遵循表单编码规则会将空格转换为 + 号;而 RFC 5987 要求空格必须编码为 %20,因此编码后务必显式将 + 替换为 %20,否则下载文件名中的空格会被浏览器还原为加号。

java
// 1. 对原始中文文件名执行 UTF-8 URL 编码,并将空格对应的 + 修正为 %20
String encodedName = URLEncoder.encode(originalName, "UTF-8")
  .replaceAll("\\+", "%20");

// 2. 过滤非 ASCII 字符、双引号与换行符,构造安全回退名并防御响应头注入
String asciiFallback = originalName.replaceAll("[^\\x20-\\x7E]|[\"\\\\]", "_");

// 3. 按 RFC 5987 规范同时输出兼容回退名与标准 UTF-8 扩展名
String headerValue = "attachment; filename=\"" + asciiFallback
  + "\"; filename*=UTF-8''" + encodedName;
resp.setHeader("Content-Disposition", headerValue);

Content-Length ​

声明响应体的精确字节长度具有两项实际价值:

  1. 客户端进度可视化:浏览器在收到 Content-Length 后才能计算已下载百分比与预估剩余时间;若缺失该响应头,Servlet 容器会自动退化为 Transfer-Encoding: chunked 分块传输,浏览器下载栏只能显示已接收字节数而无法展示总进度。

  2. 大文件 64 位长度支持:Servlet 早期提供的 setContentLength(int) 方法参数为 32 位有符号整型,当下载文件超过 2 GB(231−12^{31} - 1 字节)时会发生整型溢出变为负数导致下载损坏。Servlet 3.1 及以上版本应始终使用支持 64 位长整型的 setContentLengthLong(long)(或在老旧容器中以字符串形式手动设置 Content-Length 响应头)。

IOUtils ​

服务端输出文件数据时,严禁调用类似 Files.readAllBytes() 的方法将整个文件一次性加载进 JVM 堆内存数组,否则数百兆文件的并发下载会迅速触发 OutOfMemoryError。借助 commons-io 提供的 IOUtils(或面向 File 对象的 FileUtils),可以以恒定的小内存缓冲区(默认 8 KB)完成磁盘文件流向网络输出流的连续搬运。

使用流式拷贝时需严格规避以下四类工程陷阱:

  1. 大文件拷贝计数器溢出:IOUtils 提供了返回 int 与返回 long 的两套流拷贝方法。当传输文件体积超过 2 GB 时,返回 int 的常规拷贝方法会因累加字节数溢出返回 -1;面向任意大小文件的通用下载接口应统一选用基于 64 位计数的长整型流拷贝方法(copyLarge)。

  2. 仅关闭本地输入流,托管容器输出流:在 try-with-resources 语句中只应关闭服务端自身打开的 FileInputStream / Files.newInputStream(),**不要手动调用 resp.getOutputStream().close()**。ServletOutputStream由 Tomcat 等 Servlet 容器创建并复用,提前关闭可能干扰后续 Filter 链的后置处理(如响应统计、压缩或日志记录);传输完毕调用flush() 确保缓冲区刷出后交由容器自动关闭即可。

  3. 禁止混用字符流与字节流:在同一次请求生命周期内,resp.getOutputStream() 与 resp.getWriter() 严格互斥。若在输出二进制流之前调用过 getWriter(),再次获取字节输出流会直接抛出 IllegalStateException;因此下载接口中若需返回纯文本错误提示,应优先使用 resp.sendError() 或确保异常分支与正常流分支完全隔离。

  4. 优雅处理客户端中途取消下载:用户在浏览器中点击“取消下载”或网络闪断时,底层 TCP 连接会被客户端重置,正在执行流拷贝的线程会抛出容器特定的 IOException(如 Tomcat 的 ClientAbortException: Broken pipe)。此类异常属于正常的客户端中断行为,捕获后仅需记录调试级日志并释放本地文件流,无需作为服务端严重故障告警,也不应再向已提交的响应中尝试写入错误页面。

下载路径安全 ​

文件下载接口同样面临高危的任意文件读取(Arbitrary File Download)风险。如果接口直接接收客户端传入的文件路径(如 /download?file=../../WEB-INF/web.xml 或 /download?file=/etc/passwd),攻击者可借此窃取应用源码、数据库配置文件甚至服务器系统凭证。

构建安全的下载入口应遵循以下防御准则:

  1. 基于不透明 ID 查库映射:最佳工程实践是不向前端暴露任何物理路径或磁盘文件名,前端仅传递数据库主键或无规律业务令牌(如 /download?id=10248),由服务端鉴权后从数据库查出隔离目录内的物理相对路径与原始展示文件名。

  2. 输入清洗与规范化边界校验:若业务场景确需按文件名参数访问固定公开目录,必须先通过 FilenameUtils 剥离路径前缀并剔除空字节,再利用 NIO Path.normalize() 消除所有 .. 跳转符,最后断言规范化路径以隔离根目录开头(targetPath.startsWith(normalizedBase))且通过 Files.isRegularFile() 确认为普通文件而非目录。

  3. 阻断符号链接越界:在允许存在软链接(Symlink)的 Linux 环境中,可进一步使用 targetPath.toRealPath() 解析真实物理路径后再与 baseDir.toRealPath() 比对,防止通过目录内的符号链接绕过根目录限制读取外部文件。

示例: 标准文件下载 ​

以下完整示例演示了基于 javax.servlet 与 commons-io 的标准下载 Servlet 实现,串联了参数剥离、规范化路径边界防御、MIME 推断与防嗅探、64 位长度设置、RFC 5987 中文文件名编码以及基于 IOUtils.copyLarge 的安全流式输出:

java
package com.example.download;

import java.io.IOException;
import java.io.InputStream;
import java.net.URLEncoder;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import javax.servlet.ServletException;
import javax.servlet.ServletOutputStream;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import org.apache.commons.io.FilenameUtils;
import org.apache.commons.io.IOUtils;

@WebServlet("/download")
public class DownloadServlet extends HttpServlet {

  private static final Path BASE_DIR = Paths.get("/data/app-uploads").toAbsolutePath().normalize();

  // 1. 处理文件下载请求,完成安全校验、响应头配置与流式输出
  @Override
  protected void doGet(HttpServletRequest req, HttpServletResponse resp)
      throws ServletException, IOException {
    // 2. 提取纯文件名,阻断参数中携带的目录跳转字符
    String rawParam = req.getParameter("file");
    String safeName = FilenameUtils.getName(rawParam == null ? "" : rawParam.replace("\0", ""));
    if (safeName.isEmpty()) {
      resp.sendError(HttpServletResponse.SC_BAD_REQUEST, "缺少有效的文件参数");
      return;
    }

    // 3. 规范化物理路径并断言其位于隔离根目录内,且必须是常规可读文件
    Path targetPath = BASE_DIR.resolve(safeName).normalize();
    if (!targetPath.startsWith(BASE_DIR) || !Files.isRegularFile(targetPath)) {
      resp.sendError(HttpServletResponse.SC_NOT_FOUND, "请求的文件不存在");
      return;
    }

    // 4. 推断 MIME 类型并禁止浏览器嗅探,未识别时回退为通用二进制流
    String mimeType = getServletContext().getMimeType(safeName);
    if (mimeType == null) {
      mimeType = "application/octet-stream";
    }
    resp.setContentType(mimeType);
    resp.setHeader("X-Content-Type-Options", "nosniff");

    // 5. 设置 64 位文件长度(支持大于 2GB 文件),供客户端显示下载进度
    resp.setContentLengthLong(Files.size(targetPath));

    // 6. 按 RFC 5987 规范编码中文文件名,强制浏览器以附件方式下载
    String encodedName = URLEncoder.encode(safeName, "UTF-8").replace("+", "%20");
    String asciiFallback = safeName.replaceAll("[^\\x20-\\x7E]|[\"\\\\]", "_");
    resp.setHeader(
        "Content-Disposition",
        "attachment; filename=\"" + asciiFallback + "\"; filename*=UTF-8''" + encodedName);

    // 7. 使用 IOUtils 流式拷贝文件内容,仅关闭本地输入流,输出流交由容器托管
    try (InputStream in = Files.newInputStream(targetPath)) {
      ServletOutputStream out = resp.getOutputStream();
      IOUtils.copyLarge(in, out);
      out.flush();
    }
  }
}

API: IOUtils【待补充】 ​

API: FileUtils【待补充】 ​

API: FilenameUtils【待补充】 ​

Range 断点续传 ​

在大文件下载、流媒体播放(如在线视频快进拖拽)或网络不稳定的移动端下载场景下,如果每次因网络波动中断都必须从头重新下载,会造成严重的带宽浪费与极差的用户体验。HTTP/1.1(RFC 7233)定义了范围请求(Range Requests)规范,允许客户端仅请求文件的一个或多个特定字节片段。在 Java Servlet 中,通过解析 Range 与 If-Range 请求头、精准计算切片边界、返回 206 Partial Content 状态码并利用 RandomAccessFile 进行指针定位,可以实现标准且高效的断点续传与分片下载。

协议交互机制 ​

HTTP 范围请求的核心交互建立在客户端请求头与服务端响应头的双向协商之上:

  1. 告知支持范围请求:在普通全量下载响应(200 OK)中,服务端应附带 Accept-Ranges: bytes 头,显式告知客户端该 URL 资源支持按字节范围进行分片请求。

  2. 发起分片请求:支持断点续传的下载工具或播放器在发起请求时,会附带 Range: bytes=start-end 头。

  3. 部分内容响应:服务端接收并校验范围合法后,跳过文件前 start 个字节,仅读取并发送指定的 [start, end] 区间数据,响应 HTTP 状态码 206 Partial Content,并附带 Content-Range: bytes start-end/total 响应头说明当前分片区间与文件总长度。

  4. 范围不可达响应:若客户端请求的边界不合法(如 start 超过文件总长),服务端响应 416 Range Not Satisfiable,并返回 Content-Range: bytes */total。

image-20261120223213787

Range 语法规范 ​

客户端发起的 Range 头遵循 bytes=范围表达式 语法,常见规范如下:

  • 闭合区间(bytes=1000-2000):请求从第 1000 字节到第 2000 字节的数据(含边界,共 1001 字节)。
  • 开放区间(bytes=1000-):请求从第 1000 字节到文件末尾的所有数据(断点续传最常见场景)。
  • 后缀区间(bytes=-500):请求文件的最后 500 个字节(不指定 start,常用于读取文件尾部元数据)。
  • 多范围区间(bytes=0-10, 50-60):同时请求多个不连续的片段(RFC 规范要求返回 multipart/byteranges 复合报文)。在绝大多数 Web 工程实践中,为避免复杂的 MIME 多段组包开销,通常仅处理首个 Range 片段,或在多范围时直接回退为全量 200 响应。

状态一致性校验 (If-Range) ​

断点续传存在一个致命的隐患:如果客户端在下载前 1 MB 后暂停,数日后再请求后 1 MB,但在此期间服务器上的文件已被更新替换,客户端将前后两段完全不同版本的文件拼接在一起,会导致最终合并出的文件损坏。

为了保证断点续传时文件未被篡改,HTTP 引入了 If-Range 头:

  1. 实体凭证绑定:服务端在下发前一段数据时,必须提供强校验凭证 ETag(如基于文件最后修改时间与长度生成的哈希指纹)或 Last-Modified。

  2. 一致性断言:客户端续传时,将上次收到的 ETag 填入 If-Range: "etag-value" 中。

  3. 服务端判定分支:

    • 匹配成功:说明文件未变动,服务端正常处理 Range,返回 206 Partial Content 响应指定片段。
    • 匹配失败:说明服务器文件已更新,服务端自动忽略 Range 头,直接返回 200 OK 并下发全新的完整文件,避免客户端拼装出损坏文件。

定位与传输实现 ​

在 Servlet 中处理范围请求时,传统的 InputStream.skip(long) 方法虽然可以跳过字节,但其底层大多通过循环读取并丢弃字节来实现(或受限于缓冲区限制),在跳过数吉字节的大文件时会产生极其高昂的无效 CPU 与 I/O 损耗。

高效的断点续传应选用支持物理指针定位的 I/O 组件:

  1. RandomAccessFile:通过 seek(long pos) 直接调用操作系统的文件指针定位接口(对应系统调用 lseek),时间复杂度为 O(1)O(1),瞬间完成大文件任意偏移量定位。

  2. **NIO FileChannel**:通过 channel.position(long)定位,结合channel.transferTo(...) 甚至可实现零拷贝(Zero-Copy)网络传输,但需注意在加密、限速或特定 Filter 链下可能存在的兼容性约束。

在传输部分内容时,Content-Length 必须严格等于本次分片实际下发的字节数(end - start + 1),而非文件总长度。若误设为文件总长,客户端会因读取到流末尾仍未达标而一直处于挂起或超时状态。

示例: Range 断点续传 ​

以下完整示例演示了基于 javax.servlet 实现的标准 Range 断点续传 Servlet,涵盖 If-Range 一致性校验、Range 规范语法解析(闭合、开放与后缀范围)、边界越界检查、206 与 Content-Range 响应头配置,以及基于 RandomAccessFile 的精准分片下发:

java
package com.example.download;

import java.io.File;
import java.io.IOException;
import java.io.OutputStream;
import java.io.RandomAccessFile;
import java.net.URLEncoder;
import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

@WebServlet("/range-download")
public class RangeDownloadServlet extends HttpServlet {

  private static final String FILE_PATH = "/data/app-uploads/large-video.mp4";

  @Override
  protected void doGet(HttpServletRequest req, HttpServletResponse resp)
      throws ServletException, IOException {
    File file = new File(FILE_PATH);
    if (!file.exists() || !file.isFile()) {
      resp.sendError(HttpServletResponse.SC_NOT_FOUND, "文件不存在");
      return;
    }

    long fileLength = file.length();
    String etag = "\"" + file.lastModified() + "-" + fileLength + "\"";

    // 1. 验证 If-Range 校验头,若不匹配则放弃断点续传,回退为全量 200 下载
    String ifRange = req.getHeader("If-Range");
    boolean isRangeValid = true;
    if (ifRange != null && !ifRange.trim().isEmpty()) {
      isRangeValid = ifRange.trim().equals(etag) || ifRange.trim().equals(String.valueOf(file.lastModified()));
    }

    // 2. 声明支持范围请求,设置实体标识 ETag
    resp.setHeader("Accept-Ranges", "bytes");
    resp.setHeader("ETag", etag);

    String rangeHeader = req.getHeader("Range");

    // 3. 处理全量下载请求(无 Range 头或 If-Range 失效)
    if (rangeHeader == null || !rangeHeader.startsWith("bytes=") || !isRangeValid) {
      resp.setContentType("video/mp4");
      resp.setContentLengthLong(fileLength);
      resp.setHeader("Content-Disposition", "attachment; filename=\"video.mp4\"");
      resp.setStatus(HttpServletResponse.SC_OK);

      try (RandomAccessFile raf = new RandomAccessFile(file, "r");
           OutputStream out = resp.getOutputStream()) {
        byte[] buffer = new byte[8192];
        int read;
        while ((read = raf.read(buffer)) != -1) {
          out.write(buffer, 0, read);
        }
        out.flush();
      }
      return;
    }

    // 4. 解析 Range 请求范围(形如 bytes=start-end)
    String rangeValue = rangeHeader.substring(6).trim();
    long start = 0;
    long end = fileLength - 1;

    try {
      int dashIndex = rangeValue.indexOf('-');
      if (dashIndex == 0) {
        // 后缀范围:bytes=-500 -> 读取最后 500 字节
        long suffix = Long.parseLong(rangeValue.substring(1));
        start = fileLength - suffix;
      } else if (dashIndex == rangeValue.length() - 1) {
        // 开放范围:bytes=1000- -> 从 1000 字节到文件末尾
        start = Long.parseLong(rangeValue.substring(0, dashIndex));
      } else {
        // 闭合范围:bytes=1000-2000
        start = Long.parseLong(rangeValue.substring(0, dashIndex));
        end = Long.parseLong(rangeValue.substring(dashIndex + 1));
      }
    } catch (NumberFormatException e) {
      resp.sendError(HttpServletResponse.SC_BAD_REQUEST, "Range 格式错误");
      return;
    }

    // 5. 范围边界越界校验与调整
    if (start < 0 || end >= fileLength || start > end) {
      resp.setHeader("Content-Range", "bytes */" + fileLength);
      resp.sendError(HttpServletResponse.SC_REQUESTED_RANGE_NOT_SATISFIABLE, "请求范围不合法");
      return;
    }

    long contentLength = end - start + 1;

    // 6. 配置 206 部分内容响应头与 Content-Range
    resp.setStatus(HttpServletResponse.SC_PARTIAL_CONTENT);
    resp.setContentType("video/mp4");
    resp.setContentLengthLong(contentLength);
    resp.setHeader("Content-Range", "bytes " + start + "-" + end + "/" + fileLength);
    resp.setHeader("Content-Disposition", "attachment; filename=\"video.mp4\"");

    // 7. 使用 RandomAccessFile 定位指针并流式下发分片数据
    try (RandomAccessFile raf = new RandomAccessFile(file, "r");
         OutputStream out = resp.getOutputStream()) {
      raf.seek(start);

      byte[] buffer = new byte[8192];
      long bytesToRead = contentLength;
      int read;

      while (bytesToRead > 0 && (read = raf.read(buffer, 0, (int) Math.min(buffer.length, bytesToRead))) != -1) {
        out.write(buffer, 0, read);
        bytesToRead -= read;
      }
      out.flush();
    }
  }
}