本文介绍如何在 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<YourModel> scanWithPagination(
int pageSize,
Map<String, Object> exclusiveStartKey) {
DynamoDBScanExpression scanExpression = new DynamoDBScanExpression()
.withLimit(pageSize)
.withExclusiveStartKey(exclusiveStartKey); // 可为 null（第一页）
PaginatedScanList<YourModel> result = mapper.scan(YourModel.class, scanExpression);
// 构建可序列化的分页响应
return new PaginatedResult<>(
result.stream().toList(),
result.getLastEvaluatedKey() // 下一页游标，null 表示已到底
);
}
}
// 响应包装类（建议 JSON 可序列化）
public record PaginatedResult<T>(
List<T> items,
Map<String, Object> nextToken
) {}? 关键说明：
- exclusiveStartKey 是上一页返回的 lastEvaluatedKey，类型为 Map<String, AttributeValue>（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 连续拉取等现代前端分页交互模式。
