Spring Cloud Consul 中文文档参考手册中文版

1.2.0.RELEASE

该项目通过自动配置并绑定到Spring环境和其他Spring编程模型成语，为Spring Boot应用程序提供Consul集成。通过几个简单的注释，您可以快速启用和配置应用程序中的常见模式，并使用基于Consul的组件构建大型分布式系统。提供的模式包括服务发现，控制总线和配置。智能路由（Zuul）和客户端负载平衡（Ribbon），断路器（Hystrix）通过与Spring Cloud Netflix的集成提供。

安装Consul

请参阅安装文档获取有关如何安装Consul指令。

Consul Agent

所有Spring Cloud Consul应用程序必须可以使用Consul Agent客户端。默认情况下，代理客户端预计位于localhost:8500。有关如何启动代理客户端以及如何连接到Consul Agent服务器的集群的详细信息，请参阅代理文档。对于开发人员，在安装了领事后，您可以使用以下命令启动Consul Agent：

./src/main/bash/local_run_consul.sh

这将启动端口8500上的服务器模式的代理，其中ui可以在http：// localhost：8500上找到

服务发现与Consul

服务发现是基于微服务架构的关键原则之一。尝试配置每个客户端或某种形式的约定可能非常困难，可以非常脆弱。Consul通过HTTP API和DNS提供服务发现服务。Spring Cloud Consul利用HTTP API进行服务注册和发现。这不会阻止非Spring云应用程序利用DNS界面。Consul代理服务器在通过八卦协议进行通信的群集中运行，并使用筏式协议协议。

如何激活

要激活Consul服务发现，请使用组org.springframework.cloud和工件id spring-cloud-starter-consul-discovery的启动器。有关使用当前Spring云端列车设置构建系统的详细信息，请参阅Spring云计算页面。

注册Consul

当客户端注册Consul时，它提供有关自身的元数据，如主机和端口，ID，名称和标签。默认情况下，将创建一个HTTP 检查，每隔10秒Consul命中/health端点。如果健康检查失败，则服务实例被标记为关键。

示例Consul客户端：

@SpringBootApplication
@EnableDiscoveryClient
@RestController
public class Application {

    @RequestMapping("/")
    public String home() {
        return "Hello world";
    }

    public static void main(String[] args) {
        new SpringApplicationBuilder(Application.class).web(true).run(args);
    }

}

（即完全正常的Spring Boot应用程序）。如果Consul客户端位于localhost:8500以外的位置，则需要配置来定位客户端。例：

application.yml

spring:
  cloud:
    consul:
      host: localhost
      port: 8500

警告	如果您使用Spring Cloud Consul Config，上述值将需要放置在`bootstrap.yml`而不是`application.yml`中。

从Environment获取的默认服务名称，实例ID和端口分别为${spring.application.name}，Spring上下文ID和${server.port}。

@EnableDiscoveryClient使应用程序成为Consul“服务”（即注册自己）和“客户端”（即可以查询Consul查找其他服务）。

HTTP健康检查

Consul实例的运行状况检查默认为“/ health”，它是Spring Boot Actuator应用程序中有用端点的默认位置。如果您使用非默认上下文路径或servlet路径（例如server.servletPath=/foo）或管理端点路径（例如management.context-path=/admin）），则需要更改这些，即使是执行器应用程序。也可以配置Consul用于检查运行状况端点的间隔。“10s”和“1m”分别表示10秒和1分钟。例：

application.yml

spring:
  cloud:
    consul:
      discovery:
        healthCheckPath: ${management.context-path}/health
        healthCheckInterval: 15s

元数据和Consul标签

Consul尚不支持服务元数据。Spring Cloud的ServiceInstance有一个Map<String, String> metadata字段。Spring Cloud Consul使用Consul标签来近似元数据，直到Consul正式支持元数据。具有key=value形式的标签将被分割并分别用作Map键和值。没有相等=符号的标签将被用作键和值两者。

application.yml

spring:
  cloud:
    consul:
      discovery:
        tags: foo=bar, baz

上述配置将导致具有foo→bar和baz→baz的地图。

使Consul实例ID唯一

默认情况下，一个领事实体注册了一个等于其Spring应用程序上下文ID的ID。缺省情况下，Spring应用上下文ID为${spring.application.name}:comma,separated,profiles:${server.port}。在大多数情况下，这将允许一个服务的多个实例在一台机器上运行。如果需要进一步的唯一性，使用Spring Cloud可以通过在spring.cloud.consul.discovery.instanceId中提供唯一的标识来覆盖此。例如：

application.yml

spring:
  cloud:
    consul:
      discovery:
        instanceId: ${spring.application.name}:${vcap.application.instance_id:${spring.application.instance_id:${random.value}}}

使用这个元数据和在localhost上部署的多个服务实例，随机值将在那里进行，以使实例是唯一的。在Cloudfoundry中，vcap.application.instance_id将在Spring Boot应用程序中自动填充，因此不需要随机值。

使用DiscoveryClient

Spring Cloud支持Feign（一个REST客户端构建器），还支持Spring RestTemplate使用逻辑服务名称而不是实际的URL。

您还可以使用org.springframework.cloud.client.discovery.DiscoveryClient，它为Netflix不具体的发现客户端提供简单的API，例如

@Autowired
private DiscoveryClient discoveryClient;

public String serviceUrl() {
    List<ServiceInstance> list = discoveryClient.getInstances("STORES");
    if (list != null && list.size() > 0 ) {
        return list.get(0).getUri();
    }
    return null;
}

具有Consul的分布式配置

Consul提供了用于存储配置和其他元数据的键/值存储。Spring Cloud Consul Config是Config Server和Client的替代方案。在特殊的“引导”阶段，配置被加载到Spring环境中。默认情况下，配置存储在/config文件夹中。根据应用程序的名称和模拟Spring Cloud Config顺序解析属性的活动配置文件，创建多个PropertySource实例。例如，名为“testApp”的应用程序和“dev”配置文件将创建以下属性源：

config/testApp,dev/
config/testApp/
config/application,dev/
config/application/

最具体的物业来源位于顶部，底部最不具体。Properties是config/application文件夹适用于使用consul进行配置的所有应用程序。config/testApp文件夹中的Properties仅适用于名为“testApp”的服务实例。

配置当前在应用程序启动时被读取。发送HTTP POST到/refresh将导致重新加载配置。观看键值存储（Consul支持））目前不可能，但将来将是此项目的补充。

如何激活

要开始使用Consul配置，请使用组org.springframework.cloud和工件id spring-cloud-starter-consul-config的启动器。有关使用当前Spring云端列车设置构建系统的详细信息，请参阅Spring云计算页面。

这将启用将配置Spring Cloud Consul配置的自动配置。

定制

可以使用以下属性自定义Consul配置：

bootstrap.yml

spring:
  cloud:
    consul:
      config:
        enabled: true
        prefix: configuration
        defaultContext: apps
        profileSeparator: '::'

enabled将此值设置为“false”将禁用Consul配置
prefix设置配置值的基本文件夹
defaultContext设置所有应用程序使用的文件夹名称
profileSeparator设置分隔符的值，用于使用配置文件在属性源中分隔配置文件名称

配置观察

Consul配置观察功能可以利用领事看守钥匙前缀的能力。Config Watch会阻止Consul HTTP API调用，以确定当前应用程序是否有任何相关配置数据发生更改。如果有新的配置数据，则会发布刷新事件。这相当于调用/refresh执行器端点。

要更改Config Watch调用的频率change spring.cloud.consul.config.watch.delay。默认值为1000，以毫秒为单位。

禁用Config Watch集合spring.cloud.consul.config.watch.enabled=false。

YAML或Properties配置

存储与YAML或Properties格式的一组属性相对于单个键/值对可能更为方便。将spring.cloud.consul.config.format属性设置为YAML或PROPERTIES。例如使用YAML：

bootstrap.yml

spring:
  cloud:
    consul:
      config:
        format: YAML

必须在适当的data键中设置YAML。使用键上面的默认值将如下所示：

config/testApp,dev/data
config/testApp/data
config/application,dev/data
config/application/data

您可以将YAML文档存储在上述任何键中。

您可以使用spring.cloud.consul.config.data-key更改数据密钥。

git2consul与配置

git2consul是一个Consul社区项目，将文件从git存储库加载到各个密钥到Consul。默认情况下，密钥的名称是文件的名称。分别支持文件扩展名为.yml和.properties的YAML和Properties文件。将spring.cloud.consul.config.format属性设置为FILES。例如：

bootstrap.yml

spring:
  cloud:
    consul:
      config:
        format: FILES

给定/config中的以下密钥，development配置文件和应用程序名称为foo：

.gitignore
application.yml
bar.properties
foo-development.properties
foo-production.yml
foo.properties
master.ref

将创建以下属性来源：

config/foo-development.properties
config/foo.properties
config/application.yml

每个键的值需要是一个格式正确的YAML或Properties文件。

快速失败

在某些情况下（如本地开发或某些测试场景）可能会方便，如果不能配置领事，则不会失败。在bootstrap.yml中设置spring.cloud.consul.config.failFast=false将导致配置模块记录一个警告而不是抛出异常。这将允许应用程序继续正常启动。

Consul重试

如果您希望您的应用程序启动时可能偶尔无法使用代理商，则可以要求您在发生故障后继续尝试。您需要在您的类路径中添加spring-retry和spring-boot-starter-aop。默认行为是重试6次，初始退避间隔为1000ms，指数乘数为1.1，用于后续退避。您可以使用spring.cloud.consul.retry.*配置属性配置这些属性（和其他）。这适用于Spring Cloud Consul配置和发现注册。

提示	要完全控制重试，请使用id为“consulRetryInterceptor”添加`RetryOperationsInterceptor`类型的`@Bean`。Spring重试有一个`RetryInterceptorBuilder`，可以轻松创建一个。

Spring Cloud Bus与Consul

如何激活

要开始使用Consul总线，请使用组org.springframework.cloud和工件ID spring-cloud-starter-consul-bus的启动器。有关使用当前Spring云端列车设置构建系统的详细信息，请参阅Spring云计算页面。

有关可用的执行机构端点以及如何发送自定义消息，请参阅Spring Cloud Bus文档。

断路器与Hystrix

应用程序可以使用Spring Cloud Netflix项目提供的Hystrix断路器，将此启动器包含在项目pom.xml：spring-cloud-starter-hystrix中。Hystrix不依赖于Netflix Discovery Client。@EnableHystrix注释应放置在配置类（通常是主类）上。那么方法可以用@HystrixCommand注释来被断路器保护。有关详细信息，请参阅文档。

使用Turbine和Consul Hystrix指标聚合

Turbine（由Spring Cloud Netflix项目提供），聚合多个实例Hystrix指标流，因此仪表板可以显示聚合视图。Turbine使用DiscoveryClient接口查找相关实例。要将Turbine与Spring Cloud Consul配合使用与以下示例类似的方式配置Turbine应用程序：

pom.xml

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-netflix-turbine</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-consul-discovery</artifactId>
</dependency>

请注意，Turbine依赖不是起始者。涡轮启动器包括对Netflix Eureka的支持。

application.yml

spring.application.name: turbine
applications: consulhystrixclient
turbine:
  aggregator:
    clusterConfig: ${applications}
  appConfig: ${applications}

clusterConfig和appConfig部分必须匹配，因此将逗号分隔的服务标识列表放在单独的配置属性中是有用的。

Turbine.java

@EnableTurbine
@EnableDiscoveryClient
@SpringBootApplication
public class Turbine {
    public static void main(String[] args) {
        SpringApplication.run(DemoturbinecommonsApplication.class, args);
    }
}