开篇词
该指南将引导你搭建并消费来自 Spring Cloud Config Server 的配置。
你将创建的应用
我们将搭建一个 Config Server 并构建一个客户端,该客户端在启动时会消费配置,然后刷新配置而不用重新启动客户端。
你将需要的工具
- 大概 15 分钟左右;
- 你最喜欢的文本编辑器或集成开发环境(IDE)
- JDK 1.8 或更高版本;
- Gradle 4+ 或 Maven 3.2+
- 你还可以将代码直接导入到 IDE 中:
- Spring Too Suite (STS)
- IntelliJ IDEA
如何完成这个指南
像大多数的 Spring 入门指南一样,你可以从头开始并完成每个步骤,也可以绕过你已经熟悉的基本设置步骤。如论哪种方式,你最终都有可以工作的代码。
- 要从头开始,移步至从 Spring Initializr 开始;
- 要跳过基础,执行以下操作:
- 下载并解压缩该指南将用到的源代码,或借助 Git 来对其进行克隆操作:git clone https://github.com/spring-guides/gs-centralized-configuration.git
- 切换至 gs-centralized-configuration/initial 目录;
- 跳转至该指南的搭建一个配置服务器。
待一切就绪后,可以检查一下 gs-centralized-configuration/complete 目录中的代码。
从 Spring Initializr 开始
对于所有的 Spring 应用来说,你应该从 Spring Initializr 开始。Initializr 提供了一种快速的方法来提取应用程序所需的依赖,并为你完成许多设置。该指南需要两个应用。第一个应用(配置服务器)仅需要 Config Server 依赖。下图显示了此示例项目的 Initializr 设置:
上图显示了选择 Maven 作为构建工具的 Initializr。你也可以使用 Gradle。它还将 com.example 和 centralized-configuration-service 的值分别显示为 Group 和 Artifact。在本示例的其余部分,将用到这些值。
以下清单显示了选择 Maven 时创建的 pom.xml 文件:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.2.0.RELEASE</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.example</groupId>
<artifactId>centralized-configuration-service</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>centralized-configuration-service</name>
<description>Demo project for Spring Boot</description>
<properties>
<java.version>1.8</java.version>
<spring-cloud.version>Hoxton.M3</spring-cloud.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-config-server</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
<exclusions>
<exclusion>
<groupId>org.junit.vintage</groupId>
<artifactId>junit-vintage-engine</artifactId>
</exclusion>
</exclusions>
</dependency>
</dependencies>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-dependencies</artifactId>
<version>${spring-cloud.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
<repositories>
<repository>
<id>spring-milestones</id>
<name>Spring Milestones</name>
<url>https://repo.spring.io/milestone</url>
</repository>
</repositories>
</project>
以下清单显示了在选择 Gradle 时创建的 build.gradle 文件:
plugins {
id 'org.springframework.boot' version '2.2.0.RELEASE'
id 'io.spring.dependency-management' version '1.0.8.RELEASE'
id 'java'
}
group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '1.8'
repositories {
mavenCentral()
maven { url 'https://repo.spring.io/milestone' }
}
ext {
set('springCloudVersion', "Hoxton.M3")
}
dependencies {
implementation 'org.springframework.cloud:spring-cloud-config-server'
testImplementation('org.springframework.boot:spring-boot-starter-test') {
exclude group: 'org.junit.vintage', module: 'junit-vintage-engine'
}
}
dependencyManagement {
imports {
mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}"
}
}
test {
useJUnitPlatform()
}
第二个应用(配置客户端)需要 Config Client,Spring Boot Actuator 及 Spring Web 依赖。下图显示了为配置客户端设置的 Initializr:
上图显示了选择 Maven 作为构建工具的 Initializr。你也可以使用 Gradle。它还将 com.example 和 centralized-configuration-client 的值分别显示为 Group 和 Artifact。在本示例的其余部分,将用到这些值。
以下清单显示了选择 Maven 时创建的 pom.xml 文件:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.2.0.RELEASE</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.example</groupId>
<artifactId>centralized-configuration-client</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>centralized-configuration-client</name>
<description>Demo project for Spring Boot</description>
<properties>
<java.version>1.8</java.version>
<spring-cloud.version>Hoxton.M3</spring-cloud.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-config</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
<exclusions>
<exclusion>
<groupId>org.junit.vintage</groupId>
<artifactId>junit-vintage-engine</artifactId>
</exclusion>
</exclusions>
</dependency>
</dependencies>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-dependencies</artifactId>
<version>${spring-cloud.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
<repositories>
<repository>
<id>spring-milestones</id>
<name>Spring Milestones</name>
<url>https://repo.spring.io/milestone</url>
</repository>
</repositories>
</project>
以下清单显示了在选择 Gradle 时创建的 build.gradle 文件:
plugins {
id 'org.springframework.boot' version '2.2.0.RELEASE'
id 'io.spring.dependency-management' version '1.0.8.RELEASE'
id 'java'
}
group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '1.8'
repositories {
mavenCentral()
maven { url 'https://repo.spring.io/milestone' }
}
ext {
set('springCloudVersion', "Hoxton.M3")
}
dependencies {
implementation 'org.springframework.boot:spring-boot-starter-actuator'
implementation 'org.springframework.boot:spring-boot-starter-web'
implementation 'org.springframework.cloud:spring-cloud-starter-config'
testImplementation('org.springframework.boot:spring-boot-starter-test') {
exclude group: 'org.junit.vintage', module: 'junit-vintage-engine'
}
}
dependencyManagement {
imports {
mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}"
}
}
test {
useJUnitPlatform()
}
为方便起见,我们在项目的顶部(service 和 client 目录上方的一个目录)提供了构建文件(pom.xml 及 build.gradle 文件),我们可以使用它们一次构建两个项目。我们还在那里添加了 Maven 和 Gradle 包装器。
搭建一个配置服务器
我们首先需要一个 Eureka 服务注册表。我们可以使用 Spring Cloud 的 @EnableConfigServer 来建立注册表,其他应用可以与之通信。这是一个常规的 Spring Boot 应用,其中添加了一个注释(@EnableConfigServer)以启用服务注册表。以下清单(来自 configuration-service/src/main/java/com/example/configurationservice/ConfigurationServiceApplication.java)显示了服务应用:
package com.example.configurationservice;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.config.server.EnableConfigServer;
@EnableConfigServer
@SpringBootApplication
public class ConfigurationServiceApplication {
public static void main(String[] args) {
SpringApplication.run(ConfigurationServiceApplication.class, args);
}
}
Config Server 需要知道要管理哪个存储库。这里有几种选择,但从基于 Git 的文件系统存储库开始。我们可以轻松地将 Config Server 指向 Github 或 GitLab 存储库。在文件系统上,创建一个新目录并在其中运行 git init。然后将一个名为 a-bootiful-client.properties 的文件添加到 Git 存储库。然后在其中运行 git commit。稍后,我们将使用 Spring Boot 应用连接到 Config Server,该应用的 spring.application.name 属性将其标识为 Config Server 的 a-bootiful-client。这是 Config Server 知道要发送到特定客户端的配置集的方式。它还从 Git 存储库中名为 application.properties 或 application.yml 的任何文件中发送所有值。更具体命名的文件(例如 a-bootiful-client.properties)中的属性键会覆盖 application.properties 或 application.yml 中的属性键。
将一个简单的属性值(message = Hello World)添加到新创建的 a-bootiful-client.properties 文件中,然后 git 提交更改。
通过在 configuration-service/src/main/resources/application.properties 中指定 spring.cloud.config.server.git.uri 属性来指定 Git 存储库的路径。我们还必须指定一个不同的 server.port 值,以避免在同一台计算机上同时运行该服务器的另一个 Spring Boot 应用时发生端口冲突。以下清单(来自 configuration-service/src/main/resources/application.properties)显示了这样一个 application.properties 文件:
server.port=8888
spring.cloud.config.server.git.uri=${HOME}/Desktop/config
该示例在 ${HOME}/Desktop/config 中使用基于文件的 git 存储库。我们可以通过创建一个新目录并在其中的属性和 YAML 文件上运行 git init 来轻松创建一个目录。以下命令集可以完成该工作:
$ cd ~/Desktop/config
$ find .
./.git
...
./application.yml
或者,如果我们在应用中更改配置文件以指向它,则可以使用远程 git 存储库(例如 Github)。
使用配置客户端读取来自配置服务器的配置
现在我们已经搭建并启动了配置服务器,我们需要启动一个新的 Spring Boot 应用,该应用使用配置服务器加载自己的配置,并刷新其配置以将更改即时反映到配置服务器而无需重启 JVM。为此,添加 org.springframework.cloud:spring-cloud-starter-config 依赖关系以连接到 Config Server。Spring 会看到配置属性文件,就像从 application.properties 或 application.yml 或任何其他 PropertySource 加载的任何属性文件一样。
在引导阶段,必须先读取用以配置配置客户端的属性,然后才能从配置服务器中读取应用的其余配置。将客户端的 spring.application.name 指定为 a-bootiful-client,并在 configuration-client/src/main/resources/bootstrap.properties 中将配置服务器的位置(spring.cloud.config.uri)指定为遭遇任何其他配置的加载位置。以下清单显示了该文件:
configuration-client/src/main/resources/bootstrap.properties
spring.application.name=a-bootiful-client
# N.B. this is the default:
spring.cloud.config.uri=http://localhost:8888
我们还希望启用 /refresh 端点,以演示动态配置更改。以下清单(来自 configuration-client/src/main/resources/application.properties)显示了如何执行该操作:
management.endpoints.web.exposure.include=*
客户端可以使用传统机制(例如 @ConfigurationProperties 或 @Value("${…}") 或通过 Environment 抽象)访问配置服务器中的任何值。现在,我们需要创建一个 Spring MVC REST 控制器,该控制器返回已解析的 message 属性的值。请参阅《构建 RESTful Web 服务》指南,以了解有关使用 Spring MVC 和 Spring Boot 构建 REST 服务的更多信息。
默认情况下,配置值是在客户端启动时读物的,不会再次读取。我们可以通过使用 Spring Cloud Config 的 @RefreshScope 注解来标注 MessageRestController,然后触发刷新事件来使 bean 强制刷新其配置(即,从配置服务器中获取更新的值)。以下清单(来自 configuration-client/src/main/java/com/example/configurationclient/ConfigurationClientApplication.java)显示了如何执行该操作:
package com.example.centralizedconfigurationclient;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.context.config.annotation.RefreshScope;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@SpringBootApplication
public class CentralizedConfigurationClientApplication {
public static void main(String[] args) {
SpringApplication.run(CentralizedConfigurationClientApplication.class, args);
}
}
@RefreshScope
@RestController
class MessageRestController {
@Value("${message:Hello default}")
private String message;
@RequestMapping("/message")
String getMessage() {
return this.message;
}
}
测试应用
我们可以通过以下方式测试端到端结果:首先启动配置服务器,然后在其运行后启动客户端。在浏览器中访问客户端应用,网址为 http://localhost:8080/message。在哪里,我们应该在响应中看到 Hello world。
将 Git 存储库中的 a-bootiful-client.properties 文件中的消息密钥更改为其他名称(Hello Spring! 或许吧?)。我们可以通过访问 http://localhost:8888/a-bootiful-client/default 来确认配置服务器看到了更改。我们需要调用 refresh Spring Boot Actuator 端点,以强制客户端刷新自身并提取新值。Spring Boot 的 Actuator 公开了有关应用的操作端点(例如运行状况检查和环境信息)。要使用它,必须将 org.springframework.boot:spring-boot-starter-actuator 添加到客户端应用的类路径中。我们可以通过向客户端的 refresh 端点发送一个空的 HTTP POST 来调用 refresh Actuator 端点:http://localhost:8080/actuator/refresh。然后,我们可以通过访问 http://localhost:8080/message 端点来确认它是否有效。
以下命令调用执行器的刷新命令:
$ curl localhost:8080/actuator/refresh -d {} -H "Content-Type: application/json"
我们在客户端应用中设置了 management.endpoints.web.exposure.include=*,以使其易于测试(由于 Spring Boot 2.0 默认情况下不公开 Actuator 端点)。默认情况下,如果未设置标志,我们仍然可以通过 JMX 访问它们。
概述
恭喜你!我们刚刚使用 Spring 通过首先创建服务然后动态更新其配置来中心化所有服务的配置。
参见
以下指南也可能会有所帮助:
- 构建 RESTful Web 服务
- 使用 Spring Boot 构建应用程序
- 创建一个多模块项目(尽请期待~)