|
对于最新的稳定版本，请使用 Spring Cloud Commons 4.3.0！ |
Spring Cloud Commons：常见抽象
服务发现、负载平衡和断路器等模式适用于所有 Spring Cloud 客户端都可以使用的通用抽象层，与实现无关（例如，使用 Eureka 或 Consul 进行发现）。
这@EnableDiscoveryClient注解
Spring Cloud Commons 提供了@EnableDiscoveryClient注解。
这将查找DiscoveryClient和ReactiveDiscoveryClient接口META-INF/spring.factories.
发现客户端的实现将配置类添加到spring.factories在org.springframework.cloud.client.discovery.EnableDiscoveryClient钥匙。
示例DiscoveryClient实现包括 Spring Cloud Netflix Eureka、Spring Cloud Consul Discovery 和 Spring Cloud Zookeeper Discovery。
默认情况下，Spring Cloud 将提供阻塞和响应式服务发现客户端。
您可以通过设置spring.cloud.discovery.blocking.enabled=false或spring.cloud.discovery.reactive.enabled=false.
要完全禁用服务发现，您只需将spring.cloud.discovery.enabled=false.
默认情况下，的实现DiscoveryClient自动将本地 Spring Boot 服务器注册到远程发现服务器。
可以通过将autoRegister=false在@EnableDiscoveryClient.
@EnableDiscoveryClient不再需要。
你可以将一个DiscoveryClient实现，以使 Spring Boot 应用程序向服务发现服务器注册。 |
健康指标
Commons 自动配置以下 Spring Boot 运行状况指示器。
发现客户端健康指标
此健康指标基于当前注册的DiscoveryClient实现。
-
要完全禁用，请将
spring.cloud.discovery.client.health-indicator.enabled=false. -
要禁用描述字段，请将
spring.cloud.discovery.client.health-indicator.include-description=false. 否则，它可能会冒泡为description卷起来的HealthIndicator. -
要禁用服务检索，请将
spring.cloud.discovery.client.health-indicator.use-services-query=false. 默认情况下，该指标调用客户端的getServices方法。在具有许多注册服务的部署中，它也可能 在每次检查期间检索所有服务的成本很高。这将跳过服务检索，而是使用客户端的probe方法。
订购DiscoveryClient实例
DiscoveryClient接口扩展Ordered.这在使用多重发现时非常有用
clients，因为它允许您定义返回的发现客户端的顺序，类似于
如何对 Spring 应用程序加载的 bean 进行排序。默认情况下，任何DiscoveryClient设置为0.如果您想为自定义设置不同的顺序DiscoveryClient实现，你只需要覆盖
这getOrder()方法，以便返回适合您的设置的值。除此之外，您还可以使用
属性来设置DiscoveryClientSpring Cloud 提供的实现等ConsulDiscoveryClient,EurekaDiscoveryClient和ZookeeperDiscoveryClient.为此，您只需将spring.cloud.{clientIdentifier}.discovery.order（或eureka.client.order对于 Eureka）属性设置为所需值。
简单发现客户端
如果没有 Service-Registry 支持的DiscoveryClient在类路径中，SimpleDiscoveryClientinstance，它使用属性来获取有关服务和实例的信息。
有关可用实例的信息应以以下格式传递给 via 属性：spring.cloud.discovery.client.simple.instances.service1[0].uri=http://s11:8080哪里spring.cloud.discovery.client.simple.instances是公共前缀，则service1站
对于相关服务的 ID，而[0]表示实例的索引号
（如示例所示，索引以0），然后是uri是
实例可用的实际 URI。
服务注册表
共享资源现在提供了一个ServiceRegistry接口，该接口提供诸如register(Registration)和deregister(Registration)，这允许您提供自定义注册服务。Registration是一个标记接口。
以下示例显示了ServiceRegistry使用中：
@Configuration
@EnableDiscoveryClient(autoRegister=false)
public class MyConfiguration {
private ServiceRegistry registry;
public MyConfiguration(ServiceRegistry registry) {
this.registry = registry;
}
// called through some external process, such as an event or a custom actuator endpoint
public void register() {
Registration registration = constructRegistration();
this.registry.register(registration);
}
}每ServiceRegistry实现有自己的Registry实现。
-
ZookeeperRegistration与ZookeeperServiceRegistry -
EurekaRegistration与EurekaServiceRegistry -
ConsulRegistration与ConsulServiceRegistry
如果您正在使用ServiceRegistry接口，您将需要将
正确Registry实现ServiceRegistry实施你
正在使用。
Spring RestTemplate 作为 LoadBalancer 客户端
您可以配置RestTemplate以使用负载均衡器客户端。
创建负载平衡的RestTemplate，创建一个RestTemplate @Bean并使用@LoadBalanced限定符，如以下示例所示：
@Configuration
public class MyConfiguration {
@LoadBalanced
@Bean
RestTemplate restTemplate() {
return new RestTemplate();
}
}
public class MyClass {
@Autowired
private RestTemplate restTemplate;
public String doOtherStuff() {
String result = restTemplate.getForObject("http://stores/stores", String.class);
return result;
}
}一个RestTemplateBean 不再通过自动配置创建。
单个应用程序必须创建它。 |
URI 需要使用虚拟主机名（即服务名称，而不是主机名）。
这BlockingLoadBalancerClient用于创建完整的物理地址。
使用负载平衡RestTemplate，则需要在类路径中实现 Spring Cloud LoadBalancer。
将 Spring Cloud LoadBalancer starter 添加到您的项目以使用它。 |
多个 RestTemplate 对象
如果你想要一个RestTemplate未负载平衡的，请创建RestTemplate豆子并注入它。
访问负载平衡RestTemplate，使用@LoadBalanced限定符@Bean，如以下示例所示：
@Configuration
public class MyConfiguration {
@LoadBalanced
@Bean
RestTemplate loadBalanced() {
return new RestTemplate();
}
@Primary
@Bean
RestTemplate restTemplate() {
return new RestTemplate();
}
}
public class MyClass {
@Autowired
private RestTemplate restTemplate;
@Autowired
@LoadBalanced
private RestTemplate loadBalanced;
public String doOtherStuff() {
return loadBalanced.getForObject("http://stores/stores", String.class);
}
public String doStuff() {
return restTemplate.getForObject("http://example.com", String.class);
}
}请注意@Primary平原上的注释RestTemplate声明，以消除不限定的歧义@Autowired注射。 |
如果您看到java.lang.IllegalArgumentException: Can not set org.springframework.web.client.RestTemplate field com.my.app.Foo.restTemplate to com.sun.proxy.$Proxy89，尝试注射RestOperations或设置spring.aop.proxyTargetClass=true. |
用@LoadBalanced RestTemplateBuilder创建 LoadBalancer 客户端
您还可以配置RestTemplate通过注释RestTemplateBuilderbean 与@LoadBalanced:
import org.springframework.boot.web.client.RestTemplateBuilder;@Configuration
public class MyConfiguration {
@Bean
@LoadBalanced
RestTemplateBuilder loadBalancedRestTemplateBuilder() {
return new RestTemplateBuilder();
}
}
public class MyClass {
private final RestTemplate restTemplate;
MyClass(@LoadBalanced RestTemplateBuilder restTemplateBuilder) {
this.restTemplate = restTemplateBuilder.build();
}
public String getStores() {
return restTemplate.getForObject("http://stores/stores", String.class);
}
}URI 需要使用虚拟主机名（即服务名称，而不是主机名）。
这BlockingLoadBalancerClient用于创建完整的物理地址。
为了利用 Spring Boot 提供的附加功能RestTemplateBuilder（例如，可观测性支持），您可能希望使用自动配置的RestTemplateBuilderConfigurer在创建@LoadBalanced RestTemplateBuilder豆：
@Configuration
public class MyConfiguration {
@LoadBalanced
RestTemplateBuilder loadBalancedRestTemplateBuilder(RestTemplateBuilderConfigurer configurer) {
return configurer.configure(new RestTemplateBuilder());
}
}| 要使用它，请将 Spring Cloud LoadBalancer starter 添加到您的项目中。 |
倍数RestTemplateBuilder豆
如果你想要一个RestTemplateBuilder未负载平衡的，请创建RestTemplateBuilder豆子并注入它。
访问负载平衡RestTemplateBuilder，使用@LoadBalanced限定符@Bean，如以下示例所示：
@Configuration
public class MyConfiguration {
@LoadBalanced
@Bean
RestTemplateBuilder loadBalancedRestTemplateBuilder() {
return new RestTemplateBuilder();
}
@Primary
@Bean
RestTemplateBuilder restTemplateBuilder() {
return new RestTemplateBuilder();
}
}
public class MyClass {
@Autowired
private RestTemplateBuilder restTemplateBuilder;
@Autowired
@LoadBalanced
private RestTemplateBuilder loadBalanced;
public String doOtherStuff() {
return loadBalanced.getForObject("http://stores/stores", String.class);
}
public String doStuff() {
return restTemplateBuilder.build().getForObject("http://example.com", String.class);
}
}请注意@Primary平原上的注释RestTemplateBuilder声明，以消除不限定的歧义@Autowired注射。 |
Spring RestClient 作为 LoadBalancer 客户端
您可以配置RestClient以使用负载均衡器客户端。
创建负载平衡的RestClient，创建一个RestClient.Builder @Bean并使用@LoadBalanced限定符，如以下示例所示：
@Configuration
public class MyConfiguration {
@LoadBalanced
@Bean
RestClient.Builder restClientBuilder() {
return RestClient.builder();
}
}
public class MyClass {
@Autowired
private RestClient.Builder restClientBuilder;
public String doOtherStuff() {
return restClientBuilder.build().get().uri(URI.create("http://stores/stores")).retrieve().body(String.class);
}
}URI 需要使用虚拟主机名（即服务名称，而不是主机名）。
这BlockingLoadBalancerClient用于创建完整的物理地址。
为了利用 Spring Boot 提供的附加功能RestClient.Builder（例如，可观测性支持），您可能希望使用自动配置的RestClientBuilderConfigurer在创建@LoadBalanced RestClient.Builder豆：
@Configuration
public class MyConfiguration {
@LoadBalanced
@Bean
RestClient.Builder restClientBuilder(RestClientBuilderConfigurer configurer) {
return configurer.configure(RestClient.builder());
}
}| 要使用它，请将 Spring Cloud LoadBalancer starter 添加到您的项目中。 |
倍数RestClient.Builder对象
如果你想要一个RestClient.Builder未负载平衡的，请创建RestClient.Builder豆子并注入它。
访问负载平衡RestClient.Builder，使用@LoadBalanced限定符@Bean，如以下示例所示：
@Configuration
public class MyConfiguration {
@LoadBalanced
@Bean
RestClient.Builder loadBalanced() {
return RestClient.builder();
}
@Primary
@Bean
RestClient.Builder restClientBuilder() {
return RestClient.builder();
}
}
public class MyClass {
@Autowired
private RestClient.Builder restClientBuilder;
@Autowired
@LoadBalanced
private RestClient.Builder loadBalanced;
public String doOtherStuff() {
return loadBalanced.build().get().uri("http://stores/stores")
.retrieve().body(String.class);
}
public String doStuff() {
return restClientBuilder.build().get().uri("http://example.com")
.retrieve().body(String.class);
}
}请注意@Primary平原上的注释RestClient.Builder声明，以消除不限定的歧义@Autowired注射。 |
Spring WebClient 作为 LoadBalancer 客户端
您可以配置WebClient自动使用负载均衡器客户端。
创建负载平衡的WebClient，创建一个WebClient.Builder @Bean并使用@LoadBalanced限定符，如下所示：
@Configuration
public class MyConfiguration {
@Bean
@LoadBalanced
public WebClient.Builder loadBalancedWebClientBuilder() {
return WebClient.builder();
}
}
public class MyClass {
@Autowired
private WebClient.Builder webClientBuilder;
public Mono<String> doOtherStuff() {
return webClientBuilder.build().get().uri("http://stores/stores")
.retrieve().bodyToMono(String.class);
}
}URI 需要使用虚拟主机名（即服务名称，而不是主机名）。 Spring Cloud LoadBalancer 用于创建完整的物理地址。
为了利用 Spring Boot 提供的附加功能WebClient.Builder（例如，可观测性支持），您可能希望使用自动配置的WebClientCustomizerbean 时创建@LoadBalanced WebClient.Builder豆：
@Configuration
public class MyConfiguration {
@Bean
@LoadBalanced
public WebClient.Builder loadBalancedWebClientBuilder(ObjectProvider<WebClientCustomizer> customizerProvider) {
WebClient.Builder builder = WebClient.builder();
customizerProvider.orderedStream().forEach((customizer) -> customizer.customize(builder));
return builder;
}
}如果要使用@LoadBalanced WebClient.Builder，您需要有一个 Spring Cloud LoadBalancer
在类路径中实现。我们建议您将 Spring Cloud LoadBalancer Starters添加到您的项目中。
然后ReactiveLoadBalancer用于下面。 |
倍数WebClient.Builder对象
如果你想要一个WebClient.Buider未负载平衡的，请创建WebClient豆子并注入它。
访问负载平衡WebClient.Builder，使用@LoadBalanced限定符@Bean，如以下示例所示：
@Configuration
public class MyConfiguration {
@LoadBalanced
@Bean
WebClient.Builder loadBalanced() {
return WebClient.builder();
}
@Primary
@Bean
WebClient.Builder webClientBuilder() {
return WebClient.builder();
}
}
public class MyClass {
@Autowired
private WebClient.Builder webClientBuilder;
@Autowired
@LoadBalanced
private WebClient.Builder loadBalanced;
public Mono<String> doOtherStuff() {
return loadBalanced.build().get().uri("http://stores/stores")
.retrieve().bodyToMono(String.class);
}
public Mono<String> doStuff() {
return webClientBuilder.build().get().uri("http://example.com")
.retrieve().bodyToMono(String.class);
}
}重试失败的请求
负载平衡RestTemplate可以配置为重试失败的请求。
默认情况下，此逻辑处于禁用状态。
对于非响应式版本（RestTemplate），您可以通过将 Spring Retry 添加到应用程序的类路径来启用它。对于响应式版本（使用WebTestClient），您需要设置spring.cloud.loadbalancer.retry.enabled=true.
如果要在类路径上禁用 Spring Retry 或 Reactive Retry 的重试逻辑，可以将spring.cloud.loadbalancer.retry.enabled=false.
对于非响应式实现，如果您想实现BackOffPolicy在重试中，您需要创建一个类型为LoadBalancedRetryFactory并覆盖createBackOffPolicy()方法。
对于响应式实现，您只需通过设置spring.cloud.loadbalancer.retry.backoff.enabled自false.
您可以设置：
-
spring.cloud.loadbalancer.retry.maxRetriesOnSameServiceInstance- 表示请求应在同一次上重试多少次ServiceInstance（为每个选定的实例单独计算） -
spring.cloud.loadbalancer.retry.maxRetriesOnNextServiceInstance- 指示应重试新选择的请求的次数ServiceInstance -
spring.cloud.loadbalancer.retry.retryableStatusCodes- 始终重试失败请求的状态代码。
对于响应式实现，您可以额外设置：
-spring.cloud.loadbalancer.retry.backoff.minBackoff- 设置最小回退持续时间（默认为 5 毫秒）
-spring.cloud.loadbalancer.retry.backoff.maxBackoff- 设置最大回退持续时间（默认情况下，最大长值为毫秒）
-spring.cloud.loadbalancer.retry.backoff.jitter- 设置用于计算每次调用的实际回退持续时间的抖动（默认为 0.5）。
对于响应式实现，您还可以实现自己的LoadBalancerRetryPolicy以更详细地控制负载平衡的呼叫重试。
对于这两种实现，您还可以通过在spring.cloud.loadbalancer.[serviceId].retry.retryable-exceptions财产。如果您这样做，我们确保将RetryableStatusCodeExceptions到你提供的异常列表，以便我们也重试可重试的状态代码。如果您没有通过属性指定任何例外，则我们默认使用的例外是IOException,TimeoutException和RetryableStatusCodeException.您还可以通过设置spring.cloud.loadbalancer.[serviceId].retry.retry-on-all-exceptions自true.
如果您将阻塞实现与 Spring Retries 一起使用，如果您想保留以前版本的行为，请将spring.cloud.loadbalancer.[serviceId].retry.retry-on-all-exceptions自true因为这曾经是阻止实现的默认模式。 |
单个 Loadbalancer 客户端可以单独配置为与上述相同的属性，但前缀是spring.cloud.loadbalancer.clients.<clientId>.*哪里clientId是负载均衡器的名称。 |
对于负载平衡的重试，默认情况下，我们将ServiceInstanceListSupplierbean 与RetryAwareServiceInstanceListSupplier选择与之前选择的实例不同的实例（如果可用）。您可以通过将spring.cloud.loadbalancer.retry.avoidPreviousInstance自false. |
@Configuration
public class MyConfiguration {
@Bean
LoadBalancedRetryFactory retryFactory() {
return new LoadBalancedRetryFactory() {
@Override
public BackOffPolicy createBackOffPolicy(String service) {
return new ExponentialBackOffPolicy();
}
};
}
}如果要添加一个或多个RetryListener实现重试功能，您需要
创建类型LoadBalancedRetryListenerFactory并返回RetryListener数组
您希望用于给定服务，如以下示例所示：
@Configuration
public class MyConfiguration {
@Bean
LoadBalancedRetryListenerFactory retryListenerFactory() {
return new LoadBalancedRetryListenerFactory() {
@Override
public RetryListener[] createRetryListeners(String service) {
return new RetryListener[]{new RetryListener() {
@Override
public <T, E extends Throwable> boolean open(RetryContext context, RetryCallback<T, E> callback) {
//TODO Do you business...
return true;
}
@Override
public <T, E extends Throwable> void close(RetryContext context, RetryCallback<T, E> callback, Throwable throwable) {
//TODO Do you business...
}
@Override
public <T, E extends Throwable> void onError(RetryContext context, RetryCallback<T, E> callback, Throwable throwable) {
//TODO Do you business...
}
}};
}
};
}
}Spring WebFluxWebClient作为负载均衡器客户端
Spring WebFlux 可以处理响应式和非响应式WebClient配置，如主题所述：
Spring WebFluxWebClient跟ReactorLoadBalancerExchangeFilterFunction
您可以配置WebClient使用ReactiveLoadBalancer.
如果将 Spring Cloud LoadBalancer starter 添加到项目中
如果spring-webflux在类路径上，ReactorLoadBalancerExchangeFilterFunction是自动配置的。
以下示例演示如何配置WebClient要使用响应式负载均衡器，请执行以下作：
public class MyClass {
@Autowired
private ReactorLoadBalancerExchangeFilterFunction lbFunction;
public Mono<String> doOtherStuff() {
return WebClient.builder().baseUrl("http://stores")
.filter(lbFunction)
.build()
.get()
.uri("/stores")
.retrieve()
.bodyToMono(String.class);
}
}URI 需要使用虚拟主机名（即服务名称，而不是主机名）。
这ReactorLoadBalancer用于创建完整的物理地址。
Spring WebFluxWebClient使用非响应式负载均衡器客户端
如果spring-webflux在类路径上，LoadBalancerExchangeFilterFunction是自动配置的。但是请注意，这
在后台使用非响应式客户端。
以下示例演示如何配置WebClient要使用 load-balancer，请执行以下作：
public class MyClass {
@Autowired
private LoadBalancerExchangeFilterFunction lbFunction;
public Mono<String> doOtherStuff() {
return WebClient.builder().baseUrl("http://stores")
.filter(lbFunction)
.build()
.get()
.uri("/stores")
.retrieve()
.bodyToMono(String.class);
}
}URI 需要使用虚拟主机名（即服务名称，而不是主机名）。
这LoadBalancerClient用于创建完整的物理地址。
WARN：这种方法现在已被弃用。 我们建议您将 WebFlux 与响应式负载均衡器一起使用。
忽略网络接口
有时，忽略某些命名网络接口会很有用，以便可以将它们从服务发现注册中排除（例如，在 Docker 容器中运行时）。
可以设置正则表达式列表以忽略所需的网络接口。
以下配置忽略了docker0interface 和所有以veth:
spring:
cloud:
inetutils:
ignoredInterfaces:
- docker0
- veth.*
您还可以使用正则表达式列表强制仅使用指定的网络地址，如以下示例所示：
spring:
cloud:
inetutils:
preferredNetworks:
- 192.168
- 10.0
还可以强制仅使用站点本地地址，如以下示例所示：
spring:
cloud:
inetutils:
useOnlySiteLocalInterfaces: true
有关站点本地地址构成的更多详细信息，请参阅 Inet4Address.html.isSiteLocalAddress（）。
启用的功能
Spring Cloud Commons 提供了一个/features执行器端点。
此端点返回类路径上可用的功能以及它们是否已启用。
返回的信息包括功能类型、名称、版本和提供商。
特征类型
有两种类型的“特征”：抽象和命名。
抽象功能是定义接口或抽象类以及创建的实现的功能，例如DiscoveryClient,LoadBalancerClient或LockService. 抽象类或接口用于在上下文中查找该类型的 bean。显示的版本是bean.getClass().getPackage().getImplementationVersion().
命名功能是它们没有实现的特定类的功能。这些功能包括“断路器”、“API 网关”、“Spring Cloud Bus”等。这些功能需要名称和 bean 类型。
声明功能
任何模块都可以声明任意数量的HasFeaturebean，如以下示例所示：
@Bean
public HasFeatures commonsFeatures() {
return HasFeatures.abstractFeatures(DiscoveryClient.class, LoadBalancerClient.class);
}
@Bean
public HasFeatures consulFeatures() {
return HasFeatures.namedFeatures(
new NamedFeature("Spring Cloud Bus", ConsulBusAutoConfiguration.class),
new NamedFeature("Circuit Breaker", HystrixCommandAspect.class));
}
@Bean
HasFeatures localFeatures() {
return HasFeatures.builder()
.abstractFeature(Something.class)
.namedFeature(new NamedFeature("Some Other Feature", Someother.class))
.abstractFeature(Somethingelse.class)
.build();
}这些豆子中的每一个都应该放在适当的保护下@Configuration.
Spring Cloud 兼容性验证
由于一些用户在设置 Spring Cloud 应用程序时遇到问题，我们决定 以添加兼容性验证机制。如果您当前的设置不兼容，它将中断 与 Spring Cloud 需求一起使用，以及一份报告，显示到底出了什么问题。
目前，我们正在验证将哪个版本的 Spring Boot 添加到您的类路径中。
报告示例
*************************** APPLICATION FAILED TO START *************************** Description: Your project setup is incompatible with our requirements due to following reasons: - Spring Boot [2.1.0.RELEASE] is not compatible with this Spring Cloud release train Action: Consider applying the following actions: - Change Spring Boot version to one of the following versions [1.2.x, 1.3.x] . You can find the latest Spring Boot versions here [https://spring.io/projects/spring-boot#learn]. If you want to learn more about the Spring Cloud Release train compatibility, you can visit this page [https://spring.io/projects/spring-cloud#overview] and check the [Release Trains] section.
要禁用此功能，请将spring.cloud.compatibility-verifier.enabled自false.
如果要覆盖兼容的 Spring Boot 版本，只需将spring.cloud.compatibility-verifier.compatible-boot-versions带有逗号分隔列表的属性
兼容的 Spring Boot 版本。