DynamoDBMapper 手动分页实现指南

碧海醫心 2026-01-09 00:00:00 次阅读

本文介绍如何在 quarkus 应用中使用 dynamodbmapper 对 dynamodb 查询结果进行手动分页，通过 `exclusivestartkey` 与 `limit` 控制翻页，返回带分页令牌的结果集。

在基于 DynamoDB 的 Java 应用（尤其是 Quarkus 环境）中，DynamoDBMapper 提供了简洁的对象映射能力，但其原生不支持开箱即用的“页码+页大小”式分页（如 page=2&size=10）。DynamoDB 本身采用键驱动分页（Key-based Pagination），因此必须借助 ExclusiveStartKey（即上一页的 LastEvaluatedKey）实现高效、一致的游标分页。

以下是一个典型的分页扫描（Scan）实现示例：

public class DynamoDBPaginationService {

    private final DynamoDBMapper mapper;

    public DynamoDBPaginationService(DynamoDBMapper mapper) {
        this.mapper = mapper;
    }

    public PaginatedResult scanWithPagination(
            int pageSize,
            Map exclusiveStartKey) {

        DynamoDBScanExpression scanExpression = new DynamoDBScanExpression()
                .withLimit(pageSize)
                .withExclusiveStartKey(exclusiveStartKey); // 可为 null（第一页）

        PaginatedScanList result = mapper.scan(YourModel.class, scanExpression);

        // 构建可序列化的分页响应
        return new PaginatedResult<>(
                result.stream().toList(),
                result.getLastEvaluatedKey() // 下一页游标，null 表示已到底
        );
    }
}

// 响应包装类（建议 JSON 可序列化）
public record PaginatedResult(
        List items,
        Map nextToken
) {}

? 关键说明：

exclusiveStartKey 是上一页返回的 lastEvaluatedKey，类型为 Map（DynamoDB 内部格式），通常需在 API 层 Base64 编码后透传给前端；
pageSize 建议设为合理值（如 10–100），避免单次扫描过大导致超时或吞吐耗尽；
scan() 适用于小表或低频分页场景；若存在查询条件（如 userId = ?），优先使用 query() 配合 DynamoDBQueryExpression，性能更优且天然支持分区键范围分页；
PaginatedScanList 是懒加载集合，调用 .stream().toList() 或 .size() 会触发实际请求，注意 N+1 问题；
在 Quarkus 中，确保 DynamoDBMapper 实例通过 @Singleton 正确注入，并复用底层 AmazonDynamoDB 客户端以保障线程安全与性能。

✅ 最佳实践建议：

将 nextToken 统一编码为 Base64 字符串（如 new ObjectMapper().writeValueAsString(key) → Base64.getEncoder().encodeToString(...)），避免前端处理原始 Map 结构；
对 null 的 nextToken 显式返回 "null" 或空字符串，避免客户端解析异常；
生产环境务必添加重试逻辑与错误熔断（如 DynamoDBRequestFailedException），并监控 ScannedCount 与 Count 差值，评估扫描效率。

通过该方式，你可在保持 DynamoDBMapper 开发简洁性的同时，完全掌控分页行为，适配 REST API、GraphQL 连续拉取等现代前端分页交互模式。