服务端接收文件（PPT 第 33 页）#

PPT 第 33 页给出的接收端代码：

1
@Slf4j
2
@RestController
3
public class UploadController {
4

5
    @PostMapping("/upload")
6
    public Result handleFileUpload(String name, Integer age, MultipartFile file) {
7
        log.info("文件上传:{}", file);
8
        return Result.success();
9
    }
10
}

几个要点：

• MultipartFile：Spring 提供的接口，代表”这次请求里上传上来的那个文件”。方法参数里写一个这种类型的参数，Spring 就会自动把请求里的文件装进它；
• 参数名要跟表单对上：表单里是 <input type="file" name="file">，方法参数就叫 file；名字不一致，Spring 找不到对应那一段，参数会是 null；
• 普通表单项照常接收：name、age 这些文字项还是按名字接收，和文件一起发过来也互不影响（本机实测的那次请求就是 name=张三、age=20、file=@small.png 一起发的）；
• 这一步只是”接住”，还没存：log.info("文件上传:{}", file) 打出来的是这个对象的 toString（里面能看到原始文件名、大小、是否为空这些信息），文件此刻还在临时目录里，请求结束就没了。

为什么要改名：同名覆盖#

如果直接用用户上传时的原名保存，会出问题：张三传了一张 1.jpg，李四也传了一张 1.jpg，后传的会把先传的覆盖掉——服务器上只剩一张。所以要把文件名换成”不会重复的随机串 + 原来的扩展名”。逐句拆开：

扩展名为什么必须留着：系统靠扩展名认文件类型，浏览器也靠它决定”这张图是显示还是下载”；把扩展名换成 .png 而文件其实是 jpg，虽然多半也能看，但不规范。

一、知识回顾（读完直接做下面的实践题）#

1. 什么是文件上传：将本地图片、视频、音频等文件上传到服务器，供其他用户浏览或下载的过程；项目中应用非常广泛（发微博、发微信朋友圈都用到了）
2. 前端三要素：① 提交方式必须是 POST（method="post"）；② 编码方式必须是 enctype="multipart/form-data"；③ 必须有文件输入框 <input type="file" name="file">——其中 name 就是服务端接收文件时的参数名
3. 为什么默认编码不行：表单默认 application/x-www-form-urlencoded，只能把表单项拼成纯文本，二进制文件没法这样传；multipart/form-data 会把表单切成多段，文件单独占一段按二进制发送
4. 服务端怎么接收：Controller 方法里写一个 MultipartFile 类型的参数，参数名与表单里文件框的 name 一致；普通表单项（name、age）照常按名字接收；这一步只是”接住”，文件还在临时目录里
5. 本地存储两步：multipartFile.getOriginalFilename() 获取原始文件名、multipartFile.transferTo(File dest) 将文件转存到磁盘文件（课程代码：file.transferTo(new File("D:/images/" + uniqueFileName))）
6. 为什么要改文件名：直接用原名会同名覆盖（两个人传 1.jpg，后传的覆盖先传的）；做法是 UUID 随机串 + 原扩展名——PPT 版本是 UUID.randomUUID().toString().replaceAll("-", "")（32 位无横线），取扩展名用 originalFilename.substring(originalFilename.lastIndexOf("."))（从最后一个点截到末尾，带上点）
7. 上传大小限制：默认单个文件最大 1MB；在 application.yml 里配 spring.servlet.multipart.max-file-size（单个文件）和 max-request-size（整个请求，含所有文件和表单数据）；课程工程配的是 10MB / 100MB
8. 超限的表现（本机实测）：传一个 11MB 的文件（配置是 10MB）→ HTTP 413 + 服务端日志 org.springframework.web.multipart.MaxUploadSizeExceededException: Maximum upload size exceeded；请求在进 Controller 之前就被拦下，接口里的 log.info 不会打出来
9. 落盘实测（本机实测）：D:/tlias-images/c09f752c2a16431b86b22fe0c7de9167.png，2056 字节——32 位无横线随机串 + 原扩展名 .png；响应是 {"code":1,"msg":"success","data":null}（本地存储版没返回访问地址）
10. 本地存储的三个问题与出路：无法直接访问、磁盘满了、磁盘坏了；出路是 FastDFS（分布式文件系统）、MinIO（对象存储）、云（阿里云 OSS 等云存储服务，上传后能得到可直接访问的 URL，也不用自己维护磁盘）

二、裸写题#

• 2-1 写一个”接收上传文件并存到本地磁盘”的接口 需求：在 tlias-web-management 工程里写一个上传接口，路径 POST /upload，要求： ① 能接收前端提交上来的文件（普通表单项不用管）； ② 保存到服务器磁盘前先把文件名改成不会重复的（保留原扩展名）； ③ 文件保存到 D:/tlias-images/ 目录下（目录已存在），响应统一用 Result.success()； ④ 用日志把”文件上传”这件事记一笔。 （练习文件 test_72_文件上传.java 的题目2-1 里给了写作区。）

  提示（先自己想，实在想不出再点开）

  一级 · 思路：分四步——接住文件（方法参数）→ 从原名里取出扩展名 → 用随机串拼一个新名字 → 把文件写到”目录 + 新名字”这个位置 二级 · 方法：文件参数用 MultipartFile；取原名 file.getOriginalFilename()；取扩展名 substring(lastIndexOf("."))；随机串用 UUID.randomUUID().toString().replaceAll("-", "")；写盘用 file.transferTo(new File("D:/tlias-images/" + newFileName))；接口上 @PostMapping("/upload")，类上 @RestController + @Slf4j 三级 · 骨架：public Result upload(____ file) throws Exception { String originalFilename = file.____(); String extension = originalFilename.substring(originalFilename.____(".")); String newFileName = ____.randomUUID().toString().____("-", "") + extension; file.____(new File("____" + newFileName)); return Result.success(); }

  参考答案（做完再点开）

  1
  @Slf4j
  2
  @RestController
  3
  public class UploadController {
  4
  
  5
      @PostMapping("/upload")
  6
      public Result upload(MultipartFile file) throws Exception {
  7
          log.info("文件上传:{}", file);
  8
  
  9
          //1. 取原始文件名，并从最后一个点截出扩展名（带上点）
  10
          String originalFilename = file.getOriginalFilename(); // 例如 1.jpg
  11
          String extension = originalFilename.substring(originalFilename.lastIndexOf(".")); // .jpg
  12
  
  13
          //2. 生成不重复的新文件名：32 位随机串 + 原扩展名
  14
          String newFileName = UUID.randomUUID().toString().replaceAll("-", "") + extension;
  15
  
  16
          //3. 保存文件到磁盘（D:/tlias-images/ 目录要已经存在）
  17
          file.transferTo(new File("D:/tlias-images/" + newFileName));
  18
  
  19
          return Result.success();
  20
      }
  21
  }

  显示更多显示更少

  检查点：① 参数类型是 MultipartFile、名字与表单里文件框的 name 一致；② 扩展名是从最后一个点截的（22.2.2.2.png 要得到 .png）；③ transferTo 的目标目录必须先存在（它不会自动建目录）；④ 方法要声明 throws Exception（transferTo 会抛 IOException）。对照课程 UploadController 里注释的那份”本地存储版”：它把随机串和扩展名拼在一个 newFileName 里、保存目录写的是 D:/images/，本机实测时改成了 D:/tlias-images/。

• 2-2 让一个普通表单变成能上传文件的表单 需求：下面这个表单现在只能提交文字，请改造成”能连文件一起提交”的表单：用户填姓名、年龄，再选一张图片，点”上传文件”提交到 /upload。 ① 提交方式和编码方式要改对；② 加上文件输入框（服务端会按 file 这个参数名收文件）；③ 说明如果漏掉编码方式那一项，会发生什么。

  1
  <!-- 现在的样子（提交上去只有文字，文件根本发不出去） -->
  2
  <form action="/upload" method="get">
  3
      姓名: <input type="text" name="name"><br>
  4
      年龄: <input type="text" name="age"><br>
  5
      <input type="submit" value="上传文件">
  6
  </form>

  （练习文件 test_72_文件上传.java 的题目2-2 里给了写作区。）

  提示（先自己想，实在想不出再点开）

  一级 · 思路：对照”三要素”一条条补——提交方式、编码方式、文件输入框，缺一条文件就到不了服务端 二级 · 方法：method="post"；enctype="multipart/form-data"；<input type="file" name="file"> 三级 · 骨架：<form action="/upload" method="____" enctype="____"> … <input type="____" name="____">

  参考答案（做完再点开）

  1
  <form action="/upload" method="post" enctype="multipart/form-data">
  2
      姓名: <input type="text" name="name"><br>
  3
      年龄: <input type="text" name="age"><br>
  4
      图像: <input type="file" name="file"><br>
  5
      <input type="submit" value="上传文件">
  6
  </form>

  ③ 漏掉 enctype="multipart/form-data"：表单还是能提交，但浏览器会按默认的 application/x-www-form-urlencoded 把表单项拼成纯文本，文件内容根本没被发出去——服务端收到的 file 是 null（或直接报错）。另外 method 必须是 post：文件内容大，塞不进 URL，只有请求体能装下。

• 2-3 配上传大小限制，并说清超限时的现象 需求：现在工程用的是默认限制（单个文件 1MB），请改成”单个文件最大 10MB、整个请求最大 100MB”，并回答： ① 两个配置项分别管什么？ ② 默认值是多少？ ③ 传一个 11MB 的文件会发生什么（状态码、异常、请求有没有进到 Controller）？ （练习文件 test_72_上传配置.yml 的题目2-3 里给了写作区。）

  提示（先自己想，实在想不出再点开）

  一级 · 思路：配置写在 application.yml 的 spring → servlet → multipart 下面，一个管”单个文件”、一个管”整个请求” 二级 · 方法：spring.servlet.multipart.max-file-size（单个文件）与 spring.servlet.multipart.max-request-size（整个请求，含所有文件和表单数据） 三级 · 骨架：spring: → servlet: → multipart: 下面两行 max-file-size: ____ / max-request-size: ____

  参考答案（做完再点开）

  1
  spring:
  2
    servlet:
  3
      multipart:
  4
        #最大单个文件大小
  5
        max-file-size: 10MB
  6
        #最大请求大小(包括所有文件和表单数据)
  7
        max-request-size: 100MB

  ① max-file-size 管单个文件的上限；max-request-size 管整个请求的上限（所有文件 + 表单数据加起来）。② 两个的默认值都是 1MB——PPT 第 36 页说的”默认上传文件的最大大小为 1MB”就是指它。③ 本机实测：传 11MB 的文件得到 HTTP 413，服务端日志是 org.springframework.web.multipart.MaxUploadSizeExceededException: Maximum upload size exceeded；因为是在进 Controller 之前就拦下的，接口里那句 log.info("文件上传:{}", file) 不会打出来。

• 2-4 分析题：本地存储的三个问题 需求：接口已经能把文件存到服务器磁盘了，但课程说这不是最终方案。请回答： ① 本地存储有哪三个问题？分别会造成什么后果？ ② 为什么”无法直接访问”会让前端很尴尬（结合本机实测里接口的响应看）？ ③ 三个出路分别是什么，它们各自更适合什么情况？ （练习文件 test_72_文件上传.java 的题目2-4 里给了写作区。）

  提示（先自己想，实在想不出再点开）

  一级 · 思路：从”文件放在哪”这个角度想——放在自己服务器的一块磁盘上，会同时带来”访问”和”容量/可靠性”两方面的问题 二级 · 方法：三个问题是”无法直接访问""磁盘满了""磁盘坏了”；出路是 FastDFS（分布式文件系统）、MinIO（对象存储）、云（阿里云 OSS 等） 三级 · 骨架：① 无法直接访问 → ② 磁盘满 → ③ 磁盘坏；出路：自己搭 ____ / ____，或者用 ____

  参考答案（做完再点开）

  ① 三个问题：无法直接访问（文件存在服务器磁盘目录里，浏览器没法通过一个 URL 直接访问它，要自己写静态资源映射或下载接口）；磁盘满了（磁盘空间有限，图片视频越传越多，早晚写不进去）；磁盘坏了（单机磁盘故障或机器挂掉，文件全丢且没法恢复）。 ② 因为前端上传完图片是要立刻显示出来的（比如新增员工表单里的头像预览），而本机实测里本地存储版接口返回的是 {"code":1,"msg":"success","data":null}——文件是存下来了，但没有给前端一个能访问的地址，前端无从显示。 ③ 出路：FastDFS（分布式文件系统，多台机器一起存，适合自己搭一套）；MinIO（对象存储服务，可以自己部署，接口风格接近云厂商的对象存储）；云（阿里云 OSS 这类云存储服务，不用自己维护机器，上传后直接返回可访问的 URL，容量按需付费——Tlias 用的就是这条）。

三、综合题#

• 3-1 给 Tlias 接上”头像上传”并亲眼看到文件落盘 这一题把本节串起来：写接口 → 改前端页面 → 配大小限制 → 实测落盘 → 观察超限。

  1. 在 tlias-web-management 里新建（或复用）UploadController，写 POST /upload 接口：接收上传的文件，用 UUID 改名（保留扩展名）后保存到 D:/tlias-images/（先把目录建好），用日志记录”文件上传”；
  2. 在 src/main/resources/static/ 下准备一个 upload.html（或直接拿课程资料 资料/04. 文件上传/upload.html），把三要素补齐，页面里能填姓名、年龄并选一张图片；
  3. 在 application.yml 里配好上传限制：单个文件 10MB、整个请求 100MB；
  4. 启动工程，打开 http://localhost:8080/upload.html，选一张小图片提交（或直接用 curl -F "name=张三" -F "age=20" -F "file=@small.png" http://localhost:8080/upload），然后去 D:/tlias-images/ 看：文件名长什么样（和原来的名字还一样吗）、大小对不对；把响应和落盘文件名抄到练习文件里；
  5. 换一个 11MB 左右的文件再传一次：记下状态码与服务端日志里的异常类名，并回答”请求进到 Controller 了吗、为什么”；
  6. 回答 PPT 第 36 页的两个问题（本地存储的两个方法分别是什么？上传大小受限怎么办、默认多大？），以及”本地存储的三个问题分别是什么”；
  7. 收尾：把临时改出来的上传接口和测试文件清理掉（本机实测后也把 D:/tlias-images/ 与测试文件删掉了，工程恢复原状）。 （练习文件 test_72_文件上传.java 与 test_72_上传配置.yml 里按这 7 步给了写作区。）

  涉及知识点

  知识点	在这里的应用
  前端三要素	第 2、4 步——表单三样齐全，文件才发得出去
  MultipartFile 接收	第 1、4 步——接口把上传的文件接住
  UUID 改名 + transferTo	第 4 步——磁盘上出现一个 32 位随机串命名的文件（本机实测：c09f752c2a16431b86b22fe0c7de9167.png）
  上传大小限制	第 3、5 步——10MB / 100MB，超了报 413
  本地存储的问题	第 6 步——为什么接口返回的 data 是 null、为什么最终要换成云存储

  提示（先自己想，实在想不出再点开）

  一级 · 思路：第 1 步就是”接住 → 改名 → 写盘”三下；第 2 步只是把表单三要素补齐；第 3 步是两行 yml；第 5 步是”把闸门调小再撞一次” 二级 · 方法：MultipartFile + getOriginalFilename() + UUID.randomUUID().toString().replaceAll("-","") + transferTo(new File(...))；表单 method="post" + enctype="multipart/form-data" + <input type="file" name="file">；yml 里 spring.servlet.multipart.max-file-size / max-request-size 三级 · 骨架：@PostMapping("/____") public Result upload(____ file) throws Exception { … file.____(new File("____" + newFileName)); return Result.success(); }

  参考答案（做完再点开）

  1. 接口（与课程注释着的那份本地存储版一致，只把目录换成自己的）：

  1
  @Slf4j
  2
  @RestController
  3
  public class UploadController {
  4
  
  5
      @PostMapping("/upload")
  6
      public Result upload(MultipartFile file) throws Exception {
  7
          log.info("文件上传:{}", file);
  8
  
  9
          //1. 取原始文件名与扩展名
  10
          String originalFilename = file.getOriginalFilename(); // 1.jpg  22.2.2.2.png
  11
          String extension = originalFilename.substring(originalFilename.lastIndexOf("."));
  12
  
  13
          //2. 生成不重复的新文件名
  14
          String newFileName = UUID.randomUUID().toString().replaceAll("-", "") + extension;
  15
  
  16
          //3. 保存文件
  17
          file.transferTo(new File("D:/tlias-images/" + newFileName));
  18
  
  19
          return Result.success();
  20
      }
  21
  }

  显示更多显示更少

  2. 页面（static/upload.html，与课程资料 资料/04. 文件上传/upload.html 相同）：

  1
  <!DOCTYPE html>
  2
  <html lang="en">
  3
  <head>
  4
      <meta charset="UTF-8">
  5
      <title>上传文件</title>
  6
  </head>
  7
  <body>
  8
      <form action="/upload" method="post" enctype="multipart/form-data">
  9
          姓名: <input type="text" name="name"><br>
  10
          年龄: <input type="text" name="age"><br>
  11
          头像: <input type="file" name="file"><br>
  12
          <input type="submit" value="提交">
  13
      </form>
  14
  </body>
  15
  </html>

  显示更多显示更少

  3. 配置：

  1
  spring:
  2
    servlet:
  3
      multipart:
  4
        max-file-size: 10MB      # 最大单个文件大小
  5
        max-request-size: 100MB  # 最大请求总大小（包括所有文件和表单数据）

  4. 本机实测：

  1
  请求：curl -F "name=张三" -F "age=20" -F "file=@small.png" http://localhost:8080/upload
  2
  响应：{"code":1,"msg":"success","data":null}
  3
  落盘：D:/tlias-images/c09f752c2a16431b86b22fe0c7de9167.png   2056 字节

  文件名已经不是原来的 small.png，而是 32 位无横线的随机串 + 原扩展名（说明改名逻辑生效、同名覆盖不会发生）；响应里的 data 是 null，因为本地存储版还没给前端”访问地址”。 5. 超限实测：传 11MB 文件 → HTTP 413 + 服务端日志 org.springframework.web.multipart.MaxUploadSizeExceededException: Maximum upload size exceeded。请求没有进到 Controller（log.info 没打出来）——Spring 在读请求体时就按 max-file-size 把它拦住了，这也说明”限制是在进入业务代码之前生效的”。 6. PPT 问答：① 本地存储的两个方法——multipartFile.getOriginalFilename()（获取原始文件名）、multipartFile.transferTo(File dest)（将文件转存到磁盘文件）；② 上传大小受限——默认最大 1MB，超过需要在 application.yml 里配 spring.servlet.multipart.max-file-size（单个文件）与 max-request-size（整个请求）；③ 本地存储三个问题——无法直接访问、磁盘满了、磁盘坏了，出路是 FastDFS / MinIO / 云存储。 7. 收尾：临时改的接口、测试文件、D:/tlias-images/ 目录都清理掉，工程恢复成”用 OSS”的状态（下一篇就接着讲它）。