做JSP老项目维护和二次开发的朋友,应该都遇到过这种场景:客户发来一个几十MB甚至上百MB的文件,要求通过网页上传到服务器。传统JSP项目里,Form表单一次性提交,要么因为请求超时直接断掉,要么就是Tomcat默认的2MB上传限制把人卡死。我早期做传统JSP项目时,最怕的就是"上传大文件"这四个字,直到后来在项目里接入了WebUploader分块上传,才算是把这根刺拔掉。WebUploader是百度开源的一个上传组件,它的核心思路就是分块上传,也就是把一个大文件切成多块,逐块发送到服务端,最后再由服务端把这些分块合并成一个完整文件。这篇文章我就从JSP视角,把WebUploader分块上传的源码示例和实现原理掰开揉碎讲一遍。
很多教程只讲了前端怎么调组件,真正落到JSP项目里时,你会发现还有一堆问题要处理:后端接口怎么写、分块怎么接收、合并逻辑放哪里、断点续传怎么判断、文件校验怎么做。这些我都会在这篇源码解析里给出完整示例,并把参数设计背后的理由说清楚。无论你是刚接手老项目的开发,还是正在做基于JSP的毕业设计,这个方案都能直接用。
1. 为什么传统JSP项目里大文件上传总是让人头疼
1.1 一次性上传方式的三座大山
以前的JSP项目做文件上传,最普遍的做法就是Commons FileUpload或者Servlet 3.0的Part接口,配合一个简单的<input type="file">表单,点击提交之后后端一次性接收整个文件。这种方式对小文件没什么问题,一旦文件达到上百MB,问题就全冒出来了。
第一座大山是超时。文件通过HTTP传输时,受网络带宽限制,传输时间本身就是不可控的。很多Servlet容器默认的请求超时设置在几十秒到几分钟,如果一个100MB文件在网络状况一般的情况下传了一半,请求超时被容器强制断开,用户那边只有一个"上传失败"的提示,文件连影子都没见着。第二座大山是内存和临时目录压力。Tomcat接收大文件时,如果配置不当,会把整个请求体读入内存,或者写入磁盘临时目录,内存溢出和磁盘占用率飙升都是常见现象。第三座大山是体验问题。一次性上传期间,用户看不到任何进度,也不知道是成功还是失败,等待过程中有一种"听天由命"的感觉。
这三座大山本质上都源于同一个设计缺陷:把整个文件当作一个不可分割的整体,在一次网络请求里完成传输。这就好比搬家时把所有家具塞进一辆小货车,路况不好就翻车,而分块上传的思路是让一辆小车只搬一部分,多跑几趟。
1.2 WebUploader分块上传是如何绕开这些问题的
WebUploader分块上传的核心机制,是在前端通过HTML5的File API把文件切片,每个分块大小可以配置,比如默认的chunkSize是2MB,然后通过threads参数控制并发上传的线程数,比如一次同时传3个分块。每个分块都是独立的HTTP请求,服务端逐块接收并保存到临时目录。所有分块传完之后,由前端发送一个合并请求,后端再把这些临时文件按顺序拼接成最终文件。
这套机制绕开大文件上传困境的方式很直接:每个请求体变小了,请求超时问题不再出现,某个分块失败只需要重传那一个分块,而不是整个文件;临时文件的内存占用也大幅降低,因为服务端处理的是固定大小的块,而不是整个文件流。同时,WebUploader会为每个文件生成一个MD5值,通过MD5值可以做秒传判断和断点续传,这些是原生input[type=file]完全不具备的能力。
还有一个容易被忽略的优势:分块上传天然支持并发。前端一次发3个分块请求,服务端的处理压力分散到多个请求上,上传的总体吞吐量比串行的一次性请求更高。尤其在内网传输或者上行带宽较充足的环境里,这个优势非常明显。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 项目环境准备与WebUploader资源引入
2.1 这套方案需要的开发环境
在开始写源码前,先把环境说清楚。我这里讲的方案基于传统的JSP项目,使用Servlet 3.0或Spring MVC皆可。如果你用的是IDEA新建的一个JSP项目,或者是一个需要打成War包部署在Tomcat的老项目,这套方案都适用。我在实际项目里用的是Spring MVC,但Servlet方式也可以,后面我会分别给出接收分块和合并分块的接口写法。
前端方面,WebUploader的基础运行环境是HTML5浏览器,IE9及以下浏览器会自动降级为Flash上传模式。如果是内部管理系统,我建议直接要求用户使用现代浏览器,省去处理Flash兼容的麻烦。
需要引入的资源文件有这些:
- WebUploader的CSS样式文件
webuploader.css - WebUploader的JS核心文件
webuploader.min.js - jQuery(WebUploader依赖jQuery,我用的版本是jQuery 1.12.4)
- 上传界面相关的HTML结构和按钮样式
我在项目里是把这些资源放在webapp/statics/uploader/目录下,然后在JSP页面中按顺序引入CSS和JS。如果你用的是Spring Boot集成JSP的项目,资源放到src/main/resources/static/uploader/,JSP放在src/main/webapp/WEB-INF/views/下,引入方式一样。
2.2 JSP页面中引入上传组件资源和前端骨架
新建一个upload.jsp页面,页面的重点不是花哨的UI,而是把上传组件的基础结构搭好。WebUploader的界面由一个选择按钮、一个文件列表容器和一个上传按钮组成。
jsp复制<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<html>
<head>
<title>WebUploader分块上传示例</title>
<link rel="stylesheet" href="${pageContext.request.contextPath}/statics/uploader/webuploader.css">
<script src="${pageContext.request.contextPath}/statics/js/jquery-1.12.4.min.js"></script>
<script src="${pageContext.request.contextPath}/statics/uploader/webuploader.min.js"></script>
</head>
<body>
<div id="uploader" class="wu-example">
<!-- 存放文件选择按钮 -->
<div class="btns">
<div id="picker">选择文件</div>
<button id="ctlBtn" class="btn btn-default">开始上传</button>
</div>
<!-- 文件列表容器 -->
<div id="thelist" class="uploader-list"></div>
</div>
</body>
</html>
pageContext.request.contextPath是JSP里获取项目根路径的标准方式,这个必须写,否则JS和CSS路径在部署到不同上下文路径时会404。picker是选择按钮的容器,thelist是上传文件列表的展示区域,WebUploader会自动把每个文件的状态信息渲染到这个容器里。
这一步没有特别复杂的地方,但有一个容易踩的坑:CSS或JS路径写错会导致界面样式不加载、组件无法初始化。我见过不少刚接触JSP的初学者,把webuploader.css路径写成了相对路径webuploader/webuploader.css,结果页面一刷新样式全乱。用${pageContext.request.contextPath}拼绝对路径是JSP项目里的标准做法,能在任何目录层级下正确找到资源。
