02、携程Apollo Java客户端使用指南

一、 客户端设计

image.png

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

二、 准备工作

1、环境要求

Java1.7+
Guava15.0+ : Apollo客户端默认会引用Guava 19，如果你的项目引用了其它版本，请确保版本号大于等于15.0
注：对于Apollo客户端，如果有需要的话，可以做少量代码修改来降级到Java 1.6,如需更改可以参照官方说明Issue 483

2、必选设置

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

（1）、AppId

AppId是应用的身份信息，是从服务端获取配置的一个重要信息。
有以下3种方式设置，按照优先级从高到低分别为：

A: System Property

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

-Dapp.id=YOUR-APP-ID

B: Spring Boot application.properties

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

app.id=YOUR-APP-ID

C: app.properties

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

app.id=YOUR-APP-ID

image.png

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

（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信息，按照优先级从高到低分别为：

A:通过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");

B:通过Spring Boot的配置文件

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

C:通过操作系统的System EnvironmentAPOLLO_META

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

D:通过server.properties配置文件

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

E:通过app.properties配置文件

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

F:通过Java system property ${env}_meta

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

G:通过操作系统的System Environment ${ENV}_META (1.2.0版本开始支持)

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

H:通过apollo-env.properties文件

用户也可以创建一个apollo-env.properties，放在程序的classpath下，或者放在spring boot应用的config目录下
使用该配置方式，那么就必须要正确配置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地址
3、本地缓存路径
Apollo客户端会把从服务端获取到的配置在本地文件系统缓存一份，用于在遇到服务不可用，或网络不通的时候，依然能从本地恢复配置，不影响应用正常运行。
本地缓存路径默认位于以下路径，所以请确保/opt/data或C:\opt\data\目录存在，且应用有读写权限。

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

4、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

三、 Maven依赖

在项目中引入maven依赖

 
 com.ctrip.framework.apollo
 apollo-client
 1.1.0
 

四、 客户端用法

Apollo支持API方式和Spring整合方式，该怎么选择用哪一种方式？
API方式灵活，功能完备，配置值实时更新（热发布），支持所有Java环境。
Spring方式接入简单，结合Spring有N种酷炫的玩法，如
前提是需要将Config交由Spring管理

image.png

Placeholder方式：
代码中使用，如：@Value("{someKeyFromApollo:someDefaultValue}
Spring boot的@ConfigurationProperties方式

image.png

从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

1、API使用方式

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

（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对应的实时最新的配置值。
另外，配置值从内存中获取，所以不需要应用自己做缓存。

（2）、获取公共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）、获取非properties格式namespace的配置

String someNamespace = "test";
ConfigFile configFile = ConfigService.getConfigFile(someNamespace, ConfigFileFormat.YML);
String content = configFile.getContent();
System.out.println(content);

2、基于java配置

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

（1）、注入默认namespace的配置到Spring中

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

}

image.png

（2）、注入多个namespace的配置到spring中

@Configuration
@EnableApolloConfig // 注意@EnableApolloConfig要和@Configuration一起使用，不然不会生效。
public class ApolloConfig {

}
@Configuration
@EnableApolloConfig(value = {"TEST1.sys_application","sys_application"})
public class AnotherAppConfig {

}

（3）、注入多个namespace，并且指定顺序

@Configuration
@EnableApolloConfig(order = 1) // 注意@EnableApolloConfig要和@Configuration一起使用，不然不会生效。
public class ApolloConfig {

}
@Configuration
@EnableApolloConfig(value = {"TEST1.sys_application","sys_application"}, order = 2)
public class AnotherAppConfig {

}

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

（2）、注入非默认application namespace或多个namespace的配置示例

apollo.bootstrap.enabled = true
# will inject 'application' and 'FX.apollo' namespaces in bootstrap phase
apollo.bootstrap.namespaces = application,FX.apollo

注：红色部分的书写顺序决定了优先级

4、Spring Annotation支持

Apollo同时还增加了几个新的Annotation来简化在Spring环境中的使用。
@ApolloConfig
用来自动注入Config对象
@ApolloConfigChangeListener
用来自动注册ConfigChangeListener
@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

 /**
 * ApolloJsonValue annotated on fields example, the default value is specified as empty list - []
 * 

 * jsonBeanProperty=[{"someString":"hello","someInt":100},{"someString":"world!","someInt":200}]
 */
 @ApolloJsonValue("${jsonBeanProperty:[]}")
 private List 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 and FX.apollo
 @ApolloConfigChangeListener({"application", "FX.apollo"})
 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();
 }
}