基础示例

Kitex 基础示例

开始此章节前,确保你已经了解前置知识并完成了环境准备

获取示例代码

  • 点击 此处 直接下载示例代码仓库
  • 使用 git 克隆代码仓库:git clone https://github.com/cloudwego/kitex-examples.git

运行

直接运行

  1. 进入示例仓库的 hello 目录:

    cd kitex-examples/hello
    
  2. 运行服务端代码:

    go run .
    
    // 输出类似日志代表运行成功
    2024/01/18 20:35:08.857352 server.go:83: [Info] KITEX: server listen at addr=[::]:8888
    
  3. 另启一个终端运行客户端代码:

    go run ./client
    
    // 每隔一秒输出类似日志代表运行成功
    2024/01/18 20:39:59 Response({Message:my request})
    2024/01/18 20:40:00 Response({Message:my request})
    2024/01/18 20:40:01 Response({Message:my request})
    

Docker 运行

  1. 进入示例代码仓库:

    cd kitex-examples
    
  2. 构建 docker 镜像:

    docker build -t kitex-examples .
    
  3. 运行服务端代码:

    docker run --network host kitex-examples ./hello-server
    
    // 输出类似日志代表运行成功
    2024/01/18 12:47:34.712415 server.go:83: [Info] KITEX: server listen at addr=[::]:8888
    
  4. 运行客户端代码:

    docker run --network host kitex-examples ./hello-client
    
    // 每隔一秒输出类似日志代表运行成功
    2024/01/18 12:48:20 Response({Message:my request})
    2024/01/18 12:48:21 Response({Message:my request})
    2024/01/18 12:48:22 Response({Message:my request})
    

恭喜你,你现在成功通过 Kitex 发起了 RPC 调用。

新增方法

你已经完成现有示例代码的运行,接下来添加你自己实现的方法并运行起来吧。

打开 hello 目录下的 hello.thrift 文件,你会看到以下内容:

namespace go api

struct Request {
        1: string message
}

struct Response {
        1: string message
}

service Hello {
    Response echo(1: Request req)
}

现在让我们为新方法分别定义一个新的请求和响应,AddRequestAddResponse,并在 service Hello 中增加 add 方法:

namespace go api

struct Request {
    1: string message
}

struct Response {
    1: string message
}

struct AddRequest {
  	1: i64 first
  	2: i64 second
}

struct AddResponse {
  	1: i64 sum
}

service Hello {
    Response echo(1: Request req)
    AddResponse add(1: AddRequest req)
}

生成新代码

运行如下命令后,kitex 工具根据 hello.thrift 内容自动更新代码文件。

kitex -module "github.com/cloudwego/kitex-examples" -service a.b.c hello.thrift

执行完上述命令后,kitex 工具将更新下述文件

  1. 更新 ./handler.go,在里面增加一个 Add 方法的基本实现
  2. 更新 ./kitex_gen,里面有框架运行所必须的代码文件

补全业务逻辑

上述步骤完成后,./handler.go 中会自动补全一个 Add 方法的基本实现,类似如下代码:

// Add implements the HelloImpl interface.
func (s *HelloImpl) Add(ctx context.Context, req *api.AddRequest) (resp *api.AddResponse, err error) {
        // TODO: Your code here...
        return
}

这个方法对应我们在 hello.thrift 中新增的 Add 方法,我们要做的就是增加我们想要的业务逻辑代码。例如返回请求参数相加后的结果:

// Add implements the HelloImpl interface.
func (s *HelloImpl) Add(ctx context.Context, req *api.AddRequest) (resp *api.AddResponse, err error) {
        // TODO: Your code here...
        resp = &api.AddResponse{Sum: req.First + req.Second}
        return
}

新增客户端调用

服务端已经有了 Add 方法的处理,现在让我们在客户端增加对 Add 方法的调用。

./client/main.go 中你会看到类似如下的 for 循环:

for {
        req := &api.Request{Message: "my request"}
        resp, err := client.Echo(context.Background(), req)
        if err != nil {
                log.Fatal(err)
        }
        log.Println(resp)
        time.Sleep(time.Second)
}

现在让我们在里面增加 Add 方法的调用:

for {
        req := &api.Request{Message: "my request"}
        resp, err := client.Echo(context.Background(), req)
        if err != nil {
                log.Fatal(err)
        }
        log.Println(resp)
        time.Sleep(time.Second)
        addReq := &api.AddRequest{First: 512, Second: 512}
        addResp, err := client.Add(context.Background(), addReq)
        if err != nil {
                log.Fatal(err)
        }
        log.Println(addResp)
        time.Sleep(time.Second)
}

重新运行

按照第一次运行示例代码的方法,分别重新运行服务端与客户端代码,看到类似如下输出,代表运行成功:

// 服务端
2024/01/18 21:07:43.638115 server.go:83: [Info] KITEX: server listen at addr=[::]:8888


// 客户端
2024/01/18 21:07:52 Response({Message:my request})
2024/01/18 21:07:53 AddResponse({Sum:1024})
2024/01/18 21:07:54 Response({Message:my request})
2024/01/18 21:07:55 AddResponse({Sum:1024})
2024/01/18 21:07:56 Response({Message:my request})
2024/01/18 21:07:57 AddResponse({Sum:1024})

恭喜你,完成了快速上手的所有内容!


最后修改 July 24, 2024 : docs: fix error in render (#1110) (34e4f87)