Handling Mixed JSON and File Uploads in Spring Boot with @RequestPart

Environment: Spring 2.7.18

1. Introduction

In web development, request parameter handling is a core feature. Spring Boot provides a flexible and powerful binding mechanism that can automatically map HTTP request parameters—such as query parameters, path variables, form data, and JSON—to controller method arguments. It supports simple types, complex objects, and collections via annotations like @RequestParam , @PathVariable , and @RequestBody , and also offers validation, custom argument resolvers, and other advanced capabilities.

When the request body is JSON (Content-Type: application/json), the controller simply uses @RequestBody to convert the JSON payload into a Java object.

2. Practical Example

2.1 Basic Operation

Interface Definition

<code>@PostMapping("/requestpart")
public Object requestpart(
    @RequestPart("user") User user,
    @RequestPart("file") MultipartFile file
) throws Exception {
    // TODO
    file.transferTo(new File("f://m.png"));
    return user;
}
</code>

Each parameter is obtained from a specific part of the multipart request using @RequestPart . After defining the backend, the frontend must construct the request accordingly.

Frontend Request Handling

<code>let form = new FormData();
// File attachment
form.append('file', document.querySelector('#file').files[0]);
let data = {age: 5000, name: '中国🇨🇳'};
// Use Blob to create a JSON part with explicit content type
let user = new Blob([JSON.stringify(data)], {type: 'application/json'});
form.append('user', user);
axios({
  method: 'post',
  url: 'http://localhost:8080/api/request/requestpart',
  // Header can also be multipart/mixed
  headers: {'Content-Type': 'multipart/form-data'},
  data: form
});
</code>

Resulting request payload shows each part with its own Content-Type.

2.2 More Request Types

You can add additional parts such as XML:

<code>public Object requestpart(
    @RequestPart("user") User user,
    @RequestPart("xml") String xml,
    @RequestPart("file") MultipartFile file
);
</code>

Frontend creates a Blob with the XML content and specifies its type:

<code>let form = new FormData();
let xml = new Blob(['<message><title>@RequestPart请求参数处理</title></message>'], {type: 'application/xml'});
form.append('xml', xml);
</code>

2.3 Parameter Validation

Just like @RequestBody , @RequestPart can be combined with validation annotations:

<code>@PostMapping("/requestpart")
public Object requestpart(
    @Validated @RequestPart("user") User user,
    BindingResult result,
    @RequestPart(name = "xml", required = false) String xml,
    @RequestPart("file") MultipartFile file
) throws Exception {
    // TODO
    if (result.hasErrors()) {
        return result.toString();
    }
    return user;
}

// User entity
public static class User {
    private Integer age;
    @NotEmpty
    private String name;
    // Getters, Setters
}
</code>

Frontend receives the validation result; ensure the error object is handled to avoid uncaught exceptions.

Note: Place the error object correctly in the request; otherwise the backend may throw an exception unless a global exception handler is configured.