Spring Controller禁用URL参数绑定，仅从请求体获取参数

问题背景 #

你的Spring POST接口接收application/x-www-form-urlencoded格式请求，通过DTO自动绑定参数时，若URL查询参数与请求体表单参数同名，Spring会将两个值拼接成逗号分隔的字符串返回。但你希望仅从请求体获取参数，忽略URL中的同名参数，且@RequestBody注解无法直接用于该场景（会返回415错误）。

解决方案 #

方法一：手动读取请求体构建DTO #

直接在Controller方法中获取HttpServletRequest，读取请求体的表单数据，手动解析并构建DTO，完全跳过URL参数的绑定逻辑：

@PostMapping(path = "/test",
        consumes = {MediaType.APPLICATION_FORM_URLENCODED_VALUE},
        produces = {MediaType.APPLICATION_JSON_VALUE})
@ResponseStatus(HttpStatus.OK)
public TestDTO test(HttpServletRequest request) throws IOException {
    // 读取并解析请求体的表单数据
    String bodyContent = request.getReader().lines()
            .collect(Collectors.joining(System.lineSeparator()));
    Map<String, String> formParams = new HashMap<>();
    
    for (String paramPair : bodyContent.split("&")) {
        String[] keyValue = paramPair.split("=");
        if (keyValue.length == 2) {
            String key = URLDecoder.decode(keyValue[0], StandardCharsets.UTF_8);
            String value = URLDecoder.decode(keyValue[1], StandardCharsets.UTF_8);
            formParams.put(key, value);
        }
    }
    
    TestDTO testDTO = new TestDTO();
    testDTO.setSample(formParams.get("sample"));
    return testDTO;
}

方法二：自定义参数解析器（推荐） #

通过自定义HandlerMethodArgumentResolver，让Spring在绑定DTO时仅从请求体读取参数，保持Controller方法的简洁性：

1. 实现自定义参数解析器

public class FormBodyOnlyArgumentResolver implements HandlerMethodArgumentResolver {

    @Override
    public boolean supportsParameter(MethodParameter parameter) {
        // 指定该解析器处理TestDTO类型的参数
        return TestDTO.class.isAssignableFrom(parameter.getParameterType());
    }

    @Override
    public Object resolveArgument(MethodParameter parameter, ModelAndViewContainer mavContainer,
                                  NativeWebRequest webRequest, WebDataBinderFactory binderFactory) throws Exception {
        HttpServletRequest request = webRequest.getNativeRequest(HttpServletRequest.class);
        assert request != null;
        
        // 解析请求体的表单数据
        String body = request.getReader().lines().collect(Collectors.joining());
        Map<String, String> formParams = new HashMap<>();
        
        for (String pair : body.split("&")) {
            String[] keyValue = pair.split("=");
            if (keyValue.length == 2) {
                String key = URLDecoder.decode(keyValue[0], StandardCharsets.UTF_8);
                String value = URLDecoder.decode(keyValue[1], StandardCharsets.UTF_8);
                formParams.put(key, value);
            }
        }
        
        // 构建并返回DTO（字段多的话可以用BeanUtils/ModelMapper简化映射）
        TestDTO dto = new TestDTO();
        dto.setSample(formParams.get("sample"));
        return dto;
    }
}

2. 注册解析器到Spring配置

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
        resolvers.add(new FormBodyOnlyArgumentResolver());
    }
}

3. Controller方法保持原有写法

@PostMapping(path = "/test",
        consumes = {MediaType.APPLICATION_FORM_URLENCODED_VALUE},
        produces = {MediaType.APPLICATION_JSON_VALUE})
@ResponseStatus(HttpStatus.OK)
public TestDTO test(TestDTO testDTO){
    return testDTO;
}

原因说明 #

• Spring默认的表单参数绑定逻辑会合并URL查询参数和请求体表单参数，对于String类型的字段，同名参数的多个值会被逗号拼接。
• @RequestBody无法用于application/x-www-form-urlencoded格式：Spring默认的@RequestBody解析器（如MappingJackson2HttpMessageConverter）仅处理JSON/XML等格式，而application/x-www-form-urlencoded的解析由FormHttpMessageConverter负责，但该Converter不支持将表单数据绑定到DTO作为@RequestBody参数，因此会返回415错误。

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