diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/acm.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/acm.adoc index 3473575d..b6912de1 100644 --- a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/acm.adoc +++ b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/acm.adoc @@ -1,53 +1,17 @@ -= Spring Cloud AliCloud ACM +== Spring Cloud AliCloud ACM -Spring Cloud AliCloud ACM 提供了和阿里云上的ACM的集成。使得在项目中如果需要上云的用户可以非常方便无缝的对接阿里云，来享受云端提供的稳定服务。 +Spring Cloud AliCloud ACM 是阿里云提供的商业版应用配置管理(Application Configuration Management) 产品 在 Spring Cloud 应用侧的客户端实现，且目前完全免费。 -=== 快速开始 +Spring Cloud AliCloud ACM 是 Config Server 和 Client 的替代方案，客户端和服务器上的概念与 Spring Environment 和 PropertySource 有着一致的抽象，在特殊的 bootstrap 阶段，配置被加载到 Spring 环境中。当应用程序通过部署管道从开发到测试再到生产时，您可以管理这些环境之间的配置，并确保应用程序具有迁移时需要运行的所有内容。 -为了能够在本地开发时可以使用和云上具有相同功能的ACM服务，我们提供了用于本地开发测试的轻量版配置中心。轻量版配置中心你可以理解为用于方便的本地开发测试的Saas平台。 +=== 如何引入 Spring Cloud AliCloud ACM -==== 基于properties文件扩展名的配置 - -===== 轻量版配置中心服务端初始化 - -1、轻量版配置中心的下载和启动方式可参考 https://help.aliyun.com/document_detail/44163.html?spm=a2c4g.11186623.6.677.5f206b82Z2mTCF[这里] - -2、启动好轻量版配置中心之后，在控制台中添加如下的配置。 - -[source,subs="normal"] ----- -Group: DEFAULT_GROOUP - -DataId: acm-config.properties - -Content: user.name=alibaba - user.age=56 ----- - -NOTE: data id是以 `properties` 为扩展名(默认的文件扩展名方式)。Group 的值目前只支持 DEFAULT_GROUP，注意在使用的过程中无需更改其默认值。 - -===== 客户端使用方式 - -为了能够在应用程序中使用ACM作为Sping Cloud Config的后端存储服务，在您构建Spring Boot 应用的同时添加一个Spring Boot Starter org.springframework.cloud:spring-cloud-starter-alicloud-acm。以下是一个基础的maven 依赖配置: +Spring Cloud Alibaba 已经发布了 0.2.0.RELEASE 版本，需要首先导入依赖管理POM。 [source,xml] ---- - - org.springframework.boot - spring-boot-starter-parent - 2.0.5.RELEASE - - - - - org.springframework.cloud - spring-cloud-dependencies - Finchley.SR1 - pom - import - org.springframework.cloud spring-cloud-alibaba-dependencies @@ -57,20 +21,23 @@ NOTE: data id是以 `properties` 为扩展名(默认的文件扩展名方式)。 - - - - org.springframework.cloud - spring-cloud-starter-alicloud-acm - - - org.springframework.boot - spring-boot-starter - - ---- -现在你就可以创建一个标准的Spring Boot的应用。 +接下来引入 Spring Cloud AliCloud ACM Starter 即可。 + +[source,xml] +---- + + org.springframework.cloud + spring-cloud-starter-alicloud-acm + +---- + +=== 使用 ACM 进行配置管理 + +当客户端引入了 Spring Cloud AliCloud ACM Starter 以后，应用启动时会自动从配置管理的服务端获取配置信息，并注入到 Spring 的 Environment 中。 + +以下是一个简单的应用示例。 [source,java] ---- @@ -86,204 +53,133 @@ public class ProviderApplication { } ---- -spring-cloud-starter-alicloud-acm 对于ACM服务端的基础配置有默认值(默认配置绑定到的ip和端口为127.0.0.1和8080)，因此在运行此Example 之前， 你只需在 bootstrap.properties 配置文件配置spring.application.name即可，例如： +既然需要从配置中心服务端获取配置信息，那么肯定需要配置服务端的地址，在 bootstrap.properties 中，还需要配置上以下信息。 [source,properties] ---- -spring.application.name=acm-config #注意，spring.application.name 必须要放在bootstrap.properties中 +# 必选，应用名会被作为从服务端获取配置 key 的关键词组成部分 +spring.application.name=acm-config +server.port=18081 +# 以下就是配置中心服务端的IP和端口配置 +spring.cloud.alicloud.acm.server-list=127.0.0.1 +spring.cloud.alicloud.acm.server-port=8080 ---- +NOTE: 此时没有启动配置中心，启动应用会报错，因此在应用启动之前，应当首先启动配置中心。 + + +=== 启动配置中心 + +ACM 使用的配置中心有两种，一种是完全免费的轻量版配置中心，主要用于开发和本地调试，一种是云上配置中心ACM。通常情况下，可以使用轻量版配置中心作为开发和测试环境，使用云上的 ACM 作为灰度和生产环境。 + +==== 启动轻量版配置中心 + +轻量版配置中心的下载和启动方式可参考 https://help.aliyun.com/document_detail/44163.html?spm=a2c4g.11186623.6.677.5f206b82Z2mTCF[这里] + +NOTE: 只需要进行第1步（下载轻量配置中心）和第2步（启动轻量配置中心）即可，第3步（配置hosts）在与 ACM 结合使用时，不需要操作。 + + +==== 使用云上配置中心 + +使用云上 ACM ，可以省去服务端的维护工作，同时稳定性也会更有保障。当使用云上配置中心时，代码部分和使用轻量配置中心并没有区别，但是配置上会有一些区别。 + +以下是一个简单的使用云上配置中心的配置示例，配置详情需要在 https://acm.console.aliyun.com[ACM控制台查询] + +[source,properties] +---- +# 应用名会被作为从服务端获取配置 key 的关键词组成部分，因此是必选 +spring.application.name=ans-provider +# 端口配置自由配置即可 +server.port=18081 +# 以下就是配置中心的IP和端口配置 +spring.cloud.alicloud.acm.server-mode=EDAS +spring.cloud.alicloud.access-key=你的阿里云AK +spring.cloud.alicloud.secret-key=你的阿里云SK +spring.cloud.alicloud.acm.endpoint=acm.aliyun.com +spring.cloud.alicloud.acm.namespace=你的 ACM namespace，需要在 ACM 控制台查询 +---- + +NOTE: EDAS 提供应用托管服务，如果你将应用托管到 EDAS，那么 EDAS 将会自动为你填充所有配置。 + +=== 在配置中心添加配置 + +1. 启动好轻量版配置中心之后，在控制台中添加如下的配置。 + +[source,subs="normal"] +---- +Group: DEFAULT_GROOUP + +DataId: acm-config.properties + +Content: user.name=james + user.age=18 +---- + +NOTE: DataId 的格式为 `{prefix}. {file-extension}`,prefix 默认从配置 spring.application.name 中取值，file-extension 默认的值为 "properties"。 + +=== 启动应用验证 + 启动这个Example，可以在控制台看到打印出的值正是我们在轻量版配置中心上预先配置的值。 [source,subs="normal"] ---- -2018-11-05 11:41:50.661 INFO 1541 --- [main] com.alibaba.demo.normal.ProviderApp : Started ProviderApp in 15.809 seconds (JVM running for 16.513) -user name :alibaba; age: 56 -2018-11-05 11:41:50.710 INFO 1541 --- [gPullingdefault] s.c.a.AnnotationConfigApplicationContext : Refreshing org.springframework.context.annotation.AnnotationConfigApplicationContext@1f854e9e: startup date [Mon Nov 05 11:41:50 CST 2018]; root of context hierarchy +user name :james; age: 18 ---- -==== 基于yaml文件扩展名的配置 +=== 更改配置文件扩展名 -spring-cloud-starter-alicloud-acm 默认对文件扩展名为properties的支持，如果你习惯使用yaml格式来作为您的基础配置，也是可以支持的。这个时候你只需要在bootstrap.properties配置文件中显示的来声明使用的文件扩展名，如下所示 +spring-cloud-starter-alicloud-acm 中 DataId 默认的文件扩展名是 properties。除去 properties 格式之外，也支持 yaml 格式。 +支持通过 spring.cloud.nacos.config.file-extension 来配置文件的扩展名，yaml 格式可以配置成 `yaml` 或 `yml`。 -[source,properties] ----- -spring.application.name=acm-config -spring.cloud.nacos.config.file-extension=yaml #显示的声明使用的文件扩展名 ----- +NOTE: 修改文件扩展名后，在配置中心中的 DataID 以及 Content 的格式都必须做相应的修改。 -同时还需在轻量版配置中心的控制台新增一个dataid为yaml为扩展名的配置，如下所示： +=== 支持配置的动态更新 -[source,subs="normal"] ----- -Group: DEFAULT_GROUP +spring-cloud-starter-alicloud-acm 默认支持配置的动态更新，当您在配置中心修改配置的内容时，会触发 Spring 中的 Context Refresh 动作。 +带有 @RefreshScope 和 @ConfigurationProperties 注解的类会自动刷新。 -DataId: acm-config.yaml +NOTE: 你可以通过配置 spring.cloud.nacos.config.refresh.enabled=false 来关闭动态刷新 -Content: user.name: yaml-alibaba - user.age: 102 ----- +=== profile 粒度的配置 -NOTE: 这里的DataId的命名规则。${spring.application.name}.${spring.cloud.nacos.config.file-extension}。因为配置中配置的是 acm-config和yaml，因此根据规则这里的DataId的命名是：acm-config.yaml。 +spring-cloud-starter-alicloud-acm 在加载配置的时候，首先会尝试去加载 dataid 为{spring.application.name}.{file-extension}的配置，当设置了 spring.profiles.active 中配置有内容时，还会尝试依次去加载 spring.profile 对应的内容， dataid 的格式为{spring.application.name}-{profile}.{file-extension}的配置，且后者的优先级高于前者。 -完成之后，重启测试程序，可以在控制台看到输出的结果的值。 - -[source,subs="normal"] ----- -2018-11-05 11:50:13.829 INFO 1674 --- [main] com.alibaba.demo.normal.ProviderApp : Started ProviderApp in 15.091 seconds (JVM running for 15.626) -user name :yaml-alibaba; age: 102 -2018-11-05 11:50:13.868 INFO 1674 --- [gPullingdefault] s.c.a.AnnotationConfigApplicationContext : Refreshing org.springframework.context.annotation.AnnotationConfigApplicationContext@7f64acf5: startup date [Mon Nov 05 11:50:13 CST 2018]; root of context hierarchy ----- - -==== 支持配置的动态更新 - -spring-cloud-starter-alicloud-acm 也支持配置的动态更新，如下所示，当变更user.name时，应用程序中能够获取到最新的值： - -[source,subs="normal"] ----- -user name :yaml-alibaba; age: 102 -user name :yaml-alibaba; age: 102 -2018-11-05 11:52:15.192 INFO 1707 --- [gPullingdefault] o.s.boot.SpringApplication : Started application in 0.162 seconds (JVM running for 26.869) -2018-11-05 11:52:15.193 INFO 1707 --- [gPullingdefault] s.c.a.AnnotationConfigApplicationContext : Closing org.springframework.context.annotation.AnnotationConfigApplicationContext@36b222ff: startup date [Mon Nov 05 11:52:15 CST 2018]; parent: org.springframework.context.annotation.AnnotationConfigApplicationContext@5cfd2308 -2018-11-05 11:52:15.193 INFO 1707 --- [gPullingdefault] s.c.a.AnnotationConfigApplicationContext : Closing org.springframework.context.annotation.AnnotationConfigApplicationContext@5cfd2308: startup date [Mon Nov 05 11:52:15 CST 2018]; root of context hierarchy -//感知到配置发生变更 -user name :yaml-alibaba-update; age: 1020 ----- - -==== 可支持profile粒度的配置 - -spring-cloud-starter-alicloud 在加载配置的时候，不仅仅加载了以dataid为${spring.application.name}.${file-extension:properties}为前缀的基础配置，还加载了dataid为${spring.application.name}-${profile}.${file-extension:properties}的基础配置。在我们日常开发中如果遇到多套环境下的不同配置，我们可以打开Spring自带的配置功能，放置在application.properties 配置文件中。如下所示： +spring.profiles.active 属于配置的元数据，所以也必须配置在 bootstrap.properties 或 bootstrap.yaml 中。比如可以在 bootstrap.properties 中增加如下内容。 [sources,properties] ---- -spring.profiles.active=${deploy.env} -spring.application.name=acm-config -spring.cloud.nacos.config.file-extension=yaml #显示的声明使用的文件扩展名 +spring.profiles.active={profile-name} ---- -其中 ${deploy.env}变量的值可以在启动应用时通过-Ddeploy.env=来动态指定。比如现在在轻量版配置中心上新增了一个dataid为：acm-config-develop.yaml的基础配置，如下所示： +Note: 也可以通过 JVM 参数 -Dspring.profiles.active=develop 或者 --spring.profiles.active=develop 这类优先级更高的方式来配置，只需遵循 Spring Boot 规范即可。 -[source,subs="normal"] ----- -Group: DEFAULT_GROUP -DataId: acm-config-develop.yaml -Content: deploy.env: develop ----- +=== 支持自定义 Group 的配置 -同时启动应用的时候通过-Ddeploy.env=develop 来指定当前spring.profiles.active的值。 - -NOTE: 特别关注下这里的DataId 的命名。因为DataId的命名规则为 ${spring.application.name}-${profile}.${file-extension:properties}。而案例中配置的值依次为 acm-config、develop、yaml，因此这里的DataId为 acm-config-develop.yaml。Group的配置目前只支持 DEFAULT_GROUP，注意在使用的过程中不要更改其他的值。 - -启动 Spring Boot 应用测试的代码如下： - -[source,java] ----- -@SpringBootApplication -public class ProviderApplication { - - public static void main(String[] args) { - ConfigurableApplicationContext applicationContext = SpringApplication.run(ProviderApp.class, args); - - while (true) { - String userName = applicationContext.getEnvironment().getProperty("user.name"); - String userAge = applicationContext.getEnvironment().getProperty("user.age"); - //获取当前的部署环境 - String deployEnv = applicationContext.getEnvironment().getProperty("deploy.env"); - System.err.println("Deploy Env:"+deployEnv+"\n \t user name :" + userName + "; age: " + userAge); - TimeUnit.SECONDS.sleep(1); - } - } -} ----- - -启动后，可见控制台的输出结果： - -[source,subs="normal"] ----- -2018-11-05 14:06:25.898 INFO 1852 --- [main] com.alibaba.demo.normal.ProviderApp : Started ProviderApp in 14.947 seconds (JVM running for 15.471) -Deploy Env:develop - user name :yaml-alibaba-update; age: 1020 -2018-11-05 14:06:25.939 INFO 1852 --- [gPullingdefault] s.c.a.AnnotationConfigApplicationContext : Refreshing org.springframework.context.annotation.AnnotationConfigApplicationContext@75d62d18: startup date [Mon Nov 05 14:06:25 CST 2018]; root of context hierarchy -2018-11-05 14:06:25.967 INFO 1852 --- [gPullingdefault] f.a.AutowiredAnnotationBeanPostProcessor : JSR-330 'javax.inject.Inject' annotation found and supported for autowiring ----- - -如果我们要切换到生产环境，那么只需要更改启动的-Ddeploy.env=product 参数即可。前提是生产环境 模式下轻量版配置中心已经添加了该环境的基础配置。例如dataid为：acm-config-product.yaml的配置： - -[source,subs="normal"] ----- -Group: DEFAULT_GROUP - -DataId: acm-config-product.yaml - -Content: deploy.env: Product ----- - -以-Ddeploy.env=product 启动测试程序，输出结果如下： - -[source,subs="normal"] ----- -2018-11-05 14:10:05.481 INFO 1857 --- [gPullingdefault] s.c.a.AnnotationConfigApplicationContext : Closing org.springframework.context.annotation.AnnotationConfigApplicationContext@455d34c2: startup date [Mon Nov 05 14:10:05 CST 2018]; root of context hierarchy -Deploy Env:Product - user name :yaml-alibaba-update; age: 1020 -2018-11-05 14:10:06.798 INFO 1857 --- [ Thread-20] ConfigServletWebServerApplicationContext : Closing org.springframework.boot.web.servlet.context.AnnotationConfigServletWebServerApplicationContext@3899782c: startup date [Mon Nov 05 14:10:01 CST 2018]; parent: org.springframework.context.annotation.AnnotationConfigApplicationContext@245b4bdc ----- - -==== 基于组级别配置的高级功能 - -当你习惯使用application.properties 或者 application.yaml 来作为你的配置时，为了能够区分其他应用的配置，这个时候可以开启 spring-cloud-starter-alicloud-acm 提供的基于组级别的配置。即只需在bootstrap.properties配置文件中添加spring.application.group配置来标识应用所属的分组即可。如下所示： +在没有明确指定 `{spring.cloud.nacos.config.group}` 配置的情况下， 默认使用的是 DEFAULT_GROUP 。如果需要自定义自己的 Group，可以通过以下配置来实现： [source,properties] ---- -spring.application.group=com.infrastructure.alibaba +spring.cloud.nacos.config.group=DEVELOP_GROUP ---- -如下所示: +NOTE: 该配置必须放在 bootstrap.properties 文件中。并且在添加配置时 Group 的值一定要和 `spring.cloud.nacos.config.group` 的配置值一致。 -[source,subs="normal"] +==== 支持共享配置 + +ACM 提供了一种多个应用之间共享配置中心的同一个配置的推荐方式，供多个应用共享一些配置时使用，您在使用的时候需要添加在 bootstrap 中添加一个配置项 `spring.application.group`。 + +[source,properties] ---- -Group: DEFAULT_GROUP - -DataId: com.infrastructure.alibaba:application.yaml - -Content: owner.group: infrastructure +spring.application.group=company.department.team ---- -NOTE: 这个时候注意在轻量版配置中心填写的dataid的格式为：`${spring.application.group}:application.${file-extension}` 或者 - `${spring.application.group}:${spring.application.name}.${file-extension}` 。如果有 `spring.profiles.active` 的配置，dataid的格式还支持 - `${spring.application.group}:${spring.application.name}-${spring.profiles.active}.${file-extension}`。 Group 的值目前只支持 `DEFAULT_GROUP`，因此在使用过程中请额外注意该值配置的正确性，不要和 `spring.application.group` 这个配置搞混了。 +这时你的应用在获取之前提到的自身所独有的配置之前，会先依次从这些 DataId 去获取，分别是 company:application.properties, company.department:application.properties, company.department.team:application.properties。 +然后，还会从 {spring.application.group}:{spring.application.name}.{file-extension} 中获取 +越往后优先级越高，最高的仍然是应用自身所独有的配置。 -启动 Spring Boot 应用测试的代码如下： -[source,java] ----- -@SpringBootApplication -public class ProviderApp { +NOTE: 共享配置中 DataId 默认后缀为 properties，可以通过 spring.cloud.nacos.config.file-extension 配置. `{spring.application.group}:{spring.application.name}.{file-extension}` 。 - public static void main(String[] args) throws Exception{ - ConfigurableApplicationContext applicationContext = SpringApplication.run(ProviderApp.class, args); - - while (true) { - String userName = applicationContext.getEnvironment().getProperty("user.name"); - String userAge = applicationContext.getEnvironment().getProperty("user.age"); - String deployEnv = applicationContext.getEnvironment().getProperty("deploy.env"); - //获取当前应用所属的组 - String ownerGroup = applicationContext.getEnvironment().getProperty("owner.group"); - System.err.println("Deploy Env:"+deployEnv+"; in group :"+ownerGroup+"\n \tuser name :" + userName + "; age: " + userAge); - TimeUnit.SECONDS.sleep(1); - } - - } -} ----- - -测试输出的结果如下： - -[source,subs="normal"] ----- -2018-11-05 14:34:28.059 INFO 1902 --- [main] com.alibaba.demo.normal.ProviderApp : Started ProviderApp in 15.431 seconds (JVM running for 16.008) -Deploy Env:product; in group :Infrastructure - user name :yaml-alibaba-update; age: 1020 -2018-11-05 14:34:28.109 INFO 1902 --- [gPullingdefault] s.c.a.AnnotationConfigApplicationContext : Refreshing org.springframework.context.annotation.AnnotationConfigApplicationContext@4846b0aa: startup date [Mon Nov 05 14:34:28 CST 2018]; root of context hierarchy ----- +NOTE: 如果设置了 `spring.profiles.active` ，DataId 的格式还支持 `{spring.application.group}:{spring.application.name}-{spring.profiles.active}.{file-extension}`。优先级高于 `{spring.application.group}:{spring.application.name}.{file-extension}`