协议规范 on Apache Dubbo

Triple 协议设计理念与规范

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

1 协议设计理念

Triple 协议的设计参考了 gRPC、gRPC-Web、通用 HTTP 等多种协议模式，吸取每个协议各自的特性和优点，最终设计成为一个易于浏览器访问、完全兼容 gRPC 且支持 Streaming 通信的协议，Triple 支持同时运行在 HTTP/1、HTTP/2 协议之上。

Triple 协议的设计目标如下：

Triple 设计为对人类、开发调试友好的一款基于 HTTP 的协议，尤其是对 unary 类型的 RPC 请求。
完全兼容基于 HTTP/2 的 gRPC 协议，因此 Dubbo Triple 协议实现可以 100% 与 gRPC 体系互调互通。
仅依赖标准的、被广泛使用的 HTTP 特性，以便在实现层面可以直接依赖官方的标准 HTTP 网络库。

当与 Protocol Buffers 一起使用时（即使用 IDL 定义服务），Triple 协议可支持 unary、client-streaming、server-streaming 和 bi-streaming RPC 通信模式，支持二进制 Protobuf、JSON 两种数据格式 payload。 Triple 实现并不绑定 Protocol Buffers，比如你可以使用 Java 接口定义服务，Triple 协议有对这种模式的扩展 Content-type 支持。

2 示例

2.1 Unary 请求

以 HTTP/1 请求为例，目前 HTTP/1 协议仅支持 Unary RPC，支持使用 application/proto 和 application/json 编码类型，使用方式与 REST 风格请求保持一致，同时响应也包含常规的 HTTP 响应编码（如 200 OK）。

Triple 协议优势与目标

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

简介

Triple 协议是 Dubbo3 设计的基于 HTTP 的 RPC 通信协议规范，它完全兼容 gRPC 协议，支持 Request-Response、Streaming 流式等通信模型，可同时运行在 HTTP/1 和 HTTP/2 之上。

Dubbo 框架提供了 Triple 协议的多种语言实现，它们可以帮助你构建浏览器、gRPC 兼容的 HTTP API 接口：你只需要定义一个标准的 Protocol Buffer 格式的服务并实现业务逻辑，Dubbo 负责帮助生成语言相关的 Server Stub、Client Stub，并将整个调用流程无缝接入如路由、服务发现等 Dubbo 体系。Go、Java 等语言的 Triple 协议实现原生支持 HTTP/1 传输层通信，相比于 gRPC 官方实现，Dubbo 框架提供的协议实现更简单、更稳定，帮助你更容易的开发和治理微服务应用。

针对某些语言版本，Dubbo 框架还提供了更贴合语言特性的编程模式，即不绑定 IDL 的服务定义与开发模式，比如在 Dubbo Java 中，你可以选择使用 Java Interface 和 Pojo 类定义 Dubbo 服务，并将其发布为基于 Triple 协议通信的微服务。

协议规范(Specification)

基于 Triple 协议，你可以实现以下目标：

当 Dubbo 作为 Client 时

Dubbo Client 可以访问 Dubbo 服务端 (Server) 发布的 Triple 协议服务，同时还可以访问标准的 gRPC 服务端。

Dubbo2 协议规范

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

协议规范 Specification

Magic - Magic High & Magic Low (16 bits)

标识协议版本号，Dubbo 协议：0xdabb
Req/Res (1 bit)

标识是请求或响应。请求： 1; 响应： 0。
2 Way (1 bit)

仅在 Req/Res 为1（请求）时才有用，标记是否期望从服务器返回值。如果需要来自服务器的返回值，则设置为1。
Event (1 bit)

标识是否是事件消息，例如，心跳事件。如果这是一个事件，则设置为1。
Serialization ID (5 bit)

标识序列化类型：比如 fastjson 的值为6。
Status (8 bits)

仅在 Req/Res 为0（响应）时有用，用于标识响应的状态。
- 20 - OK
- 30 - CLIENT_TIMEOUT
- 31 - SERVER_TIMEOUT
- 40 - BAD_REQUEST
- 50 - BAD_RESPONSE
- 60 - SERVICE_NOT_FOUND
- 70 - SERVICE_ERROR
- 80 - SERVER_ERROR
- 90 - CLIENT_ERROR
- 100 - SERVER_THREADPOOL_EXHAUSTED_ERROR
Request ID (64 bits)

HTTP 协议规范

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

注意

从 Dubbo 3.3 版本开始，Rest 协议已移至 Extensions 库，由 Triple 协议来对 Rest 提供更全面的支持，具体参见 Triple Rest用户手册，如需继续使用原 Rest 协议，可引入对应 dubbo-spi-extensions 库依赖

什么是 Dubbo Http

基于 spring web 和 resteasy 注解编码风格，通过http协议进行服务间调用互通，dubbo protocol扩展实现的协议

为什么选择Dubbo Http

dubbo http 可以实现微服务与dubbo之间的互通
多协议发布服务，可以实现服务协议的平滑迁移
http的通用性，解决跨语言互通
最新版本的http 无需添加其他组件，更轻量
resteasy以及spring web的编码风格，上手更快

协议规范

Request

相对于原生的http协议dubbo http 请求增加version和group两个header用于确定服务的唯一, 如果provider一端没有声明group和version,http请求时就不需要传递这连个header,反之必须要传递目标服务的group和version, 如果使用dubbo http的RestClient这两个header将会默认通过attachment传递为区别于其他的header，attachment将会增加rest-service-前缀，因此通过其他形式的http client调用 dubbo http服务需要传递 rest-service-version 和 rest-service-group 两个header

POST /test/path HTTP/1.1
Host: localhost:8080
Content-type: application/json
Accept: text/html
rest-service-version: 1.0.0
rest-service-group: dubbo

{"name":"dubbo","age":10,"address":"hangzhou"}

Response

HTTP/1.1 200
Content-Type: text/html
Content-Length: 4
Date: Fri, 28 Apr 2023 14:16:42 GMT

"success"

content-type支持
- application/json
- application/x-www-form-urlencoded
- text/plain
- text/xml

目前支持以上media，后面还会对type进行扩展