Spring Boot REST API报错：不支持multipart/form-data;charset=UTF-8

嘿，这个问题我之前踩过坑！当把单个MultipartFile改成数组后出现HttpMediaTypeNotSupportedException，大概率是参数绑定、请求配置或者Spring解析逻辑的问题，咱们一步步排查解决：

1. 先检查Controller的参数绑定是否正确 #

最常见的错误是没给数组参数加@RequestParam注解，或者参数名和请求里的key不匹配。比如正确的写法应该是：

@PostMapping("/upload-products")
public ResponseEntity<String> upload(
        @RequestParam("productImages") MultipartFile[] productImages,
        @ModelAttribute ProductDTO productDTO) {
    // 处理文件和DTO的逻辑
    return ResponseEntity.ok("上传成功");
}

这里要注意：如果你的接口同时要传文件和DTO数据，不能直接用@RequestBody——因为multipart/form-data格式的请求里，DTO的字段是作为表单参数传递的，要用@ModelAttribute（可以省略）或者单独的@RequestParam来绑定。

2. 核对Postman的请求配置，别犯低级错误 #

Postman里的配置直接决定请求是否能被正确解析：

• 一定要选form-data类型，不要混合raw格式的JSON（这会导致Content-Type混乱）；
• 文件参数的Key要和Controller里@RequestParam的名字完全一致（比如上面的productImages），并且每个文件都要选择File类型，上传对应的文件；
• DTO的字段要作为独立的form-data参数添加，比如DTO里有productName字段，就加一个Key为productName的参数，值填对应的字符串。

3. 如果要同时传文件和JSON格式的DTO，用@RequestPart替代 #

要是你需要把DTO以JSON格式放在请求里（而不是拆成单个表单参数），就得用@RequestPart注解，同时明确指定接口接受multipart/form-data：

import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.RequestPart;

@PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public ResponseEntity<String> upload(
        @RequestPart("files") MultipartFile[] files,
        @RequestPart("product") ProductDTO productDTO) {
    // 处理逻辑
    return ResponseEntity.ok("上传成功");
}

对应的Postman配置：

• 新增一个Key为product的参数，类型选Text；
• 在这个参数的右侧，把Content-Type设置为application/json；
• 然后在值的位置填入JSON格式的DTO内容。

4. 确认Spring的Multipart配置没问题 #

• 如果是Spring Boot项目：默认已经自带了Multipart支持，只需要在application.properties里调整上传限制即可（可选）：

  spring.servlet.multipart.max-file-size=10MB
  spring.servlet.multipart.max-request-size=15MB
  

• 如果是传统Spring MVC项目：要确保配置了multipartResolver bean：

  <bean id="multipartResolver" class="org.springframework.web.multipart.commons.CommonsMultipartResolver">
      <property name="maxUploadSize" value="10485760"/> <!-- 10MB -->
  </bean>
  

最后排查常见的坑 #

• 检查Controller方法上的@PostMapping有没有错误指定consumes属性（比如写成了application/json）；
• 确认请求里的文件数量没有超过Spring配置的最大上传文件数（默认是没有限制，但可以自己配置）；
• 别在同一个请求里既传form-data又传raw的JSON，这会让Spring无法识别正确的媒体类型。

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