DynamoDB作为AWS生态中使用最广泛的NoSQL数据库服务，几乎每天都会遇到限流、网络抖动、5xx临时错误等情况。为了提升调用的健壮性，AWS SDK内置了自动重试机制，而maxRetries就是控制这个机制最直接的参数。理解它的默认值、配置方式和对整体请求耗时的影响，是每一个DynamoDB使用者都应该掌握的基础技能。
maxRetries的工作原理与默认值
当SDK向DynamoDB发起请求时，如果返回的是可重试错误（比如ProvisionedThroughputExceededException、ThrottlingException、503 Service Unavailable，或者纯网络层面的超时），客户端并不会立刻把错误抛给业务代码，而是等待一段时间后重新发送请求。等待的间隔遵循指数退避算法，通常还带一点随机抖动，避免大量客户端在同一时刻集中重试造成雪崩。
以AWS SDK for JavaScript（v2）为例，maxRetries的默认值是4，也就是说一个请求最多会被发送5次（1次原始请求加4次重试）。Java SDK v1的默认值同样是4，而新一代的SDK（比如JS v3和Java v2）改用了自适应重试模式（adaptive retry mode），默认重试次数为2，但会根据错误类型动态调整。这就是为什么很多老项目迁移到新版SDK后，重试行为突然发生变化的原因。
需要注意的是，重试次数越多，单次调用的最坏耗时就越长。假设每次退避间隔依次为几百毫秒到数秒不等，配置一个过大的maxRetries可能导致请求阻塞很久，拖垮上游服务的响应时间。因此在设置之前，一定要先想清楚业务能容忍的最大延迟。
不同语言SDK中的配置方法
先看Node.js SDK v2的写法，最简单的方式是在构造客户端时传入maxRetries：
const AWS = require('aws-sdk');
const dynamodb = new AWS.DynamoDB({
region: 'us-east-1',
maxRetries: 5, // 重试5次，加上首次请求共6次
httpOptions: {
connectTimeout: 2000, // 连接超时，毫秒
timeout: 5000 // 请求超时，毫秒
}
});
const docClient = new AWS.DynamoDB.DocumentClient({
region: 'us-east-1',
maxRetries: 5
});对于JavaScript SDK v3，配置方式有所调整。新版SDK引入了中间件机制，重试策略通过retryStrategy或者包级别的配置来控制。也可以在创建客户端后通过config更新：
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { DynamoDBDocumentClient, PutCommand } from '@aws-sdk/lib-dynamodb';
const client = new DynamoDBClient({
region: 'us-east-1',
maxAttempts: 5 // v3中改名为maxAttempts，含首次请求
});
const docClient = DynamoDBDocumentClient.from(client);Java SDK v1则可以在代码或系统属性两个层面设置。代码方式直接调用withMaxErrorRetry：
import com.amazonaws.services.dynamodbv2.AmazonDynamoDB;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder;
import com.amazonaws.retry.PredefinedRetryPolicies;
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard()
.withRegion("us-east-1")
.withClientConfiguration(
new ClientConfiguration()
.withMaxErrorRetry(5)
.withRetryPolicy(PredefinedRetryPolicies.DYNAMODB_DEFAULT)
)
.build();也可以通过JVM系统属性-Dcom.amazonaws.sdk.defaultMaxRetries=5做全局设置，这种方式适合不方便改代码的场景，但要注意它会作用于所有AWS服务客户端，影响面较大，一般不推荐在生产环境随意使用。
重试次数设置的最佳实践与常见陷阱
重试并不是越多越好，设置时需要综合考虑三个因素：业务对延迟的容忍度、错误类型以及下游DynamoDB的容量配置。对于面向用户的在线请求，建议maxRetries保持在2到3之间，让失败快速暴露，由上层逻辑决定是否降级；对于后台批处理、数据同步等对延迟不敏感的任务，可以放大到8甚至10，充分利用SDK的退避机制等待限流窗口过去。
第二个常见的坑是幂等性问题。重试意味着同一条请求可能被服务端执行多次。对于PutItem这类操作，重复写入同样的数据通常无害；但UpdateItem如果执行的是ADD类型的原子自增，重试就会导致计数多加。解决办法是在更新表达式中使用条件判断，或者改用客户端生成的确定性请求标识，确保操作可安全重复执行。
第三个需要关注的点是：如果重试次数用尽依然失败，说明问题大概率不是偶发抖动，而是容量规划或热点分区问题。这时盲目调大maxRetries只会掩盖症状。正确的做法是结合CloudWatch中的ThrottledRequests、ConsumedReadCapacityUnits等指标定位瓶颈，必要时开启自适应容量（Adaptive Capacity）或调整表的主键设计打散热点。把重试机制当作最后一道防线，而不是解决性能问题的手段，才能让系统在高压下保持稳定。
DynamoDB maxRetries重试策略SDK配置修改时间：2026-09-10 20:58:43