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 APIDNS提供服务发现服务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→barbaz→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属性设置为YAMLPROPERTIES例如使用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-retryspring-boot-starter-aop默认行为是重试6次,初始退避间隔为1000ms,指数乘数为1.1,用于后续退避。您可以使用spring.cloud.consul.retry.*配置属性配置这些属性(和其他)。这适用于Spring Cloud Consul配置和发现注册。

小费
要完全控制重试,请使用id为“consulRetryInterceptor”添加RetryOperationsInterceptor类型的@BeanSpring重试有一个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}

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

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