java客户端配置如何设计,Java客户端使用指南

#一、准备工作

##1.1 环境要求

Java: 1.7+

Guava: 15.0+

Apollo客户端默认会引用Guava 19，如果你的项目引用了其它版本，请确保版本号大于等于15.0

##1.2 必选设置

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

###1.2.1 AppId

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

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

app.id=YOUR-APP-ID

文件位置参考如下：

###1.2.2 Environment

Apollo支持应用在不同的环境有不同的配置，所以Environment是另一个从服务器获取配置的重要信息。

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

通过Java System Property

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

在Java程序启动脚本中，可以指定-Denv=YOUR-ENVIRONMENT

注意key为全小写

通过操作系统的System Environment

还可以通过操作系统的System Environment ENV来指定

注意key为全大写

通过配置文件

最后一个推荐的方式是通过配置文件来指定env=YOUR-ENVIRONMENT

对于Mac/Linux，文件位置为/opt/settings/server.properties

对于Windows，文件位置为C:\opt\settings\server.properties

文件内容形如：

env=DEV

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

DEV

FWS

FAT

UAT

PRO

###1.2.3 可选设置

Cluster(集群)

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

如果需要使用这个功能，你可以通过以下方式来指定运行时的集群：

通过Java System Property

我们可以通过Java的System Property设置apollo.cluster来指定运行时集群(注意key为全小写)

例如，可以在程序启动时通过-Dapollo.cluster=SomeCluster来指定运行时的集群为SomeCluster

注意key为全大写

通过配置文件

首先确保/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

com.ctrip.framework.apollo

apollo-client

0.1.1

#三、客户端用法

##3.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.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.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);

#四、客户端设计

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

客户端会定时从Apollo配置中心服务端拉取应用的最新配置，并保存在内存中

客户端还和服务端保持了一个长连接，从而能第一时间获得配置更新的推送。(通过Http Long Polling实现)

客户端会把从服务端获取到的配置在本地文件系统缓存一份

在遇到服务不可用，或网络不通的时候，依然能从本地恢复配置

应用程序可以从Apollo客户端获取最新的配置、订阅配置更新通知

#五、本地开发模式

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

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

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

##5.1 修改环境

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

env=Local

##准备本地配置文件

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