深入理解Apollo（四）Namespace设计

参考来源：https://github.com/ctripcorp/apollo

Java客户端使用指南

注意：本文档适用对象是Apollo系统的使用者，如果你是公司内Apollo系统的开发者/维护人员，建议先参考Apollo开发指南。

一、准备工作

1.1 环境要求
  • Java: 1.7+
  • Guava: 15.0+
    • Apollo客户端默认会引用Guava 19，如果你的项目引用了其它版本，请确保版本号大于等于15.0

注：对于Apollo客户端，如果有需要的话，可以做少量代码修改来降级到Java 1.6，详细信息可以参考Issue 483

1.2 必选设置

Apollo客户端依赖于AppId，Apollo Meta Server等环境信息来工作，所以请确保阅读下面的说明并且做正确的配置：

1.2.1 AppId

AppId是应用的身份信息，是从服务端获取配置的一个重要信息。

有以下3种方式设置，按照优先级从高到低分别为：

  1. System Property

Apollo 0.7.0+支持通过System Property传入app.id信息，如

-Dapp.id=YOUR-APP-ID
  1. Spring Boot application.properties

Apollo 1.0.0+支持通过Spring Boot的application.properties文件配置，如

app.id=YOUR-APP-ID
  1. app.properties

确保classpath:/META-INF/app.properties文件存在，并且其中内容形如：

app.id=YOUR-APP-ID

文件位置参考如下：

app-id-location

注：app.id是用来标识应用身份的唯一id，格式为string。

1.2.2 Apollo Meta Server

Apollo支持应用在不同的环境有不同的配置，所以需要在运行提供给Apollo客户端当前环境的Apollo Meta Server信息。默认情况下，meta server和config service是部署在同一个JVM进程，所以meta server的地址就是config service的地址。

为了实现meta server的高可用，推荐通过SLB（Software Load Balancer）做动态负载均衡。Meta server地址也可以填入IP，如http://1.1.1.1:8080,http://2.2.2.2:8080，不过生产环境还是建议使用域名（走slb），因为机器扩容、缩容等都可能导致IP列表的变化。

1.0.0版本开始支持以下方式配置apollo meta server信息，按照优先级从高到低分别为：

  1. 通过Java System Property

    apollo.meta

    • 可以通过Java的System Property apollo.meta来指定

    • 在Java程序启动脚本中，可以指定

      -Dapollo.meta=http://config-service-url
      • 如果是运行jar文件，需要注意格式是java -Dapollo.meta=http://config-service-url -jar xxx.jar

    • 也可以通过程序指定，如System.setProperty("apollo.meta", "http://config-service-url");

  2. 通过Spring Boot的配置文件

    • 可以在Spring Boot的application.properties或bootstrap.properties中指定apollo.meta=http://config-service-url

  3. 通过操作系统的System Environment

    APOLLO_META
    • 可以通过操作系统的System Environment APOLLO_META来指定
    • 注意key为全大写，且中间是_分隔

  4. 通过

    server.properties

    配置文件

    • 可以在server.properties配置文件中指定apollo.meta=http://config-service-url
    • 对于Mac/Linux，文件位置为/opt/settings/server.properties
    • 对于Windows，文件位置为C:\opt\settings\server.properties

  5. 通过

    app.properties

    配置文件

    • 可以在classpath:/META-INF/app.properties指定apollo.meta=http://config-service-url

  6. 通过Java system property

    ${env}_meta
    • 如果当前env是dev，那么用户可以配置-Ddev_meta=http://config-service-url
    • 使用该配置方式，那么就必须要正确配置Environment，详见1.2.4.1 Environment

  7. 通过操作系统的System Environment

    ${ENV}_META

    (1.2.0版本开始支持)

    • 如果当前env是dev，那么用户可以配置操作系统的System Environment DEV_META=http://config-service-url
    • 注意key为全大写
    • 使用该配置方式，那么就必须要正确配置Environment，详见1.2.4.1 Environment

  8. 通过

    apollo-env.properties

    文件

    • 用户也可以创建一个apollo-env.properties，放在程序的classpath下，或者放在spring boot应用的config目录下
    • 使用该配置方式，那么就必须要正确配置Environment，详见1.2.4.1 Environment
    • 文件内容形如：
dev.meta=http://1.1.1.1:8080
fat.meta=http://apollo.fat.xxx.com
uat.meta=http://apollo.uat.xxx.com
pro.meta=http://apollo.xxx.com

如果通过以上各种手段都无法获取到Meta Server地址，Apollo最终会fallback到http://apollo.meta作为Meta Server地址

1.2.2.1 自定义Apollo Meta Server地址定位逻辑

在1.0.0版本中，Apollo提供了MetaServerProvider SPI，用户可以注入自己的MetaServerProvider来自定义Meta Server地址定位逻辑。

由于我们使用典型的Java Service Loader模式，所以实现起来还是比较简单的。

有一点需要注意的是，apollo会在运行时按照顺序遍历所有的MetaServerProvider，直到某一个MetaServerProvider提供了一个非空的Meta Server地址，因此用户需要格外注意自定义MetaServerProvider的Order。规则是较小的Order具有较高的优先级，因此Order=0的MetaServerProvider会排在Order=1的MetaServerProvider的前面。

如果你的公司有很多应用需要接入Apollo，建议封装一个jar包，然后提供自定义的Apollo Meta Server定位逻辑，从而可以让接入Apollo的应用零配置使用。比如自己写一个xx-company-apollo-client，该jar包依赖apollo-client，在该jar包中通过spi方式定义自定义的MetaServerProvider实现，然后应用直接依赖xx-company-apollo-client即可。

MetaServerProvider的实现可以参考LegacyMetaServerProvider和DefaultMetaServerProvider。

1.2.3 本地缓存路径

Apollo客户端会把从服务端获取到的配置在本地文件系统缓存一份，用于在遇到服务不可用，或网络不通的时候，依然能从本地恢复配置，不影响应用正常运行。

本地缓存路径默认位于以下路径，所以请确保/opt/data或C:\opt\data\目录存在，且应用有读写权限。

  • Mac/Linux: /opt/data/{appId}/config-cache
  • Windows: C:\opt\data{appId}\config-cache

本地配置文件会以下面的文件名格式放置于本地缓存路径下：

{appId}+{cluster}+{namespace}.properties

  • appId就是应用自己的appId，如100004458
  • cluster就是应用使用的集群，一般在本地模式下没有做过配置的话，就是default
  • namespace就是应用使用的配置namespace，一般是application client-local-cache

文件内容以properties格式存储，比如如果有两个key，一个是request.timeout，另一个是batch，那么文件内容就是如下格式：

request.timeout=2000
batch=2000
1.2.3.1 自定义缓存路径

1.0.0版本开始支持以下方式自定义缓存路径，按照优先级从高到低分别为：

  1. 通过Java System Property

    apollo.cacheDir

    • 可以通过Java的System Property apollo.cacheDir来指定

    • 在Java程序启动脚本中，可以指定

      -Dapollo.cacheDir=/opt/data/some-cache-dir
      • 如果是运行jar文件，需要注意格式是java -Dapollo.cacheDir=/opt/data/some-cache-dir -jar xxx.jar

    • 也可以通过程序指定，如System.setProperty("apollo.cacheDir", "/opt/data/some-cache-dir");

  2. 通过Spring Boot的配置文件

    • 可以在Spring Boot的application.properties或bootstrap.properties中指定apollo.cacheDir=/opt/data/some-cache-dir

  3. 通过操作系统的System Environment

    APOLLO_CACHEDIR
    • 可以通过操作系统的System Environment APOLLO_CACHEDIR来指定
    • 注意key为全大写，且中间是_分隔

  4. 通过

    server.properties

    配置文件

    • 可以在server.properties配置文件中指定apollo.cacheDir=/opt/data/some-cache-dir
    • 对于Mac/Linux，文件位置为/opt/settings/server.properties
    • 对于Windows，文件位置为C:\opt\settings\server.properties

注：本地缓存路径也可用于容灾目录，如果应用在所有config service都挂掉的情况下需要扩容，那么也可以先把配置从已有机器上的缓存路径复制到新机器上的相同缓存路径

1.2.4 可选设置
1.2.4.1 Environment

Environment可以通过以下3种方式的任意一个配置：

  1. 通过Java System Property

    • 可以通过Java的System Property env来指定环境

    • 在Java程序启动脚本中，可以指定

      -Denv=YOUR-ENVIRONMENT
      • 如果是运行jar文件，需要注意格式是java -Denv=YOUR-ENVIRONMENT -jar xxx.jar

    • 注意key为全小写

  2. 通过操作系统的System Environment

    • 还可以通过操作系统的System Environment ENV来指定
    • 注意key为全大写

  3. 通过配置文件

    • 最后一个推荐的方式是通过配置文件来指定env=YOUR-ENVIRONMENT
    • 对于Mac/Linux，文件位置为/opt/settings/server.properties
    • 对于Windows，文件位置为C:\opt\settings\server.properties

文件内容形如：

env=DEV

目前，env支持以下几个值（大小写不敏感）：

  • DEV
    • Development environment
  • FAT
    • Feature Acceptance Test environment
  • UAT
    • User Acceptance Test environment
  • PRO
    • Production environment

更多环境定义，可以参考Env.java

1.2.4.2 Cluster（集群）

Apollo支持配置按照集群划分，也就是说对于一个appId和一个环境，对不同的集群可以有不同的配置。

1.0.0版本开始支持以下方式集群，按照优先级从高到低分别为：

  1. 通过Java System Property

    apollo.cluster

    • 可以通过Java的System Property apollo.cluster来指定

    • 在Java程序启动脚本中，可以指定

      -Dapollo.cluster=SomeCluster
      • 如果是运行jar文件，需要注意格式是java -Dapollo.cluster=SomeCluster -jar xxx.jar

    • 也可以通过程序指定，如System.setProperty("apollo.cluster", "SomeCluster");

  2. 通过Spring Boot的配置文件

    • 可以在Spring Boot的application.properties或bootstrap.properties中指定apollo.cluster=SomeCluster

  3. 通过

    server.properties

    配置文件

    • 可以在server.properties配置文件中指定idc=xxx
    • 对于Mac/Linux，文件位置为/opt/settings/server.properties
    • 对于Windows，文件位置为C:\opt\settings\server.properties

Cluster Precedence（集群顺序）

  1. 如果apollo.cluster和idc同时指定：
    • 我们会首先尝试从apollo.cluster指定的集群加载配置
    • 如果没找到任何配置，会尝试从idc指定的集群加载配置
    • 如果还是没找到，会从默认的集群（default）加载
  2. 如果只指定了apollo.cluster：
    • 我们会首先尝试从apollo.cluster指定的集群加载配置
    • 如果没找到，会从默认的集群（default）加载
  3. 如果只指定了idc：
    • 我们会首先尝试从idc指定的集群加载配置
    • 如果没找到，会从默认的集群（default）加载
  4. 如果apollo.cluster和idc都没有指定：
    • 我们会从默认的集群（default）加载配置

二、Maven Dependency

Apollo的客户端jar包已经上传到中央仓库，应用在实际使用时只需要按照如下方式引入即可。

    <dependency>
        <groupId>com.ctrip.framework.apollo</groupId>
        <artifactId>apollo-client</artifactId>
        <version>1.1.0</version>
    </dependency>

三、客户端用法

Apollo支持API方式和Spring整合方式，该怎么选择用哪一种方式？

  • API方式灵活，功能完备，配置值实时更新（热发布），支持所有Java环境。

  • Spring方式接入简单，结合Spring有N种酷炫的玩法，如

    • Placeholder方式：
      • 代码中直接使用，如：@Value("${someKeyFromApollo:someDefaultValue}")
      • 配置文件中使用替换placeholder，如：spring.datasource.url: ${someKeyFromApollo:someDefaultValue}
      • 直接托管spring的配置，如在apollo中直接配置spring.datasource.url=jdbc:mysql://localhost:3306/somedb?characterEncoding=utf8
    • Spring boot的@ConfigurationProperties方式
    • 从v0.10.0开始的版本支持placeholder在运行时自动更新，具体参见PR #972。（v0.10.0之前的版本在配置变化后不会重新注入，需要重启才会更新，如果需要配置值实时更新，可以参考后续3.2.2 Spring Placeholder的使用的说明）

  • Spring方式也可以结合API方式使用，如注入Apollo的Config对象，就可以照常通过API方式获取配置了：

    @ApolloConfig
private Config config; //inject config for namespace application

  • 更多有意思的实际使用场景和示例代码，请参考apollo-use-cases

3.1 API使用方式

API方式是最简单、高效使用Apollo配置的方式，不依赖Spring框架即可使用。

3.1.1 获取默认namespace的配置（application）
Config config = ConfigService.getAppConfig(); //config instance is singleton for each namespace and is never null
String someKey = "someKeyFromDefaultNamespace";
String someDefaultValue = "someDefaultValueForTheKey";
String value = config.getProperty(someKey, someDefaultValue);

通过上述的config.getProperty可以获取到someKey对应的实时最新的配置值。

另外，配置值从内存中获取，所以不需要应用自己做缓存。

3.1.2 监听配置变化事件

监听配置变化事件只在应用真的关心配置变化，需要在配置变化时得到通知时使用，比如：数据库连接串变化后需要重建连接等。

如果只是希望每次都取到最新的配置的话，只需要按照上面的例子，调用config.getProperty即可。

Config config = ConfigService.getAppConfig(); //config instance is singleton for each namespace and is never null
config.addChangeListener(new ConfigChangeListener() {
    @Override
    public void onChange(ConfigChangeEvent changeEvent) {
        System.out.println("Changes for namespace " + changeEvent.getNamespace());
        for (String key : changeEvent.changedKeys()) {
            ConfigChange change = changeEvent.getChange(key);
            System.out.println(String.format("Found change - key: %s, oldValue: %s, newValue: %s, changeType: %s", change.getPropertyName(), change.getOldValue(), change.getNewValue(), change.getChangeType()));
        }
    }
});
3.1.3 获取公共Namespace的配置
String somePublicNamespace = "CAT";
Config config = ConfigService.getConfig(somePublicNamespace); //config instance is singleton for each namespace and is never null
String someKey = "someKeyFromPublicNamespace";
String someDefaultValue = "someDefaultValueForTheKey";
String value = config.getProperty(someKey, someDefaultValue);
3.1.4 获取非properties格式namespace的配置
3.1.4.1 yaml/yml格式的namespace

apollo-client 1.3.0版本开始对yaml/yml做了更好的支持，使用起来和properties格式一致。

Config config = ConfigService.getConfig("application.yml");
String someKey = "someKeyFromYmlNamespace";
String someDefaultValue = "someDefaultValueForTheKey";
String value = config.getProperty(someKey, someDefaultValue);
3.1.4.2 非yaml/yml格式的namespace

获取时需要使用ConfigService.getConfigFile接口并指定Format，如ConfigFileFormat.XML。

String someNamespace = "test";
ConfigFile configFile = ConfigService.getConfigFile("test", ConfigFileFormat.XML);
String content = configFile.getContent();
3.2 Spring整合方式
3.2.1 配置

Apollo也支持和Spring整合（Spring 3.1.1+），只需要做一些简单的配置就可以了。

Apollo目前既支持比较传统的基于XML的配置，也支持目前比较流行的基于Java（推荐）的配置。

如果是Spring Boot环境，建议参照3.2.1.3 Spring Boot集成方式（推荐）配置。

需要注意的是，如果之前有使用org.springframework.beans.factory.config.PropertyPlaceholderConfigurer的，请替换成org.springframework.context.support.PropertySourcesPlaceholderConfigurer。Spring 3.1以后就不建议使用PropertyPlaceholderConfigurer了，要改用PropertySourcesPlaceholderConfigurer。

如果之前有使用<context:property-placeholder>，请注意xml中引入的spring-context.xsd版本需要是3.1以上（一般只要没有指定版本会自动升级的），建议使用不带版本号的形式引入，如：http://www.springframework.org/schema/context/spring-context.xsd

注1：yaml/yml格式的namespace从1.3.0版本开始支持和Spring整合

注2：非properties、非yaml/yml格式（如xml，json等）的namespace暂不支持和Spring整合。

3.2.1.1 基于XML的配置

注：需要把apollo相关的xml namespace加到配置文件头上，不然会报xml语法错误。

1.注入默认namespace的配置到Spring中

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:apollo="http://www.ctrip.com/schema/apollo"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
       http://www.ctrip.com/schema/apollo http://www.ctrip.com/schema/apollo.xsd">
    <!-- 这个是最简单的配置形式，一般应用用这种形式就可以了，用来指示Apollo注入application namespace的配置到Spring环境中 -->
    <apollo:config/>
    <bean class="com.ctrip.framework.apollo.spring.TestXmlBean">
        <property name="timeout" value="${timeout:100}"/>
        <property name="batch" value="${batch:200}"/>
    </bean>
</beans>

2.注入多个namespace的配置到Spring中

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:apollo="http://www.ctrip.com/schema/apollo"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
       http://www.ctrip.com/schema/apollo http://www.ctrip.com/schema/apollo.xsd">
    <!-- 这个是最简单的配置形式，一般应用用这种形式就可以了，用来指示Apollo注入application namespace的配置到Spring环境中 -->
    <apollo:config/>
    <!-- 这个是稍微复杂一些的配置形式，指示Apollo注入FX.apollo和application.yml namespace的配置到Spring环境中 -->
    <apollo:config namespaces="FX.apollo,application.yml"/>
    <bean class="com.ctrip.framework.apollo.spring.TestXmlBean">
        <property name="timeout" value="${timeout:100}"/>
        <property name="batch" value="${batch:200}"/>
    </bean>
</beans>

3.注入多个namespace，并且指定顺序

Spring的配置是有顺序的，如果多个property source都有同一个key，那么最终是顺序在前的配置生效。

apollo:config如果不指定order，那么默认是最低优先级。

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:apollo="http://www.ctrip.com/schema/apollo"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
       http://www.ctrip.com/schema/apollo http://www.ctrip.com/schema/apollo.xsd">
    <apollo:config order="2"/>
    <!-- 这个是最复杂的配置形式，指示Apollo注入FX.apollo和application.yml namespace的配置到Spring环境中，并且顺序在application前面 -->
    <apollo:config namespaces="FX.apollo,application.yml" order="1"/>
    <bean class="com.ctrip.framework.apollo.spring.TestXmlBean">
        <property name="timeout" value="${timeout:100}"/>
        <property name="batch" value="${batch:200}"/>
    </bean>
</beans>
3.2.1.2 基于Java的配置（推荐）

相对于基于XML的配置，基于Java的配置是目前比较流行的方式。

注意@EnableApolloConfig要和@Configuration一起使用，不然不会生效。

1.注入默认namespace的配置到Spring中

//这个是最简单的配置形式，一般应用用这种形式就可以了，用来指示Apollo注入application namespace的配置到Spring环境中
@Configuration
@EnableApolloConfig
public class AppConfig {
  @Bean
  public TestJavaConfigBean javaConfigBean() {
    return new TestJavaConfigBean();
  }
}

2.注入多个namespace的配置到Spring中

@Configuration
@EnableApolloConfig
public class SomeAppConfig {
  @Bean
  public TestJavaConfigBean javaConfigBean() {
    return new TestJavaConfigBean();
  }
}
   
//这个是稍微复杂一些的配置形式，指示Apollo注入FX.apollo和application.yml namespace的配置到Spring环境中
@Configuration
@EnableApolloConfig({"FX.apollo", "application.yml"})
public class AnotherAppConfig {}

3.注入多个namespace，并且指定顺序

//这个是最复杂的配置形式，指示Apollo注入FX.apollo和application.yml namespace的配置到Spring环境中，并且顺序在application前面
@Configuration
@EnableApolloConfig(order = 2)
public class SomeAppConfig {
  @Bean
  public TestJavaConfigBean javaConfigBean() {
    return new TestJavaConfigBean();
  }
}
@Configuration
@EnableApolloConfig(value = {"FX.apollo", "application.yml"}, order = 1)
public class AnotherAppConfig {}
3.2.1.3 Spring Boot集成方式（推荐）

Spring Boot除了支持上述两种集成方式以外，还支持通过application.properties/bootstrap.properties来配置，该方式能使配置在更早的阶段注入，比如使用@ConditionalOnProperty的场景或者是有一些spring-boot-starter在启动阶段就需要读取配置做一些事情（如dubbo-spring-boot-project），所以对于Spring Boot环境建议通过以下方式来接入Apollo(需要0.10.0及以上版本）。

使用方式很简单，只需要在application.properties/bootstrap.properties中按照如下样例配置即可。

  1. 注入默认application namespace的配置示例
     # will inject 'application' namespace in bootstrap phase
     apollo.bootstrap.enabled = true
  1. 注入非默认application namespace或多个namespace的配置示例
     apollo.bootstrap.enabled = true
     # will inject 'application', 'FX.apollo' and 'application.yml' namespaces in bootstrap phase
     apollo.bootstrap.namespaces = application,FX.apollo,application.yml
  1. 将Apollo配置加载提到初始化日志系统之前(1.2.0+)

从1.2.0版本开始，如果希望把日志相关的配置（如logging.level.root=info或logback-spring.xml中的参数）也放在Apollo管理，那么可以额外配置apollo.bootstrap.eagerLoad.enabled=true来使Apollo的加载顺序放到日志系统加载之前，不过这会导致Apollo的启动过程无法通过日志的方式输出(因为执行Apollo加载的时候，日志系统压根没有准备好呢！所以在Apollo代码中使用Slf4j的日志输出便没有任何内容)，更多信息可以参考PR 1614。参考配置示例如下：

     # will inject 'application' namespace in bootstrap phase
     apollo.bootstrap.enabled = true
     # put apollo initialization before logging system initialization
     apollo.bootstrap.eagerLoad.enabled=true
3.2.2 Spring Placeholder的使用

Spring应用通常会使用Placeholder来注入配置，使用的格式形如 s o m e K e y : s o m e D e f a u l t V a l u e ， 如 {someKey:someDefaultValue}，如 someKey:someDefaultValue，如{timeout:100}。冒号前面的是key，冒号后面的是默认值。

建议在实际使用时尽量给出默认值，以免由于key没有定义导致运行时错误。

从v0.10.0开始的版本支持placeholder在运行时自动更新，具体参见PR #972。

如果需要关闭placeholder在运行时自动更新功能，可以通过以下两种方式关闭：

  1. 通过设置System Property apollo.autoUpdateInjectedSpringProperties，如启动时传入-Dapollo.autoUpdateInjectedSpringProperties=false
  2. 通过设置META-INF/app.properties中的apollo.autoUpdateInjectedSpringProperties属性，如
app.id=SampleApp
apollo.autoUpdateInjectedSpringProperties=false
3.2.2.1 XML使用方式

假设我有一个TestXmlBean，它有两个配置项需要注入：

public class TestXmlBean {
  private int timeout;
  private int batch;
 
  public void setTimeout(int timeout) {
    this.timeout = timeout;
  }

  public void setBatch(int batch) {
    this.batch = batch;
  }
 
  public int getTimeout() {
    return timeout;
  }
 
  public int getBatch() {
    return batch;
  }
}

那么，我在XML中会使用如下方式来定义（假设应用默认的application namespace中有timeout和batch的配置项）：

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:apollo="http://www.ctrip.com/schema/apollo"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
       http://www.ctrip.com/schema/apollo http://www.ctrip.com/schema/apollo.xsd">
    <apollo:config/>
    <bean class="com.ctrip.framework.apollo.spring.TestXmlBean">
        <property name="timeout" value="${timeout:100}"/>
        <property name="batch" value="${batch:200}"/>
    </bean>
</beans>
3.2.2.2 Java Config使用方式

假设我有一个TestJavaConfigBean，通过Java Config的方式还可以使用@Value的方式注入：

public class TestJavaConfigBean {
  @Value("${timeout:100}")
  private int timeout;
  private int batch;
 
  @Value("${batch:200}")
  public void setBatch(int batch) {
    this.batch = batch;
  }
 
  public int getTimeout() {
    return timeout;
  }
 
  public int getBatch() {
    return batch;
  }
}

在Configuration类中按照下面的方式使用（假设应用默认的application namespace中有timeout和batch的配置项）：

@Configuration
@EnableApolloConfig
public class AppConfig {
  @Bean
  public TestJavaConfigBean javaConfigBean() {
    return new TestJavaConfigBean();
  }
}
3.2.2.3 ConfigurationProperties使用方式

Spring Boot提供了@ConfigurationProperties把配置注入到bean对象中。

Apollo也支持这种方式，下面的例子会把redis.cache.expireSeconds和redis.cache.commandTimeout分别注入到SampleRedisConfig的expireSeconds和commandTimeout字段中。

@ConfigurationProperties(prefix = "redis.cache")
public class SampleRedisConfig {
  private int expireSeconds;
  private int commandTimeout;

  public void setExpireSeconds(int expireSeconds) {
    this.expireSeconds = expireSeconds;
  }

  public void setCommandTimeout(int commandTimeout) {
    this.commandTimeout = commandTimeout;
  }
}

在Configuration类中按照下面的方式使用（假设应用默认的application namespace中有redis.cache.expireSeconds和redis.cache.commandTimeout的配置项）：

@Configuration
@EnableApolloConfig
public class AppConfig {
  @Bean
  public SampleRedisConfig sampleRedisConfig() {
    return new SampleRedisConfig();
  }
}

需要注意的是，@ConfigurationProperties如果需要在Apollo配置变化时自动更新注入的值，需要配合使用EnvironmentChangeEvent或RefreshScope。相关代码实现，可以参考apollo-use-cases项目中的ZuulPropertiesRefresher.java和apollo-demo项目中的SampleRedisConfig.java以及SpringBootApolloRefreshConfig.java

3.2.3 Spring Annotation支持

Apollo同时还增加了几个新的Annotation来简化在Spring环境中的使用。

  1. @ApolloConfig
    • 用来自动注入Config对象
  2. @ApolloConfigChangeListener
    • 用来自动注册ConfigChangeListener
  3. @ApolloJsonValue
    • 用来把配置的json字符串自动注入为对象

使用样例如下：

public class TestApolloAnnotationBean {
  @ApolloConfig
  private Config config; //inject config for namespace application
  @ApolloConfig("application")
  private Config anotherConfig; //inject config for namespace application
  @ApolloConfig("FX.apollo")
  private Config yetAnotherConfig; //inject config for namespace FX.apollo
  @ApolloConfig("application.yml")
  private Config ymlConfig; //inject config for namespace application.yml
 
  /**
   * ApolloJsonValue annotated on fields example, the default value is specified as empty list - []
   * <br />
   * jsonBeanProperty=[{"someString":"hello","someInt":100},{"someString":"world!","someInt":200}]
   */
  @ApolloJsonValue("${jsonBeanProperty:[]}")
  private List<JsonBean> anotherJsonBeans;

  @Value("${batch:100}")
  private int batch;
  
  //config change listener for namespace application
  @ApolloConfigChangeListener
  private void someOnChange(ConfigChangeEvent changeEvent) {
    //update injected value of batch if it is changed in Apollo
    if (changeEvent.isChanged("batch")) {
      batch = config.getIntProperty("batch", 100);
    }
  }
 
  //config change listener for namespace application
  @ApolloConfigChangeListener("application")
  private void anotherOnChange(ConfigChangeEvent changeEvent) {
    //do something
  }
 
  //config change listener for namespaces application, FX.apollo and application.yml
  @ApolloConfigChangeListener({"application", "FX.apollo", "application.yml"})
  private void yetAnotherOnChange(ConfigChangeEvent changeEvent) {
    //do something
  }

  //example of getting config from Apollo directly
  //this will always return the latest value of timeout
  public int getTimeout() {
    return config.getIntProperty("timeout", 200);
  }

  //example of getting config from injected value
  //the program needs to update the injected value when batch is changed in Apollo using @ApolloConfigChangeListener shown above
  public int getBatch() {
    return this.batch;
  }

  private static class JsonBean{
    private String someString;
    private int someInt;
  }
}

在Configuration类中按照下面的方式使用：

@Configuration
@EnableApolloConfig
public class AppConfig {
  @Bean
  public TestApolloAnnotationBean testApolloAnnotationBean() {
    return new TestApolloAnnotationBean();
  }
}
3.2.4 已有配置迁移

很多情况下，应用可能已经有不少配置了，比如Spring Boot的应用，就会有bootstrap.properties/yml, application.properties/yml等配置。

在应用接入Apollo之后，这些配置是可以非常方便的迁移到Apollo的，具体步骤如下：

  1. 在Apollo为应用新建项目
  2. 在应用中配置好META-INF/app.properties
  3. 建议把原先配置先转为properties格式，然后通过Apollo提供的文本编辑模式全部粘帖到应用的application namespace，发布配置
  4. 如果原来是yml，想继续使用yml来编辑配置，那么可以创建私有的application.yml namespace，把原来的配置全部粘贴进去，发布配置
    • 需要apollo-client是1.3.0及以上版本
  5. 把原先的配置文件如bootstrap.properties/yml, application.properties/yml从项目中删除
    • 如果需要保留本地配置文件，需要注意部分配置如server.port必须确保本地文件已经删除该配置项

如：

spring.application.name = reservation-service
server.port = 8080

logging.level = ERROR

eureka.client.serviceUrl.defaultZone = http://127.0.0.1:8761/eureka/
eureka.client.healthcheck.enabled = true
eureka.client.registerWithEureka = true
eureka.client.fetchRegistry = true
eureka.client.eurekaServiceUrlPollIntervalSeconds = 60

eureka.instance.preferIpAddress = true

text-mode-spring-boot-config-sample

3.3 Demo

项目中有一个样例客户端的项目：apollo-demo，具体信息可以参考Apollo开发指南中的2.3 Java样例客户端启动部分。

更多使用案例Demo可以参考Apollo使用场景和示例代码。

四、客户端设计

client-architecture

上图简要描述了Apollo客户端的实现原理：

  1. 客户端和服务端保持了一个长连接，从而能第一时间获得配置更新的推送。（通过Http Long Polling实现）
  2. 客户端还会定时从Apollo配置中心服务端拉取应用的最新配置。
    • 这是一个fallback机制，为了防止推送机制失效导致配置不更新
    • 客户端定时拉取会上报本地版本，所以一般情况下，对于定时拉取的操作，服务端都会返回304 - Not Modified
    • 定时频率默认为每5分钟拉取一次，客户端也可以通过在运行时指定System Property: apollo.refreshInterval来覆盖，单位为分钟。
  3. 客户端从Apollo配置中心服务端获取到应用的最新配置后，会保存在内存中
  4. 客户端会把从服务端获取到的配置在本地文件系统缓存一份
    • 在遇到服务不可用，或网络不通的时候，依然能从本地恢复配置
  5. 应用程序可以从Apollo客户端获取最新的配置、订阅配置更新通知

五、本地开发模式

Apollo客户端还支持本地开发模式，这个主要用于当开发环境无法连接Apollo服务器的时候，比如在邮轮、飞机上做相关功能开发。

在本地开发模式下，Apollo只会从本地文件读取配置信息，不会从Apollo服务器读取配置。

可以通过下面的步骤开启Apollo本地开发模式。

5.1 修改环境

修改/opt/settings/server.properties（Mac/Linux）或C:\opt\settings\server.properties（Windows）文件，设置env为Local：

env=Local

更多配置环境的方式请参考1.2.2 Environment

5.2 准备本地配置文件

在本地开发模式下，Apollo客户端会从本地读取文件，所以我们需要事先准备好配置文件。

5.2.1 本地配置目录

本地配置目录位于：

  • Mac/Linux: /opt/data/{appId}/config-cache
  • Windows: C:\opt\data{appId}\config-cache

appId就是应用的appId，如100004458。

请确保该目录存在，且应用程序对该目录有读权限。

【小技巧】 推荐的方式是先在普通模式下使用Apollo，这样Apollo会自动创建该目录并在目录下生成配置文件。

5.2.2 本地配置文件

本地配置文件需要按照一定的文件名格式放置于本地配置目录下，文件名格式如下：

{appId}+{cluster}+{namespace}.properties

  • appId就是应用自己的appId，如100004458
  • cluster就是应用使用的集群，一般在本地模式下没有做过配置的话，就是default
  • namespace就是应用使用的配置namespace，一般是application client-local-cache

文件内容以properties格式存储，比如如果有两个key，一个是request.timeout，另一个是batch，那么文件内容就是如下格式：

request.timeout=2000
batch=2000
5.3 修改配置

在本地开发模式下，Apollo不会实时监测文件内容是否有变化，所以如果修改了配置，需要重启应用生效。

六、测试模式

1.1.0版本开始增加了apollo-mockserver，从而可以很好地支持单元测试时需要mock配置的场景，使用方法如下：

6.1 引入pom依赖
<dependency>
    <groupId>com.ctrip.framework.apollo</groupId>
    <artifactId>apollo-mockserver</artifactId>
    <version>1.1.0</version>
</dependency>
6.2 在test的resources下放置mock的数据

文件名格式约定为mockdata-{namespace}.properties

image

6.3 写测试类

更多使用demo可以参考ApolloMockServerApiTest.java和ApolloMockServerSpringIntegrationTest.java。

1. 什么是Namespace?
Namespace是配置项的集合，类似于一个配置文件的概念。

2. 什么是“application”的Namespace？
Apollo在创建项目的时候，都会默认创建一个“application”的Namespace。顾名思义，“application”是给应用自身使用的，熟悉Spring Boot的同学都知道，Spring Boot项目都有一个默认配置文件application.yml。在这里application.yml就等同于“application”的Namespace。对于90%的应用来说，“application”的Namespace已经满足日常配置使用场景了。

客户端获取“application” Namespace的代码如下：
  Config config = ConfigService.getAppConfig();
客户端获取非“application” Namespace的代码如下：
  Config config = ConfigService.getConfig(namespaceName);
3. Namespace的格式有哪些？
配置文件有多种格式，例如：properties、xml、yml、yaml、json等。同样Namespace也具有这些格式。在Portal UI中可以看到“application”的Namespace上有一个“properties”标签，表明“application”是properties格式的。

注：非properties格式的namespace，在客户端使用时需要调用ConfigService.getConfigFile(String namespace, ConfigFileFormat configFileFormat)来获取，如果使用Http接口直接调用时，对应的namespace参数需要传入namespace的名字加上后缀名，如datasources.json。

4. Namespace的获取权限分类
Namespace的获取权限分为两种：

private （私有的）
public （公共的）
这里的获取权限是相对于Apollo客户端来说的。

4.1 private权限
private权限的Namespace，只能被所属的应用获取到。一个应用尝试获取其它应用private的Namespace，Apollo会报“404”异常。

4.2 public权限
public权限的Namespace，能被任何应用获取。

5. Namespace的类型
Namespace类型有三种：

私有类型
公共类型
关联类型（继承类型）
5.1 私有类型
私有类型的Namespace具有private权限。例如上文提到的“application” Namespace就是私有类型。

5.2 公共类型
5.2.1 含义
公共类型的Namespace具有public权限。公共类型的Namespace相当于游离于应用之外的配置，且通过Namespace的名称去标识公共Namespace，所以公共的Namespace的名称必须全局唯一。

5.2.2 使用场景
部门级别共享的配置
小组级别共享的配置
几个项目之间共享的配置
中间件客户端的配置
5.3 关联类型
5.3.1 含义
关联类型又可称为继承类型，关联类型具有private权限。关联类型的Namespace继承于公共类型的Namespace，用于覆盖公共Namespace的某些配置。例如公共的Namespace有两个配置项

k1 = v1
k2 = v2
然后应用A有一个关联类型的Namespace关联了此公共Namespace，且覆盖了配置项k1，新值为v3。那么在应用A实际运行时，获取到的公共Namespace的配置为：

k1 = v3
k2 = v2
5.3.2 使用场景
举一个实际使用的场景。假设RPC框架的配置（如：timeout）有以下要求：

提供一份全公司默认的配置且可动态调整
RPC客户端项目可以自定义某些配置项且可动态调整
如果把以上两点要求去掉“动态调整”，那么做法很简单。在rpc-client.jar包里有一份配置文件，每次修改配置文件然后重新发一个版本的jar包即可。同理，客户端项目修改配置也是如此。
如果只支持客户端项目可动态调整配置。客户端项目可以在Apollo “application” Namespace上配置一些配置项。在初始化service的时候，从Apollo上读取配置即可。这样做的坏处就是，每个项目都要自定义一些key，不统一。
那么如何完美支持以上需求呢？答案就是结合使用Apollo的公共类型的Namespace和关联类型的Namespace。RPC团队在Apollo上维护一个叫“rpc-client”的公共Namespace，在“rpc-client” Namespace上配置默认的参数值。rpc-client.jar里的代码读取“rpc-client”Namespace的配置即可。如果需要调整默认的配置，只需要修改公共类型“rpc-client” Namespace的配置。如果客户端项目想要自定义或动态修改某些配置项，只需要在Apollo 自己项目下关联“rpc-client”，就能创建关联类型“rpc-client”的Namespace。然后在关联类型“rpc-client”的Namespace下修改配置项即可。这里有一点需要指出的，那就是rpc-client.jar是在应用容器里运行的，所以rpc-client获取到的“rpc-client” Namespace的配置是应用的关联类型的Namespace加上公共类型的Namespace。
5.4 例子
如下图所示，有三个应用：应用A、应用B、应用C。

应用A有两个私有类型的Namespace：application和NS-Private，以及一个关联类型的Namespace：NS-Public。
应用B有一个私有类型的Namespace：application，以及一个公共类型的Namespace：NS-Public。
应用C只有一个私有类型的Namespace：application
Namespace例子

5.4.1 应用A获取Apollo配置
  //application 
  Config appConfig = ConfigService.getAppConfig();
  appConfig.getProperty("k1", null); // k1 = v11
  appConfig.getProperty("k2", null); // k2 = v21
  
  //NS-Private
  Config privateConfig = ConfigService.getConfig("NS-Private");
  privateConfig.getProperty("k1", null); // k1 = v3
  privateConfig.getProperty("k3", null); // k3 = v4
  
  //NS-Public，覆盖公共类型配置的情况，k4被覆盖
  Config publicConfig = ConfigService.getConfig("NS-Public");
  publicConfig.getProperty("k4", null); // k4 = v6 cover
  publicConfig.getProperty("k6", null); // k6 = v6
  publicConfig.getProperty("k7", null); // k7 = v7
5.4.2 应用B获取Apollo配置
  //application
  Config appConfig = ConfigService.getAppConfig();
  appConfig.getProperty("k1", null); // k1 = v12
  appConfig.getProperty("k2", null); // k2 = null
  appConfig.getProperty("k3", null); // k3 = v32
  
  //NS-Private，由于没有NS-Private Namespace 所以获取到default value
  Config privateConfig = ConfigService.getConfig("NS-Private");
  privateConfig.getProperty("k1", "default value"); 
  
  //NS-Public
  Config publicConfig = ConfigService.getConfig("NS-Public");
  publicConfig.getProperty("k4", null); // k4 = v5
  publicConfig.getProperty("k6", null); // k6 = v6
  publicConfig.getProperty("k7", null); // k7 = v7
5.4.3 应用C获取Apollo配置
  //application
  Config appConfig = ConfigService.getAppConfig();
  appConfig.getProperty("k1", null); // k1 = v12
  appConfig.getProperty("k2", null); // k2 = null
  appConfig.getProperty("k3", null); // k3 = v33
  
  //NS-Private，由于没有NS-Private Namespace 所以获取到default value
  Config privateConfig = ConfigService.getConfig("NS-Private");
  privateConfig.getProperty("k1", "default value"); 
  
  //NS-Public，公共类型的Namespace，任何项目都可以获取到
  Config publicConfig = ConfigService.getConfig("NS-Public");
  publicConfig.getProperty("k4", null); // k4 = v5
  publicConfig.getProperty("k6", null); // k6 = v6
  publicConfig.getProperty("k7", null); // k7 = v7
5.4.4 ChangeListener
以上代码例子中可以看到，在客户端Namespace映射成一个Config对象。Namespace配置变更的监听器是注册在Config对象上。

所以在应用A中监听application的Namespace代码如下：

Config appConfig = ConfigService.getAppConfig();
appConfig.addChangeListener(new ConfigChangeListener() {
  public void onChange(ConfigChangeEvent changeEvent) {
    //do something
  }
})
在应用A中监听NS-Private的Namespace代码如下：

Config privateConfig = ConfigService.getConfig("NS-Private");
privateConfig.addChangeListener(new ConfigChangeListener() {
  public void onChange(ConfigChangeEvent changeEvent) {
    //do something
  }
})
在应用A、应用B、应用C中监听NS-Public的Namespace代码如下：

Config publicConfig = ConfigService.getConfig("NS-Public");
publicConfig.addChangeListener(new ConfigChangeListener() {
  public void onChange(ConfigChangeEvent changeEvent) {
    //do something
  }
})

相关文章推荐

深入理解Apollo（一）整体架构设计
https://blog.csdn.net/shang_xs/article/details/88966455
深入理解Apollo（二）客户端架构设计
https://blog.csdn.net/shang_xs/article/details/89011263
深入理解Apollo（三）Hello World设计
https://blog.csdn.net/shang_xs/article/details/89011796
深入理解Apollo（四）Namespace设计
https://blog.csdn.net/shang_xs/article/details/89011440

Logo
GitCode 开源社区

旨在为数千万中国开发者提供一个无缝且高效的云端环境，以支持学习、使用和贡献开源项目。

更多推荐

【目标检测】目标检测的一些常用神经网络模型及方法

我的阶段性总结????文章目录1.概述1.2 目标检测的任务1.3 目标检测的分类2.R-CNN系列2.1 [R-CNN（Region with CNN features）](https://arxiv.org/pdf/1311.2524.pdf)2.2 [Fast R-CNN](https://www.cv-foundation.org/openaccess/content_iccv_2015/

avatar GitCode 开源社区
cover

用C++实现4种YOLO目标检测（内附完整代码）

avatar GitCode 开源社区
cover

静态时序分析：SDC约束命令create_generated_clock详解（上）

avatar GitCode 开源社区