文件上传下载这个功能放在整个JavaEE知识体系里看属于那种看起来简单、真动手做起来处处是坑的典型代表。很多人学Servlet的时候前面处理表单、玩转发重定向、搞Cookie和Session都挺顺一到文件上传下载这块就卡住了——要么是getParameter拿不到值要么是文件存到了服务器上但不知道存哪去了要么是下载的时候浏览器直接把文件内容显示在页面上而不是弹出保存框。这些问题我在带新人的过程中反复见到几乎每一批人都会在同样的地方栽跟头。这篇内容面向的是已经掌握了Servlet基础、正在啃文件上传下载这块硬骨头的Java学习者也适合那些工作中需要快速实现一个上传下载功能但不想引入重型框架的开发者。我会把Servlet原生方案也就是Part接口和MultipartConfig注解这套的完整实现路径拆开来讲包括前端表单怎么配、后端代码怎么写、文件存哪里、下载怎么控制、以及那些文档里不会写但实际开发中一定会遇到的坑。核心关键词围绕Servlet文件上传、Part接口、MultipartConfig、文件下载响应头、上传路径管理这几个点展开每一个都会落到能直接抄的代码和能直接避的坑上。1. 先搞清楚Servlet 3.0之后文件上传的底层逻辑变了什么1.1 从commons-fileupload到Part接口的演进如果你翻过一些老教程会发现文件上传部分大量使用commons-fileupload和commons-io这两个第三方库代码里充斥着DiskFileItemFactory、ServletFileUpload、FileItem这些类。这套方案在Servlet 3.0之前是唯一的选择因为Servlet规范本身没有提供文件上传的解析能力请求体里的multipart数据需要开发者自己或者借助第三方库来解析。Servlet 3.0对应JavaEE 6引入了一个关键变化规范层面直接支持了multipart/form-data请求的解析。具体表现为两个东西——MultipartConfig注解和HttpServletRequest接口上的getPart()/getParts()方法。这意味着容器比如Tomcat在收到multipart请求时会帮你把请求体解析好你直接通过Part对象就能拿到文件流和表单字段不需要再引入任何第三方依赖。这个变化带来的直接好处是依赖精简和代码简化。但很多教程没有讲清楚的是MultipartConfig注解不加上getPart()直接抛异常。这个异常是IllegalStateException信息大概是Request doesnt contain a multipart/form-data or multipart/mixed stream。新手看到这个报错往往一头雾水因为前端表单明明写了enctypemultipart/form-data问题出在后端Servlet没有声明自己准备接收multipart请求。1.2 容器到底帮你做了什么理解容器的工作机制对排查问题非常有帮助。当Tomcat收到一个Content-Type: multipart/form-data; boundary----WebKitFormBoundaryXXXX的请求时它做的事情大致是这样的识别出这是multipart请求根据boundary把请求体切分成多个part每个part有自己的头部包含name、filename等信息和体部实际数据如果Servlet上标注了MultipartConfig容器会把解析结果封装成Part对象集合普通表单字段也会被封装成Part通过request.getParameter()依然可以获取容器做了兼容处理这里有个细节值得注意普通字段和文件字段在Part层面是统一的。也就是说你通过request.getPart(username)也能拿到普通文本字段的值通过request.getParameter(username)也能拿到。但两者的行为有微妙差异——getParameter()在multipart请求下的可靠性依赖于容器的实现某些情况下比如文件很大、解析配置不当可能拿不到值。所以我的习惯是multipart请求里普通字段统一用getPart().getInputStream()或者更简单地用request.getParameter()但确保配置正确文件字段用getPart()。1.3 为什么你的getParameter返回了null这是最高频的问题之一。前端表单明明有input typetext namedesc后端request.getParameter(desc)却返回null。原因通常有三个第一Servlet没有加MultipartConfig。没有这个注解容器不会解析multipart请求体getParameter()自然拿不到任何东西连普通字段都拿不到。第二表单的enctype写错了。必须是multipart/form-data写成application/x-www-form-urlencoded默认值的话文件根本传不上去而且普通字段虽然能拿到但文件字段会变成文件名的字符串。第三MultipartConfig的maxRequestSize设置得太小请求被容器直接拒绝解析都没完成。这个参数默认值是-1不限制但有些开发者会随手设一个值结果大文件上传时整个请求被拒连普通字段都读不到。排查顺序建议先确认注解加了没再确认前端enctype对不对最后看容器日志有没有请求体过大的警告。2. 前端表单的写法决定了后端能不能拿到文件2.1 enctype、method和input name三件套文件上传的表单有三个硬性要求缺一个都不行form action/upload methodpost enctypemultipart/form-data input typetext namedescription / input typefile namefile / button typesubmit上传/button /formmethod必须是post因为GET请求没有请求体文件数据没地方放。enctype必须是multipart/form-data这是唯一能承载二进制文件数据的编码方式。input typefile的name属性必须有值后端就是靠这个name来定位Part的。很多人会忽略的一点是input typefile的name如果为空浏览器根本不会提交这个文件。我见过有人的代码里name写成了空字符串或者干脆忘了写后端getPart(file)返回null然后对着代码找半天。这种问题没有报错只能靠检查前端HTML发现。2.2 多文件上传的name策略如果要支持一次选多个文件有两种写法。第一种是多个input用同一个nameinput typefile namefiles multiple /注意multiple属性让用户可以在文件选择框里多选提交时同一个name会对应多个Part。后端用request.getParts()遍历或者request.getParts(files)拿到该name下的所有Part。第二种是多个input用不同name后端逐个getPart(file1)、getPart(file2)。这种方式适合文件类型或用途不同的场景比如一个头像一个附件。我个人的建议是能用multiple就用multiple后端遍历处理逻辑统一扩展性也好。但要注意multiple属性在老版本浏览器上的兼容性虽然现在基本不是问题了但如果你的用户环境特殊还是老老实实多个input。2.3 表单里混用普通字段的注意事项multipart表单里混普通文本字段是完全合法的后端用getParameter()就能拿到。但有一个坑如果Servlet没有正确配置MultipartConfiggetParameter()在multipart请求下可能返回null而不会报错。这跟普通表单请求的行为不一样普通请求下getParameter()拿不到就是真的没有multipart下可能是解析没生效。所以我的做法是在multipart场景下普通字段也通过getPart()来读用new String(part.getInputStream().readAllBytes(), StandardCharsets.UTF_8)转成字符串。这样虽然代码多两行但行为确定不依赖容器的兼容处理。当然如果你确认MultipartConfig配置正确getParameter()也是可靠的这个看个人习惯。3. 后端接收MultipartConfig的配置细节与Part操作3.1 注解参数的实际含义MultipartConfig有四个参数每个都有实际影响参数默认值实际作用踩坑点fileSizeThreshold0超过此大小的文件写入磁盘临时文件否则放内存设太小导致频繁磁盘IO设太大吃内存maxFileSize-1不限单个文件最大字节数超限抛IllegalStateExceptionmaxRequestSize-1不限整个请求最大字节数超限同样抛异常且普通字段也读不到location空容器临时目录文件临时存储目录不设的话临时文件位置不可控fileSizeThreshold这个参数容易被忽视。它的作用是小于阈值的文件Part会保存在内存中大于阈值的写到磁盘临时文件。默认0意味着所有文件都写磁盘。对于小文件居多的场景适当调大比如1MB可以减少磁盘IO但要注意内存占用。反过来如果上传的都是大文件保持0或者设小一点更稳妥。maxFileSize和maxRequestSize的区别要分清前者限制单个文件后者限制整个请求所有文件加普通字段的总和。两个都设上比较安全比如单文件限10MB、总请求限50MB。超限时容器抛IllegalStateException你需要在代码里catch住给用户友好提示否则用户看到的是500错误页。3.2 一个能跑的最小后端实现WebServlet(/upload) MultipartConfig( fileSizeThreshold 1024 * 1024, maxFileSize 10 * 1024 * 1024, maxRequestSize 50 * 1024 * 1024 ) public class UploadServlet extends HttpServlet { Override protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { req.setCharacterEncoding(UTF-8); String description req.getParameter(description); Part filePart req.getPart(file); if (filePart null || filePart.getSize() 0) { resp.getWriter().write(no file uploaded); return; } String submittedName filePart.getSubmittedFileName(); String safeName UUID.randomUUID() _ submittedName.replaceAll([^a-zA-Z0-9._-], _); String uploadDir getServletContext().getRealPath(/WEB-INF/uploads); File dir new File(uploadDir); if (!dir.exists()) dir.mkdirs(); File target new File(dir, safeName); try (InputStream in filePart.getInputStream(); OutputStream out new FileOutputStream(target)) { in.transferTo(out); } resp.setContentType(text/html;charsetUTF-8); resp.getWriter().write(uploaded: safeName); } }这段代码有几个设计决策值得说明。第一文件名做了清洗和加UUID前缀原因后面单独讲。第二存储目录用了/WEB-INF/uploads放在WEB-INF下浏览器无法直接访问必须走下载Servlet安全性更好。第三用transferTo而不是手动循环读写代码简洁且性能不差底层有优化。3.3 getSubmittedFileName的编码陷阱Part.getSubmittedFileName()返回的是客户端提交的原始文件名。这里有个经典问题中文文件名乱码。不同浏览器、不同容器版本下这个方法的编码处理不一致。有的返回正常中文有的返回乱码有的返回ISO-8859-1编码的字节串。稳妥的处理方式是对返回值做一次编码修正String rawName filePart.getSubmittedFileName(); String fileName new String(rawName.getBytes(StandardCharsets.ISO_8859_1), StandardCharsets.UTF_8);但这段代码在已经正确解码的环境下会把中文搞坏。所以更稳的做法是先判断如果字符串里包含乱码特征字符比如Ã、å这类再做转换。或者干脆不依赖原始文件名用UUID加扩展名的方式重命名原始文件名只存数据库做展示用。我倾向于后者简单粗暴且不会出错。4. 文件存哪里路径选择直接决定了安全性和可维护性4.1 getRealPath的局限性与替代方案getServletContext().getRealPath(/)拿到的是Web应用在服务器文件系统上的真实路径。把上传文件存到这个路径下比如/uploads是最直观的做法但有几个问题第一应用重新部署时文件可能丢失。很多容器在重新部署war包时会清空整个应用目录上传的文件跟着没了。第二集群环境下不可用多台服务器各自存各自的用户下次请求打到另一台就找不到文件了。第三getRealPath可能返回null当应用以war包形式部署且容器没有解压时这个方法返回null你的代码直接NPE。所以生产环境更推荐把文件存到应用目录之外的固定路径比如/data/uploadsLinux或D:/uploadsWindows路径通过配置文件或环境变量注入。这样应用部署、重启都不影响文件也方便做备份和迁移。String uploadDir System.getProperty(upload.dir, /data/uploads);用系统属性做默认值加外部覆盖本地开发和生产环境可以灵活切换。4.2 目录分片单目录文件过多的性能问题所有文件堆在一个目录里文件数量到几万级别时文件系统的目录查找性能会明显下降尤其是ext3这类用线性查找的文件系统。解决方案是按日期或哈希做二级目录分片String datePath LocalDate.now().format(DateTimeFormatter.ofPattern(yyyy/MM/dd)); File dir new File(uploadDir, datePath);这样文件按上传日期分散到不同目录单目录文件数可控。取文件时根据存储时记录的相对路径拼接即可。这个设计在文件量大的系统里几乎是标配提前做好比后期迁移省事得多。4.3 文件名安全路径穿越与覆盖攻击直接用用户提交的文件名存盘是极其危险的。攻击者可以提交../../etc/passwd这样的文件名路径穿越或者提交一个和已有文件同名的文件覆盖。虽然Part.getSubmittedFileName()在多数容器里已经做了基本过滤但不同容器行为不一致不能依赖。我的处理原则是存储文件名完全由服务端生成用户提交的名字只做展示。生成规则用UUID加原始扩展名String ext ; int dot submittedName.lastIndexOf(.); if (dot 0) ext submittedName.substring(dot).toLowerCase(); String storedName UUID.randomUUID().toString().replace(-, ) ext;扩展名也要做白名单校验只允许业务需要的类型比如图片只允许jpg/png/gif防止上传可执行文件。白名单比黑名单可靠黑名单永远列不全。5. 文件下载响应头设置错一个字节浏览器行为就完全不同5.1 Content-Disposition的inline与attachment下载功能的核心是设置Content-Disposition响应头。这个头有两个关键值inline浏览器尝试直接在页面内展示图片、PDF会直接打开attachment浏览器弹出保存对话框强制下载resp.setHeader(Content-Disposition, attachment; filename\ encodedFileName \);很多人下载图片时发现浏览器直接打开了图片而不是下载就是因为用了inline或者没设这个头。要强制下载就用attachment。5.2 中文文件名的RFC 5987编码filename参数直接放中文会乱码因为HTTP头默认是ISO-8859-1编码。RFC 5987定义了filename*参数来支持非ASCII字符String encoded URLEncoder.encode(fileName, StandardCharsets.UTF_8) .replace(, %20); resp.setHeader(Content-Disposition, attachment; filename\ encoded \; filename*UTF-8 encoded);同时提供filename和filename*是为了兼容不同浏览器。现代浏览器优先用filename*老浏览器回退到filename。注意URLEncoder会把空格编码成在HTTP头里不是空格要替换成%20。5.3 流式传输与大文件的内存控制下载的实现是把文件读出来写到response的输出流resp.setContentType(getServletContext().getMimeType(fileName)); resp.setContentLengthLong(file.length()); try (InputStream in new FileInputStream(file); OutputStream out resp.getOutputStream()) { byte[] buffer new byte[8192]; int len; while ((len in.read(buffer)) ! -1) { out.write(buffer, 0, len); } }关键点不要用Files.readAllBytes一次性读入内存大文件会OOM。用固定大小的buffer循环读写8KB是常见选择和磁盘块大小匹配。setContentLengthLong告诉浏览器文件大小浏览器才能显示下载进度条不设的话进度条就是不确定状态。还有一个细节下载完成后不要关闭response的输出流容器会管但输入流必须关闭try-with-resources保证了。如果中途出错已经写出的部分无法撤回浏览器会得到一个损坏的文件这个只能靠前端校验文件完整性来兜底。6. 那些文档里不写但一定会遇到的坑6.1 临时文件清理问题MultipartConfig的location指定的临时目录容器在请求处理完后会自动清理Part对应的临时文件。但有一个前提你必须调用了part.delete()或者请求正常结束。如果代码里把Part对象存到了Session或者某个静态集合里临时文件就不会被清理时间长了磁盘被撑满。我见过一个案例有人为了稍后处理把Part放进了ConcurrentHashMap结果临时目录几天涨了几十GB。正确做法是请求内就把文件流读完写到最终位置不要持有Part引用。6.2 上传大小超限的异常处理前面提到超限抛IllegalStateException但这个异常可能在getPart()调用时抛出也可能在请求解析阶段就被容器抛出取决于容器实现。所以catch的范围要覆盖整个doPost逻辑try { Part part req.getPart(file); // ... } catch (IllegalStateException e) { resp.setStatus(413); resp.getWriter().write(file too large); }413是Payload Too Large状态码语义正确。给用户的提示要明确说文件超过XX MB而不是笼统的上传失败。6.3 断点续传与Range请求标准Servlet下载不支持断点续传因为没处理Range请求头。如果业务需要比如大文件下载、视频播放要手动解析Range: bytesstart-end返回206状态码和Content-Range头。这块逻辑不复杂但容易写错边界条件尤其是start越界、end超过文件大小的情况。如果项目对断点续传有硬需求建议评估是否直接用现成的静态资源服务方案而不是在Servlet里手写。6.4 上传进度的实现思路原生Servlet没有内置上传进度回调。要实现进度条常见方案是前端用XMLHttpRequest的upload.onprogress事件这是前端能力和后端无关后端只需要正常接收即可。如果非要在后端做进度统计需要自己包装InputStream计数并配合Session共享进度复杂度较高一般不建议。7. 从能跑到好用几个提升健壮性的改造点7.1 文件类型校验不能只看扩展名扩展名校验可以被绕过改个后缀就行。更可靠的是读文件头部的魔数magic number。比如JPEG文件开头是FF D8 FFPNG是89 50 4E 47。读前几个字节判断真实类型byte[] header new byte[8]; try (InputStream in part.getInputStream()) { in.read(header); } // 根据header判断类型这个校验放在保存之前做不通过直接拒绝。虽然多几行代码但能挡住大部分恶意上传。7.2 存储与元数据分离文件本身存文件系统文件名、原始名、大小、类型、上传时间、上传者这些元数据存数据库。这样列表展示、检索、权限控制都方便文件系统只负责存二进制。这个设计几乎是所有文件管理功能的标配一开始就分开比后期拆省事。7.3 下载的权限校验下载Servlet不能只根据文件名直接返回文件必须先校验当前用户有没有权限下载这个文件。常见做法是文件ID走数据库查元数据校验通过后再读文件系统。直接暴露文件路径的下载接口是安全漏洞。我在实际项目里踩过最深的坑是临时文件清理和中文文件名这两块。前者是隐蔽的磁盘泄漏不监控根本发现不了后者是用户投诉下载的文件名是乱码排查半天发现是响应头编码问题。这两个点建议在实现阶段就处理好别等上线后被动修。另外上传目录的磁盘配额和监控也要提前规划文件上传功能对磁盘的消耗往往超出预期尤其是没做大小限制的时候。