Multipart Request Handling in Spring

Modern software architecture is often broken. Slow delivery leads to missed opportunities, innovation is stalled due to architectural complexities, and engineering resources are exceedingly expensive.

Orkes is the leading workflow orchestration platform built to enable teams to transform the way they develop, connect, and deploy applications, microservices, AI agents, and more.

With Orkes Conductor managed through Orkes Cloud, developers can focus on building mission critical applications without worrying about infrastructure maintenance to meet goals and, simply put, taking new products live faster and reducing total cost of ownership.

Try a 14-Day Free Trial of Orkes Conductor today.

Orkes is the leading workflow orchestration platform built to enable teams to transform the way they develop, connect, and deploy applications, microservices, AI agents, and more.

Try a 14-Day Free Trial of Orkes Conductor today.

Orkes is the leading workflow orchestration platform built to enable teams to transform the way they develop, connect, and deploy applications, microservices, AI agents, and more.

Try a 14-Day Free Trial of Orkes Conductor today.

Refactor Java code safely — and automatically — with OpenRewrite.

Refactoring big codebases by hand is slow, risky, and easy to put off. That’s where OpenRewrite comes in. The open-source framework for large-scale, automated code transformations helps teams modernize safely and consistently.

Each month, the creators and maintainers of OpenRewrite at Moderne run live, hands-on training sessions — one for newcomers and one for experienced users. You’ll see how recipes work, how to apply them across projects, and how to modernize code with confidence.

Join the next session, bring your questions, and learn how to automate the kind of work that usually eats your sprint time.

1. Introduction

In this tutorial, we’ll focus on various mechanisms for sending multipart requests in Spring Boot. Multipart requests consist of sending data of many different types separated by a boundary as part of a single HTTP method call.

Generally, we can send complicated JSON, XML, or CSV data, as well as transfer multipart file(s) in this request. Examples of multipart files include audio or image files. Furthermore, we can send simple key/value pair data with the multipart file(s) as a multipart request.

Now let’s look into the various ways we can send this data.

2. Using @ModelAttribute

Let’s consider a simple use case of sending an employee’s data consisting of a name and file using a form.

First, we’ll create an Employee abstraction to store the form data:

public class Employee { private String name; private MultipartFile document; }

Then we’ll generate the form using Thymeleaf:

<form action="#" th:action="@{/employee}" th:object="${employee}" method="post" enctype="multipart/form-data"> <p>name: <input type="text" th:field="*{name}" /></p> <p>document:<input type="file" th:field="*{document}" multiple="multiple"/> <input type="submit" value="upload" /> <input type="reset" value="Reset" /></p> </form>

The important thing to note is that we declare the enctype as multipart/form-data in the view.

Finally, we’ll create a method that accepts the form data, including the multipart file:

@PostMapping(path = "/employee", consumes = { MediaType.MULTIPART_FORM_DATA_VALUE }) public String saveEmployee(@ModelAttribute Employee employee) { employeeService.save(employee); return "employee/success"; }

Here, the two particularly important details are:

consumes attribute value is set to multipart/form-data
@ModelAttribute has captured all the form data into the Employee POJO, including the uploaded file

3. Using @RequestPart

This annotation associates a part of a multipart request with the method argument, which is useful for sending complex multi-attribute data as payload, e.g., JSON or XML.

Let’s create a method with two arguments, first of type Employee and second as MultipartFile. Furthermore, we’ll annotate both of these arguments with @RequestPart:

@PostMapping(path = "/requestpart/employee", consumes = { MediaType.MULTIPART_FORM_DATA_VALUE }) public ResponseEntity<Object> saveEmployee(@RequestPart Employee employee, @RequestPart MultipartFile document) { employee.setDocument(document); employeeService.save(employee); return ResponseEntity.ok().build(); }

Now, to see this annotation in action, we’ll create the test using MockMultipartFile:

@Test public void givenEmployeeJsonAndMultipartFile_whenPostWithRequestPart_thenReturnsOK() throws Exception { MockMultipartFile employeeJson = new MockMultipartFile("employee", null, "application/json", "{\"name\": \"Emp Name\"}".getBytes()); mockMvc.perform(multipart("/requestpart/employee") .file(A_FILE) .file(employeeJson)) .andExpect(status().isOk()); }

The important thing to note above is that we’ve set the content type of the Employee part as application/JSON. We’re also sending this data as a JSON file in addition to the multipart file.

Further details on how to test multipart requests can be found here.

4. Using @RequestParam

Another way of sending multipart data is to use @RequestParam. This is especially useful for simple data, which is sent as key/value pairs along with the file:

@RequestMapping(path = "/requestparam/employee", method = POST, consumes = { MediaType.MULTIPART_FORM_DATA_VALUE }) public ResponseEntity<Object> saveEmployee(@RequestParam String name, @RequestPart MultipartFile document) { Employee employee = new Employee(name, document); employeeService.save(employee); return ResponseEntity.ok().build(); }

Let’s write the test for this method to demonstrate:

@Test public void givenRequestPartAndRequestParam_whenPost_thenReturns200OK() throws Exception { mockMvc.perform(multipart("/requestparam/employee") .file(A_FILE) .param("name", "testname")) .andExpect(status().isOk()); }

5. Conclusion

In this article, we learned how to effectively handle multipart requests in Spring Boot.

Initially, we sent multipart form data using a model attribute. Then we looked at how to separately receive multipart data using the @RequestPart and @RequestParam annotations.

The code backing this article is available on GitHub. Once you're logged in as a Baeldung Pro Member, start learning and coding on the project.

Orkes is the leading workflow orchestration platform built to enable teams to transform the way they develop, connect, and deploy applications, microservices, AI agents, and more.

Try a 14-Day Free Trial of Orkes Conductor today.

Orkes is the leading workflow orchestration platform built to enable teams to transform the way they develop, connect, and deploy applications, microservices, AI agents, and more.

Try a 14-Day Free Trial of Orkes Conductor today.

Modern Java teams move fast — but codebases don’t always keep up. Frameworks change, dependencies drift, and tech debt builds until it starts to drag on delivery. OpenRewrite was built to fix that: an open-source refactoring engine that automates repetitive code changes while keeping developer intent intact.

The monthly training series, led by the creators and maintainers of OpenRewrite at Moderne, walks through real-world migrations and modernization patterns. Whether you’re new to recipes or ready to write your own, you’ll learn practical ways to refactor safely and at scale.

If you’ve ever wished refactoring felt as natural — and as fast — as writing code, this is a good place to start.