Yaak 插件实战:将 gRPC 请求一键转换为 gRPCurl 命令(Copy as gRPCurl)
Yaak 插件实战:将 gRPC 请求一键转换为 gRPCurl 命令(Copy as gRPCurl)
本文基于 Yaak 仓库中的官方插件 action-copy-grpcurl,完整讲解它如何把 Yaak 中配置好的 gRPC 请求(服务、方法、服务器地址、消息体、元数据、鉴权、proto 文件)自动生成一条可直接在终端执行的 grpcurl 命令,并深入源码与测试用例,说明其命令拼装、参数转义与 proto 导入路径推断的底层实现。读完本文,你既能掌握该插件的安装与日常用法,也能理解其完整生成规则,甚至可以以此为模板编写自己的"复制为命令行"类请求动作插件。
插件概览:一个动作,让 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 中的操作流程,完整步骤为:
- 在 Yaak 中照常配置好一个 gRPC 请求(选择 .proto 文件、填写服务与方法、服务器地址、消息体、元数据与鉴权信息);
- 在左侧侧边栏的请求条目上右键单击;
- 在弹出的动作菜单中选择 "Copy as gRPCurl";
- 命令会被自动复制到系统剪贴板;
- 将命令粘贴到任意终端中分享或直接执行。
从源码看,第 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):
- 用户显式配置的目录:
allProtoFiles中所有不以.proto结尾的路径,原样作为-import-path输出; - 为每个 .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 请求编写类似的"复制为命令行"插件,本文给出的源码路径与测试用例都足以作为起点。
进一步阅读:
- 插件 README:plugins/action-copy-grpcurl/README.md
- 核心实现:src/index.ts
- 测试用例:tests/index.test.ts
- 扩展点类型定义:GrpcRequestActionPlugin.ts
- 插件上下文能力:Context.ts
