Spring Boot中multipart/form-data下@ModelAttribute为null的问题

我有一个处理文件上传的Spring Boot控制器方法，尝试使用@ModelAttribute注解绑定请求中的字段，控制器代码如下：

@PostMapping(value = "/{accountNo}/upload", consumes = "multipart/form-data")
public ResponseEntity<Object> uploadDocument(
        @PathVariable Long accountNo,
        @ModelAttribute RequestDTO requestDTO,
        @RequestParam("file") MultipartFile file,
        Authentication authentication) {
    // ...
}

RequestDTO类包含需要从请求体/表单数据绑定的字段，但遇到requestDTO对象始终为null的问题。由于部分属性值过长，无法通过请求参数传递DTO数据。已确认请求发送正确，包含RequestDTO所需字段，且@RequestBody无法与multipart/form-data配合使用，我使用Swagger以JSON格式发送数据：

{
    "accountNo": "211100001201",
    "kind": "hello",
    "name": "string",
    "url": "string",
    "location": "string",
    "storageStatus": "string",
    "actionType": "string",
    "value1": "string",
    "detail": "string"
}

请问我的配置是否存在遗漏？在此场景下使用@ModelAttribute有哪些常见陷阱？如何确保requestDTO对象能从请求中正确填充？

原因分析与解决方案 #

核心问题 #

@ModelAttribute的设计是从multipart请求的表单key-value参数中绑定数据，而非解析JSON格式的请求part。你通过Swagger发送的是独立的JSON块，Spring无法自动将其映射到@ModelAttribute标注的DTO上，这是导致对象为null的根本原因。

使用@ModelAttribute的常见陷阱 #

• 混淆绑定逻辑：@ModelAttribute仅处理表单字段（即multipart请求中每个key-value形式的part），不支持直接解析JSON格式的part。如果将整个DTO以JSON字符串或JSON体发送，Spring无法完成自动绑定。
• 忽略Multipart参数格式：multipart/form-data要求数据以多个独立part传递，每个part要么是文件，要么是key-value的表单项。直接发送JSON体不符合该格式，导致绑定失败。
• DTO结构不符合要求：如果RequestDTO没有无参构造函数、字段缺少getter/setter，或者字段名与请求参数名不匹配（比如驼峰与下划线差异），都会导致绑定失败。

解决方法 #

方法1：使用@RequestPart解析JSON part（推荐）

@RequestPart支持解析multipart/form-data中不同类型的part，包括JSON格式的DTO和文件，是处理这类场景的标准方案：

@PostMapping(value = "/{accountNo}/upload", consumes = "multipart/form-data")
public ResponseEntity<Object> uploadDocument(
        @PathVariable Long accountNo,
        @RequestPart("requestDTO") RequestDTO requestDTO,
        @RequestPart("file") MultipartFile file,
        Authentication authentication) {
    // 业务逻辑
}

• 发送请求时，在Swagger中将requestDTO作为类型为application/json的独立part发送，file作为文件part。
• 确保项目依赖中包含Jackson（Spring Boot Web Starter默认已集成），Spring会自动用Jackson解析JSON part为RequestDTO对象。

方法2：手动解析JSON字符串参数

如果无法使用@RequestPart，可以将DTO以JSON字符串形式作为表单参数传递，然后手动解析：

@PostMapping(value = "/{accountNo}/upload", consumes = "multipart/form-data")
public ResponseEntity<Object> uploadDocument(
        @PathVariable Long accountNo,
        @RequestParam("requestDTO") String dtoJson,
        @RequestParam("file") MultipartFile file,
        Authentication authentication) throws JsonProcessingException {
    ObjectMapper objectMapper = new ObjectMapper();
    RequestDTO requestDTO = objectMapper.readValue(dtoJson, RequestDTO.class);
    // 业务逻辑
}

• 发送请求时，在Swagger中添加名为requestDTO的参数，值为你的JSON字符串。

配置检查要点 #

• 确认RequestDTO类有无参构造函数，所有字段都配备对应的getter和setter（Spring数据绑定必须依赖这些）。
• 检查字段名是否与请求中的键名完全匹配（注意大小写，Spring默认不自动转换驼峰与下划线，如需支持可配置@ConfigurationProperties或自定义转换器）。
• 确保Spring Boot版本支持@RequestPart（Spring 3及以上版本均支持，无版本兼容问题）。

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