This is an automated email from the ASF dual-hosted git repository.
Alanxtl pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/dubbo-website.git
The following commit(s) were added to refs/heads/master by this push:
new 8da99c6eb66 docs: improve RPC quickstart document (#3217)
8da99c6eb66 is described below
commit 8da99c6eb6683261a00a81b5805f4ddabc087959
Author: SouthwestAsiaFloat <[email protected]>
AuthorDate: Fri Aug 7 20:51:37 2026 +0800
docs: improve RPC quickstart document (#3217)
* docs: improve RPC quickstart document
* docs: address RPC quickstart review comments
---
.../overview/mannual/golang-sdk/quickstart/rpc.md | 141 ++++++++++++++-------
.../overview/mannual/golang-sdk/quickstart/rpc.md | 141 ++++++++++++++-------
2 files changed, 190 insertions(+), 92 deletions(-)
diff --git a/content/en/overview/mannual/golang-sdk/quickstart/rpc.md
b/content/en/overview/mannual/golang-sdk/quickstart/rpc.md
index c6e616486a8..affe05f7329 100644
--- a/content/en/overview/mannual/golang-sdk/quickstart/rpc.md
+++ b/content/en/overview/mannual/golang-sdk/quickstart/rpc.md
@@ -32,11 +32,10 @@ Since we are using Protocol Buffer, we first need to
install the relevant code g
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
git clone --depth 1 https://github.com/apache/dubbo-go.git
- cd dubbo-go/tools/protoc-gen-go-triple
- go install .
+ (cd dubbo-go/tools/protoc-gen-go-triple && go install .)
```
- Make sure `protoc-gen-go` and `protoc-gen-go-triple` are in your `PATH`.
You can verify this with `which protoc-gen-go`. If that command does not work,
please execute the following commands:
+ Make sure `protoc-gen-go` and `protoc-gen-go-triple` are in your `PATH`.
You can verify this with `which protoc-gen-go` and `which
protoc-gen-go-triple`. If either command does not work, run:
```shell
[ -n "$(go env GOBIN)" ] && export PATH="$(go env GOBIN):${PATH}"
@@ -49,49 +48,53 @@ Since we are using Protocol Buffer, we first need to
install the relevant code g
service definition.
## Quick Run Example
+
### Download Example Source Code
We maintain a series of dubbo-go usage examples in the <a
href="https://github.com/apache/dubbo-go-samples/";
target="_blank">apache/dubbo-go-samples</a> repository to help users quickly
learn how to use dubbo-go.
You can <a
href="https://github.com/apache/dubbo-go-samples/archive/refs/heads/main.zip";
target="_blank">download the example zip file and unzip it</a>, or clone the
repository:
```shell
-$ git clone --depth 1 https://github.com/apache/dubbo-go-samples
-```
-
-Switch to the quick start example directory:
-
-```shell
-$ cd dubbo-go-samples/helloworld
+git clone --depth 1 https://github.com/apache/dubbo-go-samples.git
+cd dubbo-go-samples/helloworld
```
### Run Server
-In the `go-server/cmd` directory:
-Run the following command to start the server:
+Run all the following commands from the `helloworld` root directory. Start the
server with:
```shell
-$ go run server.go
+go run ./go-server/cmd/main.go
```
Use `cURL` to verify that the server has been started correctly:
```shell
-$ curl \
- --header "Content-Type: application/json" \
- --data '{"name": "Dubbo"}' \
- http://localhost:20000/greet.GreetService/Greet
+curl \
+ --header "Content-Type: application/json" \
+ --data '{"name":"Dubbo"}' \
+ http://localhost:20000/greet.GreetService/Greet
+```
-Greeting: Hello world
+The response is:
+
+```json
+{"greeting":"Dubbo"}
```
### Run Client
-Open a new terminal and run the following command in the `go-client/cmd`
directory to start the client:
+Open another terminal, return to the `helloworld` root directory, and start
the client:
```shell
-$ go run client.go
+cd dubbo-go-samples/helloworld
+go run ./go-client/cmd/main.go
+```
-Greeting: Hello world
+The logs include the following response (prefixes such as the timestamp, log
level, and call site vary by environment):
+
+```text
+Greet response: hello world
```
This is a complete development process of a dubbo-go RPC communication service.
@@ -121,39 +124,43 @@ service GreetService {
}
```
-This file declares a service called `GreetService`, defining the Greet method
along with its request parameter GreetRequest and return value GreetResponse.
+`proto/greet.proto` declares the `GreetService` service and defines the
`Greet` RPC, its `GreetRequest` request, and its `GreetResponse` response.
### Generate Code
-Before running the server or client, we need to generate the relevant code
using `protoc-gen-go` and `protoc-gen-go-triple`.
+Before running the server or client, generate the code with `protoc-gen-go`
and `protoc-gen-go-triple` from the `helloworld` root directory:
```bash
-protoc --go_out=. --go_opt=paths=source_relative \
- --go-triple_out=. --go-triple_opt=paths=source_relative \
- ./greet.proto
+protoc \
+ --go_out=. \
+ --go_opt=paths=source_relative \
+ --go-triple_out=. \
+ --go-triple_opt=paths=source_relative \
+ ./proto/greet.proto
```
-After running the above command, you will see the following generated files in
the target directory:
+After the command completes, the `proto` directory has the following structure:
-```
- proto
- ├── greet.pb.go
- ├── greet.proto
- └── greet.triple.go
+```text
+proto/
+├── greet.proto
+├── greet.pb.go
+└── greet.triple.go
```
-In the proto/greet/v1 package, there are two parts:
+The generated files have different responsibilities:
-- `greet.pb.go` is generated by Google's standard `protoc-gen-go`, which
contains the structures of `GreetRequest`, `GreetResponse`, and the
encoding/decoding rules.
-- `greet.triple.go` is produced by the custom Dubbo plugin
`protoc-gen-go-triple` and includes key information, including the generated
interface `GreetService`, constructors, and more.
+- `greet.pb.go` is generated by the standard `protoc-gen-go` plugin. It
primarily contains Protobuf messages such as `GreetRequest` and
`GreetResponse`, together with their encoding and decoding code.
+- `greet.triple.go` is generated by `protoc-gen-go-triple`. It primarily
contains Triple server registration, the client proxy, and RPC invocation code,
including `RegisterGreetServiceHandler` and `NewGreetService`.
+
+After changing `proto/greet.proto`, rerun the command above to update both
generated files.
### Implement Service
-Next, we need to add business logic by implementing the `greet.GreetService`
interface.
+Next, add the business logic. `GreetTripleServer` implements the generated
`greet.GreetServiceHandler` interface:
```go
-type GreetTripleServer struct {
-}
+type GreetTripleServer struct{}
func (srv *GreetTripleServer) Greet(ctx context.Context, req
*greet.GreetRequest) (*greet.GreetResponse, error) {
resp := &greet.GreetResponse{Greeting: req.Name}
@@ -163,9 +170,29 @@ func (srv *GreetTripleServer) Greet(ctx context.Context,
req *greet.GreetRequest
### Start Server
-Create a new Server, register the `GreetTripleServer` we implemented earlier,
and then initialize and start the Server, which will listen for requests on the
specified port.
+Create a Server and register the `GreetTripleServer` implementation with
`RegisterGreetServiceHandler`. The Server listens on port `20000`:
```go
+package main
+
+import (
+ "context"
+
+ _ "dubbo.apache.org/dubbo-go/v3/imports"
+ "dubbo.apache.org/dubbo-go/v3/protocol"
+ "dubbo.apache.org/dubbo-go/v3/server"
+ "github.com/dubbogo/gost/log/logger"
+
+ greet "github.com/apache/dubbo-go-samples/helloworld/proto"
+)
+
+type GreetTripleServer struct{}
+
+func (srv *GreetTripleServer) Greet(ctx context.Context, req
*greet.GreetRequest) (*greet.GreetResponse, error) {
+ resp := &greet.GreetResponse{Greeting: req.Name}
+ return resp, nil
+}
+
func main() {
srv, err := server.NewServer(
server.WithServerProtocol(
@@ -174,15 +201,18 @@ func main() {
),
)
if err != nil {
- panic(err)
+ logger.Errorf("failed to create server: %v", err)
+ return
}
if err := greet.RegisterGreetServiceHandler(srv, &GreetTripleServer{});
err != nil {
- panic(err)
+ logger.Errorf("failed to register greet service handler: %v",
err)
+ return
}
if err := srv.Serve(); err != nil {
- logger.Error(err)
+ logger.Errorf("failed to serve: %v", err)
+ return
}
}
```
@@ -201,22 +231,41 @@ curl \
You can also use a Dubbo client to request the service. First, obtain the
service proxy from the generated code in the `greet` package, specify the
server address, and initialize it. Then you can initiate an RPC call.
```go
+package main
+
+import (
+ "context"
+ "time"
+
+ "dubbo.apache.org/dubbo-go/v3/client"
+ _ "dubbo.apache.org/dubbo-go/v3/imports"
+ "github.com/dubbogo/gost/log/logger"
+
+ greet "github.com/apache/dubbo-go-samples/helloworld/proto"
+)
+
func main() {
cli, err := client.NewClient(
client.WithClientURL("127.0.0.1:20000"),
)
if err != nil {
- panic(err)
+ logger.Errorf("failed to create client: %v", err)
+ return
}
svc, err := greet.NewGreetService(cli)
if err != nil {
- panic(err)
+ logger.Errorf("failed to create greet service: %v", err)
+ return
}
- resp, err := svc.Greet(context.Background(), &greet.GreetRequest{Name:
"hello world"})
+ ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+ defer cancel()
+
+ resp, err := svc.Greet(ctx, &greet.GreetRequest{Name: "hello world"})
if err != nil {
- logger.Error(err)
+ logger.Errorf("failed to greet: %v", err)
+ return
}
logger.Infof("Greet response: %s", resp.Greeting)
}
diff --git a/content/zh-cn/overview/mannual/golang-sdk/quickstart/rpc.md
b/content/zh-cn/overview/mannual/golang-sdk/quickstart/rpc.md
index 4e33d4d857f..4d7c5b0fc05 100644
--- a/content/zh-cn/overview/mannual/golang-sdk/quickstart/rpc.md
+++ b/content/zh-cn/overview/mannual/golang-sdk/quickstart/rpc.md
@@ -32,11 +32,10 @@ weight: 1
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
git clone --depth 1 https://github.com/apache/dubbo-go.git
- cd dubbo-go/tools/protoc-gen-go-triple
- go install .
+ (cd dubbo-go/tools/protoc-gen-go-triple && go install .)
```
- 确保 `protoc-gen-go`、`protoc-gen-go-triple` 在你的 `PATH` 中。这可以通过 `which
protoc-gen-go` 验证，如果该命令不能正常工作的话，请执行以下命令：
+ 确保 `protoc-gen-go`、`protoc-gen-go-triple` 在你的 `PATH` 中。这可以通过 `which
protoc-gen-go` 和 `which protoc-gen-go-triple` 验证。如果命令不能正常工作，请执行以下命令：
```shell
[ -n "$(go env GOBIN)" ] && export PATH="$(go env GOBIN):${PATH}"
@@ -48,49 +47,53 @@ weight: 1
目录下。请从该目录安装；修改 `.proto` 服务定义后，请同步重新生成 `*.triple.go` 文件。
## 快速运行示例
+
### 下载示例源码
我们在 <a href="https://github.com/apache/dubbo-go-samples/";
target="_blank">apache/dubbo-go-samples</a> 仓库维护了一系列 dubbo-go 使用示例，用来帮助用户快速学习
dubbo-go 使用方式。
你可以 <a
href="https://github.com/apache/dubbo-go-samples/archive/refs/heads/main.zip";
target="_blank">下载示例 zip 包并解压</a>，或者克隆仓库：
```shell
-$ git clone --depth 1 https://github.com/apache/dubbo-go-samples
-```
-
-切换到快速开始示例目录：
-
-```shell
-$ cd dubbo-go-samples/helloworld
+git clone --depth 1 https://github.com/apache/dubbo-go-samples.git
+cd dubbo-go-samples/helloworld
```
### 运行 server
-在 `go-server/cmd` 目录：
-运行以下命令，启动 server：
+以下命令均从 `helloworld` 根目录运行。启动 server：
```shell
-$ go run server.go
+go run ./go-server/cmd/main.go
```
使用 `cURL` 验证 server 已经正常启动：
```shell
-$ curl \
- --header "Content-Type: application/json" \
- --data '{"name": "Dubbo"}' \
- http://localhost:20000/greet.GreetService/Greet
+curl \
+ --header "Content-Type: application/json" \
+ --data '{"name":"Dubbo"}' \
+ http://localhost:20000/greet.GreetService/Greet
+```
-Greeting: Hello world
+响应为：
+
+```json
+{"greeting":"Dubbo"}
```
### 运行 client
-打开一个新的 terminal，运行以下命令，在 `go-client/cmd` 目录运行以下命令，启动 client
+打开一个新的终端，重新进入 `helloworld` 根目录并启动 client：
```shell
-$ go run client.go
+cd dubbo-go-samples/helloworld
+go run ./go-client/cmd/main.go
+```
-Greeting: Hello world
+日志中包含以下响应（时间、日志级别和调用位置等前缀会因运行环境而异）：
+
+```text
+Greet response: hello world
```
以上就是一个完整的 dubbo-go RPC 通信服务开发过程。
@@ -120,39 +123,43 @@ service GreetService {
}
```
-这个文件声明了一个叫做 `GreetService` 的服务，为这个服务定义了 Greet 方法以及它的请求参数 GreetRequest 和返回值
GreetResponse。
+`proto/greet.proto` 声明了名为 `GreetService` 的服务，并定义了 RPC 方法 `Greet`、请求
`GreetRequest` 和响应 `GreetResponse`。
### 生成代码
-在运行 server 或者 client 之前，我们需要使用 `protoc-gen-go`、`protoc-gen-go-triple` 生成相关的代码
+在运行 server 或 client 之前，需要在 `helloworld` 根目录使用 `protoc-gen-go` 和
`protoc-gen-go-triple` 生成相关代码：
```bash
-protoc --go_out=. --go_opt=paths=source_relative \
- --go-triple_out=. --go-triple_opt=paths=source_relative \
- ./greet.proto
+protoc \
+ --go_out=. \
+ --go_opt=paths=source_relative \
+ --go-triple_out=. \
+ --go-triple_opt=paths=source_relative \
+ ./proto/greet.proto
```
-运行以上命令后，在目标目录中看到以下生成的文件：
+运行后，`proto` 目录结构如下：
-```
- proto
- ├── greet.pb.go
- ├── greet.proto
- └── greet.triple.go
+```text
+proto/
+├── greet.proto
+├── greet.pb.go
+└── greet.triple.go
```
-在 proto/greet/v1 包下有两部分内容：
+其中：
-- `greet.pb.go` 是由谷歌标准的 `protoc-gen-go`生成，它包含 `GreetRequest`、`GreetResponse`
结构体和响应的编解码规则。
-- `greet.triple.go` 是由 Dubbo 自定义的插件`protoc-gen-go-triple`成，其中关键的信息包括生成的接口
`GreetService`、构造器等。
+- `greet.pb.go` 由标准的 `protoc-gen-go` 生成，主要包含 `GreetRequest`、`GreetResponse` 等
Protobuf 消息及编解码代码。
+- `greet.triple.go` 由 `protoc-gen-go-triple` 生成，主要包含 Triple 服务端注册、客户端代理和 RPC
调用相关代码，例如 `RegisterGreetServiceHandler` 和 `NewGreetService`。
+
+修改 `proto/greet.proto` 后，需要重新运行上述命令，同时更新这两个生成文件。
### 实现服务
-接下来我们就需要添加业务逻辑了，实现 `greet.GreetService` 接口即可。
+接下来添加业务逻辑。`GreetTripleServer` 实现生成代码中的 `greet.GreetServiceHandler` 接口：
```go
-type GreetTripleServer struct {
-}
+type GreetTripleServer struct{}
func (srv *GreetTripleServer) Greet(ctx context.Context, req
*greet.GreetRequest) (*greet.GreetResponse, error) {
resp := &greet.GreetResponse{Greeting: req.Name}
@@ -162,9 +169,29 @@ func (srv *GreetTripleServer) Greet(ctx context.Context,
req *greet.GreetRequest
### 启动 Server
-创建一个新的 Server，把我们上一步中实现的 `GreeterServer`注册给它，接下来就可以直接初始化和启动 Server
了，它将在指定的端口接收请求。
+创建 Server，并通过 `RegisterGreetServiceHandler` 注册上一步实现的
`GreetTripleServer`。Server 在 `20000` 端口接收请求：
```go
+package main
+
+import (
+ "context"
+
+ _ "dubbo.apache.org/dubbo-go/v3/imports"
+ "dubbo.apache.org/dubbo-go/v3/protocol"
+ "dubbo.apache.org/dubbo-go/v3/server"
+ "github.com/dubbogo/gost/log/logger"
+
+ greet "github.com/apache/dubbo-go-samples/helloworld/proto"
+)
+
+type GreetTripleServer struct{}
+
+func (srv *GreetTripleServer) Greet(ctx context.Context, req
*greet.GreetRequest) (*greet.GreetResponse, error) {
+ resp := &greet.GreetResponse{Greeting: req.Name}
+ return resp, nil
+}
+
func main() {
srv, err := server.NewServer(
server.WithServerProtocol(
@@ -173,15 +200,18 @@ func main() {
),
)
if err != nil {
- panic(err)
+ logger.Errorf("failed to create server: %v", err)
+ return
}
if err := greet.RegisterGreetServiceHandler(srv, &GreetTripleServer{});
err != nil {
- panic(err)
+ logger.Errorf("failed to register greet service handler: %v",
err)
+ return
}
if err := srv.Serve(); err != nil {
- logger.Error(err)
+ logger.Errorf("failed to serve: %v", err)
+ return
}
}
```
@@ -199,22 +229,41 @@ curl \
也可以使用 Dubbo client 请求服务，我们首先需要从生成代码即 `greet` 包中获取服务代理，为它指定 server
地址并初始化，之后就可以发起 RPC 调用了。
```go
+package main
+
+import (
+ "context"
+ "time"
+
+ "dubbo.apache.org/dubbo-go/v3/client"
+ _ "dubbo.apache.org/dubbo-go/v3/imports"
+ "github.com/dubbogo/gost/log/logger"
+
+ greet "github.com/apache/dubbo-go-samples/helloworld/proto"
+)
+
func main() {
cli, err := client.NewClient(
client.WithClientURL("127.0.0.1:20000"),
)
if err != nil {
- panic(err)
+ logger.Errorf("failed to create client: %v", err)
+ return
}
svc, err := greet.NewGreetService(cli)
if err != nil {
- panic(err)
+ logger.Errorf("failed to create greet service: %v", err)
+ return
}
- resp, err := svc.Greet(context.Background(), &greet.GreetRequest{Name:
"hello world"})
+ ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+ defer cancel()
+
+ resp, err := svc.Greet(ctx, &greet.GreetRequest{Name: "hello world"})
if err != nil {
- logger.Error(err)
+ logger.Errorf("failed to greet: %v", err)
+ return
}
logger.Infof("Greet response: %s", resp.Greeting)
}
