gRPC UI

grpcui 是一个命令行工具，可让你通过浏览器与 gRPC 服务器交互。它有点像 Postman，但是针对 gRPC API 而不是 REST。

在某些方面，这就像是 grpcurl 的扩展。grpcurl 是一个命令行界面，而 grpcui 提供了一个基于 Web/浏览器的 GUI。这使你可以交互式地构建请求以发送到 gRPC 服务器。

使用此工具，你还可以浏览 gRPC 服务的架构，它以可用端点列表的形式呈现。这可以通过查询支持服务器反射的服务器、读取 proto 源文件或加载编译后的 "protoset" 文件（包含编码文件描述符 protos的文件）来实现。事实上，该工具将 JSON 请求数据转换为二进制编码的 protobuf 的方式正是使用了相同的架构。因此，如果你交互的服务器不支持反射，你要么需要定义服务的 proto 源文件，要么需要 grpcui 可以使用的 protoset 文件。

这个仓库还提供了两个库包：

1. github.com/fullstorydev/grpcui：这个包包含了将 gRPC Web 表单嵌入任何 Go HTTP 服务器的构建块。它有访问 HTML 表单、驱动它的 JavaScript 代码以及用于样式化表单的示例 CSS 文件的函数。
2. github.com/fullstorydev/grpcui/standalone：这个包更进一步，提供了一个单一的、简单的 HTTP 处理程序，提供完整的 gRPC Web UI。你可以将这个处理程序连接到你的 HTTP 服务器中，嵌入一个看起来与使用 grpcui 命令行程序时完全相同的 gRPC 网页。这个单一的处理程序使用了上述包，但也提供了封装的 HTML 页面、一些其他脚本依赖项（jQuery 和 jQuery-UI）以及额外的 CSS 和图像资源。

特性

grpcui 支持所有类型的 RPC 方法，包括流式方法。但是，它要求你一次性构造整个请求消息流，然后一次性呈现整个结果响应消息流（因此你无法像 grpcurl 那样与双向流交互）。

grpcui 支持明文和 TLS 服务器，并有多种 TLS 配置选项。它还支持相互 TLS，其中客户端需要提供客户端证书。

如前所述，如果服务器支持反射服务，grpcui 可以无缝工作。如果不支持，你可以向 grpcui 提供 .proto 源文件或 protoset 文件（包含由 protoc 生成的编译描述符）。

Web UI 允许你设置请求元数据，除了定义请求消息数据。在定义请求消息数据时，它使用动态 HTML 表单，支持所有可能类型的 protobuf 消息的数据输入，包括对常见类型（如 google.protobuf.Timestamp）、一元和映射的丰富支持。

除了通过 HTML 表单输入数据外，你还可以以 JSON 格式输入数据，通过在文本表单中键入或粘贴整个 JSON 请求体。

发出 RPC 后，Web UI 显示所有 gRPC 响应元数据，包括服务器发送的头部和尾部。当然，它还以 HTML 表格的形式显示人类可理解的响应正文。

安装

Homebrew（MacOS 或 Linux）

使用 homebrew 安装：

brew install grpcui

从源代码

你可以使用 go 工具安装 grpcui：

go install github.com/fullstorydev/grpcui/cmd/grpcui@latest

这会将命令安装到 $GOPATH 环境变量指向的 bin 子文件夹中。如果这个目录已经在你的 $PATH 中，那么你应该就可以开始使用了。

如果你已经将此仓库拉取到不在 $GOPATH 中的位置，并想从源代码构建，你可以 cd 进入仓库，然后运行 make install。

如果遇到编译错误，可能是 grpcui 的依赖项版本过时。你可以通过运行 make updatedeps 来更新依赖项。

无需安装运行

go run ./cmd/grpcui/grpcui.go -plaintext localhost:9019

使用方法

工具的使用文档解释了众多选项：

grpcui -help

大多数标志控制程序如何连接到将发送请求的 gRPC 服务器。然而，有一个标志控制 grpcui 本身：-port 标志控制 HTTP 服务器应使用什么端口来公开 Web UI。如果未指定端口，将使用临时端口（因此每次运行时可能使用不同的端口，由操作系统分配）。

Web 表单

当你运行 grpcui 时，它会显示一个 URL，你可以将其放入浏览器以访问 Web UI。

$ grpcui -plaintext localhost:12345
gRPC Web UI 可在 http://127.0.0.1:60551/ 访问...

当你导航到这个 URL 时，你会看到用户界面：

<p align="center"> <img alt="Web UI 截图" width="888" src="https://yellow-cdn.veclightyear.com/835a84d5/80a938ab-69a7-4097-ad2b-dd41385bd6e5.png"> </p>

顶部的两个列表框允许你选择要发出的 RPC 的服务和方法。选择后，下面的面板将显示一个表单，允许你定义 RPC 请求。该表单是根据所选 RPC 的实际请求消息结构动态构建的。

你会注意到第二个标签页，它允许你查看（和编辑）请求数据的原始 JSON 值。这对于复制粘贴大型请求消息很有用，无需一次一个地点击定义每个字段值。

第三个标签页显示响应数据。在你实际点击页面底部的"调用"按钮之前，这个标签页是灰色的并且被禁用。

请求表单

关于表单，首先要注意的是它通常是一个表格，每行代表一个字段。表格有三个重要列：

1. 第一列显示字段的名称和类型。
2. 第二列表示字段的"基数"。典型字段是可选的。可选字段的第二列是一个复选框，表示字段是否存在。如果字段不存在，则假定其默认值。重复字段在此列中显示用于添加和删除值的按钮。绿色"+"允许你向重复字段添加值。值旁边的红色"x"将删除该值。最后，如果字段是必需的（仅在语法"proto2"中支持），该列将只包含一个星号。
3. 第三列显示字段的值。如果字段不存在，这将显示字段的默认值。嵌套消息的字段显示"未设置"，但标量类型显示其默认值（通常是类型的零值，但在使用语法"proto2"时可以配置默认值）。不存在的字段也是不可编辑的 -- 你必须先勾选第二列中的复选框以使字段存在，然后才能编辑其值。重复字段显示一个占据第二和第三列的嵌套表格，允许添加和删除值。

类型为嵌套消息的字段在第三列中包含一个嵌套表格。这个嵌套表格有自己的三列，每个字段一行。

一元字段的呈现方式略有不同。它们不是有两列表示字段的存在和值，而是包含一个嵌套表格，显示一元中所有可能的字段。但是，中间列是一个单选按钮而不是复选框，因此一次只能存在一个字段。除了一元中每个字段的行外，还有一个名为无的选项，表示未设置值的一元。

这里有一个消息的示例表单，它有两个必需字段（id 和 name）、一个重复字段（labels）、一些普通的可选字段，以及一个有四个选项的一元字段。在第一张图中，没有值存在（当然，除了顶部的必需字段）。在第二张图中，存在几个字段值。

<p align="center"> <img alt="网页界面消息字段" width="408" align="top" src="https://yellow-cdn.veclightyear.com/835a84d5/a983c238-4935-4f78-b8c3-091a4e81be4e.png"> <img alt="网页界面消息字段，包含一些值" width="420" align="top" src="https://yellow-cdn.veclightyear.com/835a84d5/5429111f-68e4-45f4-9b17-15a7bd205b34.png"> </p>

对于接受请求流的RPC，网页表单允许用户在流中定义多个消息。默认情况下是单个请求，但用户可以删除它以不发送任何请求，也可以发送多个请求。流类似于重复字段，但重复的"内容"是整个请求：

<p align="center"> <img alt="网页界面请求流" width="380" src="https://yellow-cdn.veclightyear.com/835a84d5/fab946fa-cd3e-4685-bbb4-dc1a2d06e278.png"> </p>

最后一个示例还展示了对知名消息类型的特殊处理。在该示例中，请求类型是google.protobuf.StringValue。界面并没有显示一个包含名为value且类型为string的单个字段的消息表单，而是简化了显示，省略了"装箱"过程。它只显示了一个简单的文本框用于输入字符串值。

一个更有趣的知名消息类型处理示例是google.protobuf.Timestamp，它会显示一个日期选择器：

<p align="center"> <img alt="网页界面请求流" width="640" src="https://yellow-cdn.veclightyear.com/835a84d5/9aa045f4-df1a-401c-8bcb-cdd5a4cf62de.png"> </p>

原始请求JSON

第二个标签页允许你查看在第一个标签页中定义的请求数据的JSON表示。你还可以直接编辑JSON数据 —— 包括粘贴整个JSON消息。

JSON表示使用标准的Protocol Buffers的JSON映射。

<p align="center"> <img alt="网页界面请求JSON" width="600" src="https://yellow-cdn.veclightyear.com/835a84d5/1c42ad1c-5a27-4194-aa7a-7a8ff0bddea6.png"> </p>

当处理具有流式请求的RPC时，JSON数据将是一个JSON数组，其中每个元素都是流中的单个消息。

响应

当点击"调用"按钮时，请求数据会发送到服务器，并调用所选的RPC方法。然后，网页表单将导航到第三个标签页以显示服务器的响应。

响应标签页有三个部分：

1. 响应头：显示任何响应头元数据。
2. 响应数据：显示任何响应消息和错误消息。具有流式响应的RPC方法可能同时显示消息数据和错误。错误消息显示gRPC状态码和服务器定义的消息文本。
3. 响应尾部：最后，显示任何响应尾部元数据。

<p align="center"> <img alt="网页界面响应" width="500" src="https://yellow-cdn.veclightyear.com/835a84d5/441829d9-d64e-4239-a4d0-e7c66816ba52.png"> </p>

这三个部分中的每一个都是一个数据表。响应消息是最有趣的，其结构与"请求表单"标签页中的消息结构非常相似。具有嵌套消息的字段将包含一个嵌套表格。

描述符来源

grpcui工具可以使用各种描述符来源。这些描述符是必需的，以便grpcui能够理解RPC架构，将输入转换为protobuf二进制格式，并将响应从二进制格式转换为文本。以下部分记录了支持的来源以及使用它们所需的命令行标志。

服务器反射

如果没有其他命令行标志，grpcui将尝试使用服务器反射。

有关如何设置服务器反射的示例可以在这里找到。

Proto源文件

对于不支持反射的服务器，你可以使用.proto源文件来使用grpcui。

除了使用-proto标志指向相关的proto源文件外，你可能还需要提供-import-path标志来告诉grpcui可以从哪些文件夹导入依赖项。

就像使用protoc编译时一样，你不需要为protoc附带的标准protos的位置提供导入路径（这些文件包含各种包定义为google.protobuf的"知名类型"）。这些文件被grpcui"已知"，因为它们的描述符快照已内置在grpcui二进制文件中。

Protoset文件

你还可以使用编译后的protoset文件与grpcui一起使用。Protoset文件包含二进制编码的google.protobuf.FileDescriptorSet原型。要创建protoset文件，请使用定义服务的*.proto文件调用protoc：

protoc --proto_path=. \
    --descriptor_set_out=myservice.protoset \
    --include_imports \
    my/custom/server/service.proto

--descriptor_set_out参数告诉protoc生成protoset，而--include_imports参数对于protoset包含grpcui处理和理解架构所需的所有内容是必要的。