文件上传 (Multipart)

在配置好 MultipartResolver 后，控制器可以通过 @RequestParam 或 @RequestPart 方便地处理文件上传。

基础使用 (@RequestParam)

对于常规的 multipart/form-data 请求，你可以将上传的文件绑定到 MultipartFile 参数上。

Java

@PostMapping("/upload")
public String handleUpload(@RequestParam("file") MultipartFile file) {
	if (!file.isEmpty()) {
		byte[] bytes = file.getBytes();
		// 处理文件，例如保存到硬盘或 OSS
		return "redirect:success";
	}
	return "redirect:error";
}

Kotlin

@PostMapping("/upload")
fun handleUpload(@RequestParam("file") file: MultipartFile): String {
	if (!file.isEmpty) {
		val bytes = file.bytes
		// 处理文件
		return "redirect:success"
	}
	return "redirect:error"
}

复杂对象上传 (@RequestPart)

如果你在构建 RESTful API，且请求中既有 JSON 元数据又有文件（multipart/mixed），建议使用 @RequestPart。

@PostMapping("/mixed")
public String handle(@RequestPart("meta") MetaData meta, @RequestPart("file") MultipartFile file) {
	// "meta" 自动从 JSON 转换成对象，"file" 获取上传的文件
	return "OK";
}

数据绑定到对象

你也可以直接把文件属性写在 Command 对象（POJO）里：

public class MyForm {
    private String name;
    private MultipartFile file; // 自动匹配表单字段
    // getter/setter...
}

@PostMapping("/form")
public String process(MyForm form) {
    // 同样可以工作
}

---

补充教学

1. MultipartFile vs Part

• MultipartFile：Spring 提供的抽象，功能丰富，易于测试。
• Part：Servlet 标准接口。 建议：除非你的项目要严格去 Spring 依赖（这在 MVC 项目里几乎不可能），否则首选 MultipartFile。

2. 多文件上传

如果你支持多选上传，只需把参数改为列表或数组即可：

public void upload(@RequestParam("files") List<MultipartFile> files)

3. @RequestPart vs @RequestParam

两者都能拿文件，但区别在于：

• @RequestParam：适用于简单的表单字段。它主要依靠数据绑定或类型转换器。
• @RequestPart：适用于复杂的请求部分（如 JSON/XML 片段）。它会调用 HttpMessageConverter 来解析这部分内容。 一句话总结：普通表单传图用 @RequestParam；JSON + 文件混合传参用 @RequestPart。

4. 常见的配置坑

如果文件死活传不上来（拿到的是 null 或报错）：

1. 忘记写解析器：检查是否有 StandardServletMultipartResolver（Spring Boot 默认有）。
2. 文件大小限制：Servlet 容器默认限制很小（通常是 1MB 或 10MB），需要在 application.properties 里调大 spring.servlet.multipart.max-file-size。
3. 表单类型：确保前端 HTML 的 <form> 标签里写了 enctype="multipart/form-data"。