DynamoDB ExclusiveStartKey分页怎么用？深入理解LastEvaluatedKey机制与实现方法

DynamoDB的Scan和Query操作单次请求最多只能返回1MB的数据量，一旦结果集超过这个上限，响应中会携带一个LastEvaluatedKey字段，客户端需要把它作为下一次请求的ExclusiveStartKey传入，才能拿到剩余的数据。这套机制看起来简单，但实际使用中涉及的细节不少，比如为什么要用不透明的主键对象、分页和过滤表达式的交互、以及如何实现断点续传。本文将围绕ExclusiveStartKey分页展开完整讲解，并给出可直接运行的代码示例。

一、ExclusiveStartKey与LastEvaluatedKey的工作原理

DynamoDB在执行Scan或Query时，并不会一次性遍历所有匹配的数据。它在内部按物理存储顺序（Scan）或分区键顺序（Query）读取数据，累计到1MB就会停止，并把最后一条已读取项目的主键作为LastEvaluatedKey返回。这个值对客户端来说是不透明的，不需要理解其内部结构，只需要在下一次请求时原样放入ExclusiveStartKey参数即可，DynamoDB会从这条记录之后继续读取。

判断是否还有剩余数据的唯一标准是响应中LastEvaluatedKey是否存在。如果该字段为空或不存在，说明所有匹配项目都已返回；如果不为空，就必须发起下一次请求。要注意一个反直觉的现象：即使结果集不足1MB，LastEvaluatedKey有时也会返回，比如设置了Limit参数时，读取条数达到Limit就会停止并返回该字段，因此不能想当然地认为只有超过1MB才有后续数据。

另一个容易误解的地方是FilterExpression。过滤表达式是在服务端读取数据之后应用的，它不减少底层扫描量，也不影响LastEvaluatedKey的生成。也就是说，某一次请求可能因为过滤后返回的项目数为零，但LastEvaluatedKey仍然不为空，此时必须继续分页，否则会漏掉后面的数据。这与传统数据库的LIMIT加OFFSET思维完全不同。

二、用Java和Python实现完整分页循环

理解原理后，实现分页就是一个标准的循环结构：发起请求、处理结果、检查LastEvaluatedKey、把它塞进下一次请求的ExclusiveStartKey。下面是Java SDK V2的完整写法，循环中每一次迭代对应一次网络请求。

import software.amazon.awssdk.services.dynamodb.model.*;

Map<String, AttributeValue> lastKey = null;
List<Map<String, AttributeValue>> allItems = new ArrayList<>();

do {
    ScanRequest.Builder builder = ScanRequest.builder()
            .tableName("Orders")
            .filterExpression("status = :s")
            .expressionAttributeValues(Map.of(
                    ":s", AttributeValue.builder().s("PAID").build()));

    if (lastKey != null) {
        builder.exclusiveStartKey(lastKey);
    }

    ScanResponse response = client.scan(builder.build());
    allItems.addAll(response.items());
    lastKey = response.lastEvaluatedKey();
} while (lastKey != null && !lastKey.isEmpty());

System.out.println("总共读取: " + allItems.size() + " 条");

Python的boto3写法更简洁一些，使用get方法判断LastEvaluatedKey是否存在，逻辑完全一致。

import boto3

table = boto3.resource('dynamodb').Table('Orders')
all_items = []
last_key = None

while True:
    kwargs = {
        'FilterExpression': '#st = :s',
        'ExpressionAttributeNames': {'#st': 'status'},
        'ExpressionAttributeValues': {':s': 'PAID'}
    }
    if last_key:
        kwargs['ExclusiveStartKey'] = last_key

    resp = table.scan(**kwargs)
    all_items.extend(resp['Items'])
    last_key = resp.get('LastEvaluatedKey')
    if not last_key:
        break

print(f'总共读取: {len(all_items)} 条')

注意两个代码中都做了空值和空字典的双重判断，因为部分SDK在没有剩余数据时会返回空Map而不是null。此外，不要在循环外修改lastKey的内容，某些情况下SDK返回的Map是可变的，误改会导致分页位置错乱甚至读取失败。

三、复合主键与进阶用法

当表使用复合主键（分区键加排序键）时，LastEvaluatedKey会自动包含完整的键结构，客户端无需手动构造。但如果你想实现断点续传，比如把分页游标序列化后存起来供前端翻页使用，就需要注意序列化格式。AttributeValue对象在不同SDK中都有对应的转换工具，Java中可以用AttributeValuesToJson或手动提取s、n等类型字段，Python中直接json.dumps即可，因为boto3返回的已经是普通字典。

把游标传给前端时，还要考虑安全性。ExclusiveStartKey暴露了主键内容，如果主键本身是敏感信息（如用户邮箱），可以在服务端做加密或签名后再下发，翻页请求带回时再解密还原。同时游标应该设置过期时间，因为底层数据在分页过程中可能被修改或删除，过期的游标指向的项目不存在时，DynamoDB会自动跳过该位置继续向后读取，不会报错，这是断点续传可靠性的重要保障。

对于大数据量导出场景，串行分页吞吐量很低，可以利用并行Scan加速：把表按段分成多个Segment，每个worker只扫描自己负责的段，段内依然用ExclusiveStartKey做分页，TotalSegments和Segment参数配合使用即可。最后提醒一点，ExclusiveStartKey不支持随机跳页，只能顺序向后翻，如果业务需要跳转到指定页码，要么在应用层缓存已读数据，要么重新设计查询方式，比如用排序键的范围条件缩小结果集。

DynamoDB分页ExclusiveStartKeyLastEvaluatedKey修改时间：2026-09-01 06:22:35