SpringCloud/spring-cloud-commons
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Sync docs from 2.1.x to gh-pages

Browse Source
This commit is contained in:
buildmaster
2019-09-02 18:39:37 +00:00
parent 82a820fd52
commit c09ebb82ca
4 changed files with 215 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
2.1.x/multi/multi__spring_cloud_commons_common_abstractions.html
View File

@@ -47,7 +47,7 @@ Calling <code class="literal">/service-registry</code> with GET returns the stat
Using POST to the same endpoint with a JSON body changes the status of the current <code class="literal">Registration</code> to the new value.
The JSON body has to include the <code class="literal">status</code> field with the preferred value.
Please see the documentation of the <code class="literal">ServiceRegistry</code> implementation you use for the allowed values when updating the status and the values returned for the status.
For instance, Eureka&#8217;s supported statuses are <code class="literal">UP</code>, <code class="literal">DOWN</code>, <code class="literal">OUT_OF_SERVICE</code>, and <code class="literal">UNKNOWN</code>.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_spring_resttemplate_as_a_load_balancer_client" href="#_spring_resttemplate_as_a_load_balancer_client"></a>2.3&nbsp;Spring RestTemplate as a Load Balancer Client</h2></div></div></div><p><code class="literal">RestTemplate</code> can be automatically configured to use ribbon.
For instance, Eureka&#8217;s supported statuses are <code class="literal">UP</code>, <code class="literal">DOWN</code>, <code class="literal">OUT_OF_SERVICE</code>, and <code class="literal">UNKNOWN</code>.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_spring_resttemplate_as_a_load_balancer_client" href="#_spring_resttemplate_as_a_load_balancer_client"></a>2.3&nbsp;Spring RestTemplate as a Load Balancer Client</h2></div></div></div><p><code class="literal">RestTemplate</code> can be automatically configured to use a Load-balancer client under the hood.
To create a load-balanced <code class="literal">RestTemplate</code>, create a <code class="literal">RestTemplate</code> <code class="literal">@Bean</code> and use the <code class="literal">@LoadBalanced</code> qualifier, as shown in the following example:</p><pre class="programlisting"><xslthl:annotation xmlns:xslthl="http://xslthl.sourceforge.net/">@Configuration</xslthl:annotation>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MyConfiguration {
@@ -69,7 +69,12 @@ To create a load-balanced <code class="literal">RestTemplate</code>, create a <c
}</pre><div class="caution" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Caution"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="images/caution.png"></td><th align="left">Caution</th></tr><tr><td align="left" valign="top"><p>A <code class="literal">RestTemplate</code> bean is no longer created through auto-configuration.
Individual applications must create it.</p></td></tr></table></div><p>The URI needs to use a virtual host name (that is, a service name, not a host name).
The Ribbon client is used to create a full physical address.
See <a class="link" href="https://github.com/spring-cloud/spring-cloud-netflix/blob/master/spring-cloud-netflix-ribbon/src/main/java/org/springframework/cloud/netflix/ribbon/RibbonAutoConfiguration.java" target="_top">RibbonAutoConfiguration</a> for details of how the <code class="literal">RestTemplate</code> is set up.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_spring_webclient_as_a_load_balancer_client" href="#_spring_webclient_as_a_load_balancer_client"></a>2.4&nbsp;Spring WebClient as a Load Balancer Client</h2></div></div></div><p><code class="literal">WebClient</code> can be automatically configured to use the <code class="literal">LoadBalancerClient</code>.
See <a class="link" href="https://github.com/spring-cloud/spring-cloud-netflix/blob/master/spring-cloud-netflix-ribbon/src/main/java/org/springframework/cloud/netflix/ribbon/RibbonAutoConfiguration.java" target="_top">RibbonAutoConfiguration</a> for details of how the <code class="literal">RestTemplate</code> is set up.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>In order to use a load-balanced <code class="literal">RestTemplate</code>, you need to have a load-balancer implementation in your classpath.
The recommended implementation is <code class="literal">BlockingLoadBalancerClient</code>
- add <code class="literal">org.springframework.cloud:spring-cloud-loadbalancer</code> in order to use it.
The
<code class="literal">RibbonLoadBalancerClient</code> also can be used, but it&#8217;s now under maintenance and we do not recommend adding it to new projects.</p></td></tr></table></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>If you want to use <code class="literal">BlockingLoadBalancerClient</code>, make sure you do not have
<code class="literal">RibbonLoadBalancerClient</code> in the project classpath, as for backward compatibility reasons, it will be used by default.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_spring_webclient_as_a_load_balancer_client" href="#_spring_webclient_as_a_load_balancer_client"></a>2.4&nbsp;Spring WebClient as a Load Balancer Client</h2></div></div></div><p><code class="literal">WebClient</code> can be automatically configured to use a load-balancer client.
To create a load-balanced <code class="literal">WebClient</code>, create a <code class="literal">WebClient.Builder</code> <code class="literal">@Bean</code> and use the <code class="literal">@LoadBalanced</code> qualifier, as shown in the following example:</p><pre class="programlisting"><xslthl:annotation xmlns:xslthl="http://xslthl.sourceforge.net/">@Configuration</xslthl:annotation>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MyConfiguration {
@@ -89,7 +94,17 @@ To create a load-balanced <code class="literal">WebClient</code>, create a <code
.retrieve().bodyToMono(String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>);
}
}</pre><p>The URI needs to use a virtual host name (that is, a service name, not a host name).
The Ribbon client is used to create a full physical address.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_retrying_failed_requests" href="#_retrying_failed_requests"></a>2.4.1&nbsp;Retrying Failed Requests</h3></div></div></div><p>A load-balanced <code class="literal">RestTemplate</code> can be configured to retry failed requests.
The Ribbon client is used to create a full physical address.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>If you want to use a <code class="literal">@LoadBalanced WebClient.Builder</code>, you need to have a loadbalancer
implementation in the classpath. It is recommended that you add the
<code class="literal">org.springframework.cloud:spring-cloud-loadbalancer</code> dependency to your project.
Then, <code class="literal">ReactiveLoadBalancer</code> will be used underneath.
Alternatively, this functionality will also work with spring-cloud-starter-netflix-ribbon, but the request
will be handled by a non-reactive <code class="literal">LoadBalancerClient</code> under the hood. Additionally,
spring-cloud-starter-netflix-ribbon is already in maintenance mode, so we do not recommned
adding it to new projects.</p></td></tr></table></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>The <code class="literal">ReactorLoadBalancer</code> used underneath supports caching. If <code class="literal">cacheManager</code> is detected,
cached version of <code class="literal">ServiceInstanceSupplier</code> will be used. If not, we will retrieve instances
from discovery service without caching them. We recommend <a class="link" href="https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-caching.html" target="_top">enabling caching</a> in your project
if you use <code class="literal">ReactiveLoadBalancer</code>.</p></td></tr></table></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_retrying_failed_requests" href="#_retrying_failed_requests"></a>2.4.1&nbsp;Retrying Failed Requests</h3></div></div></div><p>A load-balanced <code class="literal">RestTemplate</code> can be configured to retry failed requests.
By default, this logic is disabled.
You can enable it by adding <a class="link" href="https://github.com/spring-projects/spring-retry" target="_top">Spring Retry</a> to your application&#8217;s classpath.
The load-balanced <code class="literal">RestTemplate</code> honors some of the Ribbon configuration values related to retrying failed requests.
@@ -167,7 +182,28 @@ To access the load-balanced <code class="literal">RestTemplate</code>, use the <
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String doStuff() {
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> restTemplate.getForObject(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"https://example.com"</span>, String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>);
}
}</pre><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>Notice the use of the <code class="literal">@Primary</code> annotation on the plain <code class="literal">RestTemplate</code> declaration in the preceding example to disambiguate the unqualified <code class="literal">@Autowired</code> injection.</p></td></tr></table></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>If you see errors such as <code class="literal">java.lang.IllegalArgumentException: Can not set org.springframework.web.client.RestTemplate field com.my.app.Foo.restTemplate to com.sun.proxy.$Proxy89</code>, try injecting <code class="literal">RestOperations</code> or setting <code class="literal">spring.aop.proxyTargetClass=true</code>.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="loadbalanced-webclient" href="#loadbalanced-webclient"></a>2.6&nbsp;Spring WebFlux WebClient as a Load Balancer Client</h2></div></div></div><p><code class="literal">WebClient</code> can be configured to use the <code class="literal">LoadBalancerClient</code>. <code class="literal">LoadBalancerExchangeFilterFunction</code> is auto-configured if <code class="literal">spring-webflux</code> is on the classpath. The following example shows how to configure a <code class="literal">WebClient</code> to use load balancer:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MyClass {
}</pre><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>Notice the use of the <code class="literal">@Primary</code> annotation on the plain <code class="literal">RestTemplate</code> declaration in the preceding example to disambiguate the unqualified <code class="literal">@Autowired</code> injection.</p></td></tr></table></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>If you see errors such as <code class="literal">java.lang.IllegalArgumentException: Can not set org.springframework.web.client.RestTemplate field com.my.app.Foo.restTemplate to com.sun.proxy.$Proxy89</code>, try injecting <code class="literal">RestOperations</code> or setting <code class="literal">spring.aop.proxyTargetClass=true</code>.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="loadbalanced-webclient" href="#loadbalanced-webclient"></a>2.6&nbsp;Spring WebFlux WebClient as a Load Balancer Client</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="webflux-with-reactive-loadbalancer" href="#webflux-with-reactive-loadbalancer"></a>2.6.1&nbsp;Spring WebFlux WebClient with Reactive Load Balancer</h3></div></div></div><p><code class="literal">WebClient</code> can be configured to use the <code class="literal">ReactiveLoadBalancer</code>.
If you add <code class="literal">org.springframework.cloud:spring-cloud-loadbalancer</code> to your project,
<code class="literal">ReactorLoadBalancerExchangeFilterFunction</code> is auto-configured if <code class="literal">spring-webflux</code> is on the classpath.
The following example shows how to configure a <code class="literal">WebClient</code> to use reactive load balancer under the hood:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MyClass {
<xslthl:annotation xmlns:xslthl="http://xslthl.sourceforge.net/">@Autowired</xslthl:annotation>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> ReactorLoadBalancerExchangeFilterFunction lbFunction;
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Mono&lt;String&gt; doOtherStuff() {
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> WebClient.builder().baseUrl(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://stores"</span>)
.filter(lbFunction)
.build()
.get()
.uri(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/stores"</span>)
.retrieve()
.bodyToMono(String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>);
}
}</pre><p>The URI needs to use a virtual host name (that is, a service name, not a host name).
The <code class="literal">ReactorLoadBalancerClient</code> is used to create a full physical address.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_spring_webflux_webclient_with_non_reactive_load_balancer_client" href="#_spring_webflux_webclient_with_non_reactive_load_balancer_client"></a>2.6.2&nbsp;Spring WebFlux WebClient with non-reactive Load Balancer Client</h3></div></div></div><p>If you you don&#8217;t have <code class="literal">org.springframework.cloud:spring-cloud-loadbalancer</code> in your project,
but you do have spring-cloud-starter-netflix-ribbon, you can still use <code class="literal">WebClient</code> with <code class="literal">LoadBalancerClient</code>. <code class="literal">LoadBalancerExchangeFilterFunction</code>
will be auto-configured if <code class="literal">spring-webflux</code> is on the classpath. Please note, however, that this is
uses a non-reactive client under the hood.
The following example shows how to configure a <code class="literal">WebClient</code> to use load balancer:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MyClass {
<xslthl:annotation xmlns:xslthl="http://xslthl.sourceforge.net/">@Autowired</xslthl:annotation>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> LoadBalancerExchangeFilterFunction lbFunction;
@@ -181,7 +217,28 @@ To access the load-balanced <code class="literal">RestTemplate</code>, use the <
.bodyToMono(String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>);
}
}</pre><p>The URI needs to use a virtual host name (that is, a service name, not a host name).
The <code class="literal">LoadBalancerClient</code> is used to create a full physical address.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ignore-network-interfaces" href="#ignore-network-interfaces"></a>2.7&nbsp;Ignore Network Interfaces</h2></div></div></div><p>Sometimes, it is useful to ignore certain named network interfaces so that they can be excluded from Service Discovery registration (for example, when running in a Docker container).
The <code class="literal">LoadBalancerClient</code> is used to create a full physical address.</p><p>WARN:
This approach is now deprecated.
We suggest you use <a class="link" href="multi__spring_cloud_commons_common_abstractions.html#webflux-with-reactive-loadbalancer" title="2.6.1&nbsp;Spring WebFlux WebClient with Reactive Load Balancer">WebFlux with reactive Load-Balancer</a>
instead.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_passing_your_own_load_balancer_client_configuration" href="#_passing_your_own_load_balancer_client_configuration"></a>2.6.3&nbsp;Passing your own Load-Balancer Client configuration</h3></div></div></div><p>You can also use the <code class="literal">@LoadBalancerClient</code> annotation to pass your own load-balancer client configuration, passing the name of the load-balancer client and the configuration class, like so:</p><pre class="programlisting"><xslthl:annotation xmlns:xslthl="http://xslthl.sourceforge.net/">@Configuration</xslthl:annotation>
<xslthl:annotation xmlns:xslthl="http://xslthl.sourceforge.net/">@LoadBalancerClient(value = "stores", configuration = StoresLoadBalancerClientConfiguration.class)</xslthl:annotation>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MyConfiguration {
<xslthl:annotation xmlns:xslthl="http://xslthl.sourceforge.net/">@Bean</xslthl:annotation>
<xslthl:annotation xmlns:xslthl="http://xslthl.sourceforge.net/">@LoadBalanced</xslthl:annotation>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> WebClient.Builder loadBalancedWebClientBuilder() {
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> WebClient.builder();
}
}</pre><p>It is also possible to pass together multiple configurations (for more than one load-balancer client) via the <code class="literal">@LoadBalancerClients</code> annotation, as shown below:</p><pre class="programlisting"><xslthl:annotation xmlns:xslthl="http://xslthl.sourceforge.net/">@Configuration</xslthl:annotation>
<xslthl:annotation xmlns:xslthl="http://xslthl.sourceforge.net/">@LoadBalancerClients({@LoadBalancerClient(value = "stores", configuration = StoresLoadBalancerClientConfiguration.class), @LoadBalancerClient(value = "customers", configuration = CustomersLoadBalancerClientConfiguration.class)})</xslthl:annotation>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MyConfiguration {
<xslthl:annotation xmlns:xslthl="http://xslthl.sourceforge.net/">@Bean</xslthl:annotation>
<xslthl:annotation xmlns:xslthl="http://xslthl.sourceforge.net/">@LoadBalanced</xslthl:annotation>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> WebClient.Builder loadBalancedWebClientBuilder() {
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> WebClient.builder();
}
}</pre></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ignore-network-interfaces" href="#ignore-network-interfaces"></a>2.7&nbsp;Ignore Network Interfaces</h2></div></div></div><p>Sometimes, it is useful to ignore certain named network interfaces so that they can be excluded from Service Discovery registration (for example, when running in a Docker container).
A list of regular expressions can be set to cause the desired network interfaces to be ignored.
The following configuration ignores the <code class="literal">docker0</code> interface and all interfaces that start with <code class="literal">veth</code>:</p><p><b>application.yml.&nbsp;</b>
</p><pre class="screen">spring:

2
2.1.x/multi/multi_spring-cloud-commons.html
View File

File diff suppressed because one or more lines are too long

69
2.1.x/single/spring-cloud-commons.html
View File

File diff suppressed because one or more lines are too long

92
2.1.x/spring-cloud-commons.xml
View File

@@ -365,7 +365,7 @@ For instance, Eureka&#8217;s supported statuses are <literal>UP</literal>, <lite
</section>
<section xml:id="_spring_resttemplate_as_a_load_balancer_client">
<title>Spring RestTemplate as a Load Balancer Client</title>
<simpara><literal>RestTemplate</literal> can be automatically configured to use ribbon.
<simpara><literal>RestTemplate</literal> can be automatically configured to use a Load-balancer client under the hood.
To create a load-balanced <literal>RestTemplate</literal>, create a <literal>RestTemplate</literal> <literal>@Bean</literal> and use the <literal>@LoadBalanced</literal> qualifier, as shown in the following example:</simpara>
<programlisting language="java" linenumbering="unnumbered">@Configuration
public class MyConfiguration {
@@ -393,10 +393,21 @@ Individual applications must create it.</simpara>
<simpara>The URI needs to use a virtual host name (that is, a service name, not a host name).
The Ribbon client is used to create a full physical address.
See <link xl:href="https://github.com/spring-cloud/spring-cloud-netflix/blob/master/spring-cloud-netflix-ribbon/src/main/java/org/springframework/cloud/netflix/ribbon/RibbonAutoConfiguration.java">RibbonAutoConfiguration</link> for details of how the <literal>RestTemplate</literal> is set up.</simpara>
<important>
<simpara>In order to use a load-balanced <literal>RestTemplate</literal>, you need to have a load-balancer implementation in your classpath.
The recommended implementation is <literal>BlockingLoadBalancerClient</literal>
- add <literal>org.springframework.cloud:spring-cloud-loadbalancer</literal> in order to use it.
The
<literal>RibbonLoadBalancerClient</literal> also can be used, but it&#8217;s now under maintenance and we do not recommend adding it to new projects.</simpara>
</important>
<warning>
<simpara>If you want to use <literal>BlockingLoadBalancerClient</literal>, make sure you do not have
<literal>RibbonLoadBalancerClient</literal> in the project classpath, as for backward compatibility reasons, it will be used by default.</simpara>
</warning>
</section>
<section xml:id="_spring_webclient_as_a_load_balancer_client">
<title>Spring WebClient as a Load Balancer Client</title>
<simpara><literal>WebClient</literal> can be automatically configured to use the <literal>LoadBalancerClient</literal>.
<simpara><literal>WebClient</literal> can be automatically configured to use a load-balancer client.
To create a load-balanced <literal>WebClient</literal>, create a <literal>WebClient.Builder</literal> <literal>@Bean</literal> and use the <literal>@LoadBalanced</literal> qualifier, as shown in the following example:</simpara>
<programlisting language="java" linenumbering="unnumbered">@Configuration
public class MyConfiguration {
@@ -419,6 +430,22 @@ public class MyClass {
}</programlisting>
<simpara>The URI needs to use a virtual host name (that is, a service name, not a host name).
The Ribbon client is used to create a full physical address.</simpara>
<important>
<simpara>If you want to use a <literal>@LoadBalanced WebClient.Builder</literal>, you need to have a loadbalancer
implementation in the classpath. It is recommended that you add the
<literal>org.springframework.cloud:spring-cloud-loadbalancer</literal> dependency to your project.
Then, <literal>ReactiveLoadBalancer</literal> will be used underneath.
Alternatively, this functionality will also work with spring-cloud-starter-netflix-ribbon, but the request
will be handled by a non-reactive <literal>LoadBalancerClient</literal> under the hood. Additionally,
spring-cloud-starter-netflix-ribbon is already in maintenance mode, so we do not recommned
adding it to new projects.</simpara>
</important>
<tip>
<simpara>The <literal>ReactorLoadBalancer</literal> used underneath supports caching. If <literal>cacheManager</literal> is detected,
cached version of <literal>ServiceInstanceSupplier</literal> will be used. If not, we will retrieve instances
from discovery service without caching them. We recommend <link xl:href="https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-caching.html">enabling caching</link> in your project
if you use <literal>ReactiveLoadBalancer</literal>.</simpara>
</tip>
<section xml:id="_retrying_failed_requests">
<title>Retrying Failed Requests</title>
<simpara>A load-balanced <literal>RestTemplate</literal> can be configured to retry failed requests.
@@ -522,7 +549,36 @@ public class MyClass {
</section>
<section xml:id="loadbalanced-webclient">
<title>Spring WebFlux WebClient as a Load Balancer Client</title>
<simpara><literal>WebClient</literal> can be configured to use the <literal>LoadBalancerClient</literal>. <literal>LoadBalancerExchangeFilterFunction</literal> is auto-configured if <literal>spring-webflux</literal> is on the classpath. The following example shows how to configure a <literal>WebClient</literal> to use load balancer:</simpara>
<section xml:id="webflux-with-reactive-loadbalancer">
<title>Spring WebFlux WebClient with Reactive Load Balancer</title>
<simpara><literal>WebClient</literal> can be configured to use the <literal>ReactiveLoadBalancer</literal>.
If you add <literal>org.springframework.cloud:spring-cloud-loadbalancer</literal> to your project,
<literal>ReactorLoadBalancerExchangeFilterFunction</literal> is auto-configured if <literal>spring-webflux</literal> is on the classpath.
The following example shows how to configure a <literal>WebClient</literal> to use reactive load balancer under the hood:</simpara>
<programlisting language="java" linenumbering="unnumbered">public class MyClass {
@Autowired
private ReactorLoadBalancerExchangeFilterFunction lbFunction;
public Mono&lt;String&gt; doOtherStuff() {
return WebClient.builder().baseUrl("http://stores")
.filter(lbFunction)
.build()
.get()
.uri("/stores")
.retrieve()
.bodyToMono(String.class);
}
}</programlisting>
<simpara>The URI needs to use a virtual host name (that is, a service name, not a host name).
The <literal>ReactorLoadBalancerClient</literal> is used to create a full physical address.</simpara>
</section>
<section xml:id="_spring_webflux_webclient_with_non_reactive_load_balancer_client">
<title>Spring WebFlux WebClient with non-reactive Load Balancer Client</title>
<simpara>If you you don&#8217;t have <literal>org.springframework.cloud:spring-cloud-loadbalancer</literal> in your project,
but you do have spring-cloud-starter-netflix-ribbon, you can still use <literal>WebClient</literal> with <literal>LoadBalancerClient</literal>. <literal>LoadBalancerExchangeFilterFunction</literal>
will be auto-configured if <literal>spring-webflux</literal> is on the classpath. Please note, however, that this is
uses a non-reactive client under the hood.
The following example shows how to configure a <literal>WebClient</literal> to use load balancer:</simpara>
<programlisting language="java" linenumbering="unnumbered">public class MyClass {
@Autowired
private LoadBalancerExchangeFilterFunction lbFunction;
@@ -539,6 +595,36 @@ public class MyClass {
}</programlisting>
<simpara>The URI needs to use a virtual host name (that is, a service name, not a host name).
The <literal>LoadBalancerClient</literal> is used to create a full physical address.</simpara>
<simpara>WARN:
This approach is now deprecated.
We suggest you use <link linkend="webflux-with-reactive-loadbalancer">WebFlux with reactive Load-Balancer</link>
instead.</simpara>
</section>
<section xml:id="_passing_your_own_load_balancer_client_configuration">
<title>Passing your own Load-Balancer Client configuration</title>
<simpara>You can also use the <literal>@LoadBalancerClient</literal> annotation to pass your own load-balancer client configuration, passing the name of the load-balancer client and the configuration class, like so:</simpara>
<programlisting language="java" linenumbering="unnumbered">@Configuration
@LoadBalancerClient(value = "stores", configuration = StoresLoadBalancerClientConfiguration.class)
public class MyConfiguration {
@Bean
@LoadBalanced
public WebClient.Builder loadBalancedWebClientBuilder() {
return WebClient.builder();
}
}</programlisting>
<simpara>It is also possible to pass together multiple configurations (for more than one load-balancer client) via the <literal>@LoadBalancerClients</literal> annotation, as shown below:</simpara>
<programlisting language="java" linenumbering="unnumbered">@Configuration
@LoadBalancerClients({@LoadBalancerClient(value = "stores", configuration = StoresLoadBalancerClientConfiguration.class), @LoadBalancerClient(value = "customers", configuration = CustomersLoadBalancerClientConfiguration.class)})
public class MyConfiguration {
@Bean
@LoadBalanced
public WebClient.Builder loadBalancedWebClientBuilder() {
return WebClient.builder();
}
}</programlisting>
</section>
</section>
<section xml:id="ignore-network-interfaces">
<title>Ignore Network Interfaces</title>