RPC框架 on Apache Dubbo

流式通信

Mon, 01 Jan 0001 00:00:00 +0000

Streaming 流式通信是 Dubbo3 新提供的一种 RPC 数据传输模式，适用于以下场景:

接口需要发送大量数据，这些数据无法被放在一个 RPC 的请求或响应中，需要分批发送，但应用层如果按照传统的多次 RPC 方式无法解决顺序和性能的问题，如果需要保证有序，则只能串行发送
流式场景，数据需要按照发送顺序处理, 数据本身是没有确定边界的
推送类场景，多个消息在同一个调用的上下文中被发送和处理

Streaming 流式通信类型分为以下三种:

SERVER_STREAM(服务端流)
CLIENT_STREAM(客户端流)
BIDIRECTIONAL_STREAM(双向流)

1.介绍

本文档演示如何在 Dubbo-go 中使用流式通信，可在此查看完整示例源码地址。

2.如何使用Dubbo-go流式通信

在proto文件中需要流式通信的方法的参数前面添加stream，使用proto-gen-triple生成相应文件

service GreetService {
 rpc Greet(GreetRequest) returns (GreetResponse) {}
 rpc GreetStream(stream GreetStreamRequest) returns (stream GreetStreamResponse) {}
 rpc GreetClientStream(stream GreetClientStreamRequest) returns (GreetClientStreamResponse) {}
 rpc GreetServerStream(GreetServerStreamRequest) returns (stream GreetServerStreamResponse) {}
}

编写服务端handler文件

源文件路径: dubbo-go-sample/streaming/go-server/cmd/server.go

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 (srv *GreetTripleServer) GreetStream(ctx context.Context, stream greet.GreetService_GreetStreamServer) error {
	for {
		req, err := stream.Recv()
		if err != nil {
			if triple.IsEnded(err) {
				break
			}
			return fmt.Errorf("triple BidiStream recv error: %s", err)
		}
		if err := stream.Send(&greet.GreetStreamResponse{Greeting: req.Name}); err != nil {
			return fmt.Errorf("triple BidiStream send error: %s", err)
		}
	}
	return nil
}

func (srv *GreetTripleServer) GreetClientStream(ctx context.Context, stream greet.GreetService_GreetClientStreamServer) (*greet.GreetClientStreamResponse, error) {
	var reqs []string
	for stream.Recv() {
		reqs = append(reqs, stream.Msg().Name)
	}
	if stream.Err() != nil && !triple.IsEnded(stream.Err()) {
		return nil, fmt.Errorf("triple ClientStream recv err: %s", stream.Err())
	}
	resp := &greet.GreetClientStreamResponse{
		Greeting: strings.Join(reqs, ","),
	}

	return resp, nil
}

func (srv *GreetTripleServer) GreetServerStream(ctx context.Context, req *greet.GreetServerStreamRequest, stream greet.GreetService_GreetServerStreamServer) error {
	for i := 0; i < 5; i++ {
		if err := stream.Send(&greet.GreetServerStreamResponse{Greeting: req.Name}); err != nil {
			return fmt.Errorf("triple ServerStream send err: %s", err)
		}
	}
	return nil
}

编写客户端client文件

超时时间

Mon, 01 Jan 0001 00:00:00 +0000

1.介绍

本示例演示如何在 Dubbo-go 客户端发起调用时设置请求超时时间。可在此查看完整示例源码地址

2.如何设置请求超时时间

在创建客户端时，可以使用 client.WithRequestTimeout() 方法设置全局超时时间（所有使用改 client 的服务代理共享）。

 cli, err := client.NewClient(
 client.WithClientURL("tri://127.0.0.1:20000"),
 client.WithClientRequestTimeout(3 * time.Second),
 )

可以使用 client.WithRequestTimeout() 创建服务粒度的超时时间（以下服务代理 svc 发起的方法调用都使用这个时间）。

 svc, err := greet.NewGreetService(cli, client.WithRequestTimeout(5 * time.Second))

也可以在调用发起时，使用 client.WithCallRequestTimeout() 指定一个超时时间

resp, err := svc.GreetTimeout(context.Background(), &greet.GreetRequest{Name: "hello world"}, client.WithCallRequestTimeout(10 * time.Second))

从上往下，以上三种方式的优先级逐步提高，client.WithCallRequestTimeout() 指定的超时时间优先级最高。

3.示例详解

3.1服务端介绍

服务端proto文件

源文件路径：dubbo-go-sample/timeout/proto/greet.proto

syntax = "proto3";

package greet;

option go_package = "github.com/apache/dubbo-go-samples/timeout/proto;greet";

message GreetRequest {
 string name = 1;
}

message GreetResponse {
 string greeting = 1;
}

service GreetService {
 rpc Greet(GreetRequest) returns (GreetResponse) {}
 rpc GreetTimeout(GreetRequest) returns (GreetResponse) {}
}

服务端handler文件

Greet方法直接响应，GreetTimeout方法等待五秒后响应（模拟超时）。

健康检查

Mon, 01 Jan 0001 00:00:00 +0000

背景

Dubbo-go 内置了基于 triple 协议的健康检查服务，帮助用户管理和监测服务健康状态，可在此查看完整示例源码。

使用方法

框架在通过 instance 启动后会自动向框架中注册健康检查服务 grpc.health.v1.Health，用于记录并对外暴露每个triple服务的健康状态。
健康检查服务可以通过发起 http 请求检查框架中服务的状态，也可以通过客户端调用该健康检查服务，调用的接口为grpc.health.v1.Health，方法为 check。

1、通过客户端调用健康检查服务

启动 dubbo-go-samples/healthcheck/go-server 中的服务，通过下方客户端即可查看 greet.GreetService 的状态。

package main

import (
	"context"
	"dubbo.apache.org/dubbo-go/v3/client"
	_ "dubbo.apache.org/dubbo-go/v3/imports"
	health "dubbo.apache.org/dubbo-go/v3/protocol/triple/health/triple_health"
	"github.com/dubbogo/gost/log/logger"
)

func main() {
	cli, err := client.NewClient(
		client.WithClientURL("tri://127.0.0.1:20000"),
	)
	if err != nil {
		panic(err)
	}
	svc, err := health.NewHealth(cli)
	if err != nil {
		panic(err)
	}
	check, err := svc.Check(context.Background(), &health.HealthCheckRequest{Service: "greet.GreetService"})
	if err != nil {
		logger.Error(err)
	} else {
		logger.Info("greet.GreetService's health", check.String())
	}
	watch, err := svc.Watch(context.Background(), &health.HealthCheckRequest{Service: "greet.GreetService"})
	if err != nil {
		logger.Error(err)
	} else {
		if watch.Recv() {
			logger.Info("greet.GreetService's health", watch.Msg().String())
		}
	}
}

启动后会有以下输出

请求重试

Mon, 01 Jan 0001 00:00:00 +0000

当一次服务调用失败时，我们可以让框架选择自动重试几次，这样能提高用户侧看到的请求成功率。在 failover cluster 模式下 dubbo-go 支持自动重试。

1.介绍

本示例演示如何在 client 端调用失败时配置重试功能，完整示例源码地址

2.如何使用重试功能

在使用 client.NewClient() 创建客户端时，可以使用 client.WithClientRetries() 方法设置重试次数。

cli, err := client.NewClient(
	client.WithClientURL("tri://127.0.0.1:20000"),
	client.WithClientRetries(3),
)

或者，可以使用 client.WithRequestTimeout() 设置服务粒度的超时时间（以下配置对服务 svc 起作用）。

svc, err := greet.NewGreetService(cli, client.WithClientRetries(5))

也可以在调用发起时，使用 client.WithCallRetries() 指定重试次数

resp, err := svc.Greet(context.Background(), &greet.GreetRequest{Name: "hello world"}, client.WithCallRetries(6))

从上往下，以上三种方式的优先级逐步提高，client.WithCallRetries() 指定的重试次数优先级最高。

3.示例解读

3.1服务端介绍

服务端proto文件

源文件路径：dubbo-go-sample/retry/proto/greet.proto

syntax = "proto3";

package greet;

option go_package = "github.com/apache/dubbo-go-samples/retry/proto;greet";

message GreetRequest {
 string name = 1;
}

message GreetResponse {
 string greeting = 1;
}

service GreetService {
 rpc Greet(GreetRequest) returns (GreetResponse) {}
 rpc GreetTimeout(GreetRequest) returns (GreetResponse) {}
}

服务端handler文件

Greet方法直接响应，GreetRetry方法用于模拟重试。

通信协议

Mon, 01 Jan 0001 00:00:00 +0000

Dubbo-go 框架内置提供了两款协议：triple、dubbo，除此之外，框架还提供了多种协议扩展接入方式。

triple，基于 HTTP/1、HTTP/2 的高性能通信协议，100% 兼容 gRPC，支持 Unary、Streming 等通信模式；支持发布 REST 风格的 HTTP 服务。
dubbo，基于 TCP 的高性能私有通信协议，缺点是通用性较差，更适合在 Dubbo SDK 间使用；
任意协议扩展，通过扩展 protocol 可以之前任意 RPC 协议，官方生态库提供 JsonRPC、thrift 等支持。

本篇文档中，我们将介绍关于 triple 协议的使用方式、如何实现与已有 dubbo2 系统的互相调用、扩展更多协议支持等。更多原理性介绍请参考协议规范或者 dubbo java 中相关描述文档。

triple 协议

triple 协议支持使用 protobuf 和 non-protobuf 两种开发模式，我们 推荐使用 protobuf 模式开发服务。

目前我们大部分示例都是使用这个模式开发，可查看快速开始学习完整开发示例，以下是基本步骤：

先使用 protobuf 定义服务

syntax = "proto3";
package greet;
option go_package = "github.com/apache/dubbo-go-samples/helloworld/proto;greet";

message GreetRequest {
 string name = 1;
}

message GreetResponse {
 string greeting = 1;
}

service GreetService {
 rpc Greet(GreetRequest) returns (GreetResponse) {}
}

安装 protoc 插件，编译生成代码：

protoc --go_out=. --go_opt=paths=source_relative \
 --go-triple_out=. --go-triple_opt=paths=source_relative \
 proto/greet.proto

server 端发布服务

srv, err := server.NewServer(
	server.WithServerProtocol(
		protocol.WithPort(20000),
		protocol.WithTriple(),
	),
)

greet.RegisterGreetServiceHandler(srv, &GreetTripleServer{})

client 端调用服务

cli, err := client.NewClient(
	client.WithClientURL("127.0.0.1:20000"),
)

svc, err := greet.NewGreetService(cli)
resp, err := svc.Greet(context.Background(), &greet.GreetRequest{Name: "hello world"})

dubbo-java 体系互调

如果 java 和 go 都使用 triple+protobuf 模式，很明显他们是可以直接互调通信的。

异常类型返回值

Mon, 01 Jan 0001 00:00:00 +0000

1.介绍

本文档演示如何在 RPC 调用过程中处理 error 错误类型响应，可在此查看完整示例源码地址。

2.示例详解

2.1 服务端

服务端proto文件

源文件路径：dubbo-go-sample/error/proto/greet.proto

syntax = "proto3";

package greet;

option go_package = "github.com/apache/dubbo-go-samples/error/proto;greet";

message GreetRequest {
 string name = 1;
}

message GreetResponse {
 string greeting = 1;
}

service GreetService {
 rpc Greet(GreetRequest) returns (GreetResponse) {}
}

服务端handler文件

请注意，在本程序设计中，Greet方法只有接收到 name="right name" 时才会认为是正确请求，否则会返回错误。

源文件路径：dubbo-go-sample/context/go-server/main.go

package main

import (
	"context"
	"fmt"
	"github.com/pkg/errors"

	_ "dubbo.apache.org/dubbo-go/v3/imports"
	"dubbo.apache.org/dubbo-go/v3/protocol"
	"dubbo.apache.org/dubbo-go/v3/server"
	greet "github.com/apache/dubbo-go-samples/helloworld/proto"
	"github.com/dubbogo/gost/log/logger"
)

type GreetTripleServer struct {
}

func (srv *GreetTripleServer) Greet(ctx context.Context, req *greet.GreetRequest) (*greet.GreetResponse, error) {
	name := req.Name
	if name != "right name" {
		errInfo := fmt.Sprintf("name is not right: %s", name)
		logger.Error(errInfo)
		return nil, errors.New(errInfo)
	}

	resp := &greet.GreetResponse{Greeting: req.Name}
	return resp, nil
}

func main() {
	srv, err := server.NewServer(
		server.WithServerProtocol(
			protocol.WithPort(20000),
			protocol.WithTriple(),
		),
	)
	if err != nil {
		panic(err)
	}

	if err = greet.RegisterGreetServiceHandler(srv, &GreetTripleServer{}); err != nil {
		panic(err)
	}

	if err = srv.Serve(); err != nil {
		logger.Error(err)
	}
}

从 rpc 方法签名中，我们可以看到 func (srv *GreetTripleServer) Greet(ctx context.Context, req *greet.GreetRequest) (*greet.GreetResponse, error) 包含 error 返回值。

传递附加参数

Mon, 01 Jan 0001 00:00:00 +0000

理解隐式参数传递的最直接方式 http header，它的工作方式与 http header 完全一致，在 GET 或 POST 请求体之外可以传递任意多个 header 参数。而对于 RPC 调用而言，context就是在方法签名的参数之外提供附加参数传递能力，在实现原理上，对于不同的协议，attachment 的实现方式略有不同：

对于 triple 协议，attachment 会转换为标准的 http header 进行传输。
对于 dubbo 协议，attachment 是编码在协议体的固定位置进行传输，具体请参见 dubbo 协议规范。、

注意

在使用 triple 协议时，由于 http header 的限制，仅支持小写的 ascii 字符
path, group, version, dubbo, token, timeout 等一些 key 是保留字段，传递 attachment 时应避免使用，尽量通过业务前缀等确保 key 的唯一性。

1.介绍

本文档演示如何在 Dubbo-go 框架中使用 context 上下文传递和读取附加参数，来实现上下文信息传递，可在此查看完整示例源码地址

2.使用说明

2.1客户端使用说明

在客户端中，使用下述方式传递字段, 示例中 key 为 constant.AttachmentKey 即 “attachment”:

	ctx := context.Background()
	ctx = context.WithValue(ctx, constant.AttachmentKey, map[string]interface{}{
 "key1": "user defined value 1",
 "key2": "user defined value 2"
	})

2.2服务端使用说明

在服务端中，使用下述方式获取字段, value的类型为 map[string]interface{}：

启动时检查

Mon, 01 Jan 0001 00:00:00 +0000

Dubbo 框架缺省会在启动时检查依赖的服务是否可用（注册中心是否有可用地址），不可用时会抛出异常，阻止应用初始化完成，以便上线时，能及早发现问题，默认 check=“true”，并等待3s。

可以通过 check=“false” 关闭检查，比如，测试时，有些服务不关心，或者出现了循环依赖，必须有一方先启动。

关闭 check 后，请注意 provider数量比较多时， consumer 订阅 provider 生成服务地址可能会有一定延迟，如果 consumer 一启动就对外提供服务，可能会造成"冷启动"。所以在这个时候，请对服务进行预热。

示例：

dubbo:
 consumer:
 check : false
 reference: 
 myserivce:
 check: true

或者

cli, err := client.NewClient(
	client.WithClientCheck(false),
)

或者

svc, err := health.NewHealth(cli)
svc.Check(context.Background(), &health.HealthCheckRequest{Service: "greet.GreetService"}, client.WithCheck(false))

filter拦截器

Mon, 01 Jan 0001 00:00:00 +0000

Filter 过滤器动态拦截请求（request）或响应（response）以转换或使用请求或响应中包含的信息。过滤器本身通常不会创建响应，而是提供可以“附加”到任何一次 RPC 请求的通用函数。Dubbo Filter 是可插拔的，我们可以在一次 RPC 请求中插入任意类型的、任意多个 Filter。

Filter 工作原理如下图所示：

使用方式

1. Filter 拦截器概念

Filter 定义如下：

// Filter interface defines the functions of a filter
// Extension - Filter
type Filter interface {
	// Invoke is the core function of a filter, it determines the process of the filter
	Invoke(context.Context, protocol.Invoker, protocol.Invocation) protocol.Result
	// OnResponse updates the results from Invoke and then returns the modified results.
	OnResponse(context.Context, protocol.Result, protocol.Invoker, protocol.Invocation) protocol.Result
}

Filter 可以加载在 Consumer 端或者 Provider端。当加载在 Consumer 端，其Invoke函数调用的下游为网络层，OnResponse 为请求结束从网络层获取到返回结果后被调用。当加载在 Provider 端，其 Invoke 函数调用的下游为用户代码，OnResponse 为用户代码执行结束后向下传递至网络层前被调用。