grpcui 调试 gRPC 时怎么为请求添加 metadata 头

在 grpcui 里给 gRPC 请求添加 metadata，核心就是在选定服务和方法后，打开请求表单中的 Request Metadata，新增一行 Name 和 Value，然后再点击 Invoke。例如调试请求链路时，可以填写 x-request-id 与 debug-20261105。这组值只用于本次交互式调用，不需要改 proto 文件。

官方地址：https://github.com/fullstorydev/grpcui

先把 metadata 当作“请求表单之外的键值对”填写，再分别查看 Response Headers、Response Data 和 Response Trailers。响应页用于判断调用结果，不代表服务一定会把请求头原样回显。

一、先启动 grpcui 并打开目标服务

grpcui 需要知道目标服务的 gRPC 地址，并依靠 server reflection、proto 源文件或 protoset 文件获得服务描述。首次调试本地明文服务时，可以先用下面的最小命令：

# 本地服务使用明文 HTTP/2；生产 TLS 服务不要照搬这个连接参数
grpcui -plaintext 127.0.0.1:50051

命令启动后会给出一个本地 Web UI 地址。打开后按 Service → Method 的顺序选择目标接口；如果列表为空，先确认服务启用了 reflection，或改用 -proto / -protoset 提供描述文件。能看到请求表单，才说明调试入口已经准备好。

二、在 Request Metadata 里添加请求头

进入路径是 Request Form → Request Metadata。在表格中新增一行，左侧 Name 填键，右侧 Value 填值。调试链路时可以先使用不包含敏感信息的示例：

1. 在 Service 和 Method 下拉框选好接口。
2. 在 Request Metadata 区域点击添加行的控件。
3. 在 Name 输入 x-request-id，在 Value 输入 debug-20261105。
4. 按接口要求填写 Request Data，最后点击底部 Invoke。

这一步只改变当前 Web 表单中的调用参数。若服务需要授权头，值应来自安全的临时调试凭据，文章中的示例值不能替代真实凭据；不要把生产 token 写进共享截图、命令历史或文章。

三、固定默认头和单次请求头要分清

如果每次打开表单都想预填一个可编辑的 metadata，可以在启动 grpcui 时使用 -default-header。它只是 UI 默认值，读者仍可在表单中修改或移除：

# 只把调试环境标记预填到 Web 表单，用户仍可修改它
grpcui -default-header 'x-debug-env: staging' 127.0.0.1:50051

如果头不希望出现在 Web 表单里，才考虑命令行固定头。官方命令入口把它们分成不同范围：

• -H：加入包括 reflection 在内的请求，且不会显示在 Web 表单中；
• -rpc-header：只在真正调用选定 RPC 时发送，不用于 reflection，也不会显示在表单中；
• -default-header：只提供可编辑的表单默认值，不等于强制覆盖。

# 固定加入所有请求；示例值仅用于本地调试
grpcui -H 'x-client: grpcui-debug' 127.0.0.1:50051

# 只给实际 RPC 调用加头，不给 reflection 请求加头
grpcui -rpc-header 'x-request-scope: one-rpc' 127.0.0.1:50051

命令行固定头与用户在表单中填写的同名 metadata 冲突时，固定头优先。需要临时改值时，优先回到 Request Metadata 表格，避免误以为修改已经覆盖了命令行配置。

四、点击 Invoke 后如何确认请求结果

调用路径是 Request Form → Invoke → Response。在结果页依次看三个区域：

1. Response Headers：查看服务返回的响应头 metadata。
2. Response Data：查看响应消息，或查看 gRPC 状态码和错误文本。
3. Response Trailers：查看调用结束时返回的尾部 metadata。

如果页面显示调用完成且状态为 OK，说明这次 RPC 得到了成功状态；但 x-request-id 是否真正被服务接收，仍应结合服务端日志、链路追踪或服务实际行为判断。请求 metadata 和响应 metadata 是两个方向，服务没有回显逻辑时，在 Response Headers 中找不到请求头并不等于请求没有发送。

五、metadata 不生效时按这四处排查

• 方法选错：先确认 Service 和 Method 没有停留在另一个 RPC，尤其是同一服务有多个相似方法时。
• 空行或未保存值：检查 Name、Value 是否都填在同一行，调用前是否还能在 Request Metadata 区域看到它。
• 被命令行固定头覆盖：如果启动参数带了 -H 或 -rpc-header，同名的表单值不会按你预期替换固定值。
• 连接方式不匹配：本地明文服务使用 -plaintext，TLS 服务则按证书、域名和客户端证书要求配置；连接层失败时，先解决连接再判断 metadata。

常见问题

Request Metadata 和 Request Data 是一回事吗？

不是。Request Data 是 protobuf 请求消息本身，Request Metadata 是随 RPC 发送的键值对，常用于请求标识、租户信息或调试上下文。

为什么 Response Headers 里没有我填的请求头？

因为响应头是服务返回的另一组 metadata，服务可以选择不回显请求头。要确认请求是否被业务接收，应看服务端日志、追踪信息或接口行为，而不是要求响应页必须出现同名字段。

最短操作路径可以记成：选择 Service 和 Method，在 Request Metadata 填 Name/Value，点击 Invoke，再分别查看三个 Response 区域。临时值放表单，默认值用 -default-header，固定且不展示的头再使用 -H 或 -rpc-header。