3.1.2
该项目通过自动配置为 Spring Boot 应用程序提供 Consul 集成 并绑定到 Spring 环境和其他 Spring 编程模型习语。与一些 简单的注释,您可以快速启用和配置内部的常见模式 使用基于 Consul 的组件应用和构建大型分布式系统。这 提供的模式包括服务发现、控制总线和配置。 智能路由和客户端负载均衡、断路器 通过与其他 Spring Cloud 项目集成提供。
1. 快速入门
本快速入门介绍如何使用 Spring Cloud Consul 进行服务发现和分布式配置。
首先,在您的计算机上运行 Consul 代理。然后,您可以访问它并将其用作Spring Cloud Consul的服务注册表和配置源。
1.1. 发现客户端的使用
要在应用程序中使用这些功能,您可以将其构建为依赖于的 Spring 引导应用程序。 添加依赖项的最方便方法是使用 Spring Boot 启动器: 我们建议使用依赖项管理和。 以下示例显示了典型的 Maven 配置:spring-cloud-consul-core
org.springframework.cloud:spring-cloud-starter-consul-discovery
spring-boot-starter-parent
绒球.xml
以下示例显示了典型的 Gradle 设置:
build.gradle
现在,您可以创建一个标准的 Spring 引导应用程序,例如以下 HTTP 服务器:
当此 HTTP 服务器运行时,它将连接到在默认本地 8500 端口上运行的 Consul 代理。 要修改启动行为,您可以使用 更改 Consul Agent 的位置,如以下示例所示:application.properties
现在,您可以使用 or,or 从 Consul 检索服务和实例数据,如以下示例所示:DiscoveryClient
@LoadBalanced RestTemplate
@LoadBalanced WebClient.Builder
1.2. 分布式配置使用
要在应用程序中使用这些功能,您可以将其构建为依赖于 and 的 Spring 引导应用程序。 添加依赖项的最方便方法是使用 Spring Boot 启动器: 我们建议使用依赖项管理和。 以下示例显示了典型的 Maven 配置:spring-cloud-consul-core
spring-cloud-consul-config
org.springframework.cloud:spring-cloud-starter-consul-config
spring-boot-starter-parent
绒球.xml
以下示例显示了典型的 Gradle 设置:
build.gradle
现在,您可以创建一个标准的 Spring 引导应用程序,例如以下 HTTP 服务器:
应用程序从 Consul 检索配置数据。
如果使用 Spring Cloud Consul Config,则需要设置属性才能绑定到 Consul。 您可以在Spring 引导配置数据导入部分阅读更多相关信息。 |
2. 安装领事
有关如何安装 Consul 的说明,请参阅安装文档。
3. 领事代理
Consul 代理客户端必须可用于所有 Spring Cloud Consul 应用程序。默认情况下,代理客户端应位于。有关如何启动服务器代理客户端以及如何连接到 Consul 代理服务器集群的详细信息,请参阅代理文档。对于开发,安装 consul 后,可以使用以下命令启动 Consul 代理:localhost:8500
这将在端口 8500 上以服务器模式启动代理,UI 位于localhost:8500
4. 与领事一起发现服务
服务发现是基于微服务的架构的关键原则之一。尝试手动配置每个客户端或某种形式的约定可能非常困难,并且可能非常脆弱。Consul 通过HTTP API和DNS 提供服务发现服务。Spring Cloud Consul利用HTTP API进行服务注册和发现。这不会阻止非 Spring Cloud 应用程序利用 DNS 接口。Consul Agents服务器运行在一个集群中,该集群通过八卦协议进行通信,并使用Raft共识协议。
4.1. 如何激活
要激活 Consul 服务发现,请使用具有组和工件 ID 的启动器。有关使用当前 Spring 云发布系列设置构建系统的详细信息,请参阅Spring 云项目页面。org.springframework.cloudspring-cloud-starter-consul-discovery
4.2. 向领事注册
当客户端向 Consul 注册时,它会提供有关自身的元数据,例如主机和端口、ID、名称和标签。默认情况下会创建一个 HTTP检查,Consul 每 10 秒访问一次端点。如果运行状况检查失败,则服务实例将标记为关键。/actuator/health
领事客户端示例:
(即完全正常的 Spring 启动应用程序)。如果 Consul 客户端位于其他位置,则需要配置才能找到客户端。例:localhost:8500
应用程序.yml
如果您使用Spring Cloud Consul Config,并且您使用了setoror,则需要放置上述值。 |
默认的服务名称、实例 ID 和端口分别取自 Spring 上下文 ID。Environment
${spring.application.name}
${server.port}
要禁用 Consul 发现客户端,您可以设置为 。当设置为 时,领事发现客户端也将被禁用。spring.cloud.consul.discovery.enabled
false
spring.cloud.discovery.enabled
false
要禁用服务注册,您可以设置为。spring.cloud.consul.discovery.register
false
4.2.1. 将管理注册为单独的服务
当管理服务器端口设置为与应用程序端口不同的端口时,通过 setproperty,管理服务将注册为与应用程序服务不同的服务。例如:management.server.port
应用程序.yml
上述配置将注册以下 2 个服务:
- 应用服务:
- 管理服务:
管理服务将从应用程序服务继承它。例如:instanceId
serviceName
应用程序.yml
上述配置将注册以下 2 个服务:
- 应用服务:
- 管理服务:
可以通过以下属性进一步定制:
4.2.2. HTTP 健康检查
Consul 实例的运行状况检查默认为“/actuator/health”,这是 Spring 引导执行器应用程序中运行状况端点的默认位置。如果您使用非默认上下文路径或 Servlet 路径(例如)或管理端点路径(例如),即使对于执行器应用程序,您也需要更改此设置。server.servletPath=/foo
management.server.servlet.context-path=/admin
还可以配置 Consul 用于检查运行状况终结点的间隔。“10s”和“1m”分别代表10秒和1分钟。
此示例说明了上述内容(有关更多选项,请参阅附录页中的属性)。spring.cloud.consul.discovery.health-check-*
应用程序.yml
您可以通过设置完全禁用 HTTP 运行状况检查。spring.cloud.consul.discovery.register-health-check=false
应用标头
标头可应用于运行状况检查请求。例如,如果您尝试注册使用Vault后端的Spring Cloud Config服务器:
应用程序.yml
根据 HTTP 标准,每个标头可以有多个值,在这种情况下,可以提供数组:
应用程序.yml
4.2.3. 执行器健康指示器
如果服务实例是 Spring 引导执行器应用程序,则可以为其提供以下执行器运行状况指示器。
发现客户端健康指示器
当 Consul 服务发现处于活动状态时,将配置一个发现客户端运行状况指示器,并将其提供给执行器运行状况端点。 有关配置选项,请参阅此处。
领事健康指标
配置了一个指示器来验证 的运行状况。ConsulClient
默认情况下,它会检索 Consul 领导节点状态和所有已注册的服务。 在具有许多已注册服务的部署中,在每次运行状况检查中检索所有服务的成本可能很高。 跳过服务检索,仅检查领导节点状态集。spring.cloud.consul.health-indicator.include-services-query=false
禁用指示器集。management.health.consul.enabled=false
当应用程序在引导上下文模式(默认)下运行时, 此指示器加载到引导上下文中,并且不可用于执行器运行状况终结点。 |
4.2.4. 元数据
Consul 支持有关服务的元数据。春云的田地,由服务场填充。填充字段设置值或属性。ServiceInstance
Map<String, String> metadata
meta
meta
spring.cloud.consul.discovery.metadata
spring.cloud.consul.discovery.management-metadata
应用程序.yml
上述配置将导致元字段包含沙子的服务。myfield→myvalue
anotherfield→anothervalue
生成的元数据
领事自动注册将自动生成一些条目。
Table 1. Auto Generated Metadata
钥匙 |
价值 |
“组” |
财产。此值仅生成 ifis 不为空。 |
“安全” |
如果属性等于“https”,则为 true,否则为 false。 |
属性,默认为“区域” |
财产。此值仅生成 ifis 不为空。 |
旧版本的Spring Cloud Consul通过解析属性从Spring Cloud Commons填充该方法。这不再受支持,请迁移到使用 themap。 |
4.2.5. 使 consul 实例 ID 唯一
默认情况下,consul 实例注册的 ID 等于其 Spring 应用程序上下文 ID。默认情况下,Spring 应用程序上下文 ID 为。在大多数情况下,这将允许一个服务的多个实例在一台计算机上运行。如果需要进一步的唯一性,可以使用Spring Cloud,您可以通过提供唯一标识符来覆盖它。例如:${spring.application.name}:comma,separated,profiles:${server.port}
spring.cloud.consul.discovery.instanceId
应用程序.yml
有了这个元数据,以及在本地主机上部署的多个服务实例,随机值将在那里启动,使实例唯一。在Cloudfoundry中,将自动填充在Spring Boot应用程序中,因此不需要随机值。vcap.application.instance_id
4.3. 查找服务
4.3.1. 使用负载均衡器
Spring Cloud 支持Feign(一个 REST 客户端构建器)和SpringRestTemplate,用于使用逻辑服务名称/ID 而不是物理 URL 查找服务。Feign 和发现感知的 RestTemplate 都利用Spring Cloud LoadBalancer进行客户端负载均衡。
如果您想使用 RestTemplate 访问服务商店,只需声明:
并像这样使用它(请注意我们如何使用 Consul 的 STORES 服务名称/ID 而不是完全限定的域名):
如果在多个数据中心中具有 Consul 群集,并且想要访问另一个数据中心中的服务,则仅靠服务名称/ID 是不够的。在这种情况下 您使用属性服务名称/ID 和数据中心的位置 商店服务所在的位置。spring.cloud.consul.discovery.datacenters.STORES=dc-west
STORES
dc-west
Spring Cloud 现在还提供对Spring Cloud Load Balancer 的支持。 |
4.3.2. 使用发现客户端
您还可以使用它为发现客户端提供一个简单的API,该API并非特定于Netflix,例如org.springframework.cloud.client.discovery.DiscoveryClient
4.4. 领事目录观察
领事目录观察利用领事监视服务的能力。目录观察进行阻塞 Consul HTTP API 调用,以确定是否有任何服务已更改。如果有新的服务数据,则会发布检测信号事件。
更改配置监视调用更改的频率。默认值为 1000,以毫秒为单位。延迟是上一个调用结束和下一个调用开始后的时间量。spring.cloud.consul.config.discovery.catalog-services-watch-delay
禁用目录监视集。spring.cloud.consul.discovery.catalogServicesWatch.enabled=false
手表使用弹簧来安排对领事的呼叫。默认情况下,它与 aof 1 一起。要更改,请创建一个类型为“使用常量命名的 bean”。TaskScheduler
ThreadPoolTaskScheduler
poolSize
TaskScheduler
TaskScheduler
ConsulDiscoveryClientConfiguration.CATALOG_WATCH_TASK_SCHEDULER_NAME
5. 使用领事进行分布式配置
Consul 提供用于存储配置和其他元数据的键/值存储。Spring Cloud Consul Config 是Config Server 和 Client 的替代方案。配置在特殊的“引导”阶段加载到 Spring 环境中。默认情况下,配置存储在文件夹中。根据应用程序的名称和模仿 Spring Cloud 配置解析属性顺序的活动配置文件创建多个实例。例如,名称为“testApp”且具有“dev”配置文件的应用程序将创建以下属性源:/config
PropertySource
最具体的属性源位于顶部,最不具体的属性源位于底部。文件夹中的属性适用于所有使用 consul 进行配置的应用程序。文件夹中的属性仅适用于名为“testApp”的服务实例。config/application
config/testApp
配置当前在应用程序启动时读取。发送 HTTP POST 将导致重新加载配置。配置观察还会自动检测更改并重新加载应用程序上下文。/refresh
5.1. 如何激活
要开始使用 Consul 配置,请使用带有组和工件 ID 的启动器。有关使用当前 Spring 云发布系列设置构建系统的详细信息,请参阅Spring 云项目页面。org.springframework.cloud
spring-cloud-starter-consul-config
5.2. Spring 引导配置数据导入
Spring Boot 2.4引入了一种通过属性导入配置数据的新方法。现在,这是从 Consul 获取配置的默认方法。spring.config.import
要有选择地连接到 Consul,请在 application.properties 中设置以下内容:
应用程序属性
这将连接到默认位置“http://localhost:8500”的领事代理。删除前缀将导致 Consul 配置失败(如果它无法连接到 Consul)。要更改 Consul Config 的连接属性,请设置或将主机/端口对添加到语句中,例如。导入属性中的位置优先于主机和端口属性。optional:
spring.cloud.consul.host
spring.cloud.consul.port
spring.config.import
spring.config.import=optional:consul:myhost:8500
Consul Config 将尝试从四个自动上下文中加载值,基于 (默认为属性的值)和(默认为)。如果要指定上下文而不是使用计算上下文,可以将该信息添加到语句中。spring.cloud.consul.config.name
spring.application.name
spring.cloud.consul.config.default-context
application
spring.config.import
应用程序属性
这将选择仅从和加载配置。/contextone
/context/two
导入方式的 Spring 引导配置数据方法不需要文件(属性或 yaml)。 |
5.3. 定制
可以使用以下属性自定义领事配置:
如果您有 setor 或包含,则需要放置上述值来代替。 |
-
enabled
将此值设置为“false”将禁用领事配置 -
prefix
设置配置值的基文件夹 -
defaultContext
设置所有应用程序使用的文件夹名称 -
profileSeparator
设置用于在属性源中使用配置文件分隔配置文件名称的分隔符的值
5.4. 配置监视
领事配置监视利用领事监视密钥前缀的功能。配置观察进行阻塞 Consul HTTP API 调用,以确定当前应用程序的任何相关配置数据是否已更改。如果有新的配置数据,则会发布刷新事件。这等效于调用执行器终结点。/refresh
更改配置监视调用更改的频率。默认值为 1000,以毫秒为单位。延迟是上一个调用结束和下一个调用开始后的时间量。spring.cloud.consul.config.watch.delay
禁用配置监视集。spring.cloud.consul.config.watch.enabled=false
手表使用弹簧来安排对领事的呼叫。默认情况下,它与 aof 1 一起。要更改,请创建一个类型为“使用常量命名的 bean”。TaskScheduler
ThreadPoolTaskScheduler
poolSize
TaskScheduler
TaskScheduler
ConsulConfigAutoConfiguration.CONFIG_WATCH_TASK_SCHEDULER_NAME
5.5. 带有配置的 YAML 或属性
与单个键/值对相比,以 YAML 或属性格式存储属性 blob 可能更方便。设置属性到。例如,要使用 YAML:spring.cloud.consul.config.format
YAML
PROPERTIES
如果您有 setor 或包含,则需要放置上述值来代替。 |
必须在领事的相应键中设置 YAML。使用键上方的默认值如下所示:data
可以将 YAML 文档存储在上面列出的任何键中。
您可以使用以下方法更改数据密钥。spring.cloud.consul.config.data-key
5.6. git2consul with config
git2consul 是一个 Consul 社区项目,它将文件从 git 存储库加载到各个密钥到 Consul 中。默认情况下,键的名称是文件的名称。YAML 和属性文件分别支持文件扩展名。将属性设置为。例如:.yml
.properties
spring.cloud.consul.config.format
FILES
引导程序.yml
给定以下键,配置文件和应用程序名称为:/config
development
foo
将创建以下属性源:
每个键的值必须是格式正确的 YAML 或属性文件。
5.7. 快速失败
在某些情况下(如本地开发或某些测试场景)下,如果 consul 不可用于配置,则不会失败可能很方便。设置将导致配置模块记录警告而不是引发异常。这将允许应用程序继续正常启动。spring.cloud.consul.config.fail-fast=false
如果您有 setor 或包含,则需要放置上述值来代替。 |
6. 领事重试
如果您预计领事代理可能偶尔在以下情况下不可用 您的应用启动,您可以要求它在失败后继续尝试。您需要添加到类路径中。默认 行为是重试 6 次,初始退避间隔为 1000 毫秒,并且 后续退避的指数乘数为 1.1。您可以配置这些 属性(和其他)使用配置属性。 这适用于Spring Cloud Consul Config和Discovery注册。spring-retry
spring-boot-starter-aop
spring.cloud.consul.retry.*
要完全控制重试,请添加 id 为 “consulRetryInterceptor” 的 aof 类型。春天 重试使创建一个变得容易。 |
7. 春云巴士与领事
7.1. 如何激活
要开始使用领事总线,请使用带有组和工件 ID 的启动器。有关使用当前 Spring 云发布系列设置构建系统的详细信息,请参阅Spring 云项目页面。org.springframework.cloud
spring-cloud-starter-consul-bus
请参阅Spring 云总线文档,了解可用的执行器端点以及如何发送自定义消息。
8. 带 Hystrix 的断路器
应用程序可以使用 Spring Cloud Netflix 项目提供的 Hystrix 断路器,方法是将此启动器包含在项目 pom.xml: 中。Hystrix不依赖于Netflix Discovery Client。注释应该放在配置类(通常是主类)上。然后可以注释方法以由断路器保护。有关更多详细信息,请参阅文档。spring-cloud-starter-hystrix
@EnableHystrix
@HystrixCommand
9. Hystrix指标与涡轮机和领事的聚合
Turbine(由Spring Cloud Netflix项目提供)聚合多个实例Hystrix指标流,因此仪表板可以显示聚合视图。涡轮使用接口查找相关实例。要将涡轮机与 Spring Cloud Consul 一起使用,请以类似于以下示例的方式配置涡轮机应用程序:DiscoveryClient
绒球.xml
请注意,涡轮机依赖项不是启动器。涡轮机启动器包括对Netflix Eureka的支持。
应用程序.yml
和部分必须匹配,因此将逗号分隔的服务 ID 列表放入单独的配置属性中很有用。clusterConfig
appConfig
涡轮机.java