三、客户端用法

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方式获取配置了:

    1. @ApolloConfig
    2. private Config config; //inject config for namespace application
  • 更多有意思的实际使用场景和示例代码,请参考apollo-use-cases

3.1 API使用方式

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

3.1.1 获取默认namespace的配置(application)

  1. Config config = ConfigService.getAppConfig(); //config instance is singleton for each namespace and is never null
  2. String someKey = "someKeyFromDefaultNamespace";
  3. String someDefaultValue = "someDefaultValueForTheKey";
  4. String value = config.getProperty(someKey, someDefaultValue);

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

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

3.1.2 监听配置变化事件

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

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

  1. Config config = ConfigService.getAppConfig(); //config instance is singleton for each namespace and is never null
  2. config.addChangeListener(new ConfigChangeListener() {
  3. @Override
  4. public void onChange(ConfigChangeEvent changeEvent) {
  5. System.out.println("Changes for namespace " + changeEvent.getNamespace());
  6. for (String key : changeEvent.changedKeys()) {
  7. ConfigChange change = changeEvent.getChange(key);
  8. System.out.println(String.format("Found change - key: %s, oldValue: %s, newValue: %s, changeType: %s", change.getPropertyName(), change.getOldValue(), change.getNewValue(), change.getChangeType()));
  9. }
  10. }
  11. });

3.1.3 获取公共Namespace的配置

  1. String somePublicNamespace = "CAT";
  2. Config config = ConfigService.getConfig(somePublicNamespace); //config instance is singleton for each namespace and is never null
  3. String someKey = "someKeyFromPublicNamespace";
  4. String someDefaultValue = "someDefaultValueForTheKey";
  5. 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格式一致。

  1. Config config = ConfigService.getConfig("application.yml");
  2. String someKey = "someKeyFromYmlNamespace";
  3. String someDefaultValue = "someDefaultValueForTheKey";
  4. String value = config.getProperty(someKey, someDefaultValue);

3.1.4.2 非yaml/yml格式的namespace

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

  1. String someNamespace = "test";
  2. ConfigFile configFile = ConfigService.getConfigFile("test", ConfigFileFormat.XML);
  3. 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整合,注入时需要填写带后缀的完整名字,比如application.yml

注2:非properties、非yaml/yml格式(如xml,json等)的namespace暂不支持和Spring整合。

3.2.1.1 基于XML的配置

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

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

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

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

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

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

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

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

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

3.2.1.2 基于Java的配置(推荐)

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

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

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

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

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

  1. @Configuration
  2. @EnableApolloConfig
  3. public class SomeAppConfig {
  4. @Bean
  5. public TestJavaConfigBean javaConfigBean() {
  6. return new TestJavaConfigBean();
  7. }
  8. }
  9. //这个是稍微复杂一些的配置形式,指示Apollo注入FX.apollo和application.yml namespace的配置到Spring环境中
  10. @Configuration
  11. @EnableApolloConfig({"FX.apollo", "application.yml"})
  12. public class AnotherAppConfig {}

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

  1. //这个是最复杂的配置形式,指示Apollo注入FX.apollo和application.yml namespace的配置到Spring环境中,并且顺序在application前面
  2. @Configuration
  3. @EnableApolloConfig(order = 2)
  4. public class SomeAppConfig {
  5. @Bean
  6. public TestJavaConfigBean javaConfigBean() {
  7. return new TestJavaConfigBean();
  8. }
  9. }
  10. @Configuration
  11. @EnableApolloConfig(value = {"FX.apollo", "application.yml"}, order = 1)
  12. 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的配置示例
  1. # will inject 'application' namespace in bootstrap phase
  2. apollo.bootstrap.enabled = true
  1. 注入非默认application namespace或多个namespace的配置示例
  1. apollo.bootstrap.enabled = true
  2. # will inject 'application', 'FX.apollo' and 'application.yml' namespaces in bootstrap phase
  3. apollo.bootstrap.namespaces = application,FX.apollo,application.yml
  1. 将Apollo配置加载提到初始化日志系统之前(1.2.0+)

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

  1. # will inject 'application' namespace in bootstrap phase
  2. apollo.bootstrap.enabled = true
  3. # put apollo initialization before logging system initialization
  4. apollo.bootstrap.eagerLoad.enabled=true

3.2.2 Spring Placeholder的使用

Spring应用通常会使用Placeholder来注入配置,使用的格式形如${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属性,如

  1. app.id=SampleApp
  2. apollo.autoUpdateInjectedSpringProperties=false

3.2.2.1 XML使用方式

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

  1. public class TestXmlBean {
  2. private int timeout;
  3. private int batch;
  4. public void setTimeout(int timeout) {
  5. this.timeout = timeout;
  6. }
  7. public void setBatch(int batch) {
  8. this.batch = batch;
  9. }
  10. public int getTimeout() {
  11. return timeout;
  12. }
  13. public int getBatch() {
  14. return batch;
  15. }
  16. }

那么,我在XML中会使用如下方式来定义(假设应用默认的application namespace中有timeout和batch的配置项):

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <beans xmlns="http://www.springframework.org/schema/beans"
  3. xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  4. xmlns:apollo="http://www.ctrip.com/schema/apollo"
  5. xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
  6. http://www.ctrip.com/schema/apollo http://www.ctrip.com/schema/apollo.xsd">
  7. <apollo:config/>
  8. <bean class="com.ctrip.framework.apollo.spring.TestXmlBean">
  9. <property name="timeout" value="${timeout:100}"/>
  10. <property name="batch" value="${batch:200}"/>
  11. </bean>
  12. </beans>

3.2.2.2 Java Config使用方式

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

  1. public class TestJavaConfigBean {
  2. @Value("${timeout:100}")
  3. private int timeout;
  4. private int batch;
  5. @Value("${batch:200}")
  6. public void setBatch(int batch) {
  7. this.batch = batch;
  8. }
  9. public int getTimeout() {
  10. return timeout;
  11. }
  12. public int getBatch() {
  13. return batch;
  14. }
  15. }

在Configuration类中按照下面的方式使用(假设应用默认的application namespace中有timeoutbatch的配置项):

  1. @Configuration
  2. @EnableApolloConfig
  3. public class AppConfig {
  4. @Bean
  5. public TestJavaConfigBean javaConfigBean() {
  6. return new TestJavaConfigBean();
  7. }
  8. }

3.2.2.3 ConfigurationProperties使用方式

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

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

  1. @ConfigurationProperties(prefix = "redis.cache")
  2. public class SampleRedisConfig {
  3. private int expireSeconds;
  4. private int commandTimeout;
  5. public void setExpireSeconds(int expireSeconds) {
  6. this.expireSeconds = expireSeconds;
  7. }
  8. public void setCommandTimeout(int commandTimeout) {
  9. this.commandTimeout = commandTimeout;
  10. }
  11. }

在Configuration类中按照下面的方式使用(假设应用默认的application namespace中有redis.cache.expireSecondsredis.cache.commandTimeout的配置项):

  1. @Configuration
  2. @EnableApolloConfig
  3. public class AppConfig {
  4. @Bean
  5. public SampleRedisConfig sampleRedisConfig() {
  6. return new SampleRedisConfig();
  7. }
  8. }

需要注意的是,@ConfigurationProperties如果需要在Apollo配置变化时自动更新注入的值,需要配合使用EnvironmentChangeEventRefreshScope。相关代码实现,可以参考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字符串自动注入为对象

使用样例如下:

  1. public class TestApolloAnnotationBean {
  2. @ApolloConfig
  3. private Config config; //inject config for namespace application
  4. @ApolloConfig("application")
  5. private Config anotherConfig; //inject config for namespace application
  6. @ApolloConfig("FX.apollo")
  7. private Config yetAnotherConfig; //inject config for namespace FX.apollo
  8. @ApolloConfig("application.yml")
  9. private Config ymlConfig; //inject config for namespace application.yml
  10. /**
  11. * ApolloJsonValue annotated on fields example, the default value is specified as empty list - []
  12. * <br />
  13. * jsonBeanProperty=[{"someString":"hello","someInt":100},{"someString":"world!","someInt":200}]
  14. */
  15. @ApolloJsonValue("${jsonBeanProperty:[]}")
  16. private List<JsonBean> anotherJsonBeans;
  17. @Value("${batch:100}")
  18. private int batch;
  19. //config change listener for namespace application
  20. @ApolloConfigChangeListener
  21. private void someOnChange(ConfigChangeEvent changeEvent) {
  22. //update injected value of batch if it is changed in Apollo
  23. if (changeEvent.isChanged("batch")) {
  24. batch = config.getIntProperty("batch", 100);
  25. }
  26. }
  27. //config change listener for namespace application
  28. @ApolloConfigChangeListener("application")
  29. private void anotherOnChange(ConfigChangeEvent changeEvent) {
  30. //do something
  31. }
  32. //config change listener for namespaces application, FX.apollo and application.yml
  33. @ApolloConfigChangeListener({"application", "FX.apollo", "application.yml"})
  34. private void yetAnotherOnChange(ConfigChangeEvent changeEvent) {
  35. //do something
  36. }
  37. //example of getting config from Apollo directly
  38. //this will always return the latest value of timeout
  39. public int getTimeout() {
  40. return config.getIntProperty("timeout", 200);
  41. }
  42. //example of getting config from injected value
  43. //the program needs to update the injected value when batch is changed in Apollo using @ApolloConfigChangeListener shown above
  44. public int getBatch() {
  45. return this.batch;
  46. }
  47. private static class JsonBean{
  48. private String someString;
  49. private int someInt;
  50. }
  51. }

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

  1. @Configuration
  2. @EnableApolloConfig
  3. public class AppConfig {
  4. @Bean
  5. public TestApolloAnnotationBean testApolloAnnotationBean() {
  6. return new TestApolloAnnotationBean();
  7. }
  8. }

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必须确保本地文件已经删除该配置项

如:

  1. spring.application.name = reservation-service
  2. server.port = 8080
  3. logging.level = ERROR
  4. eureka.client.serviceUrl.defaultZone = http://127.0.0.1:8761/eureka/
  5. eureka.client.healthcheck.enabled = true
  6. eureka.client.registerWithEureka = true
  7. eureka.client.fetchRegistry = true
  8. eureka.client.eurekaServiceUrlPollIntervalSeconds = 60
  9. eureka.instance.preferIpAddress = true

text-mode-spring-boot-config-sample

3.3 Demo

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

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