Spring Boot如何处理PHP风格嵌套结构的x-www-form-urlencoded POST请求？

问题场景 #

有如下格式的POST请求（Content-Type为application/x-www-form-urlencoded）：

curl --location --request POST 'http://example.com/some/path' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'prop1=prop1Value' \
--data-urlencode 'prop2[prop2Inner1]=prop2Inner1Value' \
--data-urlencode 'prop2[prop2Inner2][inner3]=inner3Value' \
--data-urlencode 'prop2[prop2Inner2][inner4]=inner4Value'

在PHP中该请求会被自动解析为嵌套关联数组：

[
    'prop1' => 'prop1Value',
    'prop2' => [
        'prop2Inner1' => 'prop2Inner1Value',
        'prop2Inner2' => [
            'inner3' => 'inner3Value',
            'inner4' => 'inner4Value',
        ]
    ]
]

尝试在Spring Boot中通过多层DTO+@ModelAttribute接收该请求时出现绑定错误：

尝试的DTO定义 #

@NoArgsConstructor
@AllArgsConstructor
@Setter
@Getter
class MyRequest {
    private String prop1;
    private FirstInnerDto prop2;
}

@NoArgsConstructor
@AllArgsConstructor
@Setter
@Getter
class FirstInnerDto {
    private String prop2Inner1;
    private SecondInnerDto prop2Inner2;
}

@NoArgsConstructor
@AllArgsConstructor
@Setter
@Getter
class SecondInnerDto {
    private String inner3;
    private String inner4;
}

控制器代码 #

@RequestMapping("/some/path")
public ResponseEntity<SomeResponseDto> myHandler(@ModelAttribute MyRequest request) {
    // 业务逻辑处理
    return ResponseEntity.status(HttpStatus.OK).body(new SomeResponseDto());
}

错误信息 #

"Invalid property 'prop2[prop2Inner1]' of 
bean class [com.testapp.java.myapp.Model.Dto.Request.MyRequest]: 
Property referenced in indexed property path 'prop2[prop2Inner1]' is neither an array 
nor a List nor a Map; 
returned value was [FirstInnerDto{prop2Inner1='null', prop2Inner2='null'}]"

错误原因 #

Spring MVC默认会将prop2[prop2Inner1]这种格式的参数解析为集合/数组的索引访问，认为prop2是数组、List或Map类型，但我们定义的prop2是自定义DTO对象，因此触发绑定错误。

解决方案 #

方案1：手动接收参数并映射到DTO #

适合参数数量较少的场景，直接通过@RequestParam接收每个参数，手动组装成目标DTO：

@RequestMapping("/some/path")
public ResponseEntity<SomeResponseDto> myHandler(
        @RequestParam String prop1,
        @RequestParam("prop2[prop2Inner1]") String prop2Inner1,
        @RequestParam("prop2[prop2Inner2][inner3]") String inner3,
        @RequestParam("prop2[prop2Inner2][inner4]") String inner4
) {
    // 组装多层DTO
    SecondInnerDto secondInner = new SecondInnerDto(inner3, inner4);
    FirstInnerDto firstInner = new FirstInnerDto(prop2Inner1, secondInner);
    MyRequest request = new MyRequest(prop1, firstInner);
    
    // 业务逻辑处理
    return ResponseEntity.ok(new SomeResponseDto());
}

方案2：用Map接收所有参数再转换为DTO #

适合参数较多的场景，通过@RequestParam Map<String, String>接收全部参数，先转换为嵌套Map结构，再自动映射到目标DTO：

import com.fasterxml.jackson.databind.ObjectMapper;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.util.HashMap;
import java.util.Map;

@RestController
public class MyController {
    private final ObjectMapper objectMapper = new ObjectMapper();

    @RequestMapping("/some/path")
    public ResponseEntity<SomeResponseDto> myHandler(@RequestParam Map<String, String> allParams) {
        // 将扁平参数转换为嵌套Map（模拟PHP的解析结果）
        Map<String, Object> nestedMap = convertToNestedMap(allParams);
        // 嵌套Map转换为目标DTO
        MyRequest request = objectMapper.convertValue(nestedMap, MyRequest.class);
        
        // 业务逻辑处理
        return ResponseEntity.ok(new SomeResponseDto());
    }

    // 工具方法：扁平Map转嵌套Map
    private Map<String, Object> convertToNestedMap(Map<String, String> flatParams) {
        Map<String, Object> nestedMap = new HashMap<>();
        for (Map.Entry<String, String> entry : flatParams.entrySet()) {
            String key = entry.getKey();
            String value = entry.getValue();
            String[] keys = key.split("\\[|\\]");
            Map<String, Object> currentMap = nestedMap;
            for (int i = 0; i < keys.length; i++) {
                String part = keys[i].trim();
                if (part.isEmpty()) continue;
                if (i == keys.length - 1) {
                    currentMap.put(part, value);
                } else {
                    currentMap = (Map<String, Object>) currentMap.computeIfAbsent(part, k -> new HashMap<>());
                }
            }
        }
        return nestedMap;
    }
}

方案3：修改DTO结构为Map接收 #

快速验证场景可采用此方案，将DTO中的嵌套对象改为Map类型，让Spring自动绑定参数后再转换为业务DTO：

@NoArgsConstructor
@AllArgsConstructor
@Setter
@Getter
class TempRequest {
    private String prop1;
    private Map<String, Object> prop2;
}

@RequestMapping("/some/path")
public ResponseEntity<SomeResponseDto> myHandler(@ModelAttribute TempRequest tempRequest) {
    ObjectMapper mapper = new ObjectMapper();
    // 将临时DTO转换为业务DTO
    MyRequest request = mapper.convertValue(tempRequest, MyRequest.class);
    
    // 业务逻辑处理
    return ResponseEntity.ok(new SomeResponseDto());
}

总结 #

• 参数数量少优先用方案1，实现简单直接；
• 参数多或需要通用处理优先用方案2，扩展性强；
• 快速验证场景用方案3，开发成本低。

核心思路是绕开Spring MVC对[]格式参数的默认集合解析逻辑，转为手动处理或嵌套Map转换。

内容的提问来源于stack exchange，提问作者Александр Родригес