简介本资源面向Java后端初学者与Web开发人员聚焦图片上传与下载这一常见功能需求结合ckeditor4富文本编辑器讲解如何构建后端图片上传接口。内容涵盖Spring Boot环境下MultipartFile文件处理、文件存储路径规划、路径遍历与文件名重命名等安全防护、异常捕获以及ckeditor4所需的RESTful API、JSON响应格式与CORS跨域配置同时涉及静态资源映射、JWT权限校验、防盗链等下载安全策略并延伸至云存储、缩略图生成与日志记录等优化方向。资源包共71个文件以35个java源码与18个class文件为核心辅以7个xml、6个yml及3个properties配置文件另有jar依赖整体约133KB结构完整便于直接导入运行。目前已有235人学习下载适合希望快速掌握图片上传下载完整实现思路与安全细节的开发者参考。1. 图片上传下载一个被低估的 Java 基本功很多 Java 开发者第一次接触文件上传是在做课程设计或者管理后台的时候。前端一个input typefile后端一个MultipartFile看起来三行代码就能搞定。但真到了生产环境你会发现事情远没有这么简单上传大文件时内存直接飙满、下载时中文文件名变成乱码、文件存本地还是存对象存储、并发上传时文件名冲突覆盖……这些问题在面试八股文里很少被问到但在实际项目里一个都躲不掉。图片上传与下载是 Java Web 开发中最基础也最容易翻车的模块之一。它涉及 HTTP 协议的文件传输机制、Servlet 容器的 multipart 解析、文件系统的读写策略、以及安全层面的校验与防护。这篇文章不讲 Spring 源码级别的原理而是从一线开发的视角把「一个能用的图片上传下载功能」从零搭起来再把那些血泪踩坑点一个个拆开讲清楚。适合正在做课程设计的学生、刚转 Java 后端的开发者以及想把这部分知识系统梳理一遍的从业者。2. 从 HTTP 到磁盘图片上传到底经历了什么2.1 为什么不能直接用 request.getParameter 拿文件很多人一开始会想前端表单提交文件后端用request.getParameter(file)拿不就行了答案是不行。普通表单的Content-Type是application/x-www-form-urlencoded所有字段会被编码成keyvaluekeyvalue的字符串格式。但文件是二进制数据编码成字符串会直接损坏内容。文件上传必须把表单的enctype设为multipart/form-data。这个编码格式会把请求体切分成多个 part每个 part 有自己的头部和边界符boundary文件内容以原始二进制形式放在 part 的 body 里。Servlet 规范从 3.0 开始提供了Part接口和request.getParts()方法来解析这种请求但在 Spring 环境下我们通常直接用MultipartFile来接收。理解这一点很关键MultipartFile不是凭空存在的它是 Spring 对 Servlet 3.0PartAPI 的封装。知道底层是什么排查问题时才不会慌。2.2 最小可运行的上传接口先看一个不依赖任何前端框架、纯 Spring Boot 的最小实现。项目依赖只需要spring-boot-starter-web。RestController RequestMapping(/api/file) public class FileController { // 上传目录实际项目应配置在 application.yml 中 private static final String UPLOAD_DIR System.getProperty(user.dir) /uploads/; PostMapping(/upload) public MapString, Object upload(RequestParam(file) MultipartFile file) throws IOException { MapString, Object result new HashMap(); // 1. 空文件校验 if (file.isEmpty()) { result.put(code, 400); result.put(msg, 文件为空); return result; } // 2. 类型校验只允许图片 String contentType file.getContentType(); if (contentType null || !contentType.startsWith(image/)) { result.put(code, 400); result.put(msg, 只允许上传图片); return result; } // 3. 生成唯一文件名避免并发覆盖 String originalName file.getOriginalFilename(); String suffix originalName.substring(originalName.lastIndexOf(.)); String newFileName UUID.randomUUID().toString().replace(-, ) suffix; // 4. 确保目录存在 File dir new File(UPLOAD_DIR); if (!dir.exists()) { dir.mkdirs(); } // 5. 写入磁盘 File dest new File(UPLOAD_DIR newFileName); file.transferTo(dest); result.put(code, 200); result.put(fileName, newFileName); result.put(url, /api/file/download/ newFileName); return result; } }这段代码的逻辑很直白校验空文件、校验类型、生成 UUID 文件名、创建目录、写入磁盘。几个关键点需要展开说。file.getOriginalFilename()拿到的是用户上传时的原始文件名这个值不可信可能包含路径穿越字符比如../../etc/passwd所以绝对不能直接用它作为存储文件名。用 UUID 重命名是最简单有效的策略。file.transferTo(dest)是 Spring 提供的便捷方法底层会把临时文件移动到目标位置。注意如果目标文件已存在不同容器的行为不一致有的会覆盖有的会抛异常。用 UUID 就不会有这个问题。contentType是从请求头里拿的客户端可以伪造。真正安全的做法是读取文件魔数magic number来判断真实类型这个后面在避坑章节会展开。2.3 文件大小限制三个地方都要配上传大文件时最常见的报错是MaxUploadSizeExceededException。这个限制可能在三个层面生效少配一个都会出问题。第一层是 Spring Boot 的配置。在application.yml中spring: servlet: multipart: max-file-size: 10MB # 单个文件最大大小 max-request-size: 50MB # 整个请求最大大小多文件时生效 enabled: true第二层是 Servlet 容器Tomcat的限制。Spring Boot 内嵌 Tomcat 时上面的配置会自动生效。但如果你部署到外部 Tomcat需要在server.xml或应用的web.xml中配置multipart-config。第三层是 Nginx 反向代理的限制。如果前面有 Nginx默认的client_max_body_size是 1MB超过会直接返回 413。需要在 Nginx 配置中加上client_max_body_size 50m;。提示这三个限制中任何一个触发报错信息都不一样。Spring 层报MaxUploadSizeExceededExceptionTomcat 层报 400 或连接重置Nginx 层报 413。排查时先确认请求有没有到达 Java 应用。2.4 下载接口Content-Disposition 的正确用法下载看起来比上传简单就是把文件读出来写到 response 里。但中文文件名乱码是几乎每个人都会踩的坑。GetMapping(/download/{fileName}) public void download(PathVariable String fileName, HttpServletResponse response) throws IOException { File file new File(UPLOAD_DIR fileName); if (!file.exists()) { response.setStatus(404); return; } // 设置内容类型 response.setContentType(application/octet-stream); // 设置文件名URL 编码处理中文 String encodedName URLEncoder.encode(fileName, UTF-8).replace(, %20); response.setHeader(Content-Disposition, attachment; filename*UTF-8 encodedName); // 流式写出 try (InputStream in new FileInputStream(file); OutputStream out response.getOutputStream()) { byte[] buffer new byte[8192]; int len; while ((len in.read(buffer)) ! -1) { out.write(buffer, 0, len); } out.flush(); } }这里的关键在Content-Disposition头。老式的写法是attachment; filenamexxx.jpg但 filename 的值如果是中文浏览器会用 ISO-8859-1 解码直接乱码。RFC 5987 定义了filename*UTF-8的语法告诉浏览器用 UTF-8 解码文件名。URLEncoder.encode会把空格编码成而 HTTP 头里不是空格的意思所以要替换回%20。流式写出用了 8KB 的缓冲区这是磁盘 IO 和网络 IO 之间比较平衡的大小。不要用file.getBytes()一次性读入内存大文件会直接 OOM。3. 存储策略与安全校验别把文件裸奔在磁盘上3.1 本地存储 vs 对象存储的选型上面的例子把文件存在本地磁盘。这在单机部署、文件量不大的场景下完全够用。但一旦涉及多实例部署本地存储就会出问题用户上传到实例 A下次请求负载均衡到实例 B文件就找不到了。常见做法有三种方案适用场景优点缺点本地磁盘单机、课程设计、内部工具简单、零依赖无法水平扩展、备份麻烦NFS/共享盘小规模多实例改动小性能瓶颈、单点故障对象存储OSS/S3/MinIO生产环境、大规模可扩展、高可用、CDN 友好需要额外依赖和成本我一般会建议如果是学习或课程设计本地磁盘足够了把上传下载的流程跑通最重要。如果是真实项目直接上对象存储不要走 NFS 的弯路。对象存储的 SDK 通常也提供了upload和download方法接口设计和MultipartFile类似迁移成本不高。3.2 文件类型校验Content-Type 不可信前面代码里用contentType.startsWith(image/)做了校验但这只能挡住最粗心的攻击者。攻击者可以把一个.jsp文件改名为.jpg同时把请求头里的Content-Type改成image/jpeg你的校验就形同虚设。真正可靠的做法是读取文件头部的魔数。常见图片格式的魔数JPEG前两个字节FF D8PNG前八个字节89 50 4E 47 0D 0A 1A 0AGIF前三个字节47 49 46private boolean isRealImage(MultipartFile file) throws IOException { byte[] header new byte[8]; try (InputStream in file.getInputStream()) { if (in.read(header) 8) { return false; } } // JPEG if (header[0] (byte) 0xFF header[1] (byte) 0xD8) return true; // PNG if (header[0] (byte) 0x89 header[1] 0x50 header[2] 0x4E header[3] 0x47) return true; // GIF if (header[0] 0x47 header[1] 0x49 header[2] 0x46) return true; return false; }这个校验在读文件流的时候顺便做了开销很小。注意file.getInputStream()每次调用会返回新的流不会影响后续的transferTo。3.3 路径穿越防护别让用户控制文件路径下载接口里用了PathVariable String fileName然后直接拼接到UPLOAD_DIR fileName。如果用户请求/api/file/download/../../etc/passwd在某些容器配置下可能真的会读到系统文件。防护方法很简单在拼接路径之前对文件名做白名单校验只允许字母、数字、下划线和点。private boolean isSafeFileName(String fileName) { return fileName ! null fileName.matches(^[a-zA-Z0-9_.]$); }因为我们的上传接口用 UUID 重命名了文件所以下载时的文件名天然就是安全的。但如果你允许用户用原始文件名下载这个校验就必须加。3.4 用 ResponseEntity 简化下载响应手动操作HttpServletResponse比较繁琐Spring 提供了ResponseEntityResource的写法更符合 REST 风格。GetMapping(/download2/{fileName}) public ResponseEntityResource download2(PathVariable String fileName) throws IOException { File file new File(UPLOAD_DIR fileName); if (!file.exists()) { return ResponseEntity.notFound().build(); } InputStreamResource resource new InputStreamResource(new FileInputStream(file)); String encodedName URLEncoder.encode(fileName, UTF-8).replace(, %20); return ResponseEntity.ok() .contentType(MediaType.APPLICATION_OCTET_STREAM) .header(HttpHeaders.CONTENT_DISPOSITION, attachment; filename*UTF-8 encodedName) .contentLength(file.length()) .body(resource); }这种写法把状态码、头信息、body 都封装在一个对象里代码更清晰。contentLength设置后浏览器能显示下载进度条体验更好。4. 避坑指南那些让你加班到凌晨的细节4.1 上传后立即下载文件却不存在现象上传接口返回成功但马上调用下载接口报 404。原因file.transferTo(dest)在某些情况下是异步刷盘的或者上传目录配置的是相对路径而下载时的工作目录变了。更常见的原因是上传目录用了System.getProperty(user.dir)在 IDE 里运行和打包成 jar 后运行这个值是不一样的。解决把上传目录配置成绝对路径写在application.yml里用Value注入。不要依赖user.dir。file: upload-dir: /data/uploads/4.2 中文文件名下载后变成乱码现象下载下来的文件名是一串%E4%B8%AD%E6%96%87或者问号。原因Content-Disposition头里直接放了中文或者用了filename而不是filename*。解决用filename*UTF-8加 URL 编码。如果还要兼容老浏览器可以同时设置两个头但现代浏览器只认filename*。4.3 大文件上传内存溢出现象上传 100MB 以上的文件时应用抛出OutOfMemoryError。原因Spring 的MultipartFile默认会把文件写入临时目录但如果配置了spring.servlet.multipart.file-size-threshold为很大的值或者用了file.getBytes()把整个文件读进内存就会 OOM。解决保持file-size-threshold为默认值0让文件直接写临时文件。处理文件时始终用流不要用getBytes()。如果确实需要读全部内容用Files.readAllBytes()也要确保文件大小可控。4.4 并发上传同名文件互相覆盖现象两个用户同时上传photo.jpg后上传的覆盖了先上传的。原因用了原始文件名作为存储名。解决用 UUID 或者时间戳加随机数重命名。如果业务需要保留原始文件名把它存在数据库里磁盘上用唯一名。4.5 上传目录没有写权限现象本地测试正常部署到服务器后上传报FileNotFoundException或AccessDeniedException。原因运行 Java 进程的用户对上传目录没有写权限。解决创建目录后执行chmod 755或chown给运行用户。在代码里dir.mkdirs()之后检查dir.canWrite()提前给出明确错误信息。5. 进阶技巧用缩略图和断点续传提升体验图片上传下载做到能用之后下一步就是做好。两个最值得投入的方向是缩略图生成和断点续传。缩略图方面Java 原生ImageIO就能做但处理大图时性能和内存都不理想。我一般会用 Thumbnailator 这个库一行代码搞定Thumbnails.of(srcFile) .size(200, 200) .outputQuality(0.8) .toFile(thumbFile);size(200, 200)会等比缩放保持宽高比。outputQuality控制 JPEG 压缩质量0.8 是清晰度和体积的平衡点。生成缩略图后列表页加载缩略图详情页加载原图流量能省 90% 以上。断点续传稍微复杂一些核心是Range请求头。客户端发Range: bytes1024-服务端返回 206 Partial Content只写对应区间的字节。Spring 的ResourceHttpRequestHandler已经内置支持如果你用ResponseEntityResource返回文件它会自动处理 Range 请求。但如果你手动写流就需要自己解析 Range 头。String range request.getHeader(Range); if (range ! null range.startsWith(bytes)) { String[] parts range.substring(6).split(-); long start Long.parseLong(parts[0]); long end parts.length 1 ? Long.parseLong(parts[1]) : file.length() - 1; long contentLength end - start 1; response.setStatus(HttpServletResponse.SC_PARTIAL_CONTENT); response.setHeader(Content-Range, bytes start - end / file.length()); response.setHeader(Content-Length, String.valueOf(contentLength)); try (RandomAccessFile raf new RandomAccessFile(file, r)) { raf.seek(start); byte[] buffer new byte[8192]; long remaining contentLength; while (remaining 0) { int len raf.read(buffer, 0, (int) Math.min(buffer.length, remaining)); if (len -1) break; response.getOutputStream().write(buffer, 0, len); remaining - len; } } }这段代码用RandomAccessFile定位到起始位置然后按块读取。Content-Range头告诉客户端这次返回的是哪一段。客户端下载中断后下次请求带上已下载的字节数就能从断点继续。验证方法很简单用curl -H Range: bytes0-1023 -o part1.bin http://localhost:8080/api/file/download/test.jpg下载前 1KB再用Range: bytes1024-下载剩余部分最后cat part1.bin part2.bin full.jpg对比原文件是否一致。我自己的习惯是任何文件上传接口上线前必须用 1KB、10MB、100MB 三个量级的文件各测一遍再用中文名、特殊字符名、无后缀名各测一遍。这套组合拳打下来基本能把 90% 的坑提前暴露。希望帮到你。本文还有配套的精品资源点击获取
Java图片上传下载实战：从HTTP协议到断点续传的避坑指南
简介本资源面向Java后端初学者与Web开发人员聚焦图片上传与下载这一常见功能需求结合ckeditor4富文本编辑器讲解如何构建后端图片上传接口。内容涵盖Spring Boot环境下MultipartFile文件处理、文件存储路径规划、路径遍历与文件名重命名等安全防护、异常捕获以及ckeditor4所需的RESTful API、JSON响应格式与CORS跨域配置同时涉及静态资源映射、JWT权限校验、防盗链等下载安全策略并延伸至云存储、缩略图生成与日志记录等优化方向。资源包共71个文件以35个java源码与18个class文件为核心辅以7个xml、6个yml及3个properties配置文件另有jar依赖整体约133KB结构完整便于直接导入运行。目前已有235人学习下载适合希望快速掌握图片上传下载完整实现思路与安全细节的开发者参考。1. 图片上传下载一个被低估的 Java 基本功很多 Java 开发者第一次接触文件上传是在做课程设计或者管理后台的时候。前端一个input typefile后端一个MultipartFile看起来三行代码就能搞定。但真到了生产环境你会发现事情远没有这么简单上传大文件时内存直接飙满、下载时中文文件名变成乱码、文件存本地还是存对象存储、并发上传时文件名冲突覆盖……这些问题在面试八股文里很少被问到但在实际项目里一个都躲不掉。图片上传与下载是 Java Web 开发中最基础也最容易翻车的模块之一。它涉及 HTTP 协议的文件传输机制、Servlet 容器的 multipart 解析、文件系统的读写策略、以及安全层面的校验与防护。这篇文章不讲 Spring 源码级别的原理而是从一线开发的视角把「一个能用的图片上传下载功能」从零搭起来再把那些血泪踩坑点一个个拆开讲清楚。适合正在做课程设计的学生、刚转 Java 后端的开发者以及想把这部分知识系统梳理一遍的从业者。2. 从 HTTP 到磁盘图片上传到底经历了什么2.1 为什么不能直接用 request.getParameter 拿文件很多人一开始会想前端表单提交文件后端用request.getParameter(file)拿不就行了答案是不行。普通表单的Content-Type是application/x-www-form-urlencoded所有字段会被编码成keyvaluekeyvalue的字符串格式。但文件是二进制数据编码成字符串会直接损坏内容。文件上传必须把表单的enctype设为multipart/form-data。这个编码格式会把请求体切分成多个 part每个 part 有自己的头部和边界符boundary文件内容以原始二进制形式放在 part 的 body 里。Servlet 规范从 3.0 开始提供了Part接口和request.getParts()方法来解析这种请求但在 Spring 环境下我们通常直接用MultipartFile来接收。理解这一点很关键MultipartFile不是凭空存在的它是 Spring 对 Servlet 3.0PartAPI 的封装。知道底层是什么排查问题时才不会慌。2.2 最小可运行的上传接口先看一个不依赖任何前端框架、纯 Spring Boot 的最小实现。项目依赖只需要spring-boot-starter-web。RestController RequestMapping(/api/file) public class FileController { // 上传目录实际项目应配置在 application.yml 中 private static final String UPLOAD_DIR System.getProperty(user.dir) /uploads/; PostMapping(/upload) public MapString, Object upload(RequestParam(file) MultipartFile file) throws IOException { MapString, Object result new HashMap(); // 1. 空文件校验 if (file.isEmpty()) { result.put(code, 400); result.put(msg, 文件为空); return result; } // 2. 类型校验只允许图片 String contentType file.getContentType(); if (contentType null || !contentType.startsWith(image/)) { result.put(code, 400); result.put(msg, 只允许上传图片); return result; } // 3. 生成唯一文件名避免并发覆盖 String originalName file.getOriginalFilename(); String suffix originalName.substring(originalName.lastIndexOf(.)); String newFileName UUID.randomUUID().toString().replace(-, ) suffix; // 4. 确保目录存在 File dir new File(UPLOAD_DIR); if (!dir.exists()) { dir.mkdirs(); } // 5. 写入磁盘 File dest new File(UPLOAD_DIR newFileName); file.transferTo(dest); result.put(code, 200); result.put(fileName, newFileName); result.put(url, /api/file/download/ newFileName); return result; } }这段代码的逻辑很直白校验空文件、校验类型、生成 UUID 文件名、创建目录、写入磁盘。几个关键点需要展开说。file.getOriginalFilename()拿到的是用户上传时的原始文件名这个值不可信可能包含路径穿越字符比如../../etc/passwd所以绝对不能直接用它作为存储文件名。用 UUID 重命名是最简单有效的策略。file.transferTo(dest)是 Spring 提供的便捷方法底层会把临时文件移动到目标位置。注意如果目标文件已存在不同容器的行为不一致有的会覆盖有的会抛异常。用 UUID 就不会有这个问题。contentType是从请求头里拿的客户端可以伪造。真正安全的做法是读取文件魔数magic number来判断真实类型这个后面在避坑章节会展开。2.3 文件大小限制三个地方都要配上传大文件时最常见的报错是MaxUploadSizeExceededException。这个限制可能在三个层面生效少配一个都会出问题。第一层是 Spring Boot 的配置。在application.yml中spring: servlet: multipart: max-file-size: 10MB # 单个文件最大大小 max-request-size: 50MB # 整个请求最大大小多文件时生效 enabled: true第二层是 Servlet 容器Tomcat的限制。Spring Boot 内嵌 Tomcat 时上面的配置会自动生效。但如果你部署到外部 Tomcat需要在server.xml或应用的web.xml中配置multipart-config。第三层是 Nginx 反向代理的限制。如果前面有 Nginx默认的client_max_body_size是 1MB超过会直接返回 413。需要在 Nginx 配置中加上client_max_body_size 50m;。提示这三个限制中任何一个触发报错信息都不一样。Spring 层报MaxUploadSizeExceededExceptionTomcat 层报 400 或连接重置Nginx 层报 413。排查时先确认请求有没有到达 Java 应用。2.4 下载接口Content-Disposition 的正确用法下载看起来比上传简单就是把文件读出来写到 response 里。但中文文件名乱码是几乎每个人都会踩的坑。GetMapping(/download/{fileName}) public void download(PathVariable String fileName, HttpServletResponse response) throws IOException { File file new File(UPLOAD_DIR fileName); if (!file.exists()) { response.setStatus(404); return; } // 设置内容类型 response.setContentType(application/octet-stream); // 设置文件名URL 编码处理中文 String encodedName URLEncoder.encode(fileName, UTF-8).replace(, %20); response.setHeader(Content-Disposition, attachment; filename*UTF-8 encodedName); // 流式写出 try (InputStream in new FileInputStream(file); OutputStream out response.getOutputStream()) { byte[] buffer new byte[8192]; int len; while ((len in.read(buffer)) ! -1) { out.write(buffer, 0, len); } out.flush(); } }这里的关键在Content-Disposition头。老式的写法是attachment; filenamexxx.jpg但 filename 的值如果是中文浏览器会用 ISO-8859-1 解码直接乱码。RFC 5987 定义了filename*UTF-8的语法告诉浏览器用 UTF-8 解码文件名。URLEncoder.encode会把空格编码成而 HTTP 头里不是空格的意思所以要替换回%20。流式写出用了 8KB 的缓冲区这是磁盘 IO 和网络 IO 之间比较平衡的大小。不要用file.getBytes()一次性读入内存大文件会直接 OOM。3. 存储策略与安全校验别把文件裸奔在磁盘上3.1 本地存储 vs 对象存储的选型上面的例子把文件存在本地磁盘。这在单机部署、文件量不大的场景下完全够用。但一旦涉及多实例部署本地存储就会出问题用户上传到实例 A下次请求负载均衡到实例 B文件就找不到了。常见做法有三种方案适用场景优点缺点本地磁盘单机、课程设计、内部工具简单、零依赖无法水平扩展、备份麻烦NFS/共享盘小规模多实例改动小性能瓶颈、单点故障对象存储OSS/S3/MinIO生产环境、大规模可扩展、高可用、CDN 友好需要额外依赖和成本我一般会建议如果是学习或课程设计本地磁盘足够了把上传下载的流程跑通最重要。如果是真实项目直接上对象存储不要走 NFS 的弯路。对象存储的 SDK 通常也提供了upload和download方法接口设计和MultipartFile类似迁移成本不高。3.2 文件类型校验Content-Type 不可信前面代码里用contentType.startsWith(image/)做了校验但这只能挡住最粗心的攻击者。攻击者可以把一个.jsp文件改名为.jpg同时把请求头里的Content-Type改成image/jpeg你的校验就形同虚设。真正可靠的做法是读取文件头部的魔数。常见图片格式的魔数JPEG前两个字节FF D8PNG前八个字节89 50 4E 47 0D 0A 1A 0AGIF前三个字节47 49 46private boolean isRealImage(MultipartFile file) throws IOException { byte[] header new byte[8]; try (InputStream in file.getInputStream()) { if (in.read(header) 8) { return false; } } // JPEG if (header[0] (byte) 0xFF header[1] (byte) 0xD8) return true; // PNG if (header[0] (byte) 0x89 header[1] 0x50 header[2] 0x4E header[3] 0x47) return true; // GIF if (header[0] 0x47 header[1] 0x49 header[2] 0x46) return true; return false; }这个校验在读文件流的时候顺便做了开销很小。注意file.getInputStream()每次调用会返回新的流不会影响后续的transferTo。3.3 路径穿越防护别让用户控制文件路径下载接口里用了PathVariable String fileName然后直接拼接到UPLOAD_DIR fileName。如果用户请求/api/file/download/../../etc/passwd在某些容器配置下可能真的会读到系统文件。防护方法很简单在拼接路径之前对文件名做白名单校验只允许字母、数字、下划线和点。private boolean isSafeFileName(String fileName) { return fileName ! null fileName.matches(^[a-zA-Z0-9_.]$); }因为我们的上传接口用 UUID 重命名了文件所以下载时的文件名天然就是安全的。但如果你允许用户用原始文件名下载这个校验就必须加。3.4 用 ResponseEntity 简化下载响应手动操作HttpServletResponse比较繁琐Spring 提供了ResponseEntityResource的写法更符合 REST 风格。GetMapping(/download2/{fileName}) public ResponseEntityResource download2(PathVariable String fileName) throws IOException { File file new File(UPLOAD_DIR fileName); if (!file.exists()) { return ResponseEntity.notFound().build(); } InputStreamResource resource new InputStreamResource(new FileInputStream(file)); String encodedName URLEncoder.encode(fileName, UTF-8).replace(, %20); return ResponseEntity.ok() .contentType(MediaType.APPLICATION_OCTET_STREAM) .header(HttpHeaders.CONTENT_DISPOSITION, attachment; filename*UTF-8 encodedName) .contentLength(file.length()) .body(resource); }这种写法把状态码、头信息、body 都封装在一个对象里代码更清晰。contentLength设置后浏览器能显示下载进度条体验更好。4. 避坑指南那些让你加班到凌晨的细节4.1 上传后立即下载文件却不存在现象上传接口返回成功但马上调用下载接口报 404。原因file.transferTo(dest)在某些情况下是异步刷盘的或者上传目录配置的是相对路径而下载时的工作目录变了。更常见的原因是上传目录用了System.getProperty(user.dir)在 IDE 里运行和打包成 jar 后运行这个值是不一样的。解决把上传目录配置成绝对路径写在application.yml里用Value注入。不要依赖user.dir。file: upload-dir: /data/uploads/4.2 中文文件名下载后变成乱码现象下载下来的文件名是一串%E4%B8%AD%E6%96%87或者问号。原因Content-Disposition头里直接放了中文或者用了filename而不是filename*。解决用filename*UTF-8加 URL 编码。如果还要兼容老浏览器可以同时设置两个头但现代浏览器只认filename*。4.3 大文件上传内存溢出现象上传 100MB 以上的文件时应用抛出OutOfMemoryError。原因Spring 的MultipartFile默认会把文件写入临时目录但如果配置了spring.servlet.multipart.file-size-threshold为很大的值或者用了file.getBytes()把整个文件读进内存就会 OOM。解决保持file-size-threshold为默认值0让文件直接写临时文件。处理文件时始终用流不要用getBytes()。如果确实需要读全部内容用Files.readAllBytes()也要确保文件大小可控。4.4 并发上传同名文件互相覆盖现象两个用户同时上传photo.jpg后上传的覆盖了先上传的。原因用了原始文件名作为存储名。解决用 UUID 或者时间戳加随机数重命名。如果业务需要保留原始文件名把它存在数据库里磁盘上用唯一名。4.5 上传目录没有写权限现象本地测试正常部署到服务器后上传报FileNotFoundException或AccessDeniedException。原因运行 Java 进程的用户对上传目录没有写权限。解决创建目录后执行chmod 755或chown给运行用户。在代码里dir.mkdirs()之后检查dir.canWrite()提前给出明确错误信息。5. 进阶技巧用缩略图和断点续传提升体验图片上传下载做到能用之后下一步就是做好。两个最值得投入的方向是缩略图生成和断点续传。缩略图方面Java 原生ImageIO就能做但处理大图时性能和内存都不理想。我一般会用 Thumbnailator 这个库一行代码搞定Thumbnails.of(srcFile) .size(200, 200) .outputQuality(0.8) .toFile(thumbFile);size(200, 200)会等比缩放保持宽高比。outputQuality控制 JPEG 压缩质量0.8 是清晰度和体积的平衡点。生成缩略图后列表页加载缩略图详情页加载原图流量能省 90% 以上。断点续传稍微复杂一些核心是Range请求头。客户端发Range: bytes1024-服务端返回 206 Partial Content只写对应区间的字节。Spring 的ResourceHttpRequestHandler已经内置支持如果你用ResponseEntityResource返回文件它会自动处理 Range 请求。但如果你手动写流就需要自己解析 Range 头。String range request.getHeader(Range); if (range ! null range.startsWith(bytes)) { String[] parts range.substring(6).split(-); long start Long.parseLong(parts[0]); long end parts.length 1 ? Long.parseLong(parts[1]) : file.length() - 1; long contentLength end - start 1; response.setStatus(HttpServletResponse.SC_PARTIAL_CONTENT); response.setHeader(Content-Range, bytes start - end / file.length()); response.setHeader(Content-Length, String.valueOf(contentLength)); try (RandomAccessFile raf new RandomAccessFile(file, r)) { raf.seek(start); byte[] buffer new byte[8192]; long remaining contentLength; while (remaining 0) { int len raf.read(buffer, 0, (int) Math.min(buffer.length, remaining)); if (len -1) break; response.getOutputStream().write(buffer, 0, len); remaining - len; } } }这段代码用RandomAccessFile定位到起始位置然后按块读取。Content-Range头告诉客户端这次返回的是哪一段。客户端下载中断后下次请求带上已下载的字节数就能从断点继续。验证方法很简单用curl -H Range: bytes0-1023 -o part1.bin http://localhost:8080/api/file/download/test.jpg下载前 1KB再用Range: bytes1024-下载剩余部分最后cat part1.bin part2.bin full.jpg对比原文件是否一致。我自己的习惯是任何文件上传接口上线前必须用 1KB、10MB、100MB 三个量级的文件各测一遍再用中文名、特殊字符名、无后缀名各测一遍。这套组合拳打下来基本能把 90% 的坑提前暴露。希望帮到你。本文还有配套的精品资源点击获取
