以下文档已不再维护，请转至 Java客户端使用指南 获取最新文档。

注意：本文档适用对象是Apollo系统的使用者，如果你是公司内Apollo系统的开发者/维护人员，建议先参考Apollo开发指南。

注：对于Apollo客户端，如果有需要的话，可以做少量代码修改来降级到Java 1.6，详细信息可以参考Issue 483

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

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

有以下几种方式设置，按照优先级从高到低分别为：

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

Apollo 1.4.0+支持通过操作系统的System Environment APP_ID来传入app.id信息，如

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

该配置方式不适用于多个war包部署在同一个tomcat的使用场景

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

app.id=YOUR-APP-ID

文件位置参考如下：

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

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

该配置方式不适用于多个war包部署在同一个tomcat的使用场景

如果通过以上各种手段都无法获取到Meta Server地址，Apollo最终会fallback到http://apollo.meta作为Meta Server地址

在1.0.0版本中，Apollo提供了MetaServerProvider SPI，用户可以注入自己的MetaServerProvider来自定义Meta Server地址定位逻辑。

由于我们使用典型的Java Service Loader模式，所以实现起来还是比较简单的。

有一点需要注意的是，apollo会在运行时按照顺序遍历所有的MetaServerProvider，直到某一个MetaServerProvider提供了一个非空的Meta Server地址，因此用户需要格外注意自定义MetaServerProvider的Order。规则是较小的Order具有较高的优先级，因此Order=0的MetaServerProvider会排在Order=1的MetaServerProvider的前面。

如果你的公司有很多应用需要接入Apollo，建议封装一个jar包，然后提供自定义的Apollo Meta Server定位逻辑，从而可以让接入Apollo的应用零配置使用。比如自己写一个xx-company-apollo-client，该jar包依赖apollo-client，在该jar包中通过spi方式定义自定义的MetaServerProvider实现，然后应用直接依赖xx-company-apollo-client即可。

MetaServerProvider的实现可以参考LegacyMetaServerProvider和DefaultMetaServerProvider。

适用于apollo-client 0.11.0及以上版本

一般情况下都建议使用Apollo的Meta Server机制来实现Config Service的服务发现，从而可以实现Config Service的高可用。不过apollo-client也支持跳过Meta Server服务发现，主要用于以下场景：

针对以上场景，可以通过直接指定Config Service地址的方式来跳过Meta Server服务发现，按照优先级从高到低分别为：

Apollo客户端会把从服务端获取到的配置在本地文件系统缓存一份，用于在遇到服务不可用，或网络不通的时候，依然能从本地恢复配置，不影响应用正常运行。

本地缓存路径默认位于以下路径，所以请确保/opt/data或C:\opt\data\目录存在，且应用有读写权限。

本地配置文件会以下面的文件名格式放置于本地缓存路径下：

{appId}+{cluster}+{namespace}.properties

文件内容以properties格式存储，比如如果有两个key，一个是request.timeout，另一个是batch，那么文件内容就是如下格式：

1.0.0版本开始支持以下方式自定义缓存路径，按照优先级从高到低分别为：

注：本地缓存路径也可用于容灾目录，如果应用在所有config service都挂掉的情况下需要扩容，那么也可以先把配置从已有机器上的缓存路径复制到新机器上的相同缓存路径

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

通过Java System Property

通过操作系统的System Environment

通过配置文件

文件内容形如：

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

更多环境定义，可以参考Env.java

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

1.0.0版本开始支持以下方式集群，按照优先级从高到低分别为：

Cluster Precedence（集群顺序）

如果apollo.cluster和idc同时指定：

如果只指定了apollo.cluster：

如果只指定了idc：

如果apollo.cluster和idc都没有指定：

适用于1.6.0及以上版本

默认情况下，apollo client内存中的配置存放在Properties中（底下是Hashtable），不会刻意保持和页面上看到的顺序一致，对绝大部分的场景是没有影响的。不过有些场景会强依赖配置项的顺序（如spring cloud zuul的路由规则），针对这种情况，可以开启OrderedProperties特性来使得内存中的配置顺序和页面上看到的一致。

配置方式按照优先级从高到低分别为：

适用于1.6.0及以上版本

Apollo从1.6.0版本开始增加访问密钥机制，从而只有经过身份验证的客户端才能访问敏感配置。如果应用开启了访问密钥，客户端需要配置密钥，否则无法获取配置。

配置方式按照优先级从高到低分别为：

Apollo的客户端jar包已经上传到中央仓库，应用在实际使用时只需要按照如下方式引入即可。

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

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

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

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

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

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

apollo-client 1.3.0版本开始对yaml/yml做了更好的支持，使用起来和properties格式一致。

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

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。

如果之前有使用，请注意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整合。

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

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