Spring Boot 3.x及以上版本隐式@RequestParam失效问题咨询

测试@RestController时，编写了两个处理HTTP GET请求的方法：一个显式通过@RequestParam注解绑定查询参数与方法参数（requestParamV3），另一个未添加注解，期望Spring自动通过参数名完成映射（requestParamV4）。测试结果显示只有前者能正常响应，后者返回Whitelabel Error Page，想问是不是Spring Boot 3.x不再支持这种无注解的参数映射场景？

相关代码 #

控制器代码 #

@ResponseBody
@RequestMapping("/request-param-v3")
public String requestParamV3(
        @RequestParam("username") String username,
        @RequestParam("age") int age) {

    log.info("username={}, age={}", username, age);
    return "ok";
}

@ResponseBody
@RequestMapping("/request-param-v4")
public String requestParamV4(String username, int age) {
    log.info("username={}, age={}", username, age);
    return "ok";
}

build.gradle配置 #

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.2.1'
    id 'io.spring.dependency-management' version '1.1.4'
}

group = 'hello'
version = '0.0.1-SNAPSHOT'

java {
    sourceCompatibility = '17'
}

configurations {
    compileOnly {
        extendsFrom annotationProcessor
    }
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

tasks.named('test') {
    useJUnitPlatform()
}

解答 #

并非Spring Boot 3.x不支持该场景，核心原因是Java编译默认不会保留方法参数名，导致Spring无法通过反射获取参数名来自动匹配查询参数。

Java 8及后续版本支持通过-parameters编译参数保留方法参数名，但默认编译时该选项是关闭的。部分旧版本Spring Boot可能依赖的编译插件默认开启了该参数，因此能正常工作；但Spring Boot 3.x搭配Java 17时，默认编译配置未开启此选项，所以无注解的参数映射失效。

解决方式有两种：

• 推荐方式：显式添加@RequestParam注解，这不仅能解决映射问题，还能提升代码可读性，明确参数的绑定关系。
• 开启编译参数保留参数名：修改build.gradle的java编译配置，添加-parameters参数：

  java {
      sourceCompatibility = '17'
      targetCompatibility = '17'
      options.compilerArgs.add('-parameters')
  }
  

  配置后编译器会保留方法参数名，Spring就能自动完成参数与查询参数的映射。

额外注意：即使开启了参数名保留，若方法参数是基本类型（如int age），当请求未传递该参数时仍会报错（因为基本类型不能为null）。这种情况下可以将参数改为包装类型（如Integer age），或者为参数设置默认值（如int age = 0）。

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