Calling REST Services

Spring Boot 提供了几种便捷的方式来调用远程 REST 服务。如果您正在开发非阻塞式反应式应用程序并且您正在使用 Spring WebFlux，那么您可以使用 WebClient。如果您喜欢阻塞式 API，那么您可以使用 RestClient`或 `RestTemplate。

WebClient

如果您在类路径上启用了 Spring WebFlux，我们建议您使用 `WebClient`来调用远程 REST 服务。`WebClient`接口提供了一种函数式风格 API，并且完全响应。您可以在 Spring Framework 文档中的专门 {url-spring-framework-docs}/web/webflux-webclient.html[部分]中了解更多有关 `WebClient`的信息。

如果您不在编写反应式 Spring WebFlux 应用程序，则可以使用 RestClient代替 WebClient。这提供了类似的函数式 API，但它是阻塞式而不是响应式的。

Spring Boot 为您创建并预先配置了原型 `WebClient.Builder`Bean。强烈建议您将其注入到组件中并使用它来创建 `WebClient`实例。Spring Boot 配置该构建器来共享 HTTP 资源并以与服务器资源相同的方式反映编解码器设置（请参见 WebFlux HTTP codecs auto-configuration），以及更多功能。

以下代码显示了一个典型的示例：

WebClient Runtime

Spring Boot 会根据应用程序类路径中可用的库自动检测要使用哪个 ClientHttpConnector`来驱动 `WebClient。按偏好的顺序，支持以下客户端：

  1. Reactor Netty

  2. Jetty RS client

  3. Apache HttpClient

  4. JDK HttpClient

如果类路径上有多个客户端，则将使用最优先的客户端。

spring-boot-starter-webflux Starter 默认依赖于 io.projectreactor.netty:reactor-netty，它同时提供了服务器和客户端实现。如果您选择使用 Jetty 作为反应式服务器，则应该添加对 Jetty 反应式 HTTP 客户端库 `org.eclipse.jetty:jetty-reactive-httpclient`的依赖。服务器和客户端使用相同的技术有其优势，它会在客户端和服务器之间自动共享 HTTP 资源。

开发者可以通过提供自定义的 ReactorResourceFactory 或 JettyResourceFactory bean 来覆盖 Jetty 和 Reactor Netty 的资源配置，这将应用于客户端和服务器。

如果您希望对客户端覆盖该选择，则可以定义自己的 ClientHttpConnector Bean，并完全控制客户端配置。

您可以在 [Spring Framework 参考文档](/web/webflux-webclient/client-builder.html) 中了解有关 WebClient 配置选项的更多信息。

WebClient Customization

共有三种主要方法可以根据您希望自定义范围有多大来进行 WebClient 自定义。

要尽可能缩小任何自定义的范围，请注入自动配置的 WebClient.Builder，然后根据需要调用其方法。WebClient.Builder 实例是有状态的：生成器上的任何更改都会反映在随后使用它创建的所有客户端中。如果您想使用同一个生成器创建多个客户端，也可以考虑使用 WebClient.Builder other = builder.clone(); 克隆生成器。

若要对所有 WebClient.Builder 实例进行全应用程序范围内的增加性自定义，您可以声明 WebClientCustomizer Bean，并在注入时在本地更改 WebClient.Builder。

最后，您可以回退到原始 API 并使用 WebClient.create()。在这种情况下，不应用自动配置或 @"14”。

WebClient SSL Support

如果您需要在 WebClient 使用的 ClientHttpConnector 上进行自定义 SSL 配置，则可以注入一个 WebClientSsl 实例，该实例可与生成器的 apply 方法一起使用。

WebClientSsl 接口提供对您在 application.properties 或 application.yaml 文件中定义的任何 SSL bundles 的访问。

以下代码显示了一个典型的示例：

RestClient

如果您在应用程序中不使用 Spring WebFlux 或 Project Reactor，我们建议您使用 RestClient 调用远程 REST 服务。

RestClient 接口提供一个函数式风格的阻塞 API。

Spring Boot 为您创建并预配置了一个原型 RestClient.Builder Bean。强烈建议您将其注入组件并使用它创建 «26» 实例。Spring Boot 使用 HttpMessageConverters 和一个合适的 ClientHttpRequestFactory 配置该生成器。

以下代码显示了一个典型的示例：

RestClient Customization

共有三种主要方法可以根据您希望自定义范围有多大来进行 RestClient 自定义。

要尽可能缩小任何自定义的范围，请注入自动配置的 RestClient.Builder，然后根据需要调用其方法。RestClient.Builder 实例是有状态的：生成器上的任何更改都会反映在随后使用它创建的所有客户端中。如果您想使用同一个生成器创建多个客户端，也可以考虑使用 RestClient.Builder other = builder.clone(); 克隆生成器。

若要对所有 RestClient.Builder 实例进行全应用程序范围内的增加性自定义，您可以声明 RestClientCustomizer Bean，并在注入时在本地更改 RestClient.Builder。

最后，您可以回退到原始 API 并使用 RestClient.create()。在这种情况下，不应用自动配置或 RestClientCustomizer。

RestClient SSL Support

如果您需要在 RestClient 使用的 ClientHttpRequestFactory 上进行自定义 SSL 配置，则可以注入一个 RestClientSsl 实例，该实例可与生成器的 apply 方法一起使用。

RestClientSsl 接口提供对您在 application.properties 或 application.yaml 文件中定义的任何 SSL bundles 的访问。

以下代码显示了一个典型的示例：

如果您需要在 SSL 捆绑包之外应用其他自定义，可以使用带 ClientHttpRequestFactories 的 ClientHttpRequestFactorySettings 类：

RestTemplate

Spring Framework 的 {url-spring-framework-javadoc}/org/springframework/web/client/RestTemplate.html[RestTemplate] 类早于 RestClient，并且是许多应用程序用于调用远程 REST 服务的经典方式。当您有不想迁移到 RestClient 的现有代码时，或者因为您已经熟悉 RestTemplate API 时，您可能会选择使用 RestTemplate。

由于在使用 RestTemplate 实例之前通常需要对其进行自定义，因此 Spring Boot 不会提供任何单个自动配置的 RestTemplate Bean。但是，它确实会自动配置一个 RestTemplateBuilder，在需要时可将其用于创建 RestTemplate 实例。自动配置的 RestTemplateBuilder 可确保对 RestTemplate 实例应用正确的 HttpMessageConverters 和合适的 ClientHttpRequestFactory。

以下代码显示了一个典型的示例：

RestTemplateBuilder 包含许多有用的方法，可用于快速配置 RestTemplate。例如，要添加 BASIC 身份验证支持，您可以使用 builder.basicAuthentication("user", "password").build()。

RestTemplate Customization

对于 RestTemplate 自定义，有三种主要方法，这取决于你想要将自定义应用到多广的范围。

为了使任何自定义的范围尽可能窄，注入自动配置的 RestTemplateBuilder，然后根据需要调用其方法。每个方法调用都会返回一个新的 RestTemplateBuilder 实例，因此该自定义仅影响构建器的该次调用。

要进行应用范围广的附加自定义，请使用 RestTemplateCustomizer bean。所有此类 bean 会自动在自动配置的 RestTemplateBuilder 中进行注册，并应用于用其构建的任何模板。

以下示例显示了一个自定义器，配置通过代理访问除 192.168.0.5 之外的所有主机：

最后，你可以定义自己的 RestTemplateBuilder bean。这样做会替换自动配置的构建器。如果你希望任何 RestTemplateCustomizer bean 应用于你的自定义构建器，就像自动配置所做的那样，使用 RestTemplateBuilderConfigurer 进行配置。以下示例显示了一个 RestTemplateBuilder，它与 Spring Boot 的自动配置相匹配，不同之处在于还指定了自定义连接和读取超时时间：

最极端（且很少使用）的选项是创建你自己的 RestTemplateBuilder bean，而不使用配置器。除了替换自动配置的构建器外，这样还会阻止使用任何 RestTemplateCustomizer bean。

RestTemplate SSL Support

如果你需要对 RestTemplate 进行自定义 SSL 配置，可以使用此示例所示，将 SSL bundle 应用于 RestTemplateBuilder：

HTTP Client Detection for RestClient and RestTemplate

Spring Boot 会根据应用程序类路径中可用的库自动检测与 RestClient 和 RestTemplate 配合使用哪个 HTTP 客户端。按照下列偏好顺序，支持以下客户端：

  1. Apache HttpClient

  2. Jetty HttpClient

  3. OkHttp (deprecated)

  4. Simple JDK client (HttpURLConnection)

如果类路径上有多个客户端，则将使用最优先的客户端。