Spring Boot Controller 如何处理HTTP请求体

Spring Boot (通过Spring MVC) 提供了强大的机制来处理不同 Content-Type​ 的HTTP请求体。这主要依赖于 HttpMessageConverter​ 接口的各种实现，它们能够自动将请求体内容转换成Java方法参数。

一、核心机制：HttpMessageConverter​

Spring MVC会根据请求头中的 Content-Type​ 和Controller方法参数的类型，选择一个合适的 HttpMessageConverter​ 来执行数据转换。常见的转换器包括：

• MappingJackson2HttpMessageConverter: 处理 application/json，将JSON数据绑定到POJO。
• FormHttpMessageConverter: 处理 application/x-www-form-urlencoded，可以将表单数据绑定到POJO或 MultiValueMap。
• Jaxb2RootElementHttpMessageConverter: 处理 application/xml，将XML数据绑定到用JAXB注解的POJO。
• ByteArrayHttpMessageConverter: 处理原始字节流，绑定到 byte[]。
• StringHttpMessageConverter: 处理纯文本，绑定到 String。
• StandardServletMultipartResolver (配合相关转换器): 处理 multipart/form-data，通常用于文件上传，将文件部分绑定到 MultipartFile。

二、按Content-Type​处理详解

1. application/json​

• 注解: @RequestBody​

• 目标类型: POJO (Plain Old Java Object)

• 示例:

  // POJO
  // public class User {
  //     private String username;
  //     private String email;
  //     // getters and setters
  // }
  
  @PostMapping("/users")
  public User createUser(@RequestBody User user) {
      // user 对象已从JSON填充
      return userService.save(user);
  }

• 说明: 请求体中的JSON字符串会被自动映射到 User​ 对象的字段。

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

• 方式一：使用 @RequestParam​ 逐个接收

  • 注解: @RequestParam("paramName")​

  • 目标类型: 基本类型 (String​, int​, etc.)

  • 示例:

    @PostMapping("/login")
    public String login(@RequestParam String username, @RequestParam String password) {
        // username 和 password 从表单数据填充
        // ...
    }

• 方式二：直接绑定到POJO (无需 @RequestBody​)

  • 目标类型: POJO

  • 说明: 表单字段名需与POJO属性名匹配。

  • 示例:

    // POJO
    // public class RegistrationForm {
    //     private String username;
    //     private String password;
    //     // getters and setters
    // }
    
    @PostMapping("/register")
    public String register(RegistrationForm form) {
        // form 对象已从表单数据填充
        // ...
    }

3. multipart/form-data​ (常用于文件上传)

• 注解: @RequestParam​ 或 @RequestPart​

• 目标类型: MultipartFile​ (用于文件), 其他表单字段可以是基本类型或POJO。

• 配置: 可能需要在 application.properties​ 中启用和配置multipart处理：

  spring.servlet.multipart.enabled=true
  spring.servlet.multipart.max-file-size=10MB
  spring.servlet.multipart.max-request-size=10MB

• 示例:

  @PostMapping("/upload/profile")
  public String uploadProfile(@RequestParam("userId") Long userId,
                              @RequestParam("image") MultipartFile imageFile) throws IOException {
      // userId 是普通表单字段
      // imageFile 是上传的文件
      String fileName = imageFile.getOriginalFilename();
      // ... 保存文件 ...
      return "File " + fileName + " uploaded for user " + userId;
  }
  
  // 使用 @RequestPart 处理复杂multipart (例如，一个部分是JSON)
  @PostMapping("/upload/advanced")
  public String advancedUpload(@RequestPart("metadata") UserMetadata metadata, // UserMetadata 是一个POJO
                               @RequestPart("document") MultipartFile document) {
      // metadata 从一个JSON part解析
      // document 是文件 part
      // ...
      return "Advanced upload successful.";
  }

4. text/plain​

• 注解: @RequestBody​

• 目标类型: String​

• 示例:

  @PostMapping("/logs")
  public void submitLog(@RequestBody String logEntry) {
      // logEntry 包含请求体中的纯文本
      System.out.println(logEntry);
  }

5. application/xml​

• 注解: @RequestBody​

• 目标类型: 用JAXB注解的POJO (e.g., @XmlRootElement​)

• 依赖: 通常需要 jaxb-api​ 和实现 (如 org.glassfish.jaxb:jaxb-runtime​)。Spring Boot的 spring-boot-starter-web​ 默认可能不直接包含完整的JAXB运行时，需要时可添加。

• 示例:

  // POJO (用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) {
      // item 对象已从XML填充
      return itemService.save(item);
  }

6. application/octet-stream​ (或其他二进制数据)

• 注解: @RequestBody​

• 目标类型: byte[]​

• 示例:

  @PostMapping(value = "/data", consumes = "application/octet-stream")
  public String processBinaryData(@RequestBody byte[] data) {
      // data 包含原始二进制数据
      System.out.println("Received " + data.length + " bytes.");
      return "Binary data processed.";
  }

• 或者直接使用 InputStream​ (通常不带 @RequestBody​):

  @PostMapping(value = "/data-stream", consumes = "application/octet-stream")
  public String processDataStream(InputStream inputStream) throws IOException {
      // 手动从 inputStream 读取数据
      // ...
      return "Stream processed.";
  }

三、错误处理

如果请求的 Content-Type​ 不被支持，或者请求体格式错误（如无效的JSON），Spring Boot 通常会返回:

• HTTP 415 Unsupported Media Type: 如果没有HttpMessageConverter能处理该 Content-Type。
• HTTP 400 Bad Request: 如果选择的HttpMessageConverter无法解析请求体 (例如，JSON语法错误)。

四、自定义与扩展

开发者可以注册自定义的 HttpMessageConverter​ 来支持非标准或特定的数据格式，通过配置 WebMvcConfigurer​。

// @Configuration
// public class WebConfig implements WebMvcConfigurer {
//     @Override
//     public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
//         converters.add(new MyCustomMessageConverter());
//     }
//
//     @Override
//     public void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
//         // 用来添加转换器，同时不影响默认注册的转换器
//         // 或者调整已注册转换器的顺序
//     }
// }

理解这些机制对于构建健壮和灵活的Spring Boot API至关重要。