目录
3.1.1 获取默认namespace的配置(application)
APOLLO配置中心Java客户端使用指南
一、准备工作
1.1 环境要求
- Java: 1.7+
- Guava: 15.0+
- Apollo客户端默认会引用Guava 19,如果你的项目引用了其它版本,请确保其版本号大于等于15.0。
注:对于Apollo客户端,如果确有需要,可以做少量代码修改来降级到Java 1.6,详细信息可以参考Issue 483。
1.2 必选设置
Apollo客户端依赖于AppId、
Environment
等环境信息来工作,所以请确保阅读下面的说明,并且做正确的配置。
1.2.1 AppId
AppId是应用的身份信息,是从服务端获取配置的一个重要信息。
请确保classpath:/META-INF/app.properties文件存在,并且其中内容形如:
app.id=YOUR-APP-ID
v0.7.0版本后,Apollo也支持通过System Property传入app.id信息,如
-Dapp.id=YOUR-APP-ID
注:app.id是用来标识应用身份的唯一id,格式为string。
1.2.2 Environment
Apollo支持“应用在不同的环境有不同的配置”,所以Environment是另一个从服务器获取配置的重要信息。
Environment可以通过以下3种方式中任意一个来配置:
- 通过Java System Property
- 可以通过Java的System Property
env
来指定环境。 - 在Java程序启动脚本中,可以指定
-Denv=YOUR-ENVIRONMENT。
如果是运行jar文件,需要注意格式是:java -Denv=YOUR-ENVIRONMENT -jar xxx.jar
- 注意key为全小写
- 可以通过Java的System Property
- 通过操作系统的System Environment
- 可以通过操作系统的System Environment
ENV
来指定。 - 注意key为全大写。
- 可以通过操作系统的System Environment
- 通过配置文件
- 推荐的方式是通过配置文件来指定
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
注意:运行时会通过env
信息匹配meta server信息,比如env
是DEV
,就会读取apollo-core.jar中apollo-env.properties中的dev_meta
信息。如果希望在运行时覆盖meta server信息,有两个方法:
- 通过-D{env}_meta=xxx来覆盖,如-Ddev_meta=http://someIp:8080
- 准备一份单独的apollo-env.properties,放在程序运行的
classpath
中,或者放在程序运行目录下,具体可以参考apollo-env.properties的加载逻辑 - ResourceUtils和apollo-env.properties原始文件。需要注意的是,在apollo-env.properties中需要用形如{env}.meta=xxx来覆盖,如dev.meta=http://someIp:8080。
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。
文件内容以properties格式存储,如果有两个key,一个是request.timeout,另一个是batch,那么文件内容就是如下格式:
request.timeout=2000
batch=2000
注意:本地缓存路径也可用于容灾目录。如果应用在所有config service都挂掉的情况下需要扩容,那么也可以先把配置从已有机器上的缓存路径复制到新机器上的相同缓存路径。
1.2.4 可选设置
Cluster(集群)
Apollo支持配置按照集群划分,也就是说,对于一个appId和一个环境,对不同的集群可以有不同的配置。
如果需要使用这个功能,你可以通过以下方式来指定运行时的集群:
- 通过Java System Property
- 我们可以通过Java的System Property设置
apollo.cluster
来指定运行时集群(注意key为全小写)。 - 例如,可以在程序启动时通过
-Dapollo.cluster=SomeCluster
来指定运行时的集群为SomeCluster。
- 我们可以通过Java的System Property设置
- 通过配置文件
- 首先确保
/opt/settings/server.properties
(Mac/Linux)或C:\opt\settings\server.properties
(Windows)在目标机器上存在。 - 在这个文件中,可以设置数据中心集群,如
idc=xxx。
- 注意key为全小写。
- 首先确保
Cluster Precedence(集群顺序)
- 如果
apollo.cluster
和idc
同时指定:- 我们会首先尝试从
apollo.cluster
指定的集群加载配置。 - 如果没找到任何配置,会尝试从
idc
指定的集群加载配置。 - 如果还是没找到,会从默认的集群(
default
)加载。
- 我们会首先尝试从
- 如果只指定了
apollo.cluster
:- 我们会首先尝试从
apollo.cluster
指定的集群加载配置。 - 如果没找到,会从默认的集群(
default
)加载。
- 我们会首先尝试从
- 如果只指定了
idc
:- 我们会首先尝试从
idc
指定的集群加载配置。 - 如果没找到,会从默认的集群(
default
)加载。
- 我们会首先尝试从
- 如果
apollo.cluster
和idc
都没有指定:- 我们会从默认的集群(
default
)加载配置。
- 我们会从默认的集群(
二、Maven Dependency
由于客户端jar包中会包含meta server信息,无法上传一个统一的jar包到中央仓库,所以请按照分布式部署指南的文档说明打包,并上传到自己公司的Maven私服。应用在实际使用时只需要按照如下方式引入即可。
<dependency>
<groupId>com.ctrip.framework.apollo</groupId>
<artifactId>apollo-client</artifactId>
<version>0.10.2</version>
</dependency>
三、客户端用法
Apollo支持API方式和Spring整合方式,该怎么选择用哪一种方式?
- API方式灵活,功能完备,配置值实时更新(热发布),支持所有Java环境。
- Spring方式接入简单,结合Spring有N种酷炫的玩法,如:
- Placeholder方式:
- 代码中使用,如:
@Value("${someKeyFromApollo:someDefaultValue}")
- application.properties中使用,如:
spring.datasource.url: ${someKeyFromApollo:someDefaultValue}
- 代码中使用,如:
- Spring boot的@ConfigurationProperties方式。
- 从v0.10.0开始的版本,支持placeholder在运行时自动更新,具体参见PR #972。(v0.10.0之前的版本,在配置变化后,不会重新注入,需要重启才会更新。如果需要配置值实时更新,可以参考后续3.2.2 Spring Placeholder的使用的说明)
- Placeholder方式:
- Spring方式也可以结合API方式使用,如注入Apollo的Config对象,就可以照常通过API方式获取配置了。
@ApolloConfig
.........................// other code
.........................// other code
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.2 Spring整合方式
3.2.1 配置
Apollo也支持和Spring整合(Spring 3.1.1+),只需要做一些简单的配置就可以了。
Apollo目前既支持比较传统的基于
XML
的配置,也支持目前比较流行的基于
Java
(推荐)
的配置。
如果是Spring Boot环境,建议参照3.2.1.3-在spring-boot初始bootstrap阶段注入配置进行配置。
需要注意的是,如果之前有使用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
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和FX.soa namespace的配置到Spring环境中 -->
<apollo:config namespaces="FX.apollo,FX.soa"/>
<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和FX.soa namespace的配置到Spring环境中,并且顺序在application前面 -->
<apollo:config namespaces="FX.apollo,FX.soa" 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和FX.soa namespace的配置到Spring环境中
@Configuration
@EnableApolloConfig({"FX.apollo", "FX.soa"})
public class AnotherAppConfig {}
3.注入多个namespace,并且指定顺序
//这个是最复杂的配置形式,指示Apollo注入FX.apollo和FX.soa namespace的配置到Spring环境中,并且顺序在application前面。
@Configuration
@EnableApolloConfig(order = 2)
public class SomeAppConfig {
@Bean
public TestJavaConfigBean javaConfigBean() {
return new TestJavaConfigBean();
}
}
@Configuration
@EnableApolloConfig(value = {"FX.apollo", "FX.soa"}, order = 1)
public class AnotherAppConfig {}
3.2.1.3 在Spring Boot初始bootstrap阶段注入配置
使用上述两种方式的配置方式后,Apollo会在Spring的postProcessBeanFactory阶段,注入配置到Spring的Environment中,早于bean的初始化阶段。所以,对于普通的bean注入配置场景,已经能很好的满足。
不过,Spring Boot有一些场景,需要配置在更早的阶段注入,比如使用@ConditionalOnProperty
的场景,或者是有一些spring-boot-starter在启动阶段就需要读取配置做一些事情(如spring-boot-starter-dubbo)。所以,对于Spring Boot环境,建议通过以下方式来接入Apollo(需要0.10.0及以上版本)。
使用方式很简单,只需要在application.properties/bootstrap.properties中按照如下样例配置即可。
1.在bootstrap阶段,注入默认application
namespace的配置示例。
# will inject 'application' namespace in bootstrap phase
apollo.bootstrap.enabled = true
2.在bootstrap阶段,注入非默认application
namespace或多个namespace的配置示例
apollo.bootstrap.enabled = true
# will inject 'application' and 'FX.apollo' namespaces in bootstrap phase
apollo.bootstrap.namespaces = application,FX.apollo
3.2.2 Spring Placeholder的使用
Spring应用通常会使用Placeholder来注入配置,使用的格式形如${someKey:someDefaultValue},如${timeout:100}。冒号前面的是key,冒号后面的是默认值。
建议在实际使用时尽量给出默认值,以免由于key没有定义导致运行时错误。
从v0.10.0开始的版本,支持placeholder在运行时自动更新,具体参见PR #972。
如果需要关闭placeholder在运行时自动更新功能,可以通过以下两种方式关闭:
- 通过设置System Property
apollo.autoUpdateInjectedSpringProperties
,在启动时传入-Dapollo.autoUpdateInjectedSpringProperties=false
- 通过设置META-INF/app.properties中的
apollo.autoUpdateInjectedSpringProperties
属性,如
app.id=SampleApp
apollo.autoUpdateInjectedSpringProperties=false
对于v0.10.0之前的版本,placeholder只会在启动的时候赋值,在运行过程中即便在Apollo上修改发布了配置,placeholder的值也不会更新。如果需要运行时动态更新placeholder的值,有以下几种方式:
- 程序监听Apollo的ConfigChangeListener(如@ApolloConfigChangeListener),然后通过自己的代码来更新placeholder的值。
- 不使用placeholder方式获取配置,而是直接从config对象中获取配置。样例代码可以参考3.2.3 Spring Annotation支持的
getBatch
和getTimeout
方法。 - 【推荐】使用Spring Cloud的RefreshScope
- 在需要刷新配置的bean上加@RefreshScope。
- 加一个Apollo的ConfigChangeListener,然后在配置变化时调用RefreshScope的refreshAll()或者refresh(String name)的方法。
- 如果要刷新的不是自己的bean,而是spring cloud的bean(如spring cloud zuul),那么可以调用org.springframework.cloud.context.refresh.ContextRefresher#refresh来刷新配置。
- 相关代码实现,可以参考apollo-demo项目中的AnnotatedBean.java和ApolloRefreshConfig.java。
- 在非Spring Boot环境使用RefreshScope需要引入RefreshAutoConfiguration,引入方式可以参考apollo-demo项目中的相关配置代码:JavaConfig示例,XmlConfig示例。
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配置变化时自动更新注入的值,需要配合Spring Cloud的RefreshScope使用。相关代码实现,可以参考apollo-demo项目中的SampleRedisConfig.java和SpringBootApolloRefreshConfig.java
3.2.3 Spring Annotation支持
Apollo同时还增加了两个新的Annotation,来简化在Spring环境中的使用。
- @ApolloConfig 用来自动注入Config对象。
- @ApolloConfigChangeListener 用来自动注册ConfigChangeListener。
使用样例如下:
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
@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;
}
}
在Configuration类中,按照下面的方式使用:
@Configuration
@EnableApolloConfig
public class AppConfig {
@Bean
public TestApolloAnnotationBean testApolloAnnotationBean() {
return new TestApolloAnnotationBean();
}
}
3.2.4 已有配置迁移
很多情况下,应用可能已经有不少配置了,比如Spring Boot的应用,就会有bootstrap.properties, application.properties等配置。
在应用接入Apollo之后,这些配置可以非常方便地迁移到Apollo,具体步骤如下:
- 在Apollo为应用新建项目
- 在应用中配置好META-INF/app.properties
- 把原先配置(必须是properties格式)复制一下,然后通过Apollo提供的文本编辑模式,全部粘帖到应用的application namespace,发布配置:
- 如果原来是其它格式,如yml,请先转成properties格式。
- 如http://www.toyaml.com/
- 把原先的配置文件(如bootstrap.properties, application.properties)从项目中删除。
- 如果需要保留本地配置文件,需要注意部分配置(如
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
3.3 Demo
项目中有一个样例客户端的项目:apollo-demo
,具体信息可以参考Apollo开发指南中的2.3 Java样例客户端启动部分。
更多使用案例Demo可以参考Apollo使用场景和示例代码。
四、客户端设计
简要描述下Apollo客户端的实现原理:
- 客户端和服务端保持了一个长连接,从而能第一时间获得配置更新的推送。(通过Http Long Polling实现)
- 客户端还会定时从Apollo配置中心服务端拉取应用的最新配置。
- 这是一个fallback机制,为了防止推送机制失效导致配置不更新。
- 客户端定时拉取会上报本地版本,所以一般情况下,对于定时拉取的操作,服务端都会返回304 - Not Modified。
- 定时频率默认为每5分钟拉取一次,客户端也可以通过在运行时指定System Property:
apollo.refreshInterval
来覆盖,单位为分钟。
- 客户端从Apollo配置中心服务端获取到应用的最新配置后,会保存在内存中。
- 客户端会把“从服务端获取到的配置”在本地文件系统缓存一份。这样,在遇到服务不可用,或网络不通的时候,依然能从本地恢复配置。
- 应用程序可以从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
文件内容以properties格式存储,比如如果有两个key,一个是request.timeout,另一个是batch,那么文件内容就是如下格式:
request.timeout=2000
batch=2000
5.3 修改配置
在本地开发模式下,Apollo不会实时监测文件内容是否有变化。所以,如果修改了配置,需要重启应用生效。