Zookeeper Dependencies

以下主题介绍如何处理 Spring Cloud Zookeeper 依赖项:

The following topics cover how to work with Spring Cloud Zookeeper dependencies:

Using the Zookeeper Dependencies

Spring Cloud Zookeeper 让您可以将应用程序的依赖项作为属性提供。您理解的依赖项可能是注册在 Zookeeper 中,您想通过 OpenFeign(一个 REST 客户端构建器)、RestTemplateWebClient 通过 Spring Cloud Loadbalancer 来调用的其他应用程序。

Spring Cloud Zookeeper gives you a possibility to provide dependencies of your application as properties. As dependencies, you can understand other applications that are registered in Zookeeper and which you would like to call through OpenFeign (a REST client builder), RestTemplate and WebClient via Spring Cloud Loadbalancer.

您还可以使用 Zookeeper Dependency Watchers 功能来控制和监视依赖项的状态。

You can also use the Zookeeper Dependency Watchers functionality to control and monitor the state of your dependencies.

Activating Zookeeper Dependencies

包含对 org.springframework.cloud:spring-cloud-starter-zookeeper-discovery 的依赖项将启用自动配置,该配置将设置 Spring Cloud Zookeeper 依赖项。即使您在属性中提供了依赖项,也可以关闭依赖项。要执行此操作,请将 spring.cloud.zookeeper.dependency.enabled 属性设置为 false(默认为 true)。

Including a dependency on org.springframework.cloud:spring-cloud-starter-zookeeper-discovery enables autoconfiguration that sets up Spring Cloud Zookeeper Dependencies. Even if you provide the dependencies in your properties, you can turn off the dependencies. To do so, set the spring.cloud.zookeeper.dependency.enabled property to false (it defaults to true).

Setting up Zookeeper Dependencies

考虑以下依赖关系表示的示例:

Consider the following example of dependency representation:

application.yml
spring.application.name: yourServiceName
spring.cloud.zookeeper:
  dependencies:
    newsletter:
      path: /path/where/newsletter/has/registered/in/zookeeper
      loadBalancerType: ROUND_ROBIN
      contentTypeTemplate: application/vnd.newsletter.$version+json
      version: v1
      headers:
        header1:
            - value1
        header2:
            - value2
      required: false
      stubs: org.springframework:foo:stubs
    mailing:
      path: /path/where/mailing/has/registered/in/zookeeper
      loadBalancerType: ROUND_ROBIN
      contentTypeTemplate: application/vnd.mailing.$version+json
      version: v1
      required: true

接下来的几节将逐一介绍依赖项的每个部分。根属性名称为 spring.cloud.zookeeper.dependencies

The next few sections go through each part of the dependency one by one. The root property name is spring.cloud.zookeeper.dependencies.

Aliases

在 root 属性下方,你必须表示每个依赖项为一个别名。这是由于 Spring Cloud LoadBalancer 的限制,它要求应用程序标识符放入 URL。因此,你不能传递任何复杂路径,例如 /myApp/myRoute/name。该别名是你在 DiscoveryClientFeignRestTemplate 中用于替代 serviceId 的名称。

Below the root property you have to represent each dependency as an alias. This is due to the constraints of Spring Cloud LoadBalancer, which requires that the application ID be placed in the URL. Consequently, you cannot pass any complex path, suchas /myApp/myRoute/name). The alias is the name you use instead of the serviceId for DiscoveryClient, Feign, or RestTemplate.

在前面的示例中,别名是 newslettermailing。下面的示例展示了带有 newsletter 别名的 Feign 用法:

In the previous examples, the aliases are newsletter and mailing. The following example shows Feign usage with a newsletter alias:

@FeignClient("newsletter")
public interface NewsletterService {
        @RequestMapping(method = RequestMethod.GET, value = "/newsletter")
        String getNewsletters();
}

Path

路径由 path YAML 属性表示,这是依赖项在 Zookeeper 下注册的路径。如 previous section 中所述,Spring Cloud LoadBalancer 在 URL 上运行。因此,此路径不符合其要求。这就是 Spring Cloud Zookeeper 将别名映射到适当路径的原因。

The path is represented by the path YAML property and is the path under which the dependency is registered under Zookeeper. As described in the previous section, Spring Cloud LoadBalancer operates on URLs. As a result, this path is not compliant with its requirement. That is why Spring Cloud Zookeeper maps the alias to the proper path.

Load Balancer Type

负载均衡器类型由 loadBalancerType YAML 属性表示。

The load balancer type is represented by loadBalancerType YAML property.

如果你了解在调用此特定依赖项时应该应用哪种负载均衡策略,则可以在 YAML 文件中提供它,并且它会自动应用。你可以选择以下负载均衡策略之一:

If you know what kind of load-balancing strategy has to be applied when calling this particular dependency, you can provide it in the YAML file, and it is automatically applied. You can choose one of the following load balancing strategies:

  • STICKY: Once chosen, the instance is always called.

  • RANDOM: Picks an instance randomly.

  • ROUND_ROBIN: Iterates over instances over and over again.

Content-Type Template and Version

Content-Type 模板和版本通过 contentTypeTemplateversion YAML 属性表示。

The Content-Type template and version are represented by the contentTypeTemplate and version YAML properties.

如果你在 Content-Type 头中对 API 进行版本控制,则你不想将此头添加到你的每个请求中。此外,如果你希望调用 API 的新版本,则你不想四处游荡你的代码来提升 API 版本。这就是你能提供一个带有特殊 $version 占位符的 contentTypeTemplate 的原因。该占位符将由 version YAML 属性的值填充。考虑以下 contentTypeTemplate 示例:

If you version your API in the Content-Type header, you do not want to add this header to each of your requests. Also, if you want to call a new version of the API, you do not want to roam around your code to bump up the API version. That is why you can provide a contentTypeTemplate with a special $version placeholder. That placeholder will be filled by the value of the version YAML property. Consider the following example of a contentTypeTemplate:

application/vnd.newsletter.$version+json

进一步考虑以下 version

Further consider the following version:

v1

contentTypeTemplate 和版本相结合,将创建 Content-Type 头部包含每个请求,如下所示:

The combination of contentTypeTemplate and version results in the creation of a Content-Type header for each request, as follows:

application/vnd.newsletter.v1+json

Default Headers

默认头通过 YAML 中的 headers 映射表示。

Default headers are represented by the headers map in YAML.

有时,对依赖项的每一次调用都需要设置一些默认头。为不在代码中执行此操作,你可以在 YAML 文件中设置它们,如下例所示 headers 部分:

Sometimes, each call to a dependency requires setting up of some default headers. To not do that in code, you can set them up in the YAML file, as shown in the following example headers section:

headers:
    Accept:
        - text/html
        - application/xhtml+xml
    Cache-Control:
        - no-cache

headers 部分导致在 HTTP 请求中添加 AcceptCache-Control 头部以及适当的值列表。

That headers section results in adding the Accept and Cache-Control headers with appropriate list of values in your HTTP request.

Required Dependencies

必需的依赖项由 YAML 中的 required 属性表示。

Required dependencies are represented by required property in YAML.

如果在应用程序引导时需要你的一个依赖项启动,则可以在 YAML 文件中设置 required: true 属性。

If one of your dependencies is required to be up when your application boots, you can set the required: true property in the YAML file.

如果应用程序在引导期间找不到必需的依赖项,则会抛出一个异常,并且 Spring Context 将无法设置。换句话说,如果必需的依赖项未在 Zookeeper 中注册,则应用程序无法启动。

If your application cannot localize the required dependency during boot time, it throws an exception, and the Spring Context fails to set up. In other words, your application cannot start if the required dependency is not registered in Zookeeper.

您可以在 later in this document 中阅读有关 Spring Cloud Zookeeper Presence Checker 的更多信息。

You can read more about Spring Cloud Zookeeper Presence Checker later in this document.

Stubs

你可以提供一个冒号分隔的路径到包含依赖项存根的 JAR,如下例所示:

You can provide a colon-separated path to the JAR containing stubs of the dependency, as shown in the following example:

stubs: org.springframework:myApp:stubs

其中:

where:

  • org.springframework is the groupId.

  • myApp is the artifactId.

  • stubs is the classifier. (Note that stubs is the default value.)

因为 stubs 是默认分类器,所以前面的示例等于下面的示例:

Because stubs is the default classifier, the preceding example is equal to the following example:

stubs: org.springframework:myApp

Configuring Spring Cloud Zookeeper Dependencies

您可以设置以下属性启用或禁用 Zookeeper 依赖项功能的部分:

You can set the following properties to enable or disable parts of Zookeeper Dependencies functionalities:

  • spring.cloud.zookeeper.dependencies: If you do not set this property, you cannot use Zookeeper Dependencies.

  • spring.cloud.zookeeper.dependency.loadbalancer.enabled (enabled by default): Turns on Zookeeper-specific custom load-balancing strategies, including ZookeeperServiceInstanceListSupplier and dependency-based load-balanced RestTemplate setup.

  • spring.cloud.zookeeper.dependency.headers.enabled (enabled by default): This property registers a FeignBlockingLoadBalancerClient that automatically appends appropriate headers and content types with their versions, as presented in the Dependency configuration. Without this setting, those two parameters do not work.

  • spring.cloud.zookeeper.dependency.resttemplate.enabled (enabled by default): When enabled, this property modifies the request headers of a @LoadBalanced-annotated RestTemplate such that it passes headers and content type with the version set in dependency configuration. Without this setting, those two parameters do not work.