Spring多部分表单上传：QueryForm参数类型转换失败问题

问题原因 #

Spring默认没有内置转换器，无法直接将multipart/form-data表单中传递的JSON字符串转换为自定义的QueryForm对象，因此抛出MethodArgumentConversionNotSupportedException异常。

解决方案 #

方案一：使用@RequestPart接收JSON格式参数 #

@RequestPart支持在多部分表单中接收不同Content-Type的参数，适合处理JSON格式的对象参数。

修改Controller代码

@RestController
@RequestMapping("/api/files")
@Slf4j
public class FileUploadController {

  @PostMapping("/upload")
  public String handleFileUpload(
    @RequestPart("query") QueryForm form,
    @RequestPart("file") MultipartFile file)
  throws IOException {
    log.info(form.toString());
    log.info(file.getOriginalFilename());
    log.info(file.getResource().getFilename());

    log.info(form.getQuery());

    return "upload";
  }

}

对应的HTTP请求命令

使用httpie指定query参数的Content-Type为application/json：

http POST localhost:8080/api/files/upload multipart/form-data file@1mb.txt query='{"query":"example","page":1}' query:Content-Type=application/json

方案二：自定义String到QueryForm的转换器 #

通过实现Spring的Converter接口，手动实现JSON字符串到QueryForm对象的转换逻辑，让Spring自动识别并使用该转换器。

编写转换器类

@Component
public class StringToQueryFormConverter implements Converter<String, QueryForm> {
    private final ObjectMapper objectMapper;

    // 注入Spring默认的ObjectMapper
    public StringToQueryFormConverter(ObjectMapper objectMapper) {
        this.objectMapper = objectMapper;
    }

    @Override
    public QueryForm convert(String source) {
        try {
            // 将JSON字符串反序列化为QueryForm对象
            return objectMapper.readValue(source, QueryForm.class);
        } catch (JsonProcessingException e) {
            throw new IllegalArgumentException("Query参数格式错误，需为合法JSON", e);
        }
    }
}

使用说明

• Spring Boot会自动扫描并注册该Converter到ConversionService中，无需额外配置。
• 原Controller代码无需修改，只需确保请求传递的query是标准JSON字符串（如query='{"query":"example","page":1}'），Spring会自动完成转换。

方案三：拆分表单参数（适用于简单对象场景） #

如果不需要传递JSON字符串，可将QueryForm的每个字段作为单独的表单参数传递，使用@ModelAttribute自动绑定。

修改Controller代码

@RestController
@RequestMapping("/api/files")
@Slf4j
public class FileUploadController {

  @PostMapping("/upload")
  public String handleFileUpload(
    @ModelAttribute QueryForm form,
    @RequestParam("file") MultipartFile file)
  throws IOException {
    log.info(form.toString());
    log.info(file.getOriginalFilename());
    log.info(file.getResource().getFilename());

    log.info(form.getQuery());

    return "upload";
  }

}

对应的HTTP请求命令

http -f POST localhost:8080/api/files/upload file@1mb.txt query=example page=1 pageSize=10

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