SpringBoot 3.X.X升级后Cosmos DB分页功能异常求助

核心原因 #

Spring Boot 3.x适配的是Spring Data Azure Cosmos 4.x版本，该版本对自定义@Query结合Pageable的分页逻辑做了重大调整：

• 旧版本（Spring Boot 2.x + Spring Data Cosmos 3.x）会自动为自定义查询拼接OFFSET/LIMIT参数；
• 新版本为适配Cosmos DB的高效分页（基于continuation token），不再自动处理自定义查询的分页参数，导致你的Pageable配置完全失效，查询始终返回符合条件的前N条（或倒序的后N条）数据。

另外你的自定义查询语句存在语法错误：结尾多了一个冗余的)，需修正为select * from c where c.base=@baseId。

解决方案 #

方案1：手动在自定义查询中添加分页参数 #

在@Query中显式声明OFFSET和LIMIT，绑定Pageable的对应参数：

public interface BaseRepository extends CosmosRepository<Base, String>, CrudRepository<Base, String> {

    @Query("select * from c where c.base = @baseId OFFSET @offset LIMIT @pageSize")
    Page<Base> findByBaseId(
        @Param("baseId") String baseId,
        Pageable pageable);
}

注意：Cosmos DB的OFFSET从0开始计数，Spring的PageRequest默认page参数也从0开始，offset = page * size，框架会自动完成参数映射。

方案2：改用派生查询（推荐） #

放弃自定义@Query，使用Spring Data的派生查询语法，让框架自动生成符合Cosmos DB高效分页逻辑的查询：

public interface BaseRepository extends CosmosRepository<Base, String>, CrudRepository<Base, String> {

    Page<Base> findByBase(String baseId, Pageable pageable);
}

这种方式会自动使用Cosmos DB的continuation token进行分页，避免OFFSET带来的性能问题，同时完全兼容Pageable的配置。

额外检查点 #

1. 确认PageRequest的page参数是否从0开始：Spring的PageRequest.of(int page, int size, Sort sort)中page起始值为0，如果业务代码传入的是从1开始的页码，需要先减1再构造PageRequest。
2. 检查Sort配置：如果你的Sort是按时间或ID倒序，返回"最后3条"是符合排序逻辑的，但分页失效是因为参数未被应用，修正后即可按页码返回对应分片数据。

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