|
此版本仍在开发中，尚未被视为稳定版本。对于最新的稳定版本，请使用 Spring Cloud Commons 4.1.5！ |
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 健康指示器。
DiscoveryClientHealthIndicator
此运行状况指示器基于当前注册的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.如果您想为您的自定义设置不同的顺序DiscoveryClientimplementations 中，你只需要覆盖
这getOrder()方法，以便返回适合您设置的值。除此之外，您还可以使用
properties 来设置DiscoveryClientSpring Cloud 提供的实现等ConsulDiscoveryClient,EurekaDiscoveryClient和ZookeeperDiscoveryClient.为此，您只需设置spring.cloud.{clientIdentifier}.discovery.order（或eureka.client.orderfor Eureka） 属性设置为所需的值。
SimpleDiscovery客户端
如果没有 Service-Registry 支持的DiscoveryClient在 Classpath 中，SimpleDiscoveryClient实例，该实例使用属性来获取有关服务和实例的信息。
有关可用实例的信息应按以下格式通过 properties 传递给：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 服务
Commons 现在提供了一个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);
}
}每ServiceRegistryimplementation 有自己的Registry实现。
-
ZookeeperRegistration用于ZookeeperServiceRegistry -
EurekaRegistration用于EurekaServiceRegistry -
ConsulRegistration用于ConsulServiceRegistry
如果您使用的是ServiceRegistry接口中，您需要将
正确Registry实现ServiceRegistry实施
正在使用。
ServiceRegistry 自动注册
默认情况下，ServiceRegistryimplementation 会自动注册正在运行的服务。
要禁用该行为，您可以设置：
*@EnableDiscoveryClient(autoRegister=false)以永久禁用自动注册。
*spring.cloud.service-registry.auto-registration.enabled=false以通过配置禁用该行为。
Service Registry Actuator 端点
Spring Cloud Commons 提供了一个/serviceregistryactuator 端点。
此终端节点依赖于Registrationbean 的 bean 中。
叫/serviceregistrywith GET 返回Registration.
对带有 JSON 正文的同一终端节点使用 POST 会更改当前Registration设置为新值。
JSON 正文必须包含status字段。
请参阅ServiceRegistry更新 Status 时用于 allowed 值的 implementation 以及为 status 返回的值。
例如，Eureka 支持的状态是UP,DOWN,OUT_OF_SERVICE和UNKNOWN.
Spring RestTemplate作为LoadBalancer客户端
您可以配置RestTemplate以使用 Load-balancer 客户端。
创建负载平衡RestTemplate，创建一个RestTemplate @Bean并使用@LoadBalancedqualifier 中，如下例所示：
@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，你需要在 Classpath 中有一个 Spring Cloud LoadBalancer 实现。
将 Spring Cloud LoadBalancer starter 添加到您的项目中，以便使用它。 |
多个 RestTemplate 对象
如果您想要RestTemplate，请创建一个RestTemplatebean 并注入它。
要访问负载平衡的RestTemplate，请使用@LoadBalancedqualifier 时，您创建@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. |
Spring RestClient作为LoadBalancer客户端
您可以配置RestClient以使用 Load-balancer 客户端。
创建负载平衡RestClient，创建一个RestClient.Builder @Bean并使用@LoadBalancedqualifier 中，如下例所示：
@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（例如，可观察性支持）您可能希望使用 autoconfiguredRestClientBuilderConfigurer在创建@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.Builderbean 并注入它。
要访问负载平衡的RestClient，请使用@LoadBalancedqualifier 时，您创建@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平原上的注释RestTemplate声明来消除非限定@Autowired注射。 |
Spring WebClient 作为 LoadBalancer 客户端
您可以配置WebClient以自动使用负载均衡器客户端。
创建负载平衡WebClient，创建一个WebClient.Builder @Bean并使用@LoadBalancedqualifier 中，如下所示：
@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（例如，可观察性支持）您可能希望使用 autoconfiguredWebClientCustomizerbean 创建@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
implementation 的 API 中。我们建议您将 Spring Cloud LoadBalancer starter 添加到您的项目中。
然后ReactiveLoadBalancer在下面使用。 |
倍数WebClient.Builder对象
如果您想要WebClient.Buider，请创建一个WebClientbean 并注入它。
要访问负载平衡的WebClient.Builder，请使用@LoadBalancedqualifier 时，您创建@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 添加到应用程序的 Classpath 来启用它。对于响应式版本（使用WebTestClient），您需要设置spring.cloud.loadbalancer.retry.enabled=true.
如果你想在 classpath 上使用 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添加到您提供的异常列表中，以便我们也对可重试的状态代码进行重试。如果您没有通过 properties 指定任何例外，我们默认使用的例外是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因为这曾经是 blocking 实现的默认模式。 |
单个 Loadbalancer 客户端可以使用与上述相同的属性单独配置，但前缀为spring.cloud.loadbalancer.clients.<clientId>.*哪里clientId是 LoadBalancer 的名称。 |
对于负载均衡重试，默认情况下，我们将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实现到您的重试功能中，您需要
创建一个 bean 类型的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位于 Classpath 上，ReactorLoadBalancerExchangeFilterFunction是自动配置的。
以下示例显示如何配置WebClient要使用 Reactive Load Balancer：
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位于 Classpath 上，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用于创建完整的物理地址。
警告：此方法现已弃用。 我们建议您改用 WebFlux 和反应式 Load-Balancer。
忽略网络接口
有时，忽略某些命名网络接口很有用，这样就可以将它们从 Service Discovery 注册中排除（例如，在 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（） 了解有关站点本地地址的更多详细信息。
HTTP 客户端工厂
Spring Cloud Commons 提供了用于创建 Apache HTTP 客户端（ApacheHttpClientFactory） 和 OK HTTP 客户端 （OkHttpClientFactory).
这OkHttpClientFactory仅当 OK HTTP jar 位于 Classpath 上时，才会创建 bean。
此外，Spring Cloud Commons 提供了用于创建两个客户端使用的连接管理器的 bean：ApacheHttpClientConnectionManagerFactory对于 Apache HTTP 客户端和OkHttpClientConnectionPoolFactory对于 OK HTTP 客户端。
如果要自定义在下游项目中创建 HTTP Client 端的方式，则可以提供这些 bean 的自己的实现。
此外，如果您提供HttpClientBuilder或OkHttpClient.Builder中，默认工厂使用这些构建器作为返回到下游项目的构建器的基础。
您还可以通过设置spring.cloud.httpclientfactories.apache.enabled或spring.cloud.httpclientfactories.ok.enabled自false.
启用的功能
Spring Cloud Commons 提供了一个/featuresactuator 端点。
此端点返回 Classpath 上可用的功能以及这些功能是否已启用。
返回的信息包括功能类型、名称、版本和供应商。
特征类型
有两种类型的 “特征”：抽象的和命名的。
抽象功能是定义了接口或抽象类并且创建的实现（例如DiscoveryClient,LoadBalancerClient或LockService.
抽象类或接口用于在上下文中查找该类型的 bean。
显示的版本为bean.getClass().getPackage().getImplementationVersion().
命名功能是没有它们实现的特定类的功能。这些功能包括 “Circuit Breaker”、“API Gateway”、“Spring Cloud Bus” 等。这些功能需要一个 name 和一个 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();
}这些 bean 中的每一个都应该放入一个适当保护的@Configuration.
Spring Cloud 兼容性验证
由于一些用户在设置 Spring Cloud 应用程序时遇到问题，我们决定 添加兼容性验证机制。如果您当前的设置不兼容，它将中断 以及 Spring Cloud 需求，以及一份报告，显示到底出了什么问题。
目前，我们验证将哪个版本的 Spring Boot 添加到您的 Classpath 中。
报告示例
*************************** 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 版本。