SpringBoot @RestController中Pageable未按请求参数实例化问题咨询

核心原因 #

Spring Data 默认使用的分页参数名是 page（页码，从0开始）和 size（每页条数），而你请求中使用的是 pageNumber、pageSize，参数名不匹配导致框架无法正确绑定参数，只能加载默认值（page:0，size:21）。

解决方法 #

方法1：使用Spring Data默认参数名 #

直接修改请求参数，将 pageNumber 改为 page，pageSize 改为 size，示例请求：

.../api?page=3&size=100&userId=2d02a66e-d7b1-49b3-9fe2-5ec4ff3abffc

这种方式无需额外配置，直接适配Spring Data的默认规则。

方法2：自定义分页参数名（保留pageNumber/pageSize） #

如果需要保留自定义的参数名，通过配置类指定参数映射规则：

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
        PageableHandlerMethodArgumentResolver pageableResolver = new PageableHandlerMethodArgumentResolver();
        // 绑定自定义页码参数名
        pageableResolver.setPageParameterName("pageNumber");
        // 绑定自定义每页条数参数名
        pageableResolver.setSizeParameterName("pageSize");
        // 可选：若你的页码从1开始（如pageNumber=3代表第三页），开启此配置
        pageableResolver.setOneIndexedParameters(true);
        resolvers.add(pageableResolver);
    }
}

配置完成后，请求中的 pageNumber 和 pageSize 就能正确绑定到Pageable对象。

关于offset参数的说明 #

你请求中传入的 offset 参数，Spring Data默认的Pageable基于page+size分页模式，不直接支持offset。如果需要基于偏移量的分页，建议改用 OffsetPageRequest（Spring Data 2.0+支持），或手动处理offset和size参数，自行构建分页对象。

适配Swagger显示 #

如果使用Swagger，默认会显示Spring Data的默认参数名（page、size），需通过@ApiImplicitParams标注自定义参数，让Swagger展示正确的参数名：

@GetMapping("/api")
@ApiImplicitParams({
    @ApiImplicitParam(name = "pageNumber", value = "页码", defaultValue = "0", paramType = "query"),
    @ApiImplicitParam(name = "pageSize", value = "每页条数", defaultValue = "21", paramType = "query"),
    @ApiImplicitParam(name = "userId", value = "用户ID", required = true, paramType = "query")
})
public SomeDto getMyApi(@RequestParam UUID userId, Pageable pageable) {
    return testService.getMyApi(pageable, userId);
}

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