在中配置 HTTP 客户端 AWS SDK for Java 2.x

您可以使用 AWS SDK for Java 2.x更改用于服务客户端的 HTTP 客户端，也可以更改 HTTP 客户端的默认配置。本部分讨论 SDK 的 HTTP 客户端和设置。

SDK for Java 中可用的 HTTP 客户端

同步客户端

Java 开发工具包中的同步 HTTP 客户端实现了该SdkHttpClient接口。同步服务客户端（例如 S3Client 或 DynamoDbClient）需要使用同步 HTTP 客户端。 适用于 Java 的 AWS SDK 提供了三个同步 HTTP 客户端。

Apache5HttpClient （默认）

Apache5HttpClient是基于 Apache 5.x HttpClient 构建的更新版本。ApacheHttpClient版本 5.x 是 Apache 积极维护的版本，它对之前使用的版本进行了改进，带来了现代 Java 生态系统的兼容性，包括对 Java 21 的虚拟线程支持，并通过 SLF4J 增强了日志记录灵活性。ApacheHttpClientApache5HttpClient在 Java AWS 开发工具包 2.x 版本2.46.0中被替换ApacheHttpClient为默认同步客户端。它具有相同的 API 和功能，非常适合作为即插即用替代品。有关配置 Apache5HttpClient 的信息，请参阅配置基于 Apache 5.x 的 HTTP 客户端。

ApacheHttpClient

注意

ApacheHttpClient已过时，因为 Apache HttpClient 4.x 处于维护模式。使用基于 Apache HttpClient 5.x 的Apache5HttpClient。

ApacheHttpClient基于 Apache 4.x HttpClient 构建。有关配置 ApacheHttpClient 的信息，请参阅配置 Apache-based HTTP 客户端。

AwsCrtHttpClient

AwsCrtHttpClient提供高吞吐量和非阻塞 IO。它建立在 AWS 通用运行时 (CRT) Http 客户端之上。有关配置 AwsCrtHttpClient 并将其用于服务客户端的信息，请参阅配置 AWS 基于 CRT 的 HTTP 客户。

UrlConnectionHttpClient

为了最大限度地减少应用程序使用的 jar 和第三方库的数量，可以使用。 UrlConnectionHttpClient 有关配置 UrlConnectionHttpClient 的信息，请参阅配置 URLConnection基于的 HTTP 客户端。

异步客户端

Java 开发工具包中的异步 HTTP 客户端实现了该SdkAsyncHttpClient接口。异步服务客户端（例如 S3AsyncClient 或 DynamoDbAsyncClient）需要使用异步 HTTP 客户端。 适用于 Java 的 AWS SDK 提供了两个异步 HTTP 客户端。

NettyNioAsyncHttpClient （默认）

NettyNioAsyncHttpClient是异步客户端使用的默认 HTTP 客户端。有关配置 NettyNioAsyncHttpClient 的信息，请参阅配置基于 Netty 的 HTTP 客户端。

AwsCrtAsyncHttpClient

基于 AWS 通用运行时 (CRT) HTTP 客户端。 AwsCrtAsyncHttpClient 有关配置 AwsCrtAsyncHttpClient 的信息，请参阅配置 AWS 基于 CRT 的 HTTP 客户。

HTTP 客户端建议

选择 HTTP 客户端实现时，应考虑几个因素。以下信息可帮助您做出决定。

HTTP 客户端比较

下表提供了各 HTTP 客户端的详细信息。

HTTP 客户端	同步还是异步	何时使用	Limitation/drawback
基于Apache 5.x的HTTP客户端 （默认同步 HTTP 客户端）	同步	如果您更需要低延迟而不是高吞吐量，请使用它	与其他 HTTP 客户端相比，启动较慢
URLConnection-based HTTP 客户端	同步	如果您对限制第三方依赖项有硬性要求，请使用它	• 不支持某些 API 所要求的 HTTP 补丁方法，例如亚马逊 ApiGateway 更新操作 • 不支持可配置的空闲连接超时。有关详细信息，请参阅配置 URLConnection-based HTTP 客户端。
AWS CRT-based 同步 HTTP 客户端 1	同步	• 如果您的应用程序正在运行，请使用它 AWS Lambda • 如果您更需要高吞吐量而不是低延迟，请使用它 • 如果您更喜欢同步 SDK 客户端，请使用它	不支持以下 Java 系统属性： javax.net.ssl.keyStore javax.net.ssl.key StorePassword javax.net.ssl.trustStore javax.net.ssl.trust StorePassword
Netty-based HTTP 客户端 （默认异步 HTTP 客户端）	异步	• 如果您的应用程序依赖于 Java 系统属性进行 TLS 配置（例如javax.net.ssl.keyStore），请使用它	与其他 HTTP 客户端相比，启动较慢
AWS CRT-based 异步 HTTP 客户端 1	异步	• 如果您的应用程序在 AWS Lambda中运行，请使用它 • 如果您更需要高吞吐量而不是低延迟，请使用它 • 如果您更喜欢异步 SDK 客户端，请使用它	不支持以下 Java 系统属性： javax.net.ssl.keyStore javax.net.ssl.key StorePassword javax.net.ssl.trustStore javax.net.ssl.trust StorePassword

¹ 由于它们具有额外的好处，我们建议您尽可能使用 AWS CRT-based HTTP 客户端。

智能配置默认值

AWS SDK for Java 2.x （版本 2.17.102 或更高版本）提供智能配置默认功能。此功能优化了 HTTP 客户端的两个属性以及不影响 HTTP 客户端的其他属性。

智能配置默认值会根据您提供的默认模式值，为 connectTimeoutInMillis 和 tlsNegotiationTimeoutInMillis 属性设置合理的值。您可以根据应用程序的特性选择默认模式值。

有关智能配置默认值以及如何选择最适合应用程序的默认模式值的更多信息，请参阅 AWS SDKs and Tools Reference Guide。

以下是为应用程序设置默认模式的四种方法。

Service client

使用服务客户端生成器直接在服务客户端上配置默认模式。以下示例将 DynamoDbClient 的默认模式设置为 auto。

DynamoDbClient ddbClient = DynamoDbClient.builder()
                            .defaultsMode(DefaultsMode.AUTO)
                            .build();

System property

您可以使用 aws.defaultsMode 系统属性来指定默认模式。如果在 Java 中设置系统属性，则需要在初始化任何服务客户端之前设置该属性。

以下示例演示了如何使用在 Java 中设置的系统属性将默认模式设置为 auto。

System.setProperty("aws.defaultsMode", "auto");

以下示例演示了如何使用 java 命令的 -D 选项将默认模式设置为 auto。

java -Daws.defaultsMode=auto

Environment variable

为环境变量 AWS_DEFAULTS_MODE 设置一个值以选择应用程序的默认模式。

以下信息显示了使用环境变量将默认模式的值设置为 auto 时，所运行的命令。

操作系统	设置环境变量的命令
Linux、macOS 或 Unix	export AWS_DEFAULTS_MODE=auto
Windows	set AWS_DEFAULTS_MODE=auto

AWS config file

您可以向共享 AWS config文件添加defaults_mode配置属性，如以下示例所示。

[default]
defaults_mode = auto

如果您使用系统属性、环境变量或 AWS 配置文件在全局范围内设置了默认模式，则在生成 HTTP 客户端时可以覆盖这些设置。

使用 httpClientBuilder() 方法生成 HTTP 客户端时，设置仅适用于您正在生成的实例。此处显示了此方法一个示例。本示例中的 Netty-based HTTP 客户端会覆盖为connectTimeoutInMillis和tlsNegotiationTimeoutInMillis全局设置的任何默认模式值。