Spring Boot 2.5：无法将x-www-form-urlencoded表单数据转为自定义POJO

问题根源分析 #

你遇到的问题核心是对Spring处理x-www-form-urlencoded类型请求的机制理解有误：

• @RequestBody不适用于表单请求：@RequestBody默认解析JSON/XML格式的请求体，而x-www-form-urlencoded是表单编码的请求参数，不属于请求体范畴，因此使用它会直接抛出415错误。
• 顶层Map无法自动绑定嵌套参数：Spring不会把data[email]这类嵌套格式的参数自动映射到顶层Map<String,String>，因为这种语法是为绑定对象的嵌套属性设计的，并非普通键值对。
• POJO结构不匹配：你之前定义的private Map<String, Data> data结构错误，表单里的data[merges][FN]是指data对象下的merges属性（而非data这个Map的键为merges），Spring会误以为data[merges]对应的是Data对象，但Data不是集合类型，因此抛出绑定错误。

正确解决方案：匹配嵌套层级的POJO #

根据你的表单参数结构，定义层级对应的POJO，让Spring自动完成参数绑定：

1. 定义匹配的POJO类

class MyResponse {
    private String type;
    private Data data;

    // 必须提供Getter和Setter，Spring依赖这些完成属性绑定
    public String getType() { return type; }
    public void setType(String type) { this.type = type; }
    public Data getData() { return data; }
    public void setData(Data data) { this.data = data; }

    // 内部类对应data层级的参数
    static class Data {
        private String email;
        // merges用Map接收动态键值对，也可以定义自定义类（比如Merges）来接收
        private Map<String, String> merges;

        public String getEmail() { return email; }
        public void setEmail(String email) { this.email = email; }
        public Map<String, String> getMerges() { return merges; }
        public void setMerges(Map<String, String> merges) { this.merges = merges; }
    }
}

2. 编写正确的Controller方法

不需要加@RequestBody，直接用POJO作为方法参数（Spring默认用@ModelAttribute处理表单参数绑定）：

@RestController
@RequestMapping("/your-path")
public class FormController {

    @PostMapping(consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)
    public ResponseEntity<Void> handleForm(MyResponse response) {
        // 直接访问绑定后的参数
        String type = response.getType();
        String email = response.getData().getEmail();
        String fn = response.getData().getMerges().get("FN");
        
        // 业务逻辑处理...
        return ResponseEntity.ok().build();
    }
}

备选方案：用Map接收原始参数 #

如果不想定义POJO，可以用@RequestParam接收所有原始表单参数，再手动解析嵌套结构：

@PostMapping(consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)
public ResponseEntity<Void> handleForm(@RequestParam Map<String, String> allParams) {
    String type = allParams.get("type");
    String email = allParams.get("data[email]");
    String fn = allParams.get("data[merges][FN]");
    // 手动解析逻辑...
    return ResponseEntity.ok().build();
}

这种方式适合参数结构不固定的场景，但代码可读性和维护性不如POJO方案。

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