本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

在中重试 适用于 Kotlin 的 AWS SDK

调用 AWS 服务 偶尔会返回意外异常。如果重试呼叫，某些类型的错误（例如限制或暂时错误）可能会成功。

本页介绍如何自动 适用于 Kotlin 的 AWS SDK 处理重试以及如何为您的应用程序自定义重试行为。

了解重试行为

以下各节说明了 SDK 如何确定何时重试请求以及哪些异常被视为可重试。

默认重试配置

默认情况下，每个服务客户端都会自动配置标准重试策略。默认配置最多会尝试失败三次的呼叫（初次尝试加上两次重试）。每次呼叫之间的中间延迟配置为指数退避和随机抖动，以避免重试风暴。此配置适用于大多数用例，但在某些情况下可能不适合，例如高吞吐量系统。

SDK 仅在出现可重试错误时才会尝试重试。可重试错误的示例包括套接字超时、服务端限制、并发或乐观锁定失败以及暂时性服务错误。参数缺失或无效、 authentication/security 错误和配置错误异常不被视为可重试。

您可以通过设置最大尝试次数、延迟和退避次数以及令牌桶配置来自定义标准重试策略。

哪些异常是可以重试的？

适用于 Kotlin 的 AWS SDK 使用预先配置的重试策略来确定哪些异常是可重试的。服务客户端配置具有一个retryPolicy属性，用于指定应用于重试的策略。如果未指定自定义值，则默认值为AwsRetryPolicy。

以下异常通过以下方式确定为可重试：AwsRetryPolicy

可通过错误代码重试

任何ServiceException具有以下值的sdkErrorMetadata.errorCode任意：

可通过 HTTP 状态码重试

任何ServiceException具有以下值的sdkErrorMetadata.statusCode任意：

可按错误类型重试

任何ServiceException具有以下值的sdkErrorMetadata.errorType任意：

可通过 SDK 元数据重试

任何SdkBaseException地方：

有关每个服务客户端可能抛出的异常的完整列表，请参阅特定于服务的 API 参考文档。

检查异常是否可以重试

要确定 SDK 是否认为异常可重试，请检查捕获到的异常的isRetryable属性：

try {
    dynamoDbClient.putItem {
        tableName = "MyTable"
        item = mapOf("id" to AttributeValue.S("123"))
    }
} catch (e: SdkBaseException) {
    println("Exception occurred: ${e.message}")
    
    if (e.sdkErrorMetadata.isRetryable) {
        println("This exception is retryable - SDK will automatically retry")
        println("If you're seeing this, retries may have been exhausted")
    } else {
        println("This exception is not retryable - fix the underlying issue")
        
        // Common non-retryable scenarios.
        when {
            e.message?.contains("ValidationException") == true -> 
                println("Check your request parameters")
            e.message?.contains("AccessDenied") == true -> 
                println("Check your IAM permissions")
            e.message?.contains("ResourceNotFound") == true -> 
                println("Verify the resource exists")
        }
    }
}

当重试失败时，你的代码会出现哪些异常

当 SDK 的重试机制无法解决问题时，您的应用程序代码就会抛出异常。了解这些异常类型有助于您实现适当的错误处理。这些不是触发重试的例外情况，而是由 SDK 内部处理的。

当重试用尽或禁用时，你的代码将捕获以下类型的异常：

使用以下模式来处理应用程序中的这些异常：

try {
    s3Client.getObject { 
        bucket = "amzn-s3-demo-bucket"
        key = "my-key" 
    }
} catch (e: AwsServiceException) {
    // Service-side errors that persisted through all retries.
    println("Service error after retries: ${e.errorDetails?.errorCode} - ${e.message}")
    
    // Handle specific service errors that couldn't be resolved.
    if (e.errorDetails?.errorCode == "ServiceQuotaExceededException" || 
        e.errorDetails?.errorCode == "ThrottlingException") {
        println("Rate limiting persisted - consider longer delays or quota increase")
    }
} catch (e: ClientException) {
    // Client-side errors (persistent network issues, DNS resolution failures, etc.)
    println("Client error after retries: ${e.message}")
}

自定义重试行为

以下各节介绍如何针对您的特定用例自定义 SDK 的重试行为。

配置最大尝试次数

在构造客户端期间，您可以自定义 retryStrategyDSL 区块中的默认最大尝试次数 (3)。

val dynamoDb = DynamoDbClient.fromEnvironment {
    retryStrategy {
        maxAttempts = 5
    }
}

上一个片段中显示了 DynamoDB 服务客户端，SDK 最多会尝试五次失败的 API 调用（初次尝试加上四次重试）。

您可以通过将最大尝试次数设置为一次来完全禁用自动重试，如以下代码段所示。

val dynamoDb = DynamoDbClient.fromEnvironment {
    retryStrategy {
        maxAttempts = 1  // The SDK makes no retries.
    }
}

配置延迟和退缩

如果需要重试，则默认的重试策略会等待，然后再进行后续尝试。第一次重试的延迟很小，但是以后的重试会呈指数级增长。最大延迟量是有上限的，这样它就不会变得太大。

最后，随机抖动会应用于所有尝试之间的延迟。抖动有助于减轻可能导致重试风暴的大型舰队的影响。（有关指数回退和抖动的更深入讨论，请参阅这篇AWS 架构博客文章。）

延迟参数可在 delayProviderDSL 模块中进行配置。

val dynamoDb = DynamoDbClient.fromEnvironment {
    retryStrategy {
        delayProvider {
            initialDelay = 100.milliseconds
            maxBackoff = 5.seconds
        }
    }
}

使用上一个片段所示的配置，客户端将第一次重试尝试最多延迟 100 毫秒。任何重试尝试之间的最大间隔为 5 秒。

以下参数可用于调整延迟和退缩。

配置重试令牌存储桶

您可以通过调整默认令牌桶配置来进一步修改标准重试策略的行为。重试令牌存储桶有助于减少不太可能成功或可能需要更多时间才能解决的重试，例如超时和限制失败。

每次重试尝试（可选包括初次尝试）都会减少令牌桶中的一些容量。减少的金额取决于尝试的类型。例如，重试瞬态错误可能很便宜，但重试超时或限制错误可能会更昂贵。

成功尝试将容量返回到存储桶。存储桶的增量不得超过其最大容量，也不得减至零以下。

根据useCircuitBreakerMode设置的值，尝试将容量减少到零以下会导致以下结果之一：

令牌桶参数可在 tokenBucketDSL 区块中配置：

val dynamoDb = DynamoDbClient.fromEnvironment {
    retryStrategy {
        tokenBucket {
            maxCapacity = 100
            refillUnitsPerSecond = 2
        }
    }
}

以下参数可用于调整重试令牌存储桶：

有关在重试场景中引发的异常类型（包括断路器异常）的详细信息，请参阅当重试失败时，你的代码会出现哪些异常。

配置自适应重试

作为标准重试策略的替代方案，自适应重试策略是一种高级方法，它寻求理想的请求速率以最大限度地减少限制错误。

自适应重试包括标准重试的所有功能。它添加了一个客户端速率限制器，用于衡量受限制请求与非限制请求的比率。它还会限制流量以尝试保持在安全带宽内，理想情况下会导致节流错误为零。

该速率会实时适应不断变化的服务条件和交通模式，并可能相应地增加或降低流量速率。至关重要的是，在高流量场景中，速率限制器可能会延迟初始尝试。

您可以通过为retryStrategy方法提供附加参数来选择自适应重试策略。速率限制器参数可在 rateLimiterDSL 模块中进行配置。

val dynamoDb = DynamoDbClient.fromEnvironment {
    retryStrategy(AdaptiveRetryStrategy) {
        maxAttempts = 10
        rateLimiter {
            minFillRate = 1.0
            smoothing = 0.75
        }
    }
}