Spring Boot Controller's method to process HTTP request bodies

Spring Boot (via Spring MVC) provides a powerful mechanism to handle HTTP request bodies of different Content-Types. This mainly relies on various implementations of the HttpMessageConverter interface, which can automatically convert the request body content into Java method parameters.

1. Core mechanism: HttpMessageConverter

Spring MVC will select an appropriate HttpMessageConverter to perform data conversion based on the type of Content-Type and Controller method parameters in the request header. Common converters include:

MappingJackson2HttpMessageConverter: Process application/json, bind JSON data to POJO.
FormHttpMessageConverter: Processing application/x-www-form-urlencoded, you can bind form data to POJO or MultiValueMap.
Jaxb2RootElementHttpMessageConverter: Process application/xml, bind XML data to POJO annotated with JAXB.
ByteArrayHttpMessageConverter: Processes the original byte stream, bound to byte[].
StringHttpMessageConverter: Process plain text and bind to String.
StandardServletMultipartResolver (with related converters): handles multipart/form-data, which is usually used for file uploads, binding the file part to MultipartFile.

2. Press Content-Type to process detailed explanation

1. application/json

Annotation: @RequestBody
Target type: POJO (Plain Old Java Object)
Example:

// POJO
// public class User {
//     private String username;
//     private String email;
//     // getters and setters
// }
@PostMapping("/users")
public User createUser(@RequestBody User user) {
    // The user object has been populated from JSON    return (user);
}

Description: The JSON string in the request body will be automatically mapped to the fields of the User object.

2. application/x-www-form-urlencoded

Method 1: Use @RequestParam to receive one by one
- Annotation: @RequestParam("paramName")
- Target type: Basic type (String, int, etc.)
- Example:

@PostMapping("/login")
public String login(@RequestParam String username, @RequestParam String password) {
    // username and password populate from form data    // ...
}

Method 2: Bind directly to POJO (no @RequestBody required)
- Target Type: POJO
- Description: The form field name must match the POJO attribute name.
- Example:

// POJO
// public class RegistrationForm {
//     private String username;
//     private String password;
//     // getters and setters
// }
@PostMapping("/register")
public String register(RegistrationForm form) {
    // form object has been filled from form data    // ...
}

3. multipart/form-data (commonly used for file upload)

Annotation: @RequestParam or @RequestPart
Target type: MultipartFile (for file), other form fields can be primitive types or POJO.
Configuration: Multipart processing may need to be enabled and configured in :

=true
-file-size=10MB
-request-size=10MB

Example:

@PostMapping("/upload/profile")
public String uploadProfile(@RequestParam("userId") Long userId,
                            @RequestParam("image") MultipartFile imageFile) throws IOException {
    // userId is a normal form field    // imageFile is the uploaded file    String fileName = ();
    // ... Save the file ...    return "File " + fileName + " uploaded for user " + userId;
}
// Use @RequestPart to handle complex multiparts (for example, one part is JSON)@PostMapping("/upload/advanced")
public String advancedUpload(@RequestPart("metadata") UserMetadata metadata, // UserMetadata is a POJO                             @RequestPart("document") MultipartFile document) {
    // metadata parses from a JSON part    // document is a file part    // ...
    return "Advanced upload successful.";
}

4. text/plain

Annotation: @RequestBody
Target type: String
Example:

@PostMapping("/logs")
public void submitLog(@RequestBody String logEntry) {
    // logEntry contains plain text in the request body    (logEntry);
}

5. application/xml

Annotation: @RequestBody
Target type: POJO annotated with JAXB (., @XmlRootElement)
Dependencies: Usually, jaxb-api and implementation (such as :jaxb-runtime) are required. Spring Boot's spring-boot-starter-web may not directly include the complete JAXB runtime by default, and can be added if needed.
Example:

// POJO (annotated with JAXB)// @XmlRootElement(name = "item")
// public class Item {
//     @XmlElement public String name;
//     @XmlElement public double price;
// }
@PostMapping(value = "/items", consumes = "application/xml", produces = "application/xml")
public Item createItem(@RequestBody Item item) {
    // The item object has been populated from XML    return (item);
}

6. application/octet-stream (or other binary data)

Annotation: @RequestBody
Target type: byte[]
Example:

@PostMapping(value = "/data", consumes = "application/octet-stream")
public String processBinaryData(@RequestBody byte[] data) {
    // data contains raw binary data    ("Received " +  + " bytes.");
    return "Binary data processed.";
}

Or use InputStream directly (usually without @RequestBody):

@PostMapping(value = "/data-stream", consumes = "application/octet-stream")
public String processDataStream(InputStream inputStream) throws IOException {
    // Manually read data from inputStream    // ...
    return "Stream processed.";
}

3. Error handling

If the requested Content-Type is not supported, or the request body is incorrect (such as invalid JSON), Spring Boot will usually return:

HTTP 415 Unsupported Media Type: If no HttpMessageConverter can handle the Content-Type.
HTTP 400 Bad Request: If the selected HttpMessageConverter cannot resolve the request body (for example, JSON syntax error).

4. Customization and extension

Developers can register a custom HttpMessageConverter to support non-standard or specific data formats by configuring WebMvcConfigurer.

// @Configuration
// public class WebConfig implements WebMvcConfigurer {
//     @Override
//     public void configureMessageConverters(List&lt;HttpMessageConverter&lt;?&gt;&gt; converters) {
//         (new MyCustomMessageConverter());
//     }
//
//     @Override
//     public void extendMessageConverters(List&lt;HttpMessageConverter&lt;?&gt;&gt; converters) {
// // Used to add converters without affecting the default registration// // Or adjust the order of registered converters//     }
// }

Understanding these mechanisms is essential for building robust and flexible Spring Boot APIs.

This is the end of this article about how Spring Boot Controller handles HTTP request bodies. For more information about Spring Boot Controller HTTP request bodies, please search for my previous articles or continue browsing the related articles below. I hope everyone will support me in the future!

Spring Boot Controller's method to process HTTP request bodies

1. Core mechanism: HttpMessageConverter​

2. Press Content-Type to process detailed explanation

1. application/json​

2. application/x-www-form-urlencoded​

3. multipart/form-data​ (commonly used for file upload)

4. text/plain​

5. application/xml​