将 HTTP 转码为 gRPC

gRPC 是一种远程过程调用框架，使用 HTTP/2 进行传输，并使用 Protocol Buffers 定义服务和消息类型。

grpc-transcode 插件允许 HTTP 客户端通过 APISIX 调用 gRPC 服务。APISIX 将 HTTP 请求编码为 gRPC 消息，发送到配置的方法，并将响应解码为 JSON。

前置条件

• 安装 Docker。
• 安装 cURL，用于向 APISIX 发送请求进行验证。
• 安装 jq，用于将 .proto 定义嵌入 Admin API 请求。
• 安装 gRPCurl，用于直接调用示例 gRPC 服务。
• 按照快速入门教程在 Docker 中启动 APISIX。以下命令使用该教程创建的 apisix-quickstart-net 网络。
• 如果启用了 Admin API 身份认证，请将管理员角色的密钥导出为 ADMIN_API_KEY。Docker 快速入门为了便于本地评估而禁用了身份认证；生产环境中请保持启用。

部署示例 gRPC 服务器

在 APISIX 快速入门网络中启动示例 gRPC 服务器。镜像摘要固定了标签 1.0.2 中经验证的内容：

docker rm -f quickstart-grpc-example 2>/dev/null || true

docker run -d --rm \
  --name quickstart-grpc-example \
  --network apisix-quickstart-net \
  -p 50051:50051 \
  api7/grpc-server-example:1.0.2@sha256:9d822f5957724d2b9f668e81d5cd221e030a7155ac5558b56f1a07cb9e8cbbce

服务器公开 echo.EchoService。其 Echo 方法接收 EchoMsg 消息，并返回相同的消息类型。

使用 gRPCurl 直接调用该方法：

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

服务器应返回该消息：

{
  "msg": "Hello"
}

创建 Proto 对象

将服务定义保存为 echo.proto：

echo.proto

cat > echo.proto <<'EOF'
syntax = "proto3";

package echo;

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

message EchoMsg {
  string msg = 1;
}
EOF

创建 ID 为 quickstart-proto 的 proto 对象：

jq -n --rawfile content echo.proto \
  '{id: "quickstart-proto", content: $content}' \
  | curl -i "http://127.0.0.1:9180/apisix/admin/protos" -X PUT \
    -H "X-API-KEY: ${ADMIN_API_KEY}" \
    -H "Content-Type: application/json" \
    --data-binary @-

HTTP/1.1 201 Created 响应表明 APISIX 已存储该 proto 对象。

配置 grpc-transcode

创建路由，将 GET /echo 映射到 echo.EchoService/Echo：

curl -i "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "id": "quickstart-grpc",
  "methods": ["GET"],
  "uri": "/echo",
  "plugins": {
    "grpc-transcode": {
      "proto_id": "quickstart-proto",
      "service": "echo.EchoService",
      "method": "Echo"
    }
  },
  "upstream": {
    "scheme": "grpc",
    "type": "roundrobin",
    "nodes": {
      "quickstart-grpc-example:50051": 1
    }
  }
}
EOF

❶ 从 quickstart-proto proto 对象加载服务定义。

❷ 选择完全限定的 gRPC 服务名称。

❸ 选择要在该服务上调用的方法。

HTTP/1.1 201 Created 响应表明 APISIX 已创建该路由。

验证 HTTP 到 gRPC 的转码

将 EchoMsg.msg 字段作为查询参数发送 HTTP 请求：

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

APISIX 应返回 HTTP 200 和已解码的 gRPC 响应：

{
  "msg": "Hello"
}

下一步

grpc-transcode 插件支持其他请求和响应选项。有关配置详情和示例，请参阅 grpc-transcode Plugin Hub 参考文档。

对于浏览器客户端，APISIX 支持 gRPC-Web，它对原生 gRPC 协议进行了适配。请使用 grpc-web 插件进行配置。