Vert.x Config

中英文对照表

  • Overloading：重载
  • Configuration Store：配置仓库

组件介绍

Vert.x Config 提供了一种配置 Vert.x 应用的方式。

它包含：

  • 支持多种配置语法（JSON、properties、YAML（扩展）、HOCON（扩展）等）
  • 支持多种存储方式（文件、目录、HTTP、Git（扩展）、Redis（扩展）、系统属性、环境变量等）
  • 支持自定义配置处理顺序和配置重载(overloading)
  • 支持运行时重新配置(runtime reconfiguration)

概念

本组件基于如下几个概念：

  • Config Retriever 由Vert.x 应用实例化以及使用；它配置了一系列的配置仓库
  • Configuration Store 定义了配置项的数据源和语法（默认是 JSON）

配置文件最终会以 JSON 对象(JsonObject)的形式取出。

使用 Config Retriever

要使用 Config Retriever，只需要在依赖中增加以下代码片段：

  • Maven (在 pom.xml 文件中): 
  1. <dependency>
  2.   <groupId>io.vertx</groupId>
  3.   <artifactId>vertx-config</artifactId>
  4.   <version>3.4.1</version>
  5. </dependency>
  • Gradle (在 build.gradle 文件中):
  1. compile 'io.vertx:vertx-config:3.4.1'

一旦完成以上步骤，我们第一步所需要做的就是实例化 ConfigRetriever：

  1. ConfigRetriever retriever = ConfigRetriever.create(vertx);

默认配置下，Config Retriever 会按照以下的顺序进行配置：

  • Vert.x Verticle 中的 config() 函数
  • 系统配置
  • 环境变量

你可以通过下列示例自定义配置：

  1. ConfigStoreOptions httpStore = new ConfigStoreOptions()
  2.   .setType("http")
  3.   .setConfig(new JsonObject()
  4.     .put("host", "localhost").put("port", 8080).put("path", "/conf"));
  6. ConfigStoreOptions fileStore = new ConfigStoreOptions()
  7.   .setType("file")
  8.   .setConfig(new JsonObject().put("path", "my-config.json"));
  10. ConfigStoreOptions sysPropsStore = new ConfigStoreOptions().setType("sys");
  13. ConfigRetrieverOptions options = new ConfigRetrieverOptions()
  14.   .addStore(httpStore).addStore(fileStore).addStore(sysPropsStore);
  16. ConfigRetriever retriever = ConfigRetriever.create(vertx, options);

在后续章节会将更加详细的重载规则和其他可用的配置仓库设置一一展现。

一旦成功实例化 Config Retriever, 可用如下代码获取配置：

  1. retriever.getConfig(ar -> {
  2.   if (ar.failed()) {
  3.     // Failed to retrieve the configuration
  4.   } else {
  5.     JsonObject config = ar.result();
  6.   }
  7. });

重载规则

明确配置仓库的顺序对于重载极为重要。对于冲突的键名，后面的配置值将替换掉之前的。举个例子，比如我们有两个配置仓库：

  • A 含有 {a:value, b:1}
  • B 含有 {a:value2, c:2}

如果我们配置的顺序是 (A, B)，那我们的配置结果将是：{a:value2, b:1, c:2}。
如果我们将配置顺序颠倒为 (B, A)，我们最终得到的结果是：{a:value, b:1, c:2}。

支持的配置仓库

Vert.x Config 提供了一系列的配置存储支持和格式支持。更多的种类支持以扩展组件的形式提供，当然你也可以实现自己的扩展组件。

配置的数据结构

声明每一个数据存储源就必须要指明存储类型（type）。它可以指定格式（format），默认将使用 JSON。

一些配置仓库需要一些额外的配置项（比如路径）。我们可以通过 setConfig 方法传入一个 JsonObject 对象来进行上述的配置。

文件

此配置仓库仅仅从文件中读取配置，支持所有的格式。

  1. ConfigStoreOptions file = new ConfigStoreOptions()
  2.   .setType("file")
  3.   .setFormat("properties")
  4.   .setConfig(new JsonObject().put("path", "path-to-file.properties"));

其中 path 参数是必须的。

JSON

JSON 配置仓库仅支持通过给定的 JSON 对象（JsonObject）进行配置。

  1. ConfigStoreOptions json = new ConfigStoreOptions()
  2.   .setType("json")
  3.   .setConfig(new JsonObject().put("key", "value"));

本配置仓库仅支持 JSON 格式。

环境变量

此配置仓库将环境变量中的键值对映射成 JSON 对象传入，作为全局配置。

  1. ConfigStoreOptions json = new ConfigStoreOptions()
  2.   .setType("env");

此配置仓库不支持 format 配置项。

系统属性

此配置仓库将系统属性中的键值对映射成 JSON 对象传入，作为全局配置。

  1. ConfigStoreOptions json = new ConfigStoreOptions()
  2.   .setType("sys")
  3.   .setConfig(new JsonObject().put("cache", "false"));

此配置仓库不支持 format 配置项。

您可以对 cache 属性进行配置（默认为 true）。此配置项决定是否在初次获取系统属性时对其进行缓存，并且在后面不会重新加载。

HTTP

此配置仓库会通过给定的 HTTP 地址获得配置，可以使用任何支持的格式。

  1. ConfigStoreOptions http = new ConfigStoreOptions()
  2.   .setType("http")
  3.   .setConfig(new JsonObject()
  4.     .put("host", "localhost")
  5.     .put("port", 8080)
  6.     .put("path", "/A"));

它会创建一个Vert.x HTTP 客户端（HttpClient）来访问配置仓库（请看下面的代码）。你也可以通过配置 host、port 和 path 这些属性来简化这个过程。

  1. ConfigStoreOptions http = new ConfigStoreOptions()
  2.   .setType("http")
  3.   .setConfig(new JsonObject()
  4.     .put("defaultHost", "localhost")
  5.     .put("defaultPort", 8080)
  6.     .put("ssl", true)
  7.     .put("path", "/A"));

Event Bus

此配置仓库会从 Event Bus 中获取配置。这种方式让你可以在本地和分布式组件中分发你的配置。

  1. ConfigStoreOptions eb = new ConfigStoreOptions()
  2.   .setType("event-bus")
  3.   .setConfig(new JsonObject()
  4.     .put("address", "address-getting-the-conf")
  5.   );

此配置仓库也支持所有的格式。

目录

这种配置仓库非常像 file 配置方式，但是不同的是，file 只读取一个配置文件，而这种方式会从一个目录中读取一批配置文件。

此方式有两个必要的参数：

  • path - 文件所在的根结点路径
  • 至少一个 fileset - 需要读取的文件列表（模式）

每一个 fileset 都包含：pattern（匹配模式），即用于选取文件的Ant风格的匹配模式。此匹配模式使用相对路径确定配置文件位置。format（格式）作为可选的参数（每一个 fileset 都可以使用不同的格式，但是在一个 fileset 内的文件必须是同一种格式）。

  1. ConfigStoreOptions dir = new ConfigStoreOptions()
  2.   .setType("directory")
  3.   .setConfig(new JsonObject().put("path", "config")
  4.     .put("filesets", new JsonArray()
  5.       .add(new JsonObject().put("pattern", "dir/*json"))
  6.       .add(new JsonObject().put("pattern", "dir/*.properties")
  7.         .put("format", "properties"))
  8.     ));

监听配置变更

Configuration Retriever 会定期地从配置仓库处读取配置。如果读取的结果和当前的配置不一样，那么应用就会重新进行配置，默认情况下，配置的刷新时间是 5 秒钟。

  1. ConfigRetrieverOptions options = new ConfigRetrieverOptions()
  2.   .setScanPeriod(2000)
  3.   .addStore(store1)
  4.   .addStore(store2);
  6. ConfigRetriever retriever = ConfigRetriever.create(Vertx.vertx(), options);
  7. retriever.getConfig(json -> {
  8.   // Initial retrieval of the configuration
  9. });
  11. retriever.listen(change -> {
  12.   // Previous configuration
  13.   JsonObject previous = change.getPreviousConfiguration();
  14.   // New configuration
  15.   JsonObject conf = change.getNewConfiguration();
  16. });

检索最近一次获取的配置内容

可以快速、无需“等待”地获得最近一次获取的配置内容：

  1. JsonObject last = retriever.getCachedConfig();

使用流的方式读取配置

ConfigRetriever 提供流(Stream)的方式去获取配置。对应的流是 JsonObject 类型的可读流(ReadStream)。你可以注册相应的处理器(Handler)，来获得下面的事件通知：

  • 检索到新的配置
  • 获取新配置时发生错误
  • 当 ConfigRetriever 关闭时（endHandler 方法会被调用）
  1. ConfigRetrieverOptions options = new ConfigRetrieverOptions()
  2.   .setScanPeriod(2000)
  3.   .addStore(store1)
  4.   .addStore(store2);
  6. ConfigRetriever retriever = ConfigRetriever.create(Vertx.vertx(), options);
  7. retriever.configStream()
  8.   .endHandler(v -> {
  9.     // 关闭时
  10.   })
  11.   .exceptionHandler(t -> {
  12.     // 获取配置发生错误
  13.   })
  14.   .handler(conf -> {
  15.     // 配置内容
  16.   });

使用 Future 方式读取配置

ConfigRetriever 也支持采用 Future 作为返回值的方式获取配置：

  1. Future<JsonObject> future = ConfigRetriever.getConfigAsFuture(retriever);
  2. future.setHandler(ar -> {
  3.   if (ar.failed()) {
  4.     // Failed to retrieve the configuration
  5.   } else {
  6.     JsonObject config = ar.result();
  7.   }
  8. });

扩展 Config Retriever

你可以通过以下SPI对其进行扩展：

额外的配置格式

除了上文所提到的一系列现成的格式支持以外，Vert.x Config 也提供额外的格式支持组件，并可以在你的应用中使用。

HOCON 配置格式

HOCON 配置格式组件是对 Vert.x Config 的扩展，并且提供 HOCON) 格式的支持。

此格式支持 includes, json, properties, macros等。

使用 HOCON 配置格式

为了使用 HOCON 配置格式，您需要添加以下依赖：

  • Maven (在 pom.xml 文件中): 
  1. <dependency>
  2.   <groupId>io.vertx</groupId>
  3.   <artifactId>vertx-config-hocon</artifactId>
  4.   <version>3.4.1</version>
  5. </dependency>
  6. <dependency>
  7.   <groupId>io.vertx</groupId>
  8.   <artifactId>vertx-config</artifactId>
  9.   <version>3.4.1</version>
  10. </dependency>
  • Gradle (在 build.gradle 文件中):
  1. compile 'io.vertx:vertx-config:3.4.1'
  2. compile 'io.vertx:vertx-config-hocon:3.4.1'

配置使用 HOCON 格式

一旦添加完依赖，我们就需要配置 ConfigRetriever 来使用此格式：

  1. ConfigStoreOptions store = new ConfigStoreOptions()
  2.   .setType("file")
  3.   .setFormat("hocon")
  4.   .setConfig(new JsonObject()
  5.     .put("path", "my-config.conf")
  6.   );
  8. ConfigRetriever retriever = ConfigRetriever.create(vertx,
  9.     new ConfigRetrieverOptions().addStore(store));

你仅仅需要将 format 设置为 hocon。

YAML 配置格式

YAML 配置格式组件是对 Vert.x Config 的扩展，并且提供 YAML 格式的支持。

使用 YAML 配置格式

为了使用 YAML 配置格式，您需要添加以下依赖：

  • Maven (在 pom.xml 文件中): 
  1. <dependency>
  2.   <groupId>io.vertx</groupId>
  3.   <artifactId>vertx-config-yaml</artifactId>
  4.   <version>3.4.1</version>
  5. </dependency>
  6. <dependency>
  7.   <groupId>io.vertx</groupId>
  8.   <artifactId>vertx-config</artifactId>
  9.   <version>3.4.1</version>
  10. </dependency>
  • Gradle (在 build.gradle 文件中):
  1. compile 'io.vertx:vertx-config:3.4.1'
  2. compile 'io.vertx:vertx-config-yaml:3.4.1'

配置使用 YAML 格式

一旦添加完依赖，我们就需要配置 ConfigRetriever 来使用此格式：

  1. ConfigStoreOptions store = new ConfigStoreOptions()
  2.   .setType("file")
  3.   .setFormat("yaml")
  4.   .setConfig(new JsonObject()
  5.     .put("path", "my-config.yaml")
  6.   );
  8. ConfigRetriever retriever = ConfigRetriever.create(vertx,
  9.     new ConfigRetrieverOptions().addStore(store));

你仅仅需要将 format 设置为 yaml。

额外的配置仓库

除了上文所提到的一系列现成的配置仓库支持以外，Vert.x Config 也提供额外的配置仓库支持，并可以在你的应用中使用。

Git 配置仓库

Git 配置仓库组件是对 Vert.x Config 的扩展，支持从 Git 仓库(repository)中获取配置。

使用 Git 配置仓库

为了使用 Git 配置仓库，您需要添加以下依赖：

  • Maven (在 pom.xml 文件中): 
  1. <dependency>
  2.   <groupId>io.vertx</groupId>
  3.   <artifactId>vertx-config-git</artifactId>
  4.   <version>3.4.1</version>
  5. </dependency>
  6. <dependency>
  7.   <groupId>io.vertx</groupId>
  8.   <artifactId>vertx-config</artifactId>
  9.   <version>3.4.1</version>
  10. </dependency>
  • Gradle (在 build.gradle 文件中):
  1. compile 'io.vertx:vertx-config:3.4.1'
  2. compile 'io.vertx:vertx-config-git:3.4.1'

对配置仓库进行配置

一旦添加完依赖，我们就需要配置 ConfigRetriever 来使用此配置仓库：

  1. ConfigStoreOptions git = new ConfigStoreOptions()
  2.     .setType("git")
  3.     .setConfig(new JsonObject()
  4.         .put("url", "https://github.com/cescoffier/vertx-config-test.git")
  5.         .put("path", "local")
  6.         .put("filesets",
  7.             new JsonArray().add(new JsonObject().put("pattern", "*.json"))));
  9. ConfigRetriever retriever = ConfigRetriever.create(vertx,
  10.     new ConfigRetrieverOptions().addStore(git));

此配置仓库需要以下几个参数：

  • 仓库(Git repository)的 url（地址）
  • 仓库克隆的 path（本地路径）
  • 至少一个 fileset —— 需要读取的文件列表（模式）（等同于目录配置仓库的配置方式）

你也可以配置 branch(分支，默认为 master)，并且可以指定 remote（远程）仓库名称（默认读取 origin）

它是如何工作的

如果本地 path 不存在，那首先将配置的 Git 仓库克隆下来，然后从中读取匹配的文件集合。

如果本地 path 存在，那首先尝试更新（如果需要切换分支就切换分支）。如果更新失败，那配置读取也会失败。

Vert.x Config会周期性的去检查变更并更新本地仓库。

Kubernetes ConfigMap 配置仓库

Kubernetes ConfigMap 配置仓库组件是对 Vert.x Config 的扩展。它提供了对 Kubernetes ConfigMap 和 Secrets 的支持。

使用 Kubernetes ConfigMap 配置仓库

为了使用 Kubernetes ConfigMap 配置仓库，您需要添加以下依赖：

  • Maven (在 pom.xml 文件中): 
  1. <dependency>
  2.   <groupId>io.vertx</groupId>
  3.   <artifactId>vertx-config-kubernetes-configmap</artifactId>
  4.   <version>3.4.1</version>
  5. </dependency>
  6. <dependency>
  7.   <groupId>io.vertx</groupId>
  8.   <artifactId>vertx-config</artifactId>
  9.   <version>3.4.1</version>
  10. </dependency>
  • Gradle (在 build.gradle 文件中):
  1. compile 'io.vertx:vertx-config:3.4.1'
  2. compile 'io.vertx:vertx-config-kubernetes-configmap:3.4.1'

对配置仓库进行配置

一旦添加完依赖，我们需要配置 ConfigRetriever 来使用此配置仓库：

  1. ConfigStoreOptions store = new ConfigStoreOptions()
  2.     .setType("configmap")
  3.     .setConfig(new JsonObject()
  4.         .put("namespace", "my-project-namespace")
  5.         .put("name", "configmap-name")
  6.     );
  8. ConfigRetriever retriever = ConfigRetriever.create(vertx,
  9.     new ConfigRetrieverOptions().addStore(store));

你需要对配置仓库进行配置，来找到正确的 ConfigMap：

  • namespace —— 项目的命名空间，默认是 default。如果环境变量中有 KUBERNETES_NAMESPACE，则会优先使用此值
  • name —— ConfigMap 的名称。

如果 ConfigMap 由多个元素部分构成，你可以使用 key 参数确定哪一个才是我们要读取的。另外，应用必须要拥有对 ConfigMap 的读权限。

为了从 Secret 中读取数据，必须设置 secret 属性为 true：

  1. ConfigStoreOptions store = new ConfigStoreOptions()
  2.     .setType("configmap")
  3.     .setConfig(new JsonObject()
  4.         .put("namespace", "my-project-namespace")
  5.         .put("name", "my-secret")
  6.         .put("secret", true)
  7.     );
  9. ConfigRetriever retriever = ConfigRetriever.create(vertx,
  10.     new ConfigRetrieverOptions().addStore(store));

Redis 配置仓库

Redis 配置仓库组件是对 Vert.x Config 的扩展，支持从 Redis 服务器中获取配置。

使用 Redis 配置仓库

为了使用 Redis 配置仓库，您需要添加以下依赖：

  • Maven (在 pom.xml 文件中): 
  1. <dependency>
  2.   <groupId>io.vertx</groupId>
  3.   <artifactId>vertx-config-redis</artifactId>
  4.   <version>3.4.1</version>
  5. </dependency>
  6. <dependency>
  7.   <groupId>io.vertx</groupId>
  8.   <artifactId>vertx-config</artifactId>
  9.   <version>3.4.1</version>
  10. </dependency>
  • Gradle (在 build.gradle 文件中):
  1. compile 'io.vertx:vertx-config:3.4.1'
  2. compile 'io.vertx:vertx-config-redis:3.4.1'

对配置仓库进行配置

一旦添加完依赖，我们需要配置 ConfigRetriever 来使用此配置仓库：

  1. ConfigStoreOptions store = new ConfigStoreOptions()
  2.     .setType("redis")
  3.     .setConfig(new JsonObject()
  4.         .put("host", "localhost")
  5.         .put("port", 6379)
  6.         .put("key", "my-configuration")
  7.     );
  9. ConfigRetriever retriever = ConfigRetriever.create(vertx,
  10.     new ConfigRetrieverOptions().addStore(store));

此配置仓库会创建一个 RedisClient 实例。关于此部分的配置可以参考 Vert.x Redis Client 文档。

除此之外，你可以设置 key 参数用来指示存储配置对应的 field（字段），默认值是 configuration。

最终创建的 RedisClient 实例将通过 HGETALL 命令来检索配置。

ZooKeeper 配置仓库

ZooKeeper 配置仓库组件是对 Vert.x Config 的扩展，支持从 ZooKeeper 服务器中获得配置。

此组件底层使用 Apache Curator 作为访问 ZooKeeper 的客户端。

使用 ZooKeeper 配置仓库

为了使用 ZooKeeper 配置仓库，您需要添加以下依赖：

  • Maven (在 pom.xml 文件中): 
  1. <dependency>
  2.   <groupId>io.vertx</groupId>
  3.   <artifactId>vertx-config-zookeeper</artifactId>
  4.   <version>3.4.1</version>
  5. </dependency>
  6. <dependency>
  7.   <groupId>io.vertx</groupId>
  8.   <artifactId>vertx-config</artifactId>
  9.   <version>3.4.1</version>
  10. </dependency>
  • Gradle (在 build.gradle 文件中):
  1. compile 'io.vertx:vertx-config:3.4.1'
  2. compile 'io.vertx:vertx-config-zookeeper:3.4.1'

对配置仓库进行配置

一旦添加完依赖，我们需要配置 ConfigRetriever 来使用此配置仓库：

  1. ConfigStoreOptions store = new ConfigStoreOptions()
  2.     .setType("zookeeper")
  3.     .setConfig(new JsonObject()
  4.         .put("connection", "localhost:2181")
  5.         .put("path", "/path/to/my/conf")
  6.     );
  8. ConfigRetriever retriever = ConfigRetriever.create(vertx,
  9.     new ConfigRetrieverOptions().addStore(store));

使用此配置仓库通常需要配置 Apache Curator 客户端以及存储我们配置内容的 ZNode 路径（path）。此节点的数据格式可以是 JSON 或者其它任意支持的类型。

此配置仓库需要传入一系列参数：configuration 属性包含连接 ZooKeeper 服务器的地址和包含我们所配置的节点 path 路径。

额外可以配置的有：

  • maxRetries：尝试重新连接的次数，默认是 3
  • baseSleepTimeBetweenRetries： 在每一次重新尝试连接的间隔（Exponential Backoff 策略），默认是 1000 ms

Spring Config Server 配置仓库

Spring Config Server 配置仓库组件是对 Vert.x Config 的扩展，支持从 Spring Config Server 中获得配置。

使用 Spring Config Server 配置仓库

为了使用 Spring Config Server 配置仓库，您需要添加以下依赖：

  • Maven (在 pom.xml 文件中): 
  1. <dependency>
  2.   <groupId>io.vertx</groupId>
  3.   <artifactId>vertx-config-spring-config-server</artifactId>
  4.   <version>3.4.1</version>
  5. </dependency>
  6. <dependency>
  7.   <groupId>io.vertx</groupId>
  8.   <artifactId>vertx-config</artifactId>
  9.   <version>3.4.1</version>
  10. </dependency>
  • Gradle (在 build.gradle 文件中):
  1. compile 'io.vertx:vertx-config:3.4.1'
  2. compile 'io.vertx:vertx-config-spring-config-server:3.4.1'

对配置仓库进行配置

一旦添加完依赖，我们需要配置 ConfigRetriever 来使用此配置仓库。

  1. ConfigStoreOptions store = new ConfigStoreOptions()
  2.     .setType("spring-config-server")
  3.     .setConfig(new JsonObject().put("url", "http://localhost:8888/foo/development"));
  5. ConfigRetriever retriever = ConfigRetriever.create(vertx,
  6.     new ConfigRetrieverOptions().addStore(store));

以下的参数可供配置：

  • url: 读取配置的 url（必填）
  • timeout: 读取配置的超时时间，单位是毫秒，默认为 3000 ms
  • user: 用户（默认无权限）
  • password: 密码
  • httpClientConfiguration: 底层所使用的 HTTP 客户端的配置

原文档最后更新于 2017-03-15 15:54:14 CET