Apolle 客户端使用

准备工作

环境要求

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

必选设置

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

1.AppId

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

(1)System Property

Apollo 0.7.0+支持通过System Property传入app.id信息，如-Dapp.id=YOUR-APP-ID

(2)操作系统的System Environment

Apollo 1.4.0+支持通过操作系统的System Environment APP_ID来传入app.id信息,如APP_ID=YOUR-APP-ID

(3)Spring Boot application.properties

Apollo 1.0.0+支持通过Spring Boot的application.properties文件配置，如app.id=YOUR-APP-ID,该配置方式不适用于多个war包部署在同一个tomcat的使用场景

(4)app.properties

确保classpath:/META-INF/app.properties文件存在，并且其中内容形如：app.id=YOUR-APP-ID文件位置参考如下：

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

2.Apollo Meta Server

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

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(该配置方式不适用于多个war包部署在同一个tomcat的使用场景)

(3)通过操作系统的System EnvironmentAPOLLO_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

(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

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

自定义缓存路径

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 EnvironmentAPOLLO_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都挂掉的情况下需要扩容，那么也可以先把配置从已有机器上的缓存路径复制到新机器上的相同缓存路径

4.可选设置

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）

注:这里还有集群、集群顺序、配置访问等相关请查看官文

样例：建议开发本地创建server.properties文件，是apollo配置与业务代码解耦；

Maven依赖

 

客户端用法

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

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

• Spring方式接入简单，结合Spring有N种酷炫的玩法，如
  1. Placeholder方式：
     1. 代码中直接使用，如：@Value("${someKeyFromApollo:someDefaultValue}")
     2. 配置文件中使用替换placeholder，如：spring.datasource.url: ${someKeyFromApollo:someDefaultValue}
     3. 直接托管spring的配置，如在apollo中直接配置spring.datasource.url=jdbc:mysql://localhost:3306/somedb?characterEncoding=utf8

                   2. Spring boot的@ConfigurationProperties方式（这种不会自动刷新，需要配合@RefreshScope和手动刷新方法实现自动刷新）

手动刷新方法如下

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

有配置迁移

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

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

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

如：

其他问题

eureka统一注册

Apollo默认自带了Eureka作为内部的注册中心实现，一般情况下不需要考虑为Apollo单独部署注册中心。不过有些公司自己已经有了一套Eureka，如果希望把Apollo的Config Service和Admin Service也注册过去实现统一管理的话，可以按照如下步骤操作：

1. 配置Config Service不启动内置Eureka Server

为apollo-configservice配置apollo.eureka.server.enabled=false即可，通过bootstrap.yml或-D参数等方式皆可。

1. 修改ApolloConfigDB.ServerConfig表中的eureka.service.url，指向自己的Eureka地址

比如自己的Eureka服务地址是1.1.1.1:8761和2.2.2.2:8761，那么就将ApolloConfigDB.ServerConfig表中设置eureka.service.url为：

   http://1.1.1.1:8761/eureka/,http://2.2.2.2:8761/eureka/

需要注意的是更改Eureka地址只需要改ApolloConfigDB.ServerConfig表中的eureka.service.url即可，不需要修改meta server地址。默认情况下，meta service和config service是部署在同一个JVM进程，所以meta service的地址就是config service的地址，修改Eureka地址时不需要修改meta server地址。