Yaak 插件实战:将 gRPC 请求一键转换为 gRPCurl 命令(Copy as gRPCurl)

原创2026-09-30 09:27:402,558 阅读
文章标签:开发工具接口测试API设计桌面应用CLI插件系统前端认证鉴权GraphQLWebSocket

Yaak 插件实战:将 gRPC 请求一键转换为 gRPCurl 命令(Copy as gRPCurl)

本文基于 Yaak 仓库中的官方插件 action-copy-grpcurl,完整讲解它如何把 Yaak 中配置好的 gRPC 请求(服务、方法、服务器地址、消息体、元数据、鉴权、proto 文件)自动生成一条可直接在终端执行的 grpcurl 命令,并深入源码与测试用例,说明其命令拼装、参数转义与 proto 导入路径推断的底层实现。读完本文,你既能掌握该插件的安装与日常用法,也能理解其完整生成规则,甚至可以以此为模板编写自己的"复制为命令行"类请求动作插件。

Copy as gRPCurl 插件的右键菜单截图

插件概览:一个动作,让 gRPC 调试走出图形界面

action-copy-grpcurl 是 Yaak 内置的开源插件(源码位于 plugins/action-copy-grpcurl),它的作用非常聚焦:为 gRPC 请求增加一个名为 "Copy as gRPCurl" 的右键动作,把当前 gRPC 请求转换成等价的可执行 grpcurl 命令并复制到剪贴板。

这个能力的典型应用场景包括:

  • 终端排障:在只有命令行环境(如服务器、CI 流水线)的场合复现并执行 gRPC 调用;
  • 团队共享:把一条完整的请求(含鉴权头、消息体)以一条命令的形式粘贴给同事,无需对方打开 Yaak;
  • 脚本化:将生成的命令直接嵌入 Shell 脚本,用于自动化测试或监控 gRPC 服务健康状态。

生成命令所覆盖的信息维度与 Yaak 中 gRPC 请求模型一一对应,包括:

  • gRPC 服务名(service)与方法名(method);
  • 服务器地址与端口(url);
  • 请求消息数据(message,JSON 格式);
  • 元数据 / 请求头(metadata);
  • 认证凭据(authentication:basic / bearer / apikey);
  • Protocol Buffer 定义文件(proto 文件及其 import 路径)。

使用方式:三步拿到可执行的 grpcurl 命令

按照插件 README 中的操作流程,完整步骤为:

  1. 在 Yaak 中照常配置好一个 gRPC 请求(选择 .proto 文件、填写服务与方法、服务器地址、消息体、元数据与鉴权信息);
  2. 在左侧侧边栏的请求条目上右键单击;
  3. 在弹出的动作菜单中选择 "Copy as gRPCurl";
  4. 命令会被自动复制到系统剪贴板;
  5. 将命令粘贴到任意终端中分享或直接执行。

从源码看,第 2~4 步的链路非常清晰:插件通过 grpcRequestActions 注册动作,选中后调用 src/index.ts 中的 onSelect 回调——先用 ctx.grpcRequest.render() 以 purpose: "send" 渲染请求(模板变量如 ${[faker ...]} 在此阶段求值),接着调用核心函数 convert() 生成命令文本,随后 ctx.clipboard.copyText() 写入剪贴板,最后 ctx.toast.show() 弹出 "Command copied to clipboard" 的绿色成功提示。

async onSelect(ctx, args) {
  const rendered_request = await ctx.grpcRequest.render({
    grpcRequest: args.grpcRequest,
    purpose: "send",
  });
  const data = await convert(rendered_request, args.protoFiles);
  await ctx.clipboard.copyText(data);
  await ctx.toast.show({ message: "Command copied to clipboard", icon: "copy", color: "success" });
}

生成的 gRPCurl 命令示例

插件 README 给出了四类典型场景的产出结果,下面完整保留并逐一说明。

简单一元调用(Unary Call)

grpcurl -plaintext \
  -d '{"name": "John Doe"}' \
  localhost:9090 \
  user.UserService/GetUser

要点:-plaintext 对应明文(非 TLS)连接;-d 携带 JSON 格式的消息体;末尾以 服务名/方法名 的完整路径结尾。

带元数据(Metadata / 请求头)的调用

grpcurl -plaintext \
  -H "authorization: Bearer my-token" \
  -H "x-api-version: v1" \
  -d '{"user_id": "12345"}' \
  api.example.com:443 \
  user.UserService/GetUserProfile

要点:每个启用的元数据项都会被转换为一条 -H "name: value" 参数,可用于传递 token、版本号、追踪 ID 等。

启用 TLS 的调用

grpcurl \
  -d '{"query": "search term"}' \
  secure-api.example.com:443 \
  search.SearchService/Search

要点:当服务器地址使用 https:// 协议时,命令不加 -plaintext,grpcurl 默认即走 TLS。

通过 Proto 文件调用的场景

grpcurl -import-path /path/to/protos \
  -proto /other/path/to/user.proto \
  -d '{"email": "user@example.com"}' \
  localhost:9090 \
  user.UserService/CreateUser

要点:-import-path 指定 proto 的导入搜索目录,-proto 指定具体的 .proto 文件,用于在服务端未开启反射(reflection)时直接基于本地 proto 定义发起调用。

源码级解析:命令究竟是如何拼装出来的

convert() 函数(src/index.ts)是整条命令生成的唯一核心。它维护一个字符串数组 xs,从 ["grpcurl"] 开始按固定顺序追加参数,最终 join(" ") 成完整命令,其中行与行之间用换行符常量 NEWLINE = "\\\n "(即反斜杠 + 换行 + 两空格)连接,保证输出跨行时可读、可复制粘贴执行。

命令的追加顺序与规则如下:

生成顺序 内容 触发条件与规则
1 -plaintext request.url 以 http:// 开头时添加,表示明文连接;https:// 则不加
2 -import-path '<目录>' 先输出用户在 Yaak 中配置的非 .proto 后缀路径(视为导入目录),再输出为每个 proto 文件推断出的导入目录
3 -proto '<文件>' 为每个以 .proto 结尾的文件生成一条 -proto 参数
4 -H 'name: value' 遍历 request.metadata,只保留启用的条目(enabled !== false 且 name 非空)
5 鉴权头 根据 authenticationType 生成,详见下文
6 -d '<消息体>' 当 request.message 非空时生成
7 服务器地址 去除 request.url 的 http:// / https:// 协议前缀后原样输出
8 服务名/方法名 当 request.service 与 request.method 均存在时,以 service/method 形式输出
9 清理 若数组末尾恰好是 NEWLINE,则移除,避免命令尾部残留孤立的反斜杠

三种鉴权方式的转换规则

源码 src/index.ts 对 request.authenticationType 做了三种分支处理(前提是 authentication?.disabled !== true):

  • basic(基本认证):取 username 与 password,拼成 user:pass 后进行 Base64 编码,生成 -H 'Authorization: Basic <base64>';
  • bearer(Bearer 令牌):直接生成 -H 'Authorization: Bearer <token>';
  • apikey(API Key):分两种位置——
    • location === "query" 时,把 key/value 以 URL 查询参数的形式追加到服务器地址上(URL 已有 ? 时用 & 分隔,否则用 ?,并对 key 与 value 做 encodeURIComponent);
    • 其他情况生成请求头 -H '<key 或默认 X-Api-Key>: <value>'。

需要说明的是,render() 阶段已按 purpose: "send" 完成模板渲染,因此消息体中的模板标签(如 ${[faker "timestamp"]})以及 url 中的变量会先被求值,再进入 convert();若模板因故未能解析,测试用例("Sends data with unresolved template tags")证实命令中会原样保留未解析的 ${...} 文本。

POSIX 单引号转义:防止一条引号破坏整条命令

由于 grpcurl 命令通常在 Shell 中执行,插件对每个参数都统一用单引号包裹(quote())。而 POSIX 单引号内部不接受任何转义,消息体或元数据里若含有撇号 ',直接输出会提前结束字符串、导致命令残缺。因此 quote() 采用经典手法:用 '\'' 序列跳出引号、输出转义后的引号、再回到引号上下文。源码注释与测试 "Quotes an apostrophe so the command still parses" 均对该行为做了明确说明与验证,例如 don't stop 会被转义为 don'\''t stop,确保命令粘贴到 bash 后依然能正确解析。

Proto 导入路径的推断逻辑

grpcurl 调用能否成功,很大程度上取决于 -import-path 是否指向正确的 proto 搜索目录。插件对此做了两层处理(src/index.ts):

  1. 用户显式配置的目录:allProtoFiles 中所有不以 .proto 结尾的路径,原样作为 -import-path 输出;
  2. 为每个 .proto 文件推断目录:调用 findParentProtoDir()(src/index.ts)从文件所在路径开始逐级向上查找,命中名为 proto 的目录即返回;若一直找不到 proto 目录,则退而求其次,把该文件的父目录与祖父目录同时加入 -import-path(用 path.posix.join(f, "..") 与 join(f, "..", "..") 计算)。

测试用例完整覆盖了这些分支(tests/index.test.ts):

  • 单个 proto 文件 /foo/bar/baz.proto → 推断出 /foo/bar、/foo 两个 import 路径;
  • 多个 proto 文件同目录 → import 路径去重合并,-proto 逐条列出;
  • 多个 proto 文件不同目录 → 各自的父目录与祖父目录都进入 import 列表;
  • 纯目录列表 → 仅生成 -import-path;
  • 目录与文件混用 → 用户目录优先,再叠加推断路径(含根目录 / 的极端情况)。

插件如何被 Yaak 识别:grpcRequestActions 扩展点

从插件运行时类型的定义可以确认,"Copy as gRPCurl" 是 Yaak 官方暴露的 gRPC 请求动作(Grpc Request Action) 扩展点的实现:

  • PluginDefinition 中声明了 grpcRequestActions?: GrpcRequestActionPlugin[] 字段;
  • GrpcRequestActionPlugin 由 { label, icon } 与 onSelect(ctx, args) 回调组成,其中 icon: "copy" 在生成事件类型中属于合法图标之一;
  • 动作被触发时,宿主传给回调的 args 类型为 CallGrpcRequestActionArgs = { grpcRequest: GrpcRequest; protoFiles: Array<string> }(见 gen_events.ts),这正是 convert() 需要的两份输入:渲染后的请求对象与 proto 文件列表;
  • 插件可用的上下文能力(Context)非常丰富,包括 clipboard.copyText、toast.show、grpcRequest.render、store、templates.render 等(见 Context.ts),本插件只使用了其中三个。

从数据模型看,gRPC 请求在 Rust 端的定义位于 models.rs,包含 url(注释明确"Server URL (http for plaintext or https for secure)")、service、method、message、metadata、authentication_type 与 authentication(Record<string, any>)等字段,与 convert() 的读取字段一一对应;plugin-runtime-types 中生成的 gen_models.ts 为其前端镜像。

构建、测试与运行方式

插件是标准的 Yaak 插件工程,其 package.json(package.json)定义了三个脚本:

npm run build   # yaakcli build —— 构建插件产物
npm run dev     # yaakcli dev   —— 开发模式,改动即时生效
npm test        # vp test --run tests —— 运行测试

其中 yaakcli 是 Yaak 提供的插件 CLI 工具,vp test 是 Vite 生态的测试运行器。测试套件位于 tests/index.test.ts,共覆盖十余个场景:简单请求、元数据过滤(禁用的条目会被忽略)、basic / apikey(header 与 query 两种位置)、单/多 proto 文件、目录列表、混合输入、消息体传输、未解析模板标签以及单引号转义,可作为理解命令生成行为的"可执行文档"。运行 npm test 即可在本地验证全部行为。

小结

action-copy-grpcurl 用约 150 行 TypeScript 实现了"图形界面请求 → 终端命令"的完整闭环:以 grpcRequestActions 扩展点接入 Yaak,经 render → convert → clipboard → toast 四步完成一次复制动作,并对协议前缀、鉴权类型、proto 导入目录与 Shell 引号转义做了细致处理。无论你是想直接用它在终端里调试 gRPC 服务,还是想参考它的结构为 HTTP、WebSocket 请求编写类似的"复制为命令行"插件,本文给出的源码路径与测试用例都足以作为起点。

进一步阅读:

登录后查看全文
yaak