Spring Boot中MultipartFile在@PostMapping应作为RequestParam还是RequestBody？

嘿，我来帮你搞定这个MultipartFile的注解问题！其实你踩的坑很多人都遇过——MultipartFile根本不能用@RequestBody，这是核心问题，先给你把这点说清楚。

为什么@RequestBody不行？ #

@RequestBody是用来解析请求体里的序列化数据（比如JSON、XML）的，它会把整个请求体当成单一的数据流来处理。但文件上传用的是multipart/form-data格式，这种请求的内容是分割成多个部分的（比如文件部分、表单字段部分），和@RequestBody的处理逻辑完全不匹配，所以用它肯定会失败。

正确的两种用法 #

1. @RequestParam（单文件/多文件上传最常用） #

这是处理文件上传的标准方式，直接用@RequestParam绑定文件参数，代码示例：

import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.multipart.MultipartFile;

@RestController
public class FileUploadController {

    @PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public ResponseEntity<String> uploadSingleFile(@RequestParam("file") MultipartFile file) {
        // 检查文件是否为空
        if (file.isEmpty()) {
            return ResponseEntity.badRequest().body("上传的文件不能为空");
        }
        // 处理文件逻辑，比如获取文件名、保存到本地/云存储
        String fileName = file.getOriginalFilename();
        // file.transferTo(new File("/path/to/save/" + fileName));
        return ResponseEntity.ok("文件上传成功：" + fileName);
    }

    // 多文件上传的写法
    @PostMapping(value = "/upload-multiple", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public ResponseEntity<String> uploadMultipleFiles(@RequestParam("files") MultipartFile[] files) {
        for (MultipartFile file : files) {
            // 逐个处理文件
        }
        return ResponseEntity.ok("共上传" + files.length + "个文件");
    }
}

注意事项：

• 一定要在@PostMapping里指定consumes = MediaType.MULTIPART_FORM_DATA_VALUE，告诉Spring这是处理多部分表单请求
• 前端请求时，表单的enctype必须设置为multipart/form-data，且文件字段的name要和@RequestParam里的参数名一致（比如示例中的"file"）

2. @RequestPart（适合同时传文件和结构化数据） #

如果你的接口需要同时接收文件和其他JSON格式的参数（比如文件的元数据），用@RequestPart会更灵活，它能分别解析不同的请求部分：

import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestPart;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.multipart.MultipartFile;

@RestController
public class FileWithMetadataController {

    // 自定义的元数据POJO
    static class FileMetadata {
        private String fileName;
        private String description;
        // getter和setter省略
    }

    @PostMapping(value = "/upload-with-metadata", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public ResponseEntity<String> uploadWithMetadata(
            @RequestPart("file") MultipartFile file,
            @RequestPart("metadata") FileMetadata metadata) {
        return ResponseEntity.ok("收到文件：" + file.getOriginalFilename() 
                + "，描述：" + metadata.getDescription());
    }
}

这种场景下，前端可以分别发送文件部分和JSON部分，Spring会自动把metadata部分解析成对应的POJO对象。

常见失败原因排查 #

如果还是没成功，可以检查这几点：

• 前端是否正确设置了enctype="multipart/form-data"（表单提交）或者请求头Content-Type: multipart/form-data（AJAX/Postman请求）
• @RequestParam/@RequestPart的参数名和前端传入的字段名是否完全一致
• Spring Boot版本是否过低（老版本可能需要手动配置multipart支持，不过现在最新版本默认已经开启）

内容的提问来源于stack exchange，提问作者Nag