You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@dubbo.apache.org by al...@apache.org on 2021/10/28 05:04:08 UTC
[dubbo-go-samples] branch master updated: refactor: rewrite howto
(#284)
This is an automated email from the ASF dual-hosted git repository.
alexstocks pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/dubbo-go-samples.git
The following commit(s) were added to refs/heads/master by this push:
new ae0e7fb refactor: rewrite howto (#284)
ae0e7fb is described below
commit ae0e7fb6cbd9f05ae15480acc2b68b2719612c5a
Author: 氕氘氚 <cj...@163.com>
AuthorDate: Thu Oct 28 13:04:03 2021 +0800
refactor: rewrite howto (#284)
---
HOWTO.md | 88 +++++++++++++++++++++++++++++-------------------------
HOWTO_zh.md | 93 +++++++++++++++++++++++++++++++---------------------------
build/Makefile | 9 +++---
3 files changed, 103 insertions(+), 87 deletions(-)
diff --git a/HOWTO.md b/HOWTO.md
index 4a48e3f..43b8607 100644
--- a/HOWTO.md
+++ b/HOWTO.md
@@ -2,7 +2,7 @@
There are three ways to run dubbo-go samples:
-1. Quick start with makefile: a common makefile is provided under "build" subdirectory, which can be used to run each sample here quickly. It is also useful to run all samples automatically so that now it is possible to leverage samples as dubbo-go's integration test.
+1. Quick start with bash command: start the sample and perform unit testing through a simple command line
2. Quick start in IDE (**Recommended**): In ".run" subdirectory a couple of GoLand run configuration files are provided so that user can run each sample with just one click.
3. Manually config and run in IDE: For completeness purpose, a step-by-step instruction is also provided so that user can understand how to configure and run or debug a sample in IDE.
@@ -10,7 +10,7 @@ There are three ways to run dubbo-go samples:
*Prerequisite: docker environment is required*
-Here we use "attachment" as an example:
+Here we use "helloworld" as an example:
1. **Get the root path of dubbo-go-samples**
@@ -22,37 +22,41 @@ Here we use "attachment" as an example:
2. **Start register server (e.g. zookeeper)**
```bash
- cd $DUBBO_GO_SAMPLES_ROOT_PATH/attachment/go-server
- make -f $DUBBO_GO_SAMPLES_ROOT_PATH/build/Makefile docker-up
+ make -f build/Makefile docker-up
```
Once the following messages outputs, the zookeeper server is ready.
```bash
- > Starting dependency services with docker/docker-compose.yml
- Creating network "docker_default" with the default driver
- Creating docker_zookeeper_1 ... done
+ > Starting dependency services with ./integrate_test/dockercompose/docker-compose.yml
+ Docker Compose is now in the Docker CLI, try `docker compose up`
+
+ Creating network "dockercompose_default" with the default driver
+ Creating dockercompose_zookeeper_1 ... done
+ Creating etcd ... done
+ Creating nacos-standalone ... done
```
To shut it down, simple run
```bash
- make -f $DUBBO_GO_SAMPLES_ROOT_PATH/build/Makefile docker-down
+ make -f build/Makefile docker-down
```
3. **Start server**
```bash
- cd $DUBBO_GO_SAMPLES_ROOT_PATH/attachment/go-server
- make -f $DUBBO_GO_SAMPLES_ROOT_PATH/build/Makefile start
+ cd helloworld/go-server/cmd
+ export DUBBO_GO_CONFIG_PATH="../conf/dubbogo.yml"
+ go run .
```
Once the following messages outputs, the server is ready.
```bash
- > Buiding application binary: dist/darwin_amd64/release/go-server
- > Starting application go-server, output is redirected to dist/darwin_amd64/release/go-server.log
- > PID: 86428
+ 2021/10/27 00:33:10 Connected to 127.0.0.1:2181
+ 2021/10/27 00:33:10 Authenticated: id=72057926938066944, timeout=10000
+ 2021/10/27 00:33:10 Re-submitting `0` credentials after reconnec
```
The output of `go-server` can be found from 'dist/darwin_amd64/release/go-server.log'.
@@ -60,27 +64,34 @@ Here we use "attachment" as an example:
4. **Run client**
```bash
- cd $DUBBO_GO_SAMPLES_ROOT_PATH/attachment/go-client
- make -f $DUBBO_GO_SAMPLES_ROOT_PATH/build/Makefile run
+ cd helloworld/go-client/cmd
+ export DUBBO_GO_CONFIG_PATH="../conf/dubbogo.yml"
+ go run .
```
Once the following messages outputs, the `go-client` calls the `go-server` successfully.
```bash
- > Buiding application binary: dist/darwin_amd64/release/go-client
- > Running application go-client, output is redirected to dist/darwin_amd64/release/go-client.log
- ...
- 2020-10-27T14:51:37.520+0800 DEBUG dubbo/dubbo_invoker.go:144 result.Err: <nil>, result.Rest: &{A001 Alex Stocks 18 2020-10-27 14:51:37.52 +0800 CST}
- 2020-10-27T14:51:37.520+0800 DEBUG proxy/proxy.go:177 [makeDubboCallProxy] result: &{A001 Alex Stocks 18 2020-10-27 14:51:37.52 +0800 CST}, err: <nil>
- response result: &{A001 Alex Stocks 18 2020-10-27 14:51:37.52 +0800 CST}
+ 2021-10-27T00:40:44.879+0800 DEBUG triple/dubbo3_client.go:106 TripleClient.Invoke: get reply = name:"Hello laurence" id:"12345" age:21
+ 2021-10-27T00:40:44.879+0800 DEBUG proxy/proxy.go:218 [makeDubboCallProxy] result: name:"Hello laurence" id:"12345" age:21 , err: <nil>
+ 2021-10-27T00:40:44.879+0800 INFO cmd/client.go:51 client response result: name:"Hello laurence" id:"12345" age:21
```
5. **Integration test**
dubbo-go-samples is designed to serve the purposes of not only the showcases of how to use apache/dubbo-go but also the integration-test for apache/dubbo-go. To run integration test for `go-server`, run the following commands:
+ Start the server first
+ ```bash
+ cd helloworld/go-server/cmd
+ export DUBBO_GO_CONFIG_PATH="../conf/dubbogo.yml"
+ go run .
+ ```
+
+ Then switch to the single test directory, set the environment variables, and then execute the single test
```bash
- cd $DUBBO_GO_SAMPLES_ROOT_PATH/attachment/go-server
- make -f $DUBBO_GO_SAMPLES_ROOT_PATH/build/Makefile integration
+ cd integrate_test/helloworld/tests/integration
+ export DUBBO_GO_CONFIG_PATH="../../../../helloworld/go-client/conf/dubbogo.yml"
+ go test -v
```
Once the following messages outputs, the integration tests pass.
@@ -88,15 +99,14 @@ Here we use "attachment" as an example:
```bash
> Running integration test for application go-server
...
- --- PASS: TestGetUser (0.00s)
+ --- PASS: TestSayHello (0.01s)
PASS
- ok github.com/apache/dubbo-go-samples/attachment/go-server/tests/integration 3.603s
+ ok github.com/apache/dubbo-go-samples/integrate_test/helloworld/tests/integration 0.119s
```
-6. **Shutdown and cleanup**
+7. **Shutdown and cleanup**
```bash
- cd $DUBBO_GO_SAMPLES_ROOT_PATH/attachment/go-server
- make -f $DUBBO_GO_SAMPLES_ROOT_PATH/build/Makefile clean docker-down
+ make -f build/Makefile clean docker-down
```
*The following two ways are all relevant to IDE. Intellij GoLand is discussed here as an example.*
@@ -116,11 +126,11 @@ example:
1. **Start up zookeeper server**
- Open "attachment/go-server/docker/docker-compose.yaml", and click ▶︎▶︎ icon in the gutter on the left side of the
+ Open "integrate_test/dockercompose/docker-compose.yml", and click ▶︎▶︎ icon in the gutter on the left side of the
editor, then "Services" tab should pop up and shows the similar message below:
```
Deploying 'Compose: docker'...
- /usr/local/bin/docker-compose -f .../dubbo-go-samples/attachment/go-server/docker/docker-compose.yml up -d
+ /usr/local/bin/docker-compose -f .../dubbo-go-samples/helloworld/go-server/docker/docker-compose.yml up -d
Creating network "docker_default" with the default driver
Creating docker_zookeeper_1 ...
'Compose: docker' has been deployed successfully.
@@ -128,25 +138,23 @@ example:
2. **Start up service provider**
- Open "attachment/go-server/cmd/server.go", and click ▶︎ icon just besides "main" function in the gutter on the left
+ Open "helloworld/go-server/cmd/server.go", and click ▶︎ icon just besides "main" function in the gutter on the left
side, and select "Modify Run Configuration..." from the pop-up menu. Then make sure the following configs configured
correctly:
- * Working Directory: the absolute path to "attachment/go-server", for examples: *
- /home/dubbo-go-samples/attachment/go-server*
- * Environment: CONF_PROVIDER_FILE_PATH=conf/server.yml, optionally you could also specify logging configuration
- with "APP_LOG_CONF_FILE=conf/log.yml"
+ * Working Directory: the absolute path to "helloworld/go-server", for examples: *
+ /home/dubbo-go-samples/helloworld/go-server*
+ * Environment: DUBBO_GO_CONFIG_PATH="../conf/dubbogo.yml"
Then the sample server is ready to run.
3. **Run service consumer**
- Open "attachment/go-client/cmd/client.go", and click ▶︎ icon just besides "main" function in the gutter on the left
+ Open "helloworld/go-client/cmd/client.go", and click ▶︎ icon just besides "main" function in the gutter on the left
side, and select "Modify Run Configuration..." from the pop-up menu. Then make sure the following configs configured
correctly:
- * Working Directory: the absolute path to "attachment/go-client", for examples: *
- /home/dubbo-go-samples/attachment/go-client*
- * Environment: CONF_CONSUMER_FILE_PATH=conf/client.yml, optionally you could also specify logging configuration
- with "APP_LOG_CONF_FILE=conf/log.yml"
+ * Working Directory: the absolute path to "helloworld/go-client", for examples: *
+ /home/dubbo-go-samples/helloworld/go-client*
+ * Environment: DUBBO_GO_CONFIG_PATH="../conf/dubbogo.yml"
Then run it to call the remote service, you will observe the following message output:
```
diff --git a/HOWTO_zh.md b/HOWTO_zh.md
index ee89a24..b074678 100644
--- a/HOWTO_zh.md
+++ b/HOWTO_zh.md
@@ -2,79 +2,87 @@
目前有三种方式来运行 dubbo-go 的示例:
-1. 通过 makefile 快速开始: 在工程 "build" 子目录中提供了一个通用的 makefile。这个 makefile 可用于快速运行工程中的每一个示例。同时，由于这个 makefile 的存在，现在有机会可以把所有的示例串起来自动运行，从而使得通过该工程来做自动的 dubbo-go 的集成测试成为了可能。
+1. 通过 bash 命令快速开始: 通过简单的命令行启动样例以及进行单元测试
2. 在 IDE 中快速开始，这也是**推荐**的方式: 在工程 ".run" 子目录下，提供了所有示例的 GoLand 运行配置文件，因此用户可以简单在 IDE 中单击运行所有的示例。
3. 在 IDE 中手工配置并运行: 为了完整性的目的，也为了万一您不使用 GoLand 而使用其他的 IDE，这里也提供了如何一步一步的配置的指南，帮助用户理解如何在 IDE 中配置，运行或者调试 dubbo-go 的示例。
-### 1. 通过 makefile 快速开始
+### 1. 通过 命令行 快速开始
*前置条件：需要 docker 环境就绪*
-下面我们将使用 "attachment" 作为示例:
+下面我们将使用 "helloworld" 作为示例:
1. **启动注册中心（比如 zookeeper）**
```bash
- cd attachment/go-server
- make -f ../../build/Makefile docker-up
+ make -f build/Makefile docker-up
```
当看到类似下面的输出信息时，就表明 zookeeper server 启动就绪了。
```bash
- > Starting dependency services with docker/docker-compose.yml
- Creating network "docker_default" with the default driver
- Creating docker_zookeeper_1 ... done
+ > Starting dependency services with ./integrate_test/dockercompose/docker-compose.yml
+ Docker Compose is now in the Docker CLI, try `docker compose up`
+
+ Creating network "dockercompose_default" with the default driver
+ Creating dockercompose_zookeeper_1 ... done
+ Creating etcd ... done
+ Creating nacos-standalone ... done
```
如果要停掉注册中心，可以通过运行以下的命令完成:
```bash
- cd attachment/go-server
- make -f ../../build/Makefile docker-down
+ make -f build/Makefile docker-down
```
2. **启动服务提供方**
```bash
- cd attachment/go-server
- make -f ../../build/Makefile start
+ cd helloworld/go-server/cmd
+ export DUBBO_GO_CONFIG_PATH="../conf/dubbogo.yml"
+ go run .
```
当看到类似下面的输出信息时，就表明服务提供方启动就绪了。
```bash
- > Buiding application binary: dist/darwin_amd64/release/go-server
- > Starting application go-server, output is redirected to dist/darwin_amd64/release/go-server.log
- > PID: 86428
+ 2021/10/27 00:33:10 Connected to 127.0.0.1:2181
+ 2021/10/27 00:33:10 Authenticated: id=72057926938066944, timeout=10000
+ 2021/10/27 00:33:10 Re-submitting `0` credentials after reconnec
```
-
- `go-server` 的输出信息可以在 'dist/darwin_amd64/release/go-server.log' 中找到。
-
+
3. **运行服务调用方**
```bash
- cd attachment/go-client
- make -f ../../build/Makefile run
+ cd helloworld/go-client/cmd
+ export DUBBO_GO_CONFIG_PATH="../conf/dubbogo.yml"
+ go run .
```
当以下的信息输出时，说明 `go-client` 调用 `go-server` 成功。
```bash
- > Buiding application binary: dist/darwin_amd64/release/go-client
- > Running application go-client, output is redirected to dist/darwin_amd64/release/go-client.log
- ...
- 2020-10-27T14:51:37.520+0800 DEBUG dubbo/dubbo_invoker.go:144 result.Err: <nil>, result.Rest: &{A001 Alex Stocks 18 2020-10-27 14:51:37.52 +0800 CST}
- 2020-10-27T14:51:37.520+0800 DEBUG proxy/proxy.go:177 [makeDubboCallProxy] result: &{A001 Alex Stocks 18 2020-10-27 14:51:37.52 +0800 CST}, err: <nil>
- response result: &{A001 Alex Stocks 18 2020-10-27 14:51:37.52 +0800 CST}
+ 2021-10-27T00:40:44.879+0800 DEBUG triple/dubbo3_client.go:106 TripleClient.Invoke: get reply = name:"Hello laurence" id:"12345" age:21
+ 2021-10-27T00:40:44.879+0800 DEBUG proxy/proxy.go:218 [makeDubboCallProxy] result: name:"Hello laurence" id:"12345" age:21 , err: <nil>
+ 2021-10-27T00:40:44.879+0800 INFO cmd/client.go:51 client response result: name:"Hello laurence" id:"12345" age:21
```
-3. **集成测试**
+4. **集成测试**
本项目 dubbo-go-samples 除了用来展示如何使用 dubbo-go 中的功能和特性之外，还被用于 apache/dubbo-go 的集成测试。可以按照以下的步骤来运行针对 `go-server` 设计的集成测试:
-
+
+ 首先启动服务方
+ ```bash
+ cd helloworld/go-server/cmd
+ export DUBBO_GO_CONFIG_PATH="../conf/dubbogo.yml"
+ go run .
+ ```
+
+ 然后切换到单测目录， 设置环境变量，然后执行单测
```bash
- cd attachment/go-server
- make -f ../../build/Makefile integration
+ cd integrate_test/helloworld/tests/integration
+ export DUBBO_GO_CONFIG_PATH="../../../../helloworld/go-client/conf/dubbogo.yml"
+ go test -v
```
当以下信息输出时，说明集成测试通过。
@@ -82,15 +90,14 @@
```bash
> Running integration test for application go-server
...
- --- PASS: TestGetUser (0.00s)
+ --- PASS: TestSayHello (0.01s)
PASS
- ok github.com/apache/dubbo-go-samples/attachment/go-server/tests/integration 3.603s
+ ok github.com/apache/dubbo-go-samples/integrate_test/helloworld/tests/integration 0.119s
```
-4. **关闭并清理**
+7. **关闭并清理**
```bash
- cd attachment/go-server
- make -f ../../build/Makefile clean docker-down
+ make -f build/Makefile clean docker-down
```
*以下的两种运行方式都与 IDE 有关。这里我们以 Intellij GoLand 为例来讨论。*
@@ -109,10 +116,10 @@
1. **启动 zookeeper 服务器**
- 打开 "attachment/go-server/docker/docker-compose.yaml" 这个文件，然后点击位于编辑器左边 gutter 栏位中的 ▶︎▶︎ 图标运行，"Service" Tab 应当会弹出并输出类似下面的文本信息:
+ 打开 "integrate_test/dockercompose/docker-compose.yml" 这个文件，然后点击位于编辑器左边 gutter 栏位中的 ▶︎▶︎ 图标运行，"Service" Tab 应当会弹出并输出类似下面的文本信息:
```
Deploying 'Compose: docker'...
- /usr/local/bin/docker-compose -f .../dubbo-go-samples/attachment/go-server/docker/docker-compose.yml up -d
+ /usr/local/bin/docker-compose -f ...integrate_test/dockercompose/docker-compose.yml up -d
Creating network "docker_default" with the default driver
Creating docker_zookeeper_1 ...
'Compose: docker' has been deployed successfully.
@@ -120,17 +127,17 @@
2. **启动服务提供方**
- 打开 "attachment/go-server/cmd/server.go" 文件，然后点击左边 gutter 栏位中紧挨着 "main" 函数的 ▶︎ 图标，并从弹出的菜单中选择 "Modify Run Configuration..."，并确保以下配置的准确:
- * Working Directory: "attachment/go-server" 目录的绝对路径，比如： */home/dubbo-go-samples/attachment/go-server*
- * Environment: CONF_PROVIDER_FILE_PATH=conf/server.yml, 另外也可以指定这个环境变量 "APP_LOG_CONF_FILE=conf/log.yml"
+ 打开 "helloworld/go-server/cmd/server.go" 文件，然后点击左边 gutter 栏位中紧挨着 "main" 函数的 ▶︎ 图标，并从弹出的菜单中选择 "Modify Run Configuration..."，并确保以下配置的准确:
+ * Working Directory: "helloworld/go-server" 目录的绝对路径，比如： */home/dubbo-go-samples/helloworld/go-server*
+ * Environment: DUBBO_GO_CONFIG_PATH="../conf/dubbogo.yml"
这样示例中的服务端就准备就绪，随时可以运行了。
3. **运行服务消费方**
- 打开 "attachment/go-client/cmd/client.go" 这个文件，然后从左边 gutter 栏位中点击紧挨着 "main" 函数的 ▶︎ 图标，然后从弹出的菜单中选择 "Modify Run Configuration..."，并确保以下配置的准确:
- * Working Directory: "attachment/go-client" 目录的绝对路径，比如： */home/dubbo-go-samples/attachment/go-client*
- * Environment: CONF_CONSUMER_FILE_PATH=conf/client.yml, 另外也可以指定这个环境变量 "APP_LOG_CONF_FILE=conf/log.yml"
+ 打开 "helloworld/go-client/cmd/client.go" 这个文件，然后从左边 gutter 栏位中点击紧挨着 "main" 函数的 ▶︎ 图标，然后从弹出的菜单中选择 "Modify Run Configuration..."，并确保以下配置的准确:
+ * Working Directory: "helloworld/go-client" 目录的绝对路径，比如： */home/dubbo-go-samples/helloworld/go-client*
+ * Environment: DUBBO_GO_CONFIG_PATH="../conf/dubbogo.yml"
然后就可以运行并调用远端的服务了，如果调用成功，将会有以下的输出:
```
diff --git a/build/Makefile b/build/Makefile
index 588da0c..0860d41 100644
--- a/build/Makefile
+++ b/build/Makefile
@@ -17,6 +17,7 @@ PROJECT_NAME = $(shell basename "$(PWD)")
PID = /tmp/.$(PROJECT_NAME).pid
PROJECT_DIR=$(shell pwd)
BASE_DIR := $(PROJECT_DIR)/go-server/dist
+DOCKER_DIR := ./integrate_test/dockercompose
SOURCES = $(wildcard $(PROJECT_DIR)/go-server/cmd/*.go)
GO = go
@@ -105,14 +106,14 @@ docker-health-check:
## docker-up: Shutdown dependency services on docker
.PHONY: docker-up
docker-up:
- $(info > Starting dependency services with $(INTEGRATE_DIR)/docker/docker-compose.yml)
- @docker-compose -f $(INTEGRATE_DIR)/docker/docker-compose.yml up -d
+ $(info > Starting dependency services with $(DOCKER_DIR)/docker-compose.yml)
+ @docker-compose -f $(DOCKER_DIR)/docker-compose.yml up -d
## docker-down: Shutdown dependency services on docker
.PHONY: docker-down
docker-down:
- $(info > Stopping dependency services with $(INTEGRATE_DIR)/docker/docker-compose.yml)
- @docker-compose -f $(INTEGRATE_DIR)/docker/docker-compose.yml down
+ $(info > Stopping dependency services with $(DOCKER_DIR)/docker-compose.ym)
+ @docker-compose -f $(DOCKER_DIR)/docker-compose.yml down
## clean: Clean up the output and the binary of the application
.PHONY: clean