简介：本资源面向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 type="file">，后端一个MultipartFile，看起来三行代码就能搞定。但真到了生产环境，你会发现事情远没有这么简单：上传大文件时内存直接飙满、下载时中文文件名变成乱码、文件存本地还是存对象存储、并发上传时文件名冲突覆盖……这些问题在面试八股文里很少被问到，但在实际项目里一个都躲不掉。
图片上传与下载是 Java Web 开发中最基础也最容易翻车的模块之一。它涉及 HTTP 协议的文件传输机制、Servlet 容器的 multipart 解析、文件系统的读写策略、以及安全层面的校验与防护。这篇文章不讲 Spring 源码级别的原理，而是从一线开发的视角，把「一个能用的图片上传下载功能」从零搭起来，再把那些血泪踩坑点一个个拆开讲清楚。适合正在做课程设计的学生、刚转 Java 后端的开发者，以及想把这部分知识系统梳理一遍的从业者。
2. 从 HTTP 到磁盘：图片上传到底经历了什么
2.1 为什么不能直接用 request.getParameter 拿文件
很多人一开始会想：前端表单提交文件，后端用request.getParameter("file")拿不就行了？答案是不行。普通表单的Content-Type是application/x-www-form-urlencoded，所有字段会被编码成key=value&key=value的字符串格式。但文件是二进制数据，编码成字符串会直接损坏内容。
文件上传必须把表单的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 Map<String, Object> upload(@RequestParam("file") MultipartFile file) throws IOException { Map<String, 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 层报
MaxUploadSizeExceededException，Tomcat 层报 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; filename="xxx.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 D8 - PNG：前八个字节
89 50 4E 47 0D 0A 1A 0A - GIF：前三个字节
47 49 46
private 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 提供了ResponseEntity<Resource>的写法，更符合 REST 风格。
@GetMapping("/download2/{fileName}") public ResponseEntity<Resource> 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: bytes=1024-，服务端返回 206 Partial Content，只写对应区间的字节。Spring 的ResourceHttpRequestHandler已经内置支持，如果你用ResponseEntity<Resource>返回文件，它会自动处理 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: bytes=0-1023" -o part1.bin http://localhost:8080/api/file/download/test.jpg下载前 1KB，再用Range: bytes=1024-下载剩余部分，最后cat part1.bin part2.bin > full.jpg，对比原文件是否一致。
我自己的习惯是：任何文件上传接口，上线前必须用 1KB、10MB、100MB 三个量级的文件各测一遍，再用中文名、特殊字符名、无后缀名各测一遍。这套组合拳打下来，基本能把 90% 的坑提前暴露。希望帮到你。
本文还有配套的精品资源，点击获取
