From 9fbe1aa3c502a5dc4461f5a44629b9ac66d4f86f Mon Sep 17 00:00:00 2001 From: xiaolongzuo <150349407@qq.com> Date: Thu, 8 Nov 2018 14:59:05 +0800 Subject: [PATCH] Add ANS and ACM readme doc. --- .../acm-local-example/readme-zh.md | 46 +++++++++++++++++ .../src/main/resources/bootstrap.properties | 1 - .../ans-consumer-feign-example/readme-zh.md | 25 ++++++++++ .../ans-consumer-ribbon-example/readme-zh.md | 25 ++++++++++ .../ans-provider-example/readme-zh.md | 35 +++++++++++++ .../oss-example/readme-zh.md | 48 ++++++------------ .../oss-example/readme.md | 50 ++++++------------- .../src/main/resources/oss-test.json | 2 +- 8 files changed, 162 insertions(+), 70 deletions(-) create mode 100644 spring-cloud-alibaba-examples/acm-example/acm-local-example/readme-zh.md create mode 100644 spring-cloud-alibaba-examples/ans-example/ans-consumer-feign-example/readme-zh.md create mode 100644 spring-cloud-alibaba-examples/ans-example/ans-consumer-ribbon-example/readme-zh.md create mode 100644 spring-cloud-alibaba-examples/ans-example/ans-provider-example/readme-zh.md diff --git a/spring-cloud-alibaba-examples/acm-example/acm-local-example/readme-zh.md b/spring-cloud-alibaba-examples/acm-example/acm-local-example/readme-zh.md new file mode 100644 index 000000000..f76577aa9 --- /dev/null +++ b/spring-cloud-alibaba-examples/acm-example/acm-local-example/readme-zh.md @@ -0,0 +1,46 @@ +# ACM Local Example + +## 项目说明 + +本项目展示了，在Spring Cloud规范下，如何以最简单且免费的方式，使用ACM产品，将配置统一管理。 + +应用配置管理（Application Configuration Management，简称 ACM），其前身为淘宝内部配置中心 Diamond，是一款应用配置中心产品。基于该应用配置中心产品，您可以在微服务、DevOps、大数据等场景下极大地减轻配置管理的工作量的同时，保证配置的安全合规。更多 ACM 相关的信息，请参考 [ACM官网](https://www.aliyun.com/product/acm)。 + +## 示例 + +### 准备工作 + +ACM支持直接使用免费的轻量版配置中心，进行开发和调试工作。本示例也是基于轻量版配置中心的，因此我们需要首先安装和启动轻量版配置中心。 + +1. [下载轻量版配置中心](https://edas-public.oss-cn-hangzhou.aliyuncs.com/install_package/LCC/2018-11-01/edas-lite-configcenter.tar.gz?file=edas-lite-configcenter.tar.gz) + +2. 解压 edas-lite-configcenter.tar.gz ，然后执行以下命令。 + + cd edas-config-center && sh startup.sh + +出现以下内容说明轻量版配置中心启动成功。 + + Edas-config-center has been started successfully. + You can see more details in logs/config-center.log. + +3. 进入页面 http://127.0.0.1:8080，在左侧"配置列表"页面中，点击"添加"按钮，添加如下配置。 + + Group：DEFAULT_GROUP + DataId：acm-local.properties + Content：user.id=xiaolongzuo + +### 启动应用 + +直接运行main class，即`AcmApplication`。 + +### 查看效果 + +1. 使用`curl`可以看到在配置中心配置的user.id。 + + curl http://127.0.0.1:18089/ + +2. 进入页面 http://127.0.0.1:8080，在左侧"配置列表"页面中，更改user.id的值以后，再次使用`curl`命令，可以看到配置变化。 + + +如果您对 Spring Cloud ACM Starter 有任何建议或想法，欢迎提交 issue 中或者通过其他社区渠道向我们反馈。 + diff --git a/spring-cloud-alibaba-examples/acm-example/acm-local-example/src/main/resources/bootstrap.properties b/spring-cloud-alibaba-examples/acm-example/acm-local-example/src/main/resources/bootstrap.properties index 448a0c7dd..40947c21a 100644 --- a/spring-cloud-alibaba-examples/acm-example/acm-local-example/src/main/resources/bootstrap.properties +++ b/spring-cloud-alibaba-examples/acm-example/acm-local-example/src/main/resources/bootstrap.properties @@ -1,4 +1,3 @@ -spring.application.group=com.alibaba.acm spring.application.name=acm-local server.port=18089 spring.cloud.alicloud.acm.server-list=127.0.0.1 diff --git a/spring-cloud-alibaba-examples/ans-example/ans-consumer-feign-example/readme-zh.md b/spring-cloud-alibaba-examples/ans-example/ans-consumer-feign-example/readme-zh.md new file mode 100644 index 000000000..4b8ad3728 --- /dev/null +++ b/spring-cloud-alibaba-examples/ans-example/ans-consumer-feign-example/readme-zh.md @@ -0,0 +1,25 @@ +# ANS Consumer Feign Example + +## 项目说明 + +本项目展示了，在Spring Cloud规范下，如何以最简单且免费的方式，使用Feign客户端，调用一个服务。 + +## 示例 + +### 准备工作 + +ans-provider-example已经成功启动，并发布服务成功。 + +### 启动应用 + +直接运行main class，即`ConsumerApplication`。 + +### 查看效果 + +使用`curl`命令可以看到应用打印出相应的调用日志，命令如下。 + + curl http://127.0.0.1:18082/ + + +如果您对 Spring Cloud ANS Starter 有任何建议或想法，欢迎提交 issue 中或者通过其他社区渠道向我们反馈。 + diff --git a/spring-cloud-alibaba-examples/ans-example/ans-consumer-ribbon-example/readme-zh.md b/spring-cloud-alibaba-examples/ans-example/ans-consumer-ribbon-example/readme-zh.md new file mode 100644 index 000000000..b15eb89c6 --- /dev/null +++ b/spring-cloud-alibaba-examples/ans-example/ans-consumer-ribbon-example/readme-zh.md @@ -0,0 +1,25 @@ +# ANS Consumer Ribbon Example + +## 项目说明 + +本项目展示了，在Spring Cloud规范下，如何以最简单且免费的方式，使用Ribbon客户端，调用一个服务。 + +## 示例 + +### 准备工作 + +ans-provider-example已经成功启动，并发布服务成功。 + +### 启动应用 + +直接运行main class，即`ConsumerApplication`。 + +### 查看效果 + +使用`curl`命令可以看到应用打印出相应的调用日志，命令如下。 + + curl http://127.0.0.1:18082/ + + +如果您对 Spring Cloud ANS Starter 有任何建议或想法，欢迎提交 issue 中或者通过其他社区渠道向我们反馈。 + diff --git a/spring-cloud-alibaba-examples/ans-example/ans-provider-example/readme-zh.md b/spring-cloud-alibaba-examples/ans-example/ans-provider-example/readme-zh.md new file mode 100644 index 000000000..82b158740 --- /dev/null +++ b/spring-cloud-alibaba-examples/ans-example/ans-provider-example/readme-zh.md @@ -0,0 +1,35 @@ +# ANS Provider Example + +## 项目说明 + +本项目展示了，在Spring Cloud规范下，如何以最简单且免费的方式，发布一个服务。 + +## 示例 + +### 准备工作 + +ANS支持直接使用免费的轻量版配置中心，进行开发和调试工作。本示例也是基于轻量版配置中心的，因此我们需要首先安装和启动轻量版配置中心。 + +1. [下载轻量版配置中心](https://edas-public.oss-cn-hangzhou.aliyuncs.com/install_package/LCC/2018-11-01/edas-lite-configcenter.tar.gz?file=edas-lite-configcenter.tar.gz) + +2. 解压 edas-lite-configcenter.tar.gz ，然后执行以下命令。 + + cd edas-config-center && sh startup.sh + +出现以下内容说明轻量版配置中心启动成功。 + + Edas-config-center has been started successfully. + You can see more details in logs/config-center.log. + + +### 启动应用 + +直接运行main class，即`ProviderApplication`。 + +### 查看效果 + +进入页面 http://127.0.0.1:8080，在左侧"服务列表"页面中，可以看到一条名为`ans-provider`的服务。 + + +如果您对 Spring Cloud ANS Starter 有任何建议或想法，欢迎提交 issue 中或者通过其他社区渠道向我们反馈。 + diff --git a/spring-cloud-alibaba-examples/oss-example/readme-zh.md b/spring-cloud-alibaba-examples/oss-example/readme-zh.md index 56ac5cb68..54cc88d28 100644 --- a/spring-cloud-alibaba-examples/oss-example/readme-zh.md +++ b/spring-cloud-alibaba-examples/oss-example/readme-zh.md @@ -11,7 +11,7 @@ ### 接入 OSS 在启动示例进行演示之前，我们先了解一下如何接入 OSS。 -**注意：本节只是为了便于您理解接入方式，本示例代码中已经完成接入工作，您只需修改 accessKeyId、secretAccessKey、region 即可。** +**注意：本节只是为了便于您理解接入方式，本示例代码中已经完成接入工作，您只需修改 accessKey、secretKey、endpoint 即可。** 1. 修改 pom.xml 文件，引入 alicloud-oss starter。 @@ -20,24 +20,24 @@ spring-cloud-starter-alicloud-oss -2. 在配置文件中配置 OSS 服务对应的 accessKeyId、secretAccessKey 和 region。 +2. 在配置文件中配置 OSS 服务对应的 accessKey、secretKey 和 endpoint。 // application.properties - spring.cloud.alibaba.oss.accessKeyId=your-ak - spring.cloud.alibaba.oss.secretAccessKey=your-sk - spring.cloud.alibaba.oss.region=cn-beijing + spring.cloud.alicloud.access-key=your-ak + spring.cloud.alicloud.secret-key=your-sk + spring.cloud.alicloud.oss.endpoint=*** - 以阿里云 accessKeyId、secretAccessKey 为例，获取方式如下。 + 以阿里云 accessKey、secretKey 为例，获取方式如下。 i. 在阿里云控制台界面，单击右上角头像，选择 accesskeys，或者直接登录[用户信息管理界面](https://usercenter.console.aliyun.com/)： ![undefined](https://cdn.nlark.com/lark/0/2018/png/64647/1535371973274-3ebec90a-ebde-4eb7-96ed-5372f6b32fe0.png) - ii. 获取 accessKeyId、secretAccessKey： + ii. 获取 accessKey、secretKey： ![undefined](https://cdn.nlark.com/lark/0/2018/png/64647/1535372168883-b94a3d77-3f81-4938-b409-611945a9e21c.png) - **注意：**如果您使用了阿里云 [STS服务](https://help.aliyun.com/document_detail/28756.html) 进行短期访问权限管理，则除了 accessKeyId、secretAccessKey、region 以外，还需配置 securityToken。 + **注意：**如果您使用了阿里云 [STS服务](https://help.aliyun.com/document_detail/28756.html) 进行短期访问权限管理，则除了 accessKey、secretKey、endpoint 以外，还需配置 securityToken。 3. 注入 OSSClient 并进行文件上传下载等操作。 @@ -61,9 +61,9 @@ spring.application.name=oss-example server.port=18084 - spring.cloud.alibaba.oss.accessKeyId=your-ak - spring.cloud.alibaba.oss.secretAccessKey=your-sk - spring.cloud.alibaba.oss.region=cn-beijing + spring.cloud.alicloud.access-key=your-ak + spring.cloud.alicloud.secret-key=your-sk + spring.cloud.alicloud.oss.endpoint=*** 2. 通过 IDE 直接启动或者编译打包后启动应用。 @@ -72,7 +72,7 @@ 1. 执行 `mvn clean package` 将工程编译打包； 2. 执行 `java -jar oss-example.jar`启动应用。 -应用启动后会自动在 OSS 上创建一个名为 `spring-cloud-alibaba` 的 Bucket。 +应用启动后会自动在 OSS 上创建一个名为 `spring-cloud-alibaba-test` 的 Bucket。 ### 上传或下载文件 @@ -96,7 +96,7 @@ 显示结果： // 如果配置正确，则输出 - download success, content: { "name": "spring-cloud-alibaba", "github": "https://github.com/spring-cloud-incubator/spring-cloud-alibaba", "authors": ["Jim", "flystar32"], "emails": ["fangjian0423@gmail.com", "flystar32@163.com"] } + download success, content: { "name": "oss-test" } // 下载的过程中如果发生异常，则会输出download fail: fail reason。比如accessKeyId配置错误，则fail reason内容如下 download fail: The OSS Access Key Id you provided does not exist in our records. [ErrorCode]: InvalidAccessKeyId [RequestId]: RequestId [HostId]: xxx.oss-cn-beijing.aliyuncs.com [ResponseError]: InvalidAccessKeyId The OSS Access Key Id you provided does not exist in our records. RequestId sxxx.oss-cn-beijing.aliyuncs.com xxx-accessKeyId @@ -106,11 +106,11 @@ 完成文件上传或者下载操作后，可以登录 OSS 控制台进行验证。 -1. 登陆[OSS控制台](https://oss.console.aliyun.com/)，可以看到左侧 Bucket 列表新增一个名字为`spring-cloud-alibaba`的 Bucket。 +1. 登陆[OSS控制台](https://oss.console.aliyun.com/)，可以看到左侧 Bucket 列表新增一个名字为`spring-cloud-alibaba-test`的 Bucket。 ![undefined](https://cdn.nlark.com/lark/0/2018/png/64647/1535369224513-387afdf9-6078-4a42-9f18-d9fe9926a9cd.png) -2. 单击`spring-cloud-alibaba` Bucket，选择 `文件管理` 页签，发现上传的 oss-test 文件在 custom-dir 目录中。上传的 objectName 为`custom-dir/oss-test`。目录和文件以'/'符号分割。 +2. 单击`spring-cloud-alibaba-test` Bucket，选择 `文件管理` 页签，发现上传的 oss-test 文件。上传的 objectName 为`oss-test.json`。目录和文件以'/'符号分割。 ![undefined](https://cdn.nlark.com/lark/0/2018/png/64647/1535615378605-df1381e9-c5ff-4da1-b3b3-ce9acfef313f.png) @@ -134,24 +134,6 @@ Endpoint 内部会显示所有的 OSSClient 配置信息，以及该 OSSClient ![undefined](https://cdn.nlark.com/lark/0/2018/png/64647/1535373658171-20674565-6fe1-4e1e-a596-1dd6f4159ec3.png) - -## 多个 OSSClient 场景 - -如果您需要配置多个 OSSClient，类似多数据源的配置，则可以先构造 `OSSProperties`，再构造 `OSSClient`，并分别为每个 OSSClient 配置相应的 accessKeyId、secretAccessKey 等信息。 - - @Bean - @ConfigurationProperties(prefix = "spring.cloud.alibaba.oss1") - public OSSProperties ossProperties1() { - return new OSSProperties(); - } - - @Bean - public OSS ossClient1(@Qualifier("ossProperties1") OSSProperties ossProperties) { - return new OSSClientBuilder().build(ossProperties.getEndpoint(), - ossProperties.getAccessKeyId(), ossProperties.getSecretAccessKey(), - ossProperties.getSecurityToken(), ossProperties.getConfiguration()); - } -

以 Resource 的形式读取文件

OSS Starter 支持以 Resource 的形式得到文件对象。如果只需读取少量文件，您可以使用这种方式。 diff --git a/spring-cloud-alibaba-examples/oss-example/readme.md b/spring-cloud-alibaba-examples/oss-example/readme.md index 17dfbbdc3..11ea77c82 100644 --- a/spring-cloud-alibaba-examples/oss-example/readme.md +++ b/spring-cloud-alibaba-examples/oss-example/readme.md @@ -11,7 +11,7 @@ If your applications are Spring Cloud applications and you need to use Alibaba C ### Connect to OSS Before we start the demo, let's learn how to connect OSS to a Spring Cloud application. -**Note: This section is to show you how to connect to oss. The actual configurations have been completed in the following example, and you only need to specify your accessKeyId, secretAccessKey and region.** +**Note: This section is to show you how to connect to oss. The actual configurations have been completed in the following example, and you only need to specify your accessKey, secretKey and endpoint.** 1. Add dependency spring-cloud-starter-alicloud-oss in the pom.xml file in your Spring Cloud project. @@ -23,21 +23,21 @@ Before we start the demo, let's learn how to connect OSS to a Spring Cloud appli 2. Configure accessKeyId, secretAccessKey and region in application.properties. // application.properties - spring.cloud.alibaba.oss.accessKeyId=your-ak - spring.cloud.alibaba.oss.secretAccessKey=your-sk - spring.cloud.alibaba.oss.region=cn-beijing + spring.cloud.alicloud.access-key=your-ak + spring.cloud.alicloud.secret-key=your-sk + spring.cloud.alicloud.oss.endpoint=*** - To get accessKeyId, secretAccessKey, follow these steps: + To get accessKey, secretKey, follow these steps: 1. On the Alibaba Cloud console, click your avatar on the upper-right corner and click accesskeys. Or visit [User Management](https://usercenter.console.aliyun.com/) page directly： ![undefined](https://cdn.nlark.com/lark/0/2018/png/64647/1535464041257-5c7ae997-daff-45b3-89d4-02d578da4ac7.png) - 2. Get your accessKeyId、secretAccessKey： + 2. Get your accessKey、secretKey： ![undefined](https://cdn.nlark.com/lark/0/2018/png/64647/1535464098793-517491f6-156b-4a98-a5a4-6113cb3c01a4.png) - **Note:** If you are using [STS](https://www.alibabacloud.com/help/doc-detail/28756.html), you should configure securityToken in addition to accessKeyId, secretAccessKey, and region. + **Note:** If you are using [STS](https://www.alibabacloud.com/help/doc-detail/28756.html), you should configure securityToken in addition to accessKey, secretKey, and endpoint. 3. Inject OSSClient and use it to upload files to the OSS server and download a file from OSS server. @@ -60,9 +60,9 @@ Before we start the demo, let's learn how to connect OSS to a Spring Cloud appli spring.application.name=oss-example server.port=18084 - spring.cloud.alibaba.oss.accessKeyId=your-ak - spring.cloud.alibaba.oss.secretAccessKey=your-sk - spring.cloud.alibaba.oss.region=cn-beijing + spring.cloud.alicloud.access-key=your-ak + spring.cloud.alicloud.secret-key=your-sk + spring.cloud.alicloud.oss.endpoint=*** 2. Start the application in IDE or by building a fatjar. @@ -71,7 +71,7 @@ Before we start the demo, let's learn how to connect OSS to a Spring Cloud appli 1. Execute command `mvn clean package` to build a fatjar. 2. Run command `java -jar oss-example.jar` to start the application. -After startup, a bucket called 'spring-cloud-alibaba' is automatically created in OSS. +After startup, a bucket called 'spring-cloud-alibaba-test' is automatically created in OSS. ### Upload or download files @@ -88,14 +88,14 @@ Results： upload fail: The OSS Access Key Id you provided does not exist in our records. [ErrorCode]: InvalidAccessKeyId [RequestId]: RequestId [HostId]: xxx.oss-cn-beijing.aliyuncs.com [ResponseError]: InvalidAccessKeyId The OSS Access Key Id you provided does not exist in our records. RequestId xxx.oss-cn-beijing.aliyuncs.com xxx-accessKeyId #### Download files -Use `curl` command to download files. It will download the oss-test.json file that you uploaded just now and print in result): +Use `curl` command to download files. It will download the oss-test.json file that you uploaded just now and print in result: curl http://localhost:18084/download Results： // If configurations are correct, the output will be as follows - download success, content: { "name": "spring-cloud-alibaba", "github": "https://github.com/spring-cloud-incubator/spring-cloud-alibaba", "authors": ["Jim", "flystar32"], "emails": ["fangjian0423@gmail.com", "flystar32@163.com"] } + download success, content: { "name": "oss-tes" } // If an error occurs during downloading, the output will be 'download fail: fail reason'. For example, if accessKeyId is wrong，fail reason will be as follows download fail: The OSS Access Key Id you provided does not exist in our records. [ErrorCode]: InvalidAccessKeyId [RequestId]: RequestId [HostId]: xxx.oss-cn-beijing.aliyuncs.com [ResponseError]: InvalidAccessKeyId The OSS Access Key Id you provided does not exist in our records. RequestId sxxx.oss-cn-beijing.aliyuncs.com xxx-accessKeyId @@ -103,11 +103,11 @@ Results： ### Verify results on OSS You can verify results on the OSS console when you finish uploading or downloading files. -1. Log on to the [OSS console](https://oss.console.aliyun.com/)，and you will find a bucket named `spring-cloud-alibaba`. +1. Log on to the [OSS console](https://oss.console.aliyun.com/)，and you will find a bucket named `spring-cloud-alibaba-test`. ![undefined](https://cdn.nlark.com/lark/0/2018/png/64647/1535464204462-ccebb9e0-7233-499c-8dec-8b8348231b2b.png) -2. Click the `spring-cloud-alibaba` bucket, select the Files tab, and you will find the oss-test file. The file 'oss-test' is located in directory 'custom-dir'. The objectName of the file is 'custom-dir/oss-test'. File directory and file is separated by '/'. +2. Click the `spring-cloud-alibaba-test` bucket, select the Files tab, and you will find the oss-test.json file. The objectName of the file is 'oss-test.json'. File directory and file is separated by '/'. ![undefined](https://cdn.nlark.com/lark/0/2018/png/64647/1535618026281-613a338c-f89c-4c7b-8b04-d404d1320699.png) @@ -133,26 +133,6 @@ Endpoint will show the configurations and the list of buckets of all OSSClients. ![undefined](https://cdn.nlark.com/lark/0/2018/png/64647/1535373658171-20674565-6fe1-4e1e-a596-1dd6f4159ec3.png) -## Multiple OSSClients - -If you need multiple OSSClients，like Multi DataSources, build `OSSProperties` first，and then build `OSSClient`. Specify information such as assessKeyId and secrectAccessKey for each OSSClient. - - @Bean - @ConfigurationProperties(prefix = "spring.cloud.alibaba.oss1") - public OSSProperties ossProperties1() { - return new OSSProperties(); - } - - @Bean - public OSS ossClient1(@Qualifier("ossProperties1") OSSProperties ossProperties) { - return new OSSClientBuilder().build(ossProperties.getEndpoint(), - ossProperties.getAccessKeyId(), ossProperties.getSecretAccessKey(), - ossProperties.getSecurityToken(), ossProperties.getConfiguration()); - } - - -* OSSClient shutdown：You do not need to shutdown OSSClient. It will be done in `OSSApplicationListener`. -

Read file using resource mode

OSS Starter supports getting file objects by `Spring Resource`. Simply configure OSS protocol of the resource： diff --git a/spring-cloud-alibaba-examples/oss-example/src/main/resources/oss-test.json b/spring-cloud-alibaba-examples/oss-example/src/main/resources/oss-test.json index f1683e94f..68682f46e 100644 --- a/spring-cloud-alibaba-examples/oss-example/src/main/resources/oss-test.json +++ b/spring-cloud-alibaba-examples/oss-example/src/main/resources/oss-test.json @@ -1,3 +1,3 @@ { - "name": "chenzhu-test" + "name": "oss-test" } \ No newline at end of file