全部产品
云市场

开始使用动态配置

更新时间:2020-01-13 17:56:14

动态配置是一个配置管理框架,可以在分布式环境下、运行期动态管理应用集群配置参数。动态配置广泛用于业务参数配置、应急开关切换等场景。动态配置是微服务下的模块之一,用户只需要在每个工作空间开通中间件微服务,即可使用动态配置。用户实例之间的数据通过实例标识进行逻辑隔离,保证数据安全。

  • 编程 API 简单: 面向注解和普通 JavaBean 编程,编程方式统一且简单。
  • 实时性高: 秒级推送能力,集群实时配置变更。
  • 一致性高: 除变更推送能力外,客户端还定时检查数据版本,一旦有数据不一致就触发主动拉数据。

动态配置快速入门

开始使用前,请确认您已经完成系统环境配置,详情见 前置条件

使用动态配置的步骤为:

  1. 本地开发
  2. 发布应用
  3. 云端管控动态配置类

完整的工程示例参见 动态配置教程

本地开发

SOFA 中间件的 maven 坐标已统一规范,现有文档仅提供最新写法,升级兼容相关变更见:SOFABoot 发布说明

在 SOFABoot 工程中,仅需在 POM 中增加以下依赖。注意动态配置对 SOFABoot 父 POM 版本有要求,需要使用最新的 SOFABoot 版本,无需关注 ddcs-enterprise-sofa-boot-starter 的版本。

为保障中间件的安全性,所有的调用均需要验证访问者的身份,安全配置请参考 引入 SOFA 中间件

  1. <dependency>
  2. <groupId>com.alipay.sofa</groupId>
  3. <artifactId>ddcs-enterprise-sofa-boot-starter</artifactId>
  4. </dependency>

然后,创建动态配置类,配置类代码示例:

  1. @DObject(region = "AntCloud", appName = "dynamic-configuration-tutorial", id = "com.antcloud.tutorial.configuration.DynamicConfig")
  2. public class DynamicConfig {
  3. @DAttribute
  4. private String name;
  5. @DAttribute
  6. private int age;
  7. @DAttribute
  8. private boolean man;
  9. public void init() {
  10. DRMClient.getInstance().register(this);
  11. }
  12. public String getName() {
  13. return name;
  14. }
  15. public void setName(String name) {
  16. this.name = name;
  17. }
  18. public int getAge() {
  19. return age;
  20. }
  21. public void setAge(int age) {
  22. this.age = age;
  23. }
  24. public boolean isMan() {
  25. return man;
  26. }
  27. public void setMan(boolean man) {
  28. this.man = man;
  29. }
  30. }

Spring 配置示例:

  1. <bean id="dynamicConfig" class="com.antcloud.tutorial.configuration.tutorial.config.DynamicConfig" init-method="init"/>
  1. 首先,要提供一个普通的 Java 类,称之为配置类。该配置类它要符合 Java Bean 的规范,有若干私有属性,属性有对应的 getset 方法。例如上面的 nameageman,称为资源属性,资源属性只允许 String 和基本类型。
  2. 在配置类上加上 @DObject 注解,注意它的包名是 com.alipay.drm.client.api.annotation@DObject 需要提供属性 idregionappName
    • id 是全站唯一的字符串,一般用全类名来保证唯一,如不设值,则默认为全类名。
    • region 是用于区分不同组织的域,如可为每个子公司设定独立域。
    • appName 是应用名。
  3. 在资源属性上加上 @DAttribute 注解。注意包名同样是 com.alipay.drm.client.api.annotation
  4. 动态配置框架将通过反射的方式调用 getset 方法,从而读写资源属性。在特殊应用场景下,可能想要改变 getset 方法的内容,而不是简单的赋值、取值。这是可以的,但是不可以修改方法的形式(方法名、参数、返回值)。因为系统启动时动态配置框架会检查该属性是否符合 Java Bean 的规范,如果不符合,会跳过注册这个属性。
  5. 提供两个可选的注解 @BeforeUpdate@AfterUpdate。如果需要在每个属性更新前或更新后执行统一的操作,例如打日志,可以提供参数 (String,Object),无返回值的方法,打上相应注解。

    说明:这两个方法被调用时,传入的参数都是属性名和本次 set 方法的入参,并不是对应的私有属性更新前和更新后的值。这两个方法只适合用来执行打日志等次要任务,真正的业务逻辑要放在 set 方法中。

  6. 调用 register 方法注册到动态配置客户端后即可享受服务端动态修改数据后的秒级推送能力。

有关注解使用方法,参见 使用注解标识配置类

发布应用

SOFABoot 应用的发布,参见 SOFABoot 快速开始 - 云端运行

云端管控动态配置类

应用发布完成后,您需要前往微服务控制台进行动态配置项的创建、管理与推送操作。

新增动态配置

动态配置属性以键值对的形式定义,隶属于某一动态配置类。配置类与属性的关系可类比 Java 中的类与属性的关系。

  1. 在微服务平台页面,选择 微服务 >动态配置
  2. 点击 新增配置类
  3. 输入以下必填信息:
    • 所属域:配置类的一个命名空间,默认值为 Alipay,可通过编程注解修改。
    • 所属应用:配置类所属的应用名。
    • 类标识:必须与代码中配置类的注解 @DObject 中的字段保持一致。
    • 描述:自定义的描述信息。
      新增配置类
  4. 点击 确定,完成新增。
  5. 点击 新增属性,输入属性名与描述。属性为 key-value 的形式。具体属性值在推送至服务器时定义。
  6. 点击 确定

属性配置完成后,您可以选择将属性值直接发布到目标服务器上或通过灰度推送进行测试。

推送动态配置

您可以根据实际需求选择推送动态配置的方式:

  • 直接推送:立即将配置发布至所有订阅服务器。建议在验证配置无误后再进行此操作。
  • 灰度推送:仅将配置推送到几台服务器进行测试验证,并不保存入数据库。

操作步骤如下:

  1. 前往 微服务平台 > 微服务 > 动态配置 页面,在列表中点击要推送的配置类前的加号,展开属性列表。
  2. 点击要推送的属性名称,进入属性基本信息页面。
  3. 输入推送值。
    推送
  4. 选择推送方式:
    • 直接推送:点击 推送配置 > 确定
    • 灰度推送:
      1. 点击 灰度推送
      2. 在弹窗中勾选要推送的机器 IP 地址。只有已经订阅该配置的服务器 IP 地址会显示在弹窗列表中。您可以使用右上角的搜索栏来快速筛选要查找的服务器 IP 地址。
      3. 点击 推送

查看推送记录

点击属性基本信息页面的 查看推送记录 链接以查看推送记录列表。

每条推送记录包括以下信息:

  • 推送时间
  • 操作者
  • 推送值:本次操作推送的属性值。
  • 推送结果:Success(成功)或 Failure(失败)。

点击 复用 将关闭推送记录窗口并将当前推送记录的推送值填充到推送值文本框中,方便您重新进行推送。

使用注解标识配置类

动态配置的主要编程方式为使用注解标识配置类信息,参见上文 动态配置快速入门 了解如何完全使用注解方式配置一个动态配置类。通过本文,您将了解如何覆盖注解配置,实现更灵活的动态配置类初始化。

本文包含以下内容:

覆盖注解配置的方法

动态配置客户端提供两种方式注册配置类:

  1. # 1. 直接注册含有所有注解配置的配置类
  2. DistributedResourceManager#register(Object resourceObject);
  3. # 2. 注册配置类实例的同时,传入覆盖注解的配置项,Config 包含 @DObject 中的所有属性,Config 中配置的值会覆盖注解配置
  4. DistributedResourceManager#register(Object resourceObject, Config config);

属性注解高阶用法

动态配置默认用法是,当服务端推送配置后,客户端启动时会默认同步加载服务端配置值。如果希望服务端配置值仅在运行期生效,或者不希望客户端在启动期同步拉取配置值,可通过 @DAttribute 中的 DependencyLevel 来定义此属性的依赖等级。

属性依赖等级有以下几种:

依赖等级 依赖描述
NONE 无依赖,启动期不加载服务端值,启动此级别后,客户端仅会接收在运行期间服务端产生的配置推送。
ASYNC 异步更新,启动期异步加载服务端值,不关注加载结果。
WEAK 弱依赖,启动期同步加载服务端推送值,当服务端不可用时不影响应用正常启动;服务端可用后,客户端会依靠心跳检测重新拉取到服务端值。
STRONG 强依赖,启动期同步加载服务端值,如服务端未设置值则使用代码初始化值,如从服务端获取数据请求异常或客户端设值异常时均会抛出异常,应用启动失败。
EAGER 最强依赖,启动期必须拉取到服务端值,如服务端未推送过值则抛异常,应用启动失败。

导入导出动态配置元数据

动态配置提供元数据导入、导出,以方便用于数据迁移。操作步骤如下:

  • 进入 动态配置 页面,点击 更多 > 导出 按钮,导出文件。
  • 点击 更多 > 导入 按钮,可以导入任意一版产品导出的文件。

导入、导出元数据

导入数据文件格式

数据导入功能主要用于跨环境数据迁移,使用 JSON 格式。数据文件每一行对应一个完整的配置类 JSON 结构。多个配置类的 JSON 数据以换行符分隔。

导入数据示例如下:

  1. {"appName":"drmtestProject","attributes":[{"attributeName":"age","name":"年龄"},{"attributeName":"name","name":"名称"},{"attributeName":"test","name":"dd"}],"name":"测试资源类","region":"Alipay","resourceDomain":"Alipay.drmtestProject","resourceId":"com.alipay.share.drm.NormalDrmResourceTest"}
  2. {"appName":"test","attributes":[{"attributeName":"ddd","name":"xxx"}],"name":"描述","region":"domain","resourceDomain":"domain.test","resourceId":"classa"}

配置类 JSON 数据结构解析:

  1. {
  2. "region": "domain",
  3. "appName": "test",
  4. "resourceId": "classa",
  5. "name": "描述",
  6. "attributes": [
  7. {
  8. "attributeName": "ddd",
  9. "name": "xxx"
  10. }
  11. ]
  12. }