Skip to content

Commit

Permalink
provide HOWTO, and translate all docs into Chinese.
Browse files Browse the repository at this point in the history
  • Loading branch information
@beiwei30
beiwei30 committed Feb 4, 2021
1 parent ca1fc7d commit a2b55f3
Show file tree
Hide file tree
Showing 5 changed files with 192 additions and 141 deletions.
141 changes: 141 additions & 0 deletions HOWTO_zh.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
# 如何运行

目前有三种方式来运行 dubbo-go 的示例:

1. 通过 makefile 快速开始: 在工程 "build" 子目录中提供了一个通用的 makefile。这个 makefile 可用于快速运行工程中的每一个示例。同时，由于这个 makefile 的存在，现在有机会可以把所有的示例串起来自动运行，从而使得通过该工程来做自动的 dubbo-go 的集成测试成为了可能。
2. 在 IDE 中快速开始，这也是**推荐**的方式: 在工程 ".run" 子目录下，提供了所有示例的 GoLand 运行配置文件，因此用户可以简单在 IDE 中单击运行所有的示例。
3. 在 IDE 中手工配置并运行: 为了完整性的目的，也为了万一您不使用 GoLand 而使用其他的 IDE，这里也提供了如何一步一步的配置的指南，帮助用户理解如何在 IDE 中配置，运行或者调试 dubbo-go 的示例。

### 1. 通过 makefile 快速开始

*前置条件：需要 docker 环境就绪*

下面我们将使用 "attachment" 作为示例:

1. **启动注册中心（比如 zookeeper）**

```bash
cd attachment/server
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
```

如果要停掉注册中心，可以通过运行以下的命令完成:

```bash
cd attachment/server
make -f ../../build/Makefile docker-down
```

2. **启动服务提供方**

```bash
cd attachment/server
make -f ../../build/Makefile start
```

当看到类似下面的输出信息时，就表明服务提供方启动就绪了。

```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
```

`go-server` 的输出信息可以在 'dist/darwin_amd64/release/go-server.log' 中找到。

3. **运行服务调用方**

```bash
cd attachment/client
make -f ../../build/Makefile 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}
```

3. **集成测试**
本项目 dubbo-go-samples 除了用来展示如何使用 dubbo-go 中的功能和特性之外，还被用于 apache/dubbo-go 的集成测试。可以按照以下的步骤来运行针对 `go-server` 设计的集成测试:

```bash
cd attachment/server
make -f ../../build/Makefile integration
```

当以下信息输出时，说明集成测试通过。

```bash
> Running integration test for application go-server
...
--- PASS: TestGetUser (0.00s)
PASS
ok github.com/apache/dubbo-go-samples/attachment/go-server/tests/integration 3.603s
```

4. **关闭并清理**
```bash
cd attachment/server
make -f ../../build/Makefile clean docker-down
```

*以下的两种运行方式都与 IDE 有关。这里我们以 Intellij GoLand 为例来讨论。*

### 2. 在 IDE 中快速开始

一旦在 GoLand 中打开本项目，可以发现，在 "Run Configuration" 弹出菜单中已经存在了一系列事先配置好了的用来运行相关服务提供方和调用方的选项，例如："helloworld-go-server" 和 "helloworld-go-client"。

![run-configuration.png](.images/run-configurations.png)

可以选择其中的任意一个快速启动相关示例。当然在运行之前，假设需要的注册中心已经事先启动了，不然用例将会失败。您可以选择手动自行启动的方式，也可以利用工程中提供的 "docker-compose.yml" 在启动注册中心的 docker 实例。选择后者的话，可以参考[第三种方式](#3-manually-run-in-ide)中的细节。

### 3. 在 IDE 中手工运行

这里以 *Intellij GoLand* 为例。在 GoLand 中打开 dubbo-go-samples 工程之后，按照以下的步骤来运行/调试本示例:

1. **启动 zookeeper 服务器**

打开 "attachment/go-server/docker/docker-compose.yaml" 这个文件，然后点击位于编辑器左边 gutter 栏位中的 ▶︎▶︎ 图标运行，"Service" Tab 应当会弹出并输出类似下面的文本信息:
```
Deploying 'Compose: docker'...
/usr/local/bin/docker-compose -f .../dubbo-go-samples/attachment/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.
```

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"

这样示例中的服务端就准备就绪，随时可以运行了。

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"

然后就可以运行并调用远端的服务了，如果调用成功，将会有以下的输出:
```
[2021-02-03/16:19:30 main.main: client.go: 66] response result: &{A001 Alex Stocks 18 2020-02-04 16:19:30.422 +0800 CST}
```

如果需要调试该示例或者 dubbo-go 框架，可以在 IDE 中从 "Run" 切换到 "Debug"。如果要结束的话，直接点击 ◼︎ 就好了。

35 changes: 17 additions & 18 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,29 +4,28 @@

## What It Contains

* async: An async example. dubbo-go supports client to call server asynchronously.
* async: An async example.
* attachment: An attachment example, to show how to use attachment to pass user data from the client to the server.
* configcenter: Some examples of different config center. There are three -- zookeeper, apollo and nacos at present.
* direct: A direct example. This feature make start of dubbo-go get easy.
* filter: Some examples of different filter. Including custom_filter and tpslimit
* general: A general example. It had validated zookeeper registry and different parameter lists of service.
* generic: A generic example. It show how to use generic feature of dubbo-go.
* helloworld: A simplest example. It contain 'go-client', 'go-server', 'java-server' of dubbo protocol.
* multi_registry: An example of multiple registries.
And it has a comprehensive testing with dubbo/jsonrpc/grpc/rest protocol. You can refer to it to create your first complete dubbo-go project.
* registry: Some examples of different registry. There are kubernetes, nacos and etcd at present. **Note**: When use the different registry, you need update config file, but also must import the registry package. see the etcd `README`
* router: Some router examples. Now, a condition router example is existing.
* seata: Transaction system examples by seata.
* shop: Shop sample, make consumer and provider run in a go program.
* tracing: Some tracing examples. We have tracing support of dubbo/grpc/jsonrpc protocol at present.
* configcenter: uses of different config centers, including zookeeper, apollo and nacos at present.
* direct: A direct invocation example.
* filter: Some examples of different filter, including custom_filter and tpslimit
* general: A general example
* generic: A generic invocation example
* helloworld: A 101 example
* multi_registry: A multi-registry example
* registry: uses of different registres, including kubernetes, nacos, etcd and service-discovery
* router: router examples, including condition and tag
* seata: A seata example
* shop: Shop sample
* tracing: tracing example

## How To Run

Pls. refer [How To Run](HOWTO.md) for the instructions.

## How to contribute

If you want to add some samples, we hope that you can do this:
1. Adding samples in appropriate directory. If you dont' know which directory you should put your samples into, you can get some advices from dubbo-go community.
2. You must run the samples locally and there must be no any error.
3. If your samples have some third party dependency, including another framework, we hope that you can provide some docs, script is better.
If you want to add more samples, pls. read on:
1. Create new sub directory and give it an appropriate name for your new sample. Pls. follow the layout of the existing sample if you are not sure how to organize your code.
2. Make sure your sample work as expected before submit PR, and make sure GitHub CI passes after PR is submitted. Pls. refer to the existing sample on how to test the sample.
3. Pls. provide README.md to explain your samples.
32 changes: 32 additions & 0 deletions README_zh.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# Dubbo Golang 示例

![CI](https://github.com/apache/dubbo-go-samples/workflows/CI/badge.svg)

## 本工程包含的示例

* async: 异步调用
* attachment: 如何通过 attachment 把用户数据从调用方传递给服务方
* configcenter: 使用不同的配置中心，目前支持三种：zookeeper、apollo、和 nacos
* direct: 直连模式
* filter: 使用和扩展不同的 filter，目前包含了 custom_filter 和 tpslimit
* general: 通用例子，展示 zookeeper 注册中心的使用以及不同的配置项
* generic: 泛化调用
* helloworld: 入门例子
* multi_registry: 多注册
* registry: 展示与不同注册中心的对接，包含了 nacos、etcd、kubernetes 和 servicediscovery
* router: 展示了不同的路由，包含了 condition 和 tag
* seata: 展示了与 seata 的对接
* shop: 一个在线商店的小例子
* tracing: 链路追踪

## 如何运行

请参阅 [HOWTO](HOWTO_zh.md)

## 如何贡献

如果您希望增加新的用例，请继续阅读:

1. 为您的示例起合适的名字并创建子目录。如果您不太确定如何做，请参考现有示例摆放目录结构
2. 提交 PR 之前请确保在本地运行通过，提交 PR 之后请确保 GitHub 上的集成测试通过。请参考现有示例增加对应的测试
3. 请提供示例相关的 README.md 的中英文版本
63 changes: 1 addition & 62 deletions attachment/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,66 +31,5 @@ func (u *UserProvider) GetUser(ctx context.Context, req []interface{}) (*User, e
}
```

### How to run

#### Quick Start with makefile

*Prerequisite: docker environment*

1. **Start server**
```bash
cd attachment/server
make -f ../../build/Makefile docker-up start
```
2. **Run client**
```bash
cd attachment/client
make -f ../../build/Makefile run
```
3. **Integration test**
```bash
cd attachment/server
make -f ../../build/Makefile integration
```
4. **Shutdown and cleanup**
```bash
cd attachment/server
make -f ../../build/Makefile clean docker-down
```

#### Run in IDE

Use *Intellij GoLand* as an example. After open dubbo-go-samples in GoLand, follow the steps below to run/debug this 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 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
Creating network "docker_default" with the default driver
Creating docker_zookeeper_1 ...
'Compose: docker' has been deployed successfully.
```
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 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"
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 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"
Then run it to call the remote service, you will observe the following message output:
```
[2021-02-03/16:19:30 main.main: client.go: 66] response result: &{A001 Alex Stocks 18 2020-02-04 16:19:30.422 +0800 CST}
```
If you need to debug either the samples or dubbo-go, you may consider switch to **Debug** instead of **Run** in GoLand. To stop, simply click ◼︎ to shutdown everything.
Pls. refer to [HOWTO.md](../HOWTO.md) under the root directory to run this sample.

62 changes: 1 addition & 61 deletions attachment/README_zh.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,66 +32,6 @@ func (u *UserProvider) GetUser(ctx context.Context, req []interface{}) (*User, e
}
```

### 如何运行
请参阅根目录中的 [HOWTO.md](../HOWTO_zh.md) 来运行本例。

#### 通过 Makefile 的方式快速开始

*先决条件：需要提前安装好 Docker*

1. **启动服务端**
```bash
cd attachment/server
make -f ../../build/Makefile docker-up start
```
2. **运行客户端**
```bash
cd attachment/client
make -f ../../build/Makefile run
```
3. **集成测试**
```bash
cd attachment/server
make -f ../../build/Makefile integration
```
4. **清理现场**
```bash
cd attachment/server
make -f ../../build/Makefile clean docker-down
```

#### 在 IDE 中运行

这里以 *Intellij GoLand* 为例。在 GoLand 中打开 dubbo-go-samples 工程之后，按照以下的步骤来运行/调试本示例:

1. **启动 zookeeper 服务器**

打开 "attachment/go-server/docker/docker-compose.yaml" 这个文件，然后点击位于编辑器左边 gutter 栏位中的 ▶︎▶︎ 图标运行，"Service" Tab 应当会弹出并输出类似下面的文本信息:
```
Deploying 'Compose: docker'...
/usr/local/bin/docker-compose -f .../dubbo-go-samples/attachment/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.
```
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"
这样示例中的服务端就准备就绪，随时可以运行了。
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"
然后就可以运行并调用远端的服务了，如果调用成功，将会有以下的输出:
```
[2021-02-03/16:19:30 main.main: client.go: 66] response result: &{A001 Alex Stocks 18 2020-02-04 16:19:30.422 +0800 CST}
```
如果需要调试该示例或者 dubbo-go 框架，可以在 IDE 中从 "Run" 切换到 "Debug"。如果要结束的话，直接点击 ◼︎ 就好了。

0 comments on commit a2b55f3

Please sign in to comment.