跳到主要内容

将 HTTP 转换为 gRPC

gRPC 是一个基于 HTTP/2 协议的开源高性能远程过程调用 (RPC) 框架。它使用 protocol buffers (protobuf) 作为接口描述语言 (IDL)。

本指南将向你展示如何使用 grpc-transcode 插件与 proto 对象 在 RESTful HTTP 请求和 gRPC 请求以及它们相应的响应之间进行转换。


REST 到 gRPC 图解

备注

Ingress Controller 目前不支持 proto 资源。

前置条件​

  • 安装 Docker。
  • 安装 cURL 以向 APISIX 发送请求进行验证。
  • 安装 gRPCurl 以向 gRPC 服务发送请求进行验证。
  • 按照 快速入门教程 在 Docker 中启动一个新的 APISIX 实例。

部署示例 gRPC 服务器​

启动一个 示例 gRPC 服务器 Docker 实例 quickstart-grpc-example，端口为 50051：

docker run -d \
  --name quickstart-grpc-example \
  --network=apisix-quickstart-net \
  -p 50051:50051 \
  api7/grpc-server-example:1.0.2

此示例 gRPC 服务器拥有多个服务，例如 echo.EchoService：

echo.proto
syntax = "proto3";

package echo;

service EchoService {
  rpc Echo (EchoMsg) returns (EchoMsg);
}

message EchoMsg {
  string msg = 1;
}

在此示例中，Echo 是 EchoService 中的一个方法，它接受 EchoMsg 类型的参数。

使用 gRPCurl 测试 gRPC 方法 echo.EchoService.Echo：

grpcurl -plaintext -d '{"msg": "Hello"}' "127.0.0.1:50051" "echo.EchoService/Echo"

类似以下的响应验证了 gRPC 服务正在运行：

{
  "msg": "Hello"
}

创建 Proto 对象以存储 Protobuf 文件​

将 protobuf 文件 echo.proto 作为 proto 对象存储在 APISIX 中，ID 为 quickstart-proto：

curl -i "http://127.0.0.1:9180/apisix/admin/protos" -X PUT -d '
{
  "id": "quickstart-proto",
  "content": "syntax = \"proto3\";

  package echo;

  service EchoService {
    rpc Echo (EchoMsg) returns (EchoMsg);
  }

  message EchoMsg {
    string msg = 1;
  }"
}'

HTTP/1.1 201 Created 响应验证了 proto 对象已成功创建。

启用 grpc-transcode 插件​

创建 ID 为 quickstart-grpc 的路由并启用插件 grpc-transcode：

curl -i "http://127.0.0.1:9180/apisix/admin/routes" -X PUT -d '
{
  "id": "quickstart-grpc",
  "methods": ["GET"],
  "uri": "/echo",
  "plugins": {
    "grpc-transcode": {
// Annotate 1
      "proto_id": "quickstart-proto",
// Annotate 2
      "service": "echo.EchoService",
// Annotate 3
      "method": "Echo"
    }
  },
  "upstream": {
    "scheme": "grpc",
    "type": "roundrobin",
    "nodes": {
      "quickstart-grpc-example:50051": 1
    }
  }
}'

❶ proto_id：定义 gRPC 服务的 proto 对象

❷ service：使用的 gRPC 服务 echo.EchoService

❸ method：使用的 gRPC 方法 Echo

HTTP/1.1 201 Created 响应验证了路由已创建并且插件 grpc-transcode 已成功启用。

APISIX 现在将 /echo 路由接收到的 RESTful HTTP 请求转换为 gRPC 请求，并将其转发到上游 gRPC 服务器 quickstart-grpc-example 以调用 echo.EchoService/Echo 方法。一旦 gRPC 服务器响应，APISIX 将 gRPC 响应转换回客户端的 RESTful HTTP 响应。

以 RESTful 方式测试 gRPC 服务​

向 /echo 发送 HTTP 请求，并带有 EchoMsg 中定义的参数：

curl -i "http://127.0.0.1:9080/echo?msg=Hello"

类似以下的有效响应验证了插件 grpc-transcode 正在工作：

{"msg":"Hello"}

下一步​

查看 grpc-transcode 插件文档 以获取更多配置选项和示例。

除了将 HTTP 请求转码为 gRPC 请求外，APISIX 还支持 gRPC-Web（本机 gRPC 协议 的变体），使用 APISIX 插件 grpc-web。