本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 在中配置 HTTP 客户端 AWS SDK for Java 2.x
您可以使用 AWS SDK for Java 2.x更改用于服务客户端的 HTTP 客户端，也可以更改 HTTP 客户端的默认配置。本部分讨论 SDK 的 HTTP 客户端和设置。
## SDK for Java 中可用的 HTTP 客户端
### 同步客户端
适用于 Java 的 SDK 中的同步 HTTP 客户端实现了该[SdkHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/SdkHttpClient.html)接口。同步服务客户端（例如 `S3Client` 或 `DynamoDbClient`）需要使用同步 HTTP 客户端。 适用于 Java 的 AWS SDK 提供了三个同步 HTTP 客户端。
**ApacheHttpClient （默认）**
[ApacheHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.html)是同步服务客户端的默认 HTTP 客户端。有关配置 `ApacheHttpClient` 的信息，请参阅[配置基于 Apache 的 HTTP 客户端](http-configuration-apache.md)。
**AwsCrtHttpClient**
[AwsCrtHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtHttpClient.html)提供高吞吐量和无阻塞 IO。它建立在 AWS 通用运行时 (CRT) Http 客户端之上。有关配置 `AwsCrtHttpClient` 并将其用于服务客户端的信息，请参阅[配置 AWS 基于 CRT 的 HTTP 客户](http-configuration-crt.md)。
**UrlConnectionHttpClient**
要最大限度地减少应用程序使用的 jar 和第三方库的数量，可以使用。[UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html)有关配置 `UrlConnectionHttpClient` 的信息，请参阅[配置 URLConnection基于的 HTTP 客户端](http-configuration-url.md)。
**Apache5 HttpClient**
[Apache5 HttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache5/Apache5HttpClient.html) *是在 Apache 5.x 上构建`ApacheHttpClient`的更新版本。 HttpClient版本 5.x* 是 Apache 积极维护的版本，`ApacheHttpClient`通过引入现代 Java 生态系统兼容性（包括对 Java 21 的虚拟线程支持）以及通过 SLF4 J 增强的日志灵活性，对之前的版本进行了改进，`Apache5HttpClient`将在未来版本的 Java AWS SDK 2.x 中取代`ApacheHttpClient`默认同步客户端。它具有相同的 API 和功能，非常适合作为即用型替代品。有关配置 `Apache5HttpClient` 的信息，请参阅[配置基于 Apache 5.x 的 HTTP 客户端](http-configuration-apache5.md)。
### 异步客户端
适用于 Java 的 SDK 中的异步 HTTP 客户端实现了该[SdkAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/async/SdkAsyncHttpClient.html)接口。异步服务客户端（例如 `S3AsyncClient` 或 `DynamoDbAsyncClient`）需要使用异步 HTTP 客户端。 适用于 Java 的 AWS SDK 提供了两个异步 HTTP 客户端。
**NettyNioAsyncHttpClient （默认）**
[NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html)是异步客户端使用的默认 HTTP 客户端。有关配置 `NettyNioAsyncHttpClient` 的信息，请参阅[配置基于 Netty 的 HTTP 客户端](http-configuration-netty.md)。
**AwsCrtAsyncHttpClient**
基于 AWS 通用运行时 (CRT) HTTP 客户端。[AwsCrtAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.html)有关配置 `AwsCrtAsyncHttpClient` 的信息，请参阅[配置 AWS 基于 CRT 的 HTTP 客户](http-configuration-crt.md)。
## HTTP 客户端建议
选择 HTTP 客户端实现时，应考虑几个因素。以下信息可帮助您做出决定。
### 建议流程图
以下流程图提供了一般指导，有助于确定使用哪个 HTTP 客户端。
![\[HTTP 客户端建议流程图。\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/images/JavaDevGuide-HTTPflowchart-DI.png)
### HTTP 客户端比较
下表提供了各 HTTP 客户端的详细信息。
| HTTP 客户端 | 同步还是异步 | 何时使用 | 限制/缺点 |
| --- | --- | --- | --- |
| 基于 Apache 的 HTTP 客户端 *（默认同步 HTTP 客户端）* | 同步 | 如果您更需要低延迟而不是高吞吐量，请使用它 | 与其他 HTTP 客户端相比，启动较慢 |
| 基于 URLConnection 的 HTTP 客户端 | 同步 | 如果您对限制第三方依赖项有硬性要求，请使用它 | 不支持某些 API 所要求的 HTTP 补丁方法，例如亚马逊 APIGateway 更新操作 |
| AWS 基于 CRT 同步的 HTTP 客户端 1 | 同步 | • 如果您的应用程序正在中运行，请使用它 AWS Lambda • 如果您更需要高吞吐量而不是低延迟，请使用它 • 如果您更喜欢同步 SDK 客户端，请使用它 | 不支持以下 Java 系统属性： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/http-configuration.html) |
| 基于 Netty 的 HTTP 客户端 *（默认异步 HTTP 客户端）* | 异步 | • 如果您的应用程序调用需要 HTTP/2 支持（例如 Kinesis API） APIs ，请使用它 [SubscribeToShard](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_SubscribeToShard.html) | 与其他 HTTP 客户端相比，启动较慢 |
| AWS 基于 CRT 的异步 HTTP 客户端 1 | 异步 | • 如果您的应用程序在 AWS Lambda中运行，请使用它• 如果您更需要高吞吐量而不是低延迟，请使用它• 如果您更喜欢异步 SDK 客户端，请使用它 | • 不支持需要 HTTP/2 支持的服务客户端，例如 `KinesisAsynClient` 和 `TranscribeStreamingAsyncClient` 不支持以下 Java 系统属性： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/http-configuration.html) |
1 由于基于 CRT 的 HTTP 客户端，我们建议您尽可能使用 AWS 基于 CRT 的 HTTP 客户端。
## 智能配置默认值
AWS SDK for Java 2.x （版本 2.17.102 或更高版本）提供智能配置默认功能。此功能优化了 HTTP 客户端的两个属性以及不影响 HTTP 客户端的其他属性。
智能配置默认值会根据您提供的默认模式值，为 `connectTimeoutInMillis` 和 `tlsNegotiationTimeoutInMillis` 属性设置合理的值。您可以根据应用程序的特性选择默认模式值。
有关智能配置默认值以及如何选择最适合您的应用程序的默认模式值的更多信息，请参阅[AWS SDKs 和工具参考指南](https://docs.aws.amazon.com/sdkref/latest/guide/feature-smart-config-defaults.html)。
以下是为应用程序设置默认模式的四种方法。
------
#### [ 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\$1DEFAULTS\$1MODE=auto |
| Windows | set AWS\$1DEFAULTS\$1MODE=auto |
------
#### [ AWS config file ]
您可以向共享 AWS `config`文件添加`defaults_mode`配置属性，如下例所示。
```
[default]
defaults_mode = auto
```
------
如果您使用系统属性、环境变量或 AWS 配置文件在全局范围内设置了默认模式，则在生成 HTTP 客户端时可以覆盖这些设置。
使用 `httpClientBuilder()` 方法生成 HTTP 客户端时，设置仅适用于您正在生成的实例。[此处](http-configuration-netty.md#http-config-netty-one-client)显示了此方法一个示例。本示例中基于 Netty 的 HTTP 客户端会覆盖在全局范围内为 `connectTimeoutInMillis` 和 `tlsNegotiationTimeoutInMillis` 设置的任何默认模式值。
# 配置基于 Apache 的 HTTP 客户端
默认情况下，中的同步服务客户端 AWS SDK for Java 2.x 使用基于 Apache 的 HTTP 客户端。[ApacheHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.html)该软件开发工具包基`ApacheHttpClient`于 Apache [HttpClient](https://hc.apache.org/httpcomponents-client-4.5.x/index.html)。
SDK 还提供 [UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html)，加载速度更快，但功能较少。有关配置 `UrlConnectionHttpClient` 的信息，请参阅[配置 URLConnection基于的 HTTP 客户端](http-configuration-url.md)。
要查看可供您使用的全套配置选项，请参阅 [ApacheHttpClient.Builder 和 [ProxyConfiguration.](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ProxyConfiguration.Builder.html) Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.Builder.html)。`ApacheHttpClient`
## 访问 `ApacheHttpClient`
在大多数情况下，您无需进行任何显式配置即可使用 `ApacheHttpClient`。您只需声明您的服务客户端，SDK 将使用标准值为您配置 `ApacheHttpClient`。
如果要显式配置 `ApacheHttpClient` 或将其用于多个服务客户端，则需要将其设置为可供配置。
### 无需配置
当您在 Maven 中声明对服务客户端的依赖项时，SDK 会添加对 `apache-client` 构件的*运行时系统*依赖项。这使得 `ApacheHttpClient` 类在运行时可供您的代码使用，但在编译时不可用。如果您没有配置基于 Apache 的 HTTP 客户端，则无需为其指定依赖项。
在以下 Maven `pom.xml` 文件的 XML 片段中，使用 `s3` 声明的依赖项会自动引入基于 Apache 的 HTTP 客户端。您无需专门为其声明依赖项。
```
software.amazon.awssdk
bom
2.27.21
pom
import
software.amazon.awssdk
s3
```
有了这些依赖项，您无法进行任何显式 HTTP 配置更改，因为 `ApacheHttpClient` 库仅位于运行时系统类路径上。
### 需要配置
要配置 `ApacheHttpClient`，您需要在*编译* 时添加对 `apache-client` 库的依赖项。
请参阅以下 Maven `pom.xml` 文件示例来配置 `ApacheHttpClient`。
```
software.amazon.awssdk
bom
2.27.21
pom
import
software.amazon.awssdk
s3
software.amazon.awssdk
apache-client
```
## 使用和配置 `ApacheHttpClient`
您可以在生成服务客户端的同时配置一个 `ApacheHttpClient` 实例，也可以将单个实例配置为在多个服务客户端之间共享。
无论采用哪种方法，都可以使用 `[ApacheHttpClient.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.Builder.html)` 来配置基于 Apache 的 HTTP 客户端的属性。
### 最佳实践：将一个 `ApacheHttpClient` 实例专用于一个服务客户端
如果您需要配置 `ApacheHttpClient` 实例，建议您生成专用 `ApacheHttpClient` 实例。您可以通过使用服务客户端生成器的 `httpClientBuilder` 方法来执行此操作。这样，HTTP 客户端的生命周期就由 SDK 管理，这有助于避免在不再需要 `ApacheHttpClient` 实例却不关闭实例时可能发生的内存泄漏。
以下示例创建了一个 `S3Client` 并配置了具有 `maxConnections` 和 `connectionTimeout` 值的 `ApacheHttpClient` 嵌入式实例。HTTP 实例是使用 `S3Client.Builder` 的 `httpClientBuilder` 方法创建的。
**导入**
```
import software.amazon.awssdk.http.apache.ApacheHttpClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.time.Duration;
```
**代码**
```
S3Client s3Client = S3Client // Singleton: Use the s3Client for all requests.
.builder()
.httpClientBuilder(ApacheHttpClient.builder()
.maxConnections(100)
.connectionTimeout(Duration.ofSeconds(5))
).build();
// Perform work with the s3Client.
s3Client.close(); // Requests completed: Close all service clients.
```
### 替代方法：共享 `ApacheHttpClient` 实例
为了帮助降低应用程序的资源和内存使用量，您可以配置 `ApacheHttpClient` 并在多个服务客户端之间共享该客户端。将共享 HTTP 连接池，从而降低资源使用量。
**注意**
共享 `ApacheHttpClient` 实例时，必须在准备好弃置实例时将其关闭。服务客户端关闭后，SDK 不会关闭实例。
以下示例配置了一个基于 Apache 的 HTTP 客户端，该客户端由两个服务客户端使用。配置的 `ApacheHttpClient` 实例将传递给每个生成器的 `httpClient` 方法。当不再需要服务客户端和 HTTP 客户端时，代码会显式关闭它们。代码最后关闭 HTTP 客户端。
**导入**
```
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.apache.ApacheHttpClient;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.s3.S3Client;
```
**代码**
```
SdkHttpClient apacheHttpClient = ApacheHttpClient.builder()
.maxConnections(100).build();
// Singletons: Use the s3Client and dynamoDbClient for all requests.
S3Client s3Client =
S3Client.builder()
.httpClient(apacheHttpClient).build();
DynamoDbClient dynamoDbClient =
DynamoDbClient.builder()
.httpClient(apacheHttpClient).build();
// Perform work with the s3Client and dynamoDbClient.
// Requests completed: Close all service clients.
s3Client.close();
dynamoDbClient.close();
apacheHttpClient.close(); // Explicitly close apacheHttpClient.
```
## 代理配置示例
以下代码段使用了[适用于 Apache HTTP 客户端的代理配置生成器](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ProxyConfiguration.Builder.html)。
```
SdkHttpClient apacheHttpClient = ApacheHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.endpoint(URI.create("http://example.com:1234"))
.username("username")
.password("password")
.addNonProxyHost("localhost")
.addNonProxyHost("host.example.com")
.build())
.build();
```
以下命令行片段显示了代理配置的等效 Java 系统属性。
```
$ java -Dhttp.proxyHost=example.com -Dhttp.proxyPort=1234 -Dhttp.proxyUser=username \
-Dhttp.proxyPassword=password -Dhttp.nonProxyHosts=localhost|host.example.com -cp ... App
```
使用环境变量的等效设置为：
```
// Set the following environment variables.
// $ export HTTP_PROXY="http://username:password@example.com:1234"
// $ export NO_PROXY="localhost|host.example.com"
// Set the 'useSystemPropertyValues' to false on the proxy configuration.
SdkHttpClient apacheHttpClient = ApacheHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.useSystemPropertyValues(Boolean.FALSE)
.build())
.build();
// Run the application.
// $ java -cp ... App
```
**注意**
Apache HTTP 客户端目前不支持 HTTPS 代理系统属性或 HTTPS\$1PROXY 环境变量。
# 配置 URLConnection基于的 HTTP 客户端
与默认客户端相比， AWS SDK for Java 2.x 它提供了更轻量`[UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html)`的 HTTP 客户端。`ApacheHttpClient``UrlConnectionHttpClient` 基于 Java 的 `[URLConnection](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/net/URLConnection.html)`。
`UrlConnectionHttpClient` 的加载速度比基于 Apache 的 HTTP 客户端快，但功能较少。由于加载速度更快，因此该客户端是 Java AWS Lambda 函数的[良好解决方案](lambda-optimize-starttime.md)。
`UrlConnectionHttpClient` 提供了几个[可配置的选项](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.Builder.html)供您使用。
**注意**
`UrlConnectionHttpClient` 不支持 HTTP PATCH 方法。
少数 AWS API 操作需要补丁请求。这些操作的名称通常以 `Update*` 开头。以下是几个示例。
AWS Security Hub CSPM API 中的@@ [几个`Update*`操作](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_Operations.html)以及[BatchUpdateFindings](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_BatchUpdateFindings.html)操作
所有 Amazon API Gateway API 的 [`Update*` 操作](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAccount.html)
如果你可能使用`UrlConnectionHttpClient`，请先参阅你正在使用 AWS 服务 的 API 参考。了解您需要的操作是否使用 PATCH 操作。
## 访问 `UrlConnectionHttpClient`
要配置和使用 `UrlConnectionHttpClient`，请在 `pom.xml` 文件中声明对 `url-connection-client` Maven 构件的依赖项。
与 `ApacheHttpClient` 不同的是，`UrlConnectionHttpClient` 不会自动添加到您的项目中，因此，要使用该客户端必须对其进行特别声明。
以下 `pom.xml` 文件示例显示了使用和配置 HTTP 客户端所需的依赖项。
```
software.amazon.awssdk
bom
2.27.21
pom
import
software.amazon.awssdk
url-connection-client
```
## 使用和配置 `UrlConnectionHttpClient`
您可以在生成服务客户端的同时配置一个 `UrlConnectionHttpClient` 实例，也可以将单个实例配置为在多个服务客户端之间共享。
无论采用哪种方法，您都可以使用 [UrlConnectionHttpClient.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.Builder.html) 来配置 URLConnection基于的 HTTP 客户端的属性。
### 最佳实践：将一个 `UrlConnectionHttpClient` 实例专用于一个服务客户端
如果您需要配置 `UrlConnectionHttpClient` 实例，建议您生成专用 `UrlConnectionHttpClient` 实例。您可以通过使用服务客户端生成器的 `httpClientBuilder` 方法来执行此操作。这样，HTTP 客户端的生命周期就由 SDK 管理，这有助于避免在不再需要 `UrlConnectionHttpClient` 实例却不关闭实例时可能发生的内存泄漏。
以下示例创建了一个 `S3Client` 并配置了具有 `socketTimeout` 和 `proxyConfiguration` 值的 `UrlConnectionHttpClient` 嵌入式实例。`proxyConfiguration` 方法采用类型为 ` Consumer<[ProxyConfiguration.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/ProxyConfiguration.Builder.html)>` 的 Java lambda 表达式。
**导入**
```
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
import java.net.URI;
import java.time.Duration;
```
**代码**
```
// Singleton: Use the s3Client for all requests.
S3Client s3Client =
S3Client.builder()
.httpClientBuilder(UrlConnectionHttpClient.builder()
.socketTimeout(Duration.ofMinutes(5))
.proxyConfiguration(proxy -> proxy.endpoint(URI.create("http://proxy.mydomain.net:8888"))))
.credentialsProvider(EnvironmentVariableCredentialsProvider.create())
.build();
// Perform work with the s3Client.
s3Client.close(); // Requests completed: Close the s3client.
```
### 替代方法：共享 `UrlConnectionHttpClient` 实例
为了帮助降低应用程序的资源和内存使用量，您可以配置 `UrlConnectionHttpClient` 并在多个服务客户端之间共享该客户端。将共享 HTTP 连接池，从而降低资源使用量。
**注意**
共享 `UrlConnectionHttpClient` 实例时，必须在准备好弃置实例时将其关闭。服务客户端关闭后，SDK 不会关闭实例。
以下示例配置了由两个服务客户端使用的 URLConnection基于 HTTP 客户端。配置的 `UrlConnectionHttpClient` 实例将传递给每个生成器的 `httpClient` 方法。当不再需要服务客户端和 HTTP 客户端时，代码会显式关闭它们。代码最后关闭 HTTP 客户端。
**导入**
```
import software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider;
import software.amazon.awssdk.awscore.defaultsmode.DefaultsMode;
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.urlconnection.ProxyConfiguration;
import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.net.URI;
import java.time.Duration;
```
**代码**
```
SdkHttpClient urlHttpClient = UrlConnectionHttpClient.create();
// Singletons: Use the s3Client and dynamoDbClient for all requests.
S3Client s3Client =
S3Client.builder()
.httpClient(urlHttpClient)
.defaultsMode(DefaultsMode.IN_REGION)
.credentialsProvider(EnvironmentVariableCredentialsProvider.create())
.build();
DynamoDbClient dynamoDbClient =
DynamoDbClient.builder()
.httpClient(urlHttpClient)
.defaultsMode(DefaultsMode.IN_REGION)
.credentialsProvider(EnvironmentVariableCredentialsProvider.create())
.build();
// Perform work with the s3Client and dynamoDbClient.
// Requests completed: Close all service clients.
s3Client.close();
dynamoDbClient.close();
urlHttpClient.close();
```
#### 将 `URLConnectionHttpClient` 和 `ApacheHttpClient` 一起使用
在应用程序中使用 `UrlConnectionHttpClient` 时，您必须使用服务客户端生成器的 `httpClientBuilder` 方法为每个服务客户端提供一个 `URLConnectionHttpClient` 实例或一个 `ApacheHttpClient` 实例。
如果程序使用多个服务客户端，并且同时存在以下两个条件，则会发生异常：
+ 一个服务客户端配置为使用一个 `UrlConnectionHttpClient` 实例
+ 另一个服务客户端使用默认 `ApacheHttpClient`，但没有使用 `httpClient()` 或 `httpClientBuilder()` 方法显式生成
该异常将声明在类路径中找到了多个 HTTP 实现。
以下示例代码片段会导致异常。
```
// The dynamoDbClient uses the UrlConnectionHttpClient
DynamoDbClient dynamoDbClient = DynamoDbClient.builder()
.httpClient(UrlConnectionHttpClient.create())
.build();
// The s3Client below uses the ApacheHttpClient at runtime, without specifying it.
// An SdkClientException is thrown with the message that multiple HTTP implementations were found on the classpath.
S3Client s3Client = S3Client.create();
// Perform work with the s3Client and dynamoDbClient.
dynamoDbClient.close();
s3Client.close();
```
通过显式使用 `ApacheHttpClient` 来配置 `S3Client`，可避免异常。
```
DynamoDbClient dynamoDbClient = DynamoDbClient.builder()
.httpClient(UrlConnectionHttpClient.create())
.build();
S3Client s3Client = S3Client.builder()
.httpClient(ApacheHttpClient.create()) // Explicitly build the ApacheHttpClient.
.build();
// Perform work with the s3Client and dynamoDbClient.
dynamoDbClient.close();
s3Client.close();
```
**注意**
要显式创建 `ApacheHttpClient`，必须在 Maven 项目文件中[添加对 `apache-client` 构件的依赖项](http-configuration-apache.md#http-apache-dependency)。
## 代理配置示例
以下代码片段将[代理配置生成器用于 URL 连接 HTTP 客户端](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/ProxyConfiguration.Builder.html)。
```
SdkHttpClient urlHttpClient = UrlConnectionHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.endpoint(URI.create("http://example.com:1234"))
.username("username")
.password("password")
.addNonProxyHost("localhost")
.addNonProxyHost("host.example.com")
.build())
.build();
```
以下命令行片段显示了代理配置的等效 Java 系统属性。
```
$ java -Dhttp.proxyHost=example.com -Dhttp.proxyPort=1234 -Dhttp.proxyUser=username \
-Dhttp.proxyPassword=password -Dhttp.nonProxyHosts=localhost|host.example.com -cp ... App
```
使用环境变量的等效设置为：
```
// Set the following environment variables.
// $ export HTTP_PROXY="http://username:password@example.com:1234"
// $ export NO_PROXY="localhost|host.example.com"
// Set the 'useSystemPropertyValues' to false on the proxy configuration.
SdkHttpClient apacheHttpClient = UrlConnectionHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.useSystemPropertyValues(Boolean.FALSE)
.build())
.build();
// Run the application.
// $ java -cp ... App
```
**注意**
URLConnection基于的 HTTP 客户端当前不支持 HTTPS 代理系统属性或 HTTPS\$1PROXY 环境变量。
# 配置基于 Netty 的 HTTP 客户端
中用于异步操作的默认 HTTP 客户端 AWS SDK for Java 2.x 是基于 Netty 的。[NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html)基于 Netty 的客户端以 [Netty 项目](https://netty.io/)的异步事件驱动网络框架为基础。
作为备选 HTTP 客户端，您可以使用新的[基于AWS CRT 的 HTTP 客户端](http-configuration-crt.md)。本主题演示如何配置 `NettyNioAsyncHttpClient`。
## 访问 `NettyNioAsyncHttpClient`
在大多数情况下，您无需在异步程序中进行任何显式配置即可使用 `NettyNioAsyncHttpClient`。您只需声明您的异步客户端，SDK 将使用标准值为您配置 `NettyNioAsyncHttpClient`。
如果要显式配置 `NettyNioAsyncHttpClient` 或将其用于多个服务客户端，则需要将其设置为可供配置。
### 无需配置
当您在 Maven 中声明对服务客户端的依赖项时，SDK 会添加对 `netty-nio-client` 构件的*运行时系统*依赖项。这使得 `NettyNioAsyncHttpClient` 类在运行时可供您的代码使用，但在编译时不可用。如果您没有配置基于 Netty 的 HTTP 客户端，则无需为其指定依赖项。
在以下 Maven `pom.xml` 文件的 XML 片段中，使用 `dynamodb-enhanced` 声明的依赖项会以传递的方式引入基于 Netty 的 HTTP 客户端。您无需专门为其声明依赖项。
```
software.amazon.awssdk
bom
2.27.21
pom
import
software.amazon.awssdk
dynamodb-enhanced
```
有了这些依赖项，您无法进行任何 HTTP 配置更改，因为 `NettyNioAsyncHttpClient` 库仅位于运行时系统类路径上。
### 需要配置
要配置 `NettyNioAsyncHttpClient`，您需要在*编译* 时添加对 `netty-nio-client` 构件的依赖项。
请参阅以下 Maven `pom.xml` 文件示例来配置 `NettyNioAsyncHttpClient`。
```
software.amazon.awssdk
bom
2.27.21
pom
import
software.amazon.awssdk
dynamodb-enhanced
software.amazon.awssdk
netty-nio-client
```
## 使用和配置 `NettyNioAsyncHttpClient`
您可以在生成服务客户端的同时配置一个 `NettyNioAsyncHttpClient` 实例，也可以将单个实例配置为在多个服务客户端之间共享。
无论采用哪种方法，您都可以使用 [NettyNioAsyncHttpClient.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.Builder.html) 来配置基于 Netty 的 HTTP 客户端实例的属性。
### 最佳实践：将一个 `NettyNioAsyncHttpClient` 实例专用于一个服务客户端
如果您需要配置 `NettyNioAsyncHttpClient` 实例，建议您生成专用 `NettyNioAsyncHttpClient` 实例。您可以通过使用服务客户端生成器的 `httpClientBuilder` 方法来执行此操作。这样，HTTP 客户端的生命周期就由 SDK 管理，这有助于避免在不再需要 `NettyNioAsyncHttpClient` 实例却不关闭实例时可能发生的内存泄漏。
以下示例创建了一个 `DynamoDbAsyncClient` 实例，该实例供 `DynamoDbEnhancedAsyncClient` 实例使用。该 `DynamoDbAsyncClient` 实例包含具有 `connectionTimeout` 和 `maxConcurrency` 值的 `NettyNioAsyncHttpClient` 实例。HTTP 实例是使用 `DynamoDbAsyncClient.Builder` 的 `httpClientBuilder` 方法创建的。
**导入**
```
import software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider;
import software.amazon.awssdk.awscore.defaultsmode.DefaultsMode;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedAsyncClient;
import software.amazon.awssdk.enhanced.dynamodb.extensions.AutoGeneratedTimestampRecordExtension;
import software.amazon.awssdk.http.nio.netty.NettyNioAsyncHttpClient;
import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;
import java.time.Duration;
```
**代码**
```
// DynamoDbAsyncClient is the lower-level client used by the enhanced client.
DynamoDbAsyncClient dynamoDbAsyncClient =
DynamoDbAsyncClient
.builder()
.httpClientBuilder(NettyNioAsyncHttpClient.builder()
.connectionTimeout(Duration.ofMillis(5_000))
.maxConcurrency(100)
.tlsNegotiationTimeout(Duration.ofMillis(3_500)))
.defaultsMode(DefaultsMode.IN_REGION)
.credentialsProvider(EnvironmentVariableCredentialsProvider.create())
.build();
// Singleton: Use dynamoDbAsyncClient and enhancedClient for all requests.
DynamoDbEnhancedAsyncClient enhancedClient =
DynamoDbEnhancedAsyncClient
.builder()
.dynamoDbClient(dynamoDbAsyncClient)
.extensions(AutoGeneratedTimestampRecordExtension.create())
.build();
// Perform work with the dynamoDbAsyncClient and enhancedClient.
// Requests completed: Close dynamoDbAsyncClient.
dynamoDbAsyncClient.close();
```
### 替代方法：共享 `NettyNioAsyncHttpClient` 实例
为了帮助降低应用程序的资源和内存使用量，您可以配置 `NettyNioAsyncHttpClient` 并在多个服务客户端之间共享该客户端。将共享 HTTP 连接池，从而降低资源使用量。
**注意**
共享 `NettyNioAsyncHttpClient` 实例时，必须在准备好弃置实例时将其关闭。服务客户端关闭后，SDK 不会关闭实例。
以下示例配置了一个基于 Netty 的 HTTP 客户端，该客户端由两个服务客户端使用。配置的 `NettyNioAsyncHttpClient` 实例将传递给每个生成器的 `httpClient` 方法。当不再需要服务客户端和 HTTP 客户端时，代码会显式关闭它们。代码最后关闭 HTTP 客户端。
**导入**
```
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.apache.ApacheHttpClient;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.s3.S3Client;
```
**代码**
```
// Create a NettyNioAsyncHttpClient shared instance.
SdkAsyncHttpClient nettyHttpClient = NettyNioAsyncHttpClient.builder().maxConcurrency(100).build();
// Singletons: Use the s3AsyncClient, dbAsyncClient, and enhancedAsyncClient for all requests.
S3AsyncClient s3AsyncClient =
S3AsyncClient.builder()
.httpClient(nettyHttpClient)
.build();
DynamoDbAsyncClient dbAsyncClient =
DynamoDbAsyncClient.builder()
.httpClient(nettyHttpClient)
.defaultsMode(DefaultsMode.IN_REGION)
.credentialsProvider(EnvironmentVariableCredentialsProvider.create())
.build();
DynamoDbEnhancedAsyncClient enhancedAsyncClient =
DynamoDbEnhancedAsyncClient.builder()
.dynamoDbClient(dbAsyncClient)
.extensions(AutoGeneratedTimestampRecordExtension.create())
.build();
// Perform work with s3AsyncClient, dbAsyncClient, and enhancedAsyncClient.
// Requests completed: Close all service clients.
s3AsyncClient.close();
dbAsyncClient.close()
nettyHttpClient.close(); // Explicitly close nettyHttpClient.
```
## 配置 ALPN 协议协商
ALPN（应用层协议协商）是一个 TLS 扩展，该扩展让应用层可以协商在建立安全连接时应执行哪个协议，从而避免额外的网络往返并提供更好的性能。
要使基于 Netty 的 HTTP 客户端能够使用 ALPN，请调用生成器方法，如以下代码段所示：
```
import software.amazon.awssdk.http.Protocol;
import software.amazon.awssdk.http.ProtocolNegotiation;
import software.amazon.awssdk.http.async.SdkAsyncHttpClient;
import software.amazon.awssdk.http.nio.netty.NettyNioAsyncHttpClient;
import software.amazon.awssdk.services.transcribestreaming.TranscribeStreamingAsyncClient;
// Configure the Netty-based HTTP client to use the ALPN protocol.
SdkAsyncHttpClient nettyClient = NettyNioAsyncHttpClient.builder()
.protocol(Protocol.HTTP2)
.protocolNegotiation(ProtocolNegotiation.ALPN)
.build();
// Use the Netty-based HTTP client with a service client.
TranscribeStreamingAsyncClient transcribeClient = TranscribeStreamingAsyncClient.builder()
.httpClient(nettyClient)
.build();
```
如前面的代码段所示，ALPN 协议协商目前仅适用于 HTTP/2 协议。
## 代理配置示例
以下代码段使用了[适用于 Netty HTTP 客户端的代理配置生成器](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/ProxyConfiguration.Builder.html)。
```
SdkAsyncHttpClient nettyHttpClient = NettyNioAsyncHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.scheme("https")
.host("myproxy")
.port(1234)
.username("username")
.password("password")
.nonProxyHosts(Set.of("localhost", "host.example.com"))
.build())
.build();
```
以下命令行片段显示了代理配置的等效 Java 系统属性。
```
$ java -Dhttps.proxyHost=myproxy -Dhttps.proxyPort=1234 -Dhttps.proxyUser=username \
-Dhttps.proxyPassword=password -Dhttp.nonProxyHosts=localhost|host.example.com -cp ... App
```
**重要**
要使用任何 HTTPS 代理系统属性，必须在代码中将 `scheme` 属性设置为 `https`。如果未在代码中设置 scheme 属性，则架构默认为 HTTP，SDK 仅查找 `http.*` 系统属性。
使用环境变量的等效设置为：
```
// Set the following environment variables.
// $ export HTTPS_PROXY="https://username:password@myproxy:1234"
// $ export NO_PROXY="localhost|host.example.com"
// Set the 'useSystemPropertyValues' to false on the proxy configuration.
SdkAsyncHttpClient nettyHttpClient = NettyNioAsyncHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.useSystemPropertyValues(Boolean.FALSE)
.build())
.build();
// Run the application.
// $ java -cp ... App
```
# 配置 AWS 基于 CRT 的 HTTP 客户
AWS 基于 CRT 的 HTTP 客户端包括同步客户端[AwsCrtHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtHttpClient.html)和异步[AwsCrtAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.html)客户端。 AWS 基于 CRT 的 HTTP 客户端具有以下 HTTP 客户端优势：
+ 更快的 SDK 启动时间
+ 更小的内存占用空间
+ 缩短了延迟时间
+ 连接运行状况管理
+ DNS 负载均衡
**AWS SDK 中基于 CRT 的组件**
本主题中介绍 AWS 的基于 CRT 的 *HTTP* 客户端和 AWS 基于 CRT 的 *S3* 客户端是软件开发工具包中的不同组件。
同步和异步**基于AWS CRT 的 HTTP 客户端**是 SDK HTTP 客户端接口的实现，用于一般 HTTP 通信。它们是 SDK 中其他同步或异步 HTTP 客户端的替代方案，提供额外优点。
**[AWS 基于 CRT 的 S3 客户端](crt-based-s3-client.md)**是 S [3 AsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3AsyncClient.html) 接口的实现，用于与 Amazon S3 服务配合使用。它是基于 Java 的 `S3AsyncClient` 接口实现的替代方案，具有多种优点。
尽管两个组件都使用[AWS 公共运行时](https://docs.aws.amazon.com/sdkref/latest/guide/common-runtime.html)中的库，但 AWS 基于 CRT 的 HTTP 客户端不使用 [aws-c-s3 库](https://github.com/awslabs/aws-c-s3)，也不支持 [S3 分段上传 API](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html) 功能。相比之下， AWS 基于 CRT 的 S3 客户端是专门为支持 S3 分段上传 API 功能而设计的。
## 访问 AWS 基于 CRT 的 HTTP 客户端
在使用 AWS 基于 CRT 的 HTTP 客户端之前，请将最低版本为 2.22.0 的`aws-crt-client`工件添加到项目的依赖项中。
使用以下选项之一来设置 Maven `pom.xml` 文件。
**注意**
如果您需要缩小运行时依赖项的大小（例如，如果您的应用程序在函数中运行），则可以选择使用*平台特定的 jar 选项*。 AWS Lambda
------
#### [ Uber-jar option ]
默认情况下，`aws-crt-client`使用一大堆 AWS CRT工件，其中包含多个平台的二进制文件，包括Linux、Windows和macOS。
```
2.29.10*
software.amazon.awssdk
bom
${aws.sdk.version}
pom
import
software.amazon.awssdk
aws-crt-client
```
\$1将以红色显示的版本替换为您要使用的 Java SDK 版本。在 [Maven Central](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) 上查找最新版本。
------
#### [ Platform-specific jar option ]
*要将 Java 运行时限制为特定平台版本的 AWS CRT 库，请对 Uber-JAR 选项进行以下更改。*
+ 向 SDK 的 `aws-crt-client` 构件添加一个 `exclusions` 元素。此排除会阻止 SDK 以传递方式使用 C AWS RT 超级jar。
+ 为你需要的特定 AWS CRT 平台版本添加依赖元素。有关**如何确定正确版本的信息，请参阅下面的确定 AWS CRT 构件版本的步骤**。
```
2.29.101
software.amazon.awssdk
bom
${aws.sdk.java.version}
pom
import
software.amazon.awssdk
aws-crt-client
software.amazon.awssdk.crt
aws-crt
software.amazon.awssdk.crt
aws-crt
0.31.32
linux-x86_643
```
1将以红色显示的版本替换为您要使用的 Java SDK 版本。在 [Maven Central](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) 上查找最新版本。
2替换*全能 JAR 包选项*将提供的 `software.amazon.awssdk.crt:aws-crt` 版本。**要确定 AWS CRT 构件版本，请参阅以下步骤**。
3将 `classifier` 值替换为适用于您平台的值。有关[可用值的列表](https://github.com/awslabs/aws-crt-java?tab=readme-ov-file#platform-specific-jars)，请参阅 Java 版 AWS CRT GitHub 页面。
**确定 AWS CRT 构件版本的步骤**
使用以下步骤来确定与您正在使用的适用于 Java 的 SDK 版本兼容的 AWS CRT 构件版本。
1. 按照*全能 JAR 包选项*所示设置您的 `pom.xml` 文件。借助此设置，您可以查看默认情况下 SDK 会引入什么版本的 `software.amazon.awssdk.crt:aws-crt`。
1. 在项目的根目录下（与 `pom.xml` 文件位于同一目录中），运行以下 Maven 命令：
```
mvn dependency:tree -Dincludes=software.amazon.awssdk.crt:aws-crt
```
Maven 可能会执行其他操作，但最后您应该会看到 SDK 以传递依赖方式使用的 `software.amazon.awssdk.crt:aws-crt` 依赖项的控制台输出。以下代码段显示了基于 SDK 版本 `2.29.10` 的示例输出：
```
[INFO] org.example:yourProject:jar:1.0-SNAPSHOT
[INFO] \- software.amazon.awssdk:aws-crt-client:jar:2.29.10:compile
[INFO] \- software.amazon.awssdk.crt:aws-crt:jar:0.31.3:compile
```
1. 使用控制台为 `software.amazon.awssdk.crt:aws-crt` 构件显示的版本。在本例中，将 `0.31.3` 添加到您的 `pom.xml` 文件中。
------
## 使用和配置 AWS 基于 CRT 的 HTTP 客户端
您可以在构建服务客户端的同时配置 AWS 基于 CRT 的 HTTP 客户端，也可以将单个实例配置为在多个服务客户端之间共享。
无论采用哪种方法，您都可以使用生成器来[配置 AWS 基于 CRT 的 HTTP 客户端实例的属性](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtHttpClient.Builder.html)。
### 最佳实践：将一个实例专用于一个服务客户端
如果您需要配置 AWS 基于 CRT 的 HTTP 客户端的实例，我们建议您将该实例与服务客户端一起构建，从而将其专用。您可以通过使用服务客户端生成器的 `httpClientBuilder` 方法来执行此操作。这样，HTTP 客户端的生命周期就由 SDK 管理，这有助于避免在不再需要 AWS 基于 CRT 的 HTTP 客户端实例时未关闭时可能发生的内存泄漏。
以下示例创建一个 S3 服务客户端，并使用和值配置 AWS 基于 CRT 的 HTTP 客户端`connectionTimeout`。`maxConcurrency`
------
#### [ Synchronous client ]
**导入**
```
import software.amazon.awssdk.http.crt.AwsCrtHttpClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.time.Duration;
```
**代码**
```
// Singleton: Use s3Client for all requests.
S3Client s3Client = S3Client.builder()
.httpClientBuilder(AwsCrtHttpClient
.builder()
.connectionTimeout(Duration.ofSeconds(3))
.maxConcurrency(100))
.build();
// Perform work with the s3Client.
// Requests completed: Close the s3Client.
s3Client.close();
```
------
#### [ Asynchronous client ]
**导入**
```
import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient;
import software.amazon.awssdk.services.s3.S3AsyncClient;
import java.time.Duration;
```
**代码**
```
// Singleton: Use s3AsyncClient for all requests.
S3AsyncClient s3AsyncClient = S3AsyncClient.builder()
.httpClientBuilder(AwsCrtAsyncHttpClient
.builder()
.connectionTimeout(Duration.ofSeconds(3))
.maxConcurrency(100))
.build();
// Perform work with the s3AsyncClient.
// Requests completed: Close the s3AsyncClient.
s3AsyncClient.close();
```
------
### 替代方法：共享 实例
为了帮助降低应用程序的资源和内存使用量，您可以配置 AWS 基于 CRT 的 HTTP 客户端，并在多个服务客户端之间共享该客户端。将共享 HTTP 连接池，从而降低资源使用量。
**注意**
共享 AWS 基于 CRT 的 HTTP 客户端实例时，您必须在准备好处置时将其关闭。服务客户端关闭后，SDK 不会关闭实例。
以下示例使用`connectionTimeout`和`maxConcurrency`值配置 AWS 基于 CRT 的 HTTP 客户端实例。配置的实例将传递给每个服务客户端的生成器的 `httpClient` 方法。当不再需要服务客户端和 HTTP 客户端时，它们将被显式关闭。HTTP 客户端最后关闭。
------
#### [ Synchronous client ]
**导入**
```
import software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider;
import software.amazon.awssdk.awscore.defaultsmode.DefaultsMode;
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.crt.AwsCrtHttpClient;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.time.Duration;
```
**代码**
```
// Create an AwsCrtHttpClient shared instance.
SdkHttpClient crtHttpClient = AwsCrtHttpClient.builder()
.connectionTimeout(Duration.ofSeconds(3))
.maxConcurrency(100)
.build();
// Singletons: Use the s3Client and dynamoDbClient for all requests.
S3Client s3Client = S3Client.builder()
.httpClient(crtHttpClient)
.credentialsProvider(EnvironmentVariableCredentialsProvider.crea
.defaultsMode(DefaultsMode.IN_REGION)
.region(Region.US_EAST_1)
.build();
DynamoDbClient dynamoDbClient = DynamoDbClient.builder()
.httpClient(crtHttpClient)
.credentialsProvider(EnvironmentVariableCredentialsProvider.crea
.defaultsMode(DefaultsMode.IN_REGION)
.region(Region.US_EAST_1)
.build();
// Requests completed: Close all service clients.
s3Client.close();
dynamoDbClient.close();
crtHttpClient.close(); // Explicitly close crtHttpClient.
```
------
#### [ Asynchronous client ]
**导入**
```
import software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider;
import software.amazon.awssdk.awscore.defaultsmode.DefaultsMode;
import software.amazon.awssdk.http.async.SdkAsyncHttpClient;
import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;
import software.amazon.awssdk.services.s3.S3AsyncClient;
import java.time.Duration;
```
**代码**
```
// Create an AwsCrtAsyncHttpClient shared instance.
SdkAsyncHttpClient crtAsyncHttpClient = AwsCrtAsyncHttpClient.builder()
.connectionTimeout(Duration.ofSeconds(3))
.maxConcurrency(100)
.build();
// Singletons: Use the s3AsyncClient and dynamoDbAsyncClient for all requests.
S3AsyncClient s3AsyncClient = S3AsyncClient.builder()
.httpClient(crtAsyncHttpClient)
.credentialsProvider(EnvironmentVariableCredentialsProvider.create())
.defaultsMode(DefaultsMode.IN_REGION)
.region(Region.US_EAST_1)
.build();
DynamoDbAsyncClient dynamoDbAsyncClient = DynamoDbAsyncClient.builder()
.httpClient(crtAsyncHttpClient)
.credentialsProvider(EnvironmentVariableCredentialsProvider.create())
.defaultsMode(DefaultsMode.IN_REGION)
.region(Region.US_EAST_1)
.build();
// Requests completed: Close all service clients.
s3AsyncClient.close();
dynamoDbAsyncClient.close();
crtAsyncHttpClient.close(); // Explicitly close crtAsyncHttpClient.
```
------
## 将 AWS 基于 CRT 的 HTTP 客户端设置为默认客户端
你可以设置你的 Maven 编译文件，让 SDK 使用 AWS 基于 CRT 的 HTTP 客户端作为服务客户端的默认 HTTP 客户端。
为此，您可以向每个服务客户端构件添加一个具有默认 HTTP 客户端依赖项的 `exclusions` 元素。
在以下`pom.xml`示例中，软件开发工具包将 AWS 基于 CRT 的 HTTP 客户端用于 S3 服务。如果您的代码中的服务客户端是 `S3AsyncClient`，则 SDK 使用 `AwsCrtAsyncHttpClient`。如果服务客户端是 S3Client，则 SDK 使用 `AwsCrtHttpClient`。在此设置下，默认的基于 Netty 的异步 HTTP 客户端和默认的基于 Apache 的同步 HTTP 不可用。
```
VERSION
software.amazon.awssdk
s3
${aws.sdk.version}
software.amazon.awssdk
netty-nio-client
software.amazon.awssdk
apache-client
software.amazon.awssdk
aws-crt-client
```
访问 Maven 中央存储库获取最新[https://central.sonatype.com/artifact/software.amazon.awssdk/bom](https://central.sonatype.com/artifact/software.amazon.awssdk/bom)值。
**注意**
如果在一个 `pom.xml` 文件中声明了多个服务客户端，则所有服务客户端都需要 `exclusions` XML 元素。
### 使用 Java 系统属性
要使用 AWS 基于 CRT 的 HTTP 客户端作为应用程序的默认 HTTP，可以将 Java 系统属性的`software.amazon.awssdk.http.async.service.impl``software.amazon.awssdk.http.crt.AwsCrtSdkHttpService`值设置为。
要在应用程序启动期间设置，请运行类似以下示例的命令。
```
java app.jar -Dsoftware.amazon.awssdk.http.async.service.impl=\
software.amazon.awssdk.http.crt.AwsCrtSdkHttpService
```
然后使用以下代码段在应用程序代码中设置系统属性。
```
System.setProperty("software.amazon.awssdk.http.async.service.impl",
"software.amazon.awssdk.http.crt.AwsCrtSdkHttpService");
```
**注意**
在使用系统属性配置基于 AWS CRT 的 HTTP 客户端的使用时，需要在`poml.xml`文件中添加对`aws-crt-client`工件的依赖关系。
## AWS 基于 CRT 的 HTTP 客户端的高级配置
您可以使用 AWS 基于 CRT 的 HTTP 客户端的各种配置设置，包括连接运行状况配置和最大空闲时间。您可以查看适用于 `AwsCrtAsyncHttpClient` 的[可用配置选项](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.Builder.html)。您可以为 `AwsCrtHttpClient` 配置相同的选项。
### 连接运行状况配置
您可以使用 HTTP 客户端生成器上的`connectionHealthConfiguration`方法为 AWS 基于 CRT 的 HTTP 客户端配置连接运行状况配置。
以下示例创建了一个 S3 服务客户端，该客户端使用 AWS 基于 CRT 的 HTTP 客户端实例，该实例配置了连接运行状况配置和连接的最大空闲时间。
------
#### [ Synchronous client ]
**导入**
```
import software.amazon.awssdk.http.crt.AwsCrtHttpClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.time.Duration;
```
**代码**
```
// Singleton: Use the s3Client for all requests.
S3Client s3Client = S3Client.builder()
.httpClientBuilder(AwsCrtHttpClient
.builder()
.connectionHealthConfiguration(builder -> builder
.minimumThroughputInBps(32000L)
.minimumThroughputTimeout(Duration.ofSeconds(3)))
.connectionMaxIdleTime(Duration.ofSeconds(5)))
.build();
// Perform work with s3Client.
// Requests complete: Close the service client.
s3Client.close();
```
------
#### [ Asynchronous client ]
**导入**
```
import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient;
import software.amazon.awssdk.services.s3.S3AsyncClient;
import java.time.Duration;
```
**代码**
```
// Singleton: Use the s3AsyncClient for all requests.
S3AsyncClient s3AsyncClient = S3AsyncClient.builder()
.httpClientBuilder(AwsCrtAsyncHttpClient
.builder()
.connectionHealthConfiguration(builder -> builder
.minimumThroughputInBps(32000L)
.minimumThroughputTimeout(Duration.ofSeconds(3)))
.connectionMaxIdleTime(Duration.ofSeconds(5)))
.build();
// Perform work with s3AsyncClient.
// Requests complete: Close the service client.
s3AsyncClient.close();
```
------
## HTTP/2 支持
AWS 基于 CRT 的 HTTP 客户端尚不支持 HTTP/2 协议，但计划在将来的版本中推出。
同时，如果您使用的是需要 HTTP/2 支持的服务客户端，例如[KinesisAsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/kinesis/KinesisAsyncClient.html)或 [TranscribeStreamingAsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/transcribestreaming/TranscribeStreamingAsyncClient.html)，请考虑改用。[NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html)
## 代理配置示例
以下代码段显示了如何使用 [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/ProxyConfiguration.Builder.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/ProxyConfiguration.Builder.html) 在代码中配置代理设置。
------
#### [ Synchronous client ]
**导入**
```
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.crt.AwsCrtHttpClient;
import software.amazon.awssdk.http.crt.ProxyConfiguration;
```
**代码**
```
SdkHttpClient crtHttpClient = AwsCrtHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.scheme("https")
.host("myproxy")
.port(1234)
.username("username")
.password("password")
.nonProxyHosts(Set.of("localhost", "host.example.com"))
.build())
.build();
```
------
#### [ Asynchronous client ]
**导入**
```
import software.amazon.awssdk.http.async.SdkAsyncHttpClient;
import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient;
import software.amazon.awssdk.http.crt.ProxyConfiguration;
```
**代码**
```
SdkAsyncHttpClient crtAsyncHttpClient = AwsCrtAsyncHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.scheme("https")
.host("myproxy")
.port(1234)
.username("username")
.password("password")
.nonProxyHosts(Set.of("localhost", "host.example.com"))
.build())
.build();
```
------
以下命令行片段显示了代理配置的等效 Java 系统属性。
```
$ java -Dhttps.proxyHost=myproxy -Dhttps.proxyPort=1234 -Dhttps.proxyUser=username \
-Dhttps.proxyPassword=password -Dhttp.nonProxyHosts=localhost|host.example.com -cp ... App
```
**重要**
要使用任何 HTTPS 代理系统属性，必须在代码中将 `scheme` 属性设置为 `https`。如果未在代码中设置 scheme 属性，则架构默认为 HTTP，SDK 仅查找 `http.*` 系统属性。
使用环境变量的等效设置为：
```
// Set the following environment variables.
// $ export HTTPS_PROXY="https://username:password@myproxy:1234"
// $ export NO_PROXY="localhost|host.example.com"
// Set the 'useSystemPropertyValues' to false on the proxy configuration.
SdkAsyncHttpClient crtAsyncHttpClient = AwsCrtAsyncHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.scheme("https")
.useSystemPropertyValues(Boolean.FALSE)
.build())
.build();
// Run the application.
// $ java -cp ... App
```
# 配置 HTTP 代理
您可以通过使用代码、设置 Java 系统属性或设置环境变量来配置 HTTP 代理。
## 在代码中配置
在生成服务客户端时，您可以使用特定于客户端的 `ProxyConfiguration` 生成器在代码中配置代理。以下代码显示了 Amazon S3 服务客户端所用的基于 Apache 的 HTTP 客户端的示例代理配置。
```
SdkHttpClient httpClient1 = ApacheHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.endpoint(URI.create("http://proxy.example.com"))
.username("username")
.password("password")
.addNonProxyHost("localhost")
.build())
.build();
S3Client s3Client = S3Client.builder()
.httpClient(httpClient)
.build();
```
本主题中提及的每个 HTTP 客户端都在其详细介绍部分提供了一个代理配置示例。
+ [Apache HTTP 客户端](http-configuration-apache.md#http-configuration-apache-proxy-conf-ex)
+ [URLConnection基于 HTTP 客户端](http-configuration-url.md#http-configuration-url-proxy-conf-ex)
+ [基于 Netty 的 HTTP 客户端](http-configuration-netty.md#http-config-netty-proxy-ex)
+ [AWS 基于 CRT 的 HTTP](http-configuration-crt.md#http-config-crt-proxy-ex)
## 使用外部设置配置 HTTP 代理
即使您没有在代码中明确使用 `ProxyConfiguration` 生成器，SDK 也会查找外部设置来配置默认代理配置。
默认情况下，SDK 先搜索 JVM 系统属性。即使只找到一个属性，SDK 也会使用该值和任何其他系统属性值。如果没有可用的系统属性，SDK 会查找代理环境变量。
SDK 可以使用以下 Java 系统属性和环境变量。
**Java 系统属性**
| 系统属性 | 说明 | HTTP 客户端支持 |
| --- | --- | --- |
| http.proxyHost | HTTP 代理服务器主机名 | 全部 |
| http.proxyPort | HTTP 代理服务器端口号 | 全部 |
| http.proxyUser | HTTP 代理身份验证用户名 | 全部 |
| http.proxyPassword | HTTP 代理身份验证密码 | 全部 |
| http。 nonProxyHosts | 应绕过代理直接访问的主机列表。[使用 HTTPS 时此列表也有效](https://docs.oracle.com/javase/8/docs/technotes/guides/net/proxies.html)。 | 全部 |
| https.proxyHost | HTTPS 代理服务器主机名 | Netty、CRT |
| https.proxyPort | HTTPS 代理服务器端口号 | Netty、CRT |
| https.proxyUser | HTTPS 代理身份验证用户名 | Netty、CRT |
| https.proxyPassword | HTTPS 代理身份验证密码 | Netty、CRT |
**环境变量**
| 环境变量 | 说明 | HTTP 客户端支持 |
| --- | --- | --- |
| HTTP\$1PROXY1 | 采用 HTTP 架构的有效 URL | 全部 |
| HTTPS\$1PROXY1 | 采用 HTTPS 架构的有效 URL | Netty、CRT |
| NO\$1PROXY2 | 应绕过代理直接访问的主机列表。该列表对 HTTP 和 HTTPS 均有效。 | 全部 |
### 查看要点和脚注
**全部** - SDK 提供全部 HTTP 客户端（`UrlConnectionHttpClient`、`ApacheHttpClient`、`NettyNioAsyncHttpClient`、`AwsCrtAsyncHttpClient`）。
**Netty** - 基于 Netty 的 HTTP 客户端（`NettyNioAsyncHttpClient`）。
**CRT**- AWS 基于 CRT 的 HTTP 客户端，（`AwsCrtHttpClient`和）。`AwsCrtAsyncHttpClient`
1查询的环境变量（`HTTP_PROXY` 或 `HTTPS_PROXY`）取决于客户端的 `ProxyConfiguration` 中的架构设置。默认架构是 HTTP。以下代码段说明如何将用于环境变量解析的架构更改为 HTTPS。
```
SdkHttpClient httpClient = ApacheHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.scheme("https")
.build())
.build();
```
2`NO_PROXY` 环境变量支持在主机名之间混用“\$1”和“,”分隔符。主机名可能包括“\$1”通配符。
## 使用多种设置的组合
您可以在代码、系统属性和环境变量中组合使用 HTTP 代理设置。
**Example - 系统属性和代码提供的配置**
```
// Command line with the proxy password set as a system property.
$ java -Dhttp.proxyPassword=SYS_PROP_password -cp ... App
// Since the 'useSystemPropertyValues' setting is 'true' (the default), the SDK will supplement
// the proxy configuration in code with the 'http.proxyPassword' value from the system property.
SdkHttpClient apacheHttpClient = ApacheHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.endpoint(URI.create("http://localhost:1234"))
.username("username")
.build())
.build();
// Use the apache HTTP client with proxy configuration.
DynamoDbClient dynamoDbClient = DynamoDbClient.builder()
.httpClient(apacheHttpClient)
.build();
```
SDK 解析以下代理设置。
```
Host = localhost
Port = 1234
Password = SYS_PROP_password
UserName = username
Non ProxyHost = null
```
**Example - 系统属性和环境变量都可用**
每个 HTTP 客户端的 `ProxyConfiguration` 生成器都提供名为 `useSystemPropertyValues` 和 `useEnvironmentVariablesValues` 的设置。默认情况下，两个设置均为 `true`。当设置为 `true` 时，SDK 会自动将来自系统属性或环境变量的值用于 `ProxyConfiguration` 生成器未提供的选项。
系统属性优先于环境变量。如果找到 HTTP 代理系统属性，SDK 将从系统属性中检索***全部***值，而不会从环境变量中检索任何值。如果要使环境变量优先于系统属性，请将 `useSystemPropertyValues` 设置为 `false`。
在本示例中，以下设置在运行时可用：
```
// System properties
http.proxyHost=SYS_PROP_HOST.com
http.proxyPort=2222
http.password=SYS_PROP_PASSWORD
http.user=SYS_PROP_USER
// Environment variables
HTTP_PROXY="http://EnvironmentUser:EnvironmentPassword@ENV_VAR_HOST:3333"
NO_PROXY="environmentnonproxy.host,environmentnonproxy2.host:1234"
```
使用以下语句之一创建服务客户端。这些语句都没有明确设置代理设置。
```
DynamoDbClient client = DynamoDbClient.create();
DynamoDbClient client = DynamoDbClient.builder().build();
DynamoDbClient client = DynamoDbClient.builder()
.httpClient(ApacheHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.build())
.build())
.build();
```
SDK 解析以下代理设置：
```
Host = SYS_PROP_HOST.com
Port = 2222
Password = SYS_PROP_PASSWORD
UserName = SYS_PROP_USER
Non ProxyHost = null
```
由于服务客户端具有默认代理设置，因此 SDK 会搜索系统属性，然后搜索环境变量。由于系统属性设置优先于环境变量，因此 SDK 仅使用系统属性。
如果将系统属性的使用更改为 `false`，如以下代码所示，则 SDK 仅解析环境变量。
```
DynamoDbClient client = DynamoDbClient.builder()
.httpClient(ApacheHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.useSystemPropertyValues(Boolean.FALSE)
.build())
.build())
.build();
```
使用 HTTP 解析的代理设置包括：
```
Host = ENV_VAR_HOST
Port = 3333
Password = EnvironmentPassword
UserName = EnvironmentUser
Non ProxyHost = environmentnonproxy.host, environmentnonproxy2.host:1234
```
# 配置基于 Apache 5.x 的 HTTP 客户端
## 访问 Apache5 HttpClient
要使用，`Apache5HttpClient`您必须添加对服务客户端的依赖关系**apache5-client**并在服务客户端`Apache5HttpClient`上进行显式配置。
```
software.amazon.awssdk
bom
2.41.0*
pom
import
software.amazon.awssdk
s3
software.amazon.awssdk
apache5-client
```
\$1将以红色显示的版本替换为您要使用的 Java SDK 版本。在 [Maven Central](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) 上查找最新版本。
### 使用和配置 `Apache5HttpClient`
您可以在生成服务客户端的同时配置一个 `Apache5HttpClient` 实例，也可以将单个实例配置为在多个服务客户端之间共享。
无论哪种方法，您都可以使用 [Apache5. HttpClient Builder 为基于 Apache 5](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache5/Apache5HttpClient.Builder.html) 的 HTTP 客户端配置属性。
#### 最佳实践：将 Apache5 HttpClient 实例专用于服务客户端
如果您需要配置 `Apache5HttpClient` 实例，建议您生成专用 `Apache5HttpClient` 实例。您可以使用服务客户端生成器的 httpClientBuilder 方法来执行此操作。这样，HTTP 客户端的生命周期就由 SDK 管理，这有助于避免在不再需要 `Apache5HttpClient` 实例却不关闭实例时可能发生的内存泄漏。
以下示例创建了一个 S3Client，并使用 maxConnections 和 ConnectionTimeout 值配置`Apache5HttpClient`的嵌入式实例。HTTP 实例是使用 `S3Client.Builder` 的 `httpClientBuilder` 方法创建的。
**导入**
```
import software.amazon.awssdk.http.apache5.Apache5HttpClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.time.Duration;
```
**代码**
```
S3Client s3Client = S3Client // Singleton: Use the s3Client for all requests.
.builder()
.httpClientBuilder(Apache5HttpClient.builder()
.maxConnections(100)
.connectionTimeout(Duration.ofSeconds(5))
)
.build();
// Perform work with the s3Client.
s3Client.close(); // Requests completed: Close all service clients.
```
#### 替代方法：共享 `Apache5HttpClient` 实例
为了帮助降低应用程序的资源和内存使用量，您可以配置 `Apache5HttpClient` 并在多个服务客户端之间共享该客户端。将共享 HTTP 连接池，从而降低资源使用量。
**注意**
共享 `Apache5HttpClient` 实例时，必须在准备好弃置实例时将其关闭。服务客户端关闭后，SDK 不会关闭实例。
以下示例配置了一个基于 Apache 的 HTTP 客户端，该客户端由两个服务客户端使用。配置的`ApacheHttpClient`实例将传递给每个生成器的 HttpClient 方法。当不再需要服务客户端和 HTTP 客户端时，代码会显式关闭它们。代码最后关闭 HTTP 客户端。
**导入**
```
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.apache5.Apache5HttpClient;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.s3.S3Client;
```
**代码**
```
SdkHttpClient apache5HttpClient = Apache5HttpClient.builder()
.maxConnections(100).build();
// Singletons: Use the s3Client and dynamoDbClient for all requests.
S3Client s3Client =
S3Client.builder()
.httpClient(apache5HttpClient).build();
DynamoDbClient dynamoDbClient =
DynamoDbClient.builder()
.httpClient(apache5HttpClient).build();
// Perform work with the s3Client and dynamoDbClient.
// Requests completed: Close all service clients.
s3Client.close();
dynamoDbClient.close();
apache5HttpClient.close(); // Explicitly close apache5HttpClient.
```