grpcurl 命令行工具快速上手：gRPC 接口测试与调试实用指南-开发者社区

grpcurl 命令行工具快速上手：gRPC 接口测试与调试实用指南

【免费下载链接】grpcurlLike cURL, but for gRPC: Command-line tool for interacting with gRPC servers项目地址: https://gitcode.com/gh_mirrors/gr/grpcurl

gRPC 服务在网络上使用 protobuf 二进制编码，普通的 curl 命令根本无法直接与之交互。grpcurl 就是为此而生的命令行工具：你把 JSON 格式的请求交给它，它负责转成 protobuf 二进制发给 gRPC 服务器，再把响应输出成可读文本。当你需要验证某个接口是否可用、查看字段定义，或是在终端里临时发一个测试请求时，它就是趁手的工具。

整条使用路径其实就四步：把工具装好、确认服务列表、发起第一次方法调用、处理服务器不支持反射的场景。按顺序走一遍即可。

装好工具，先跑通一条命令

不同环境有对应的安装方式，挑一种适合自己的即可：

macOS 上用 Homebrew 一行装完：

brew install grpcurl

支持 snap 的 Linux 发行版：

snap install grpcurl

已经装好 Go 环境，直接通过 go 命令安装：

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

可执行文件会落在$GOPATH/bin（未设置 GOPATH 时默认是$HOME/go/bin），确认该目录已加入 PATH 就能直接运行。

不想占用本机环境，也可以进容器里跑：

docker pull fullstorydev/grpcurl:latest docker run fullstorydev/grpcurl api.grpc.me:443 list

或者从发布页下载对应平台的二进制文件，解压后把可执行文件放进 PATH。

需要本地编译时，先克隆仓库，再进仓库执行make install：

git clone https://gitcode.com/gh_mirrors/gr/grpcurl cd grpcurl make install

装完后先确认工具能正常工作：

grpcurl -help

选项都能打印出来就说明安装成功。之后遇到拿不准的参数，随时用这条命令查完整说明。

第一次调用：先 list，再 describe，最后发请求

以本地测试服务为例（目标地址用localhost:8787）：

列出服务器暴露的全部服务：

grpcurl localhost:8787 list

查看某个服务里的所有方法：

grpcurl localhost:8787 list my.custom.server.Service

查看某个方法的字段定义，相当于读接口的文档：

grpcurl localhost:8787 describe my.custom.server.Service.MethodOne

确认好结构后就可以正式发起调用。最简单的调用不携带请求体：

grpcurl grpc.server.com:443 my.custom.server.Service/Method

写命令时有两个容易踩的点：

所有选项参数必须写在服务器地址和方法名之前；
服务器没启用 TLS 时要加-plaintext，否则连接会失败。

组织请求：JSON 请求体、管道输入与请求头

用 -d 传 JSON 请求体

方法有入参时，用-d传 JSON。grpcurl 会负责把它转换成 protobuf 二进制再发送：

grpcurl -d '{"id": 1234, "tags": ["foo", "bar"]}' \ grpc.server.com:443 my.custom.server.Service/Method

从文件读请求体（-d @）

请求体很长、或者是由脚本（比如 jq 处理后的结果）生成时，用-d @让它从标准输入读取：

grpcurl -d @ grpc.server.com:443 my.custom.server.Service/Method < request.json

附加请求头（-H）

认证凭据、追踪 ID 这类信息通常走元数据头，-H可以重复使用：

grpcurl -H "Authorization: Bearer <token>" \ -H "X-Request-ID: 123" \ -d '{"id": 1234}' grpc.server.com:443 my.custom.server.Service/Method

若服务器返回 401 一类的错误，优先核对 token 是否有效、头字段名是否与服务器约定一致。

服务器不支持反射时的两条替代路径

默认情况下 grpcurl 依赖服务器的反射服务来拿接口 schema。如果反射服务没开，连接本身能建立，但拿不到任何接口信息，这时需要你自己提供 schema。

方式一：用 .proto 源文件

用-proto指定服务定义文件，用-import-path指定依赖 proto 所在的目录：

grpcurl -import-path ../protos -proto my-stuff.proto list

两个细节值得了解：

protoc 附带的标准类型（google.protobuf下的各类 well-known types）已内置在 grpcurl 可执行文件里，不需要为它们指定 import 路径；
用 proto 源文件做 list / describe 时，可以省略服务器地址，因为这两种操作只读取本地文件。

方式二：用 protoset 编译文件

写脚本批量调用时，先用 protoc 编译一次、反复复用同一个文件，能省掉每次调用都解析源码的开销：

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

--include_imports不能漏，它保证 protoset 里包含 schema 所需的全部依赖。之后用-protoset传入即可：

grpcurl -protoset my-protos.bin describe my.custom.server.Service.MethodOne

顺手把接口定义导出来

反过来，服务器支持反射时，也可以借describe把接口定义导出成 proto 源文件或 protoset 文件，方便补全文档或存档：

# 导出 proto 源文件 grpcurl -plaintext -proto-out-dir "out_protos" "localhost:8787" describe my.custom.server.Service # 导出 protoset 文件 grpcurl -plaintext -protoset-out "out.protoset" "localhost:8787" describe my.custom.server.Service

连接方式与流式方法

服务器启用了 TLS（默认模式）：不加额外参数即可连接；自签名证书或内部 CA 的情况，用 TLS 相关选项调整，具体选项用grpcurl -help查看。
服务器是明文（无 TLS）：务必加-plaintext，例如：

grpcurl -plaintext grpc.server.com:80 my.custom.server.Service/Method

流式方法同样支持：服务端流方法直接用-d发送请求，响应会边接收边输出。双向流方法可以在交互式终端中运行 grpcurl 并让请求体走标准输入，持续发送消息直到结束。

常见卡点按这个顺序排查

连接失败：先确认服务器已启动并监听在预期端口，再核对 TLS 模式是否匹配——明文服务器漏加-plaintext是最常见的原因。
找不到服务或方法：先用list核对完整名是否正确（含包名前缀）；反射未开启的场景要改用-proto或-protoset提供 schema。
权限类错误：通常是缺少认证元数据头，用-H补上。
Docker 环境的特殊问题：
- 访问宿主机回环上的服务，Mac / Windows 要用host.docker.internal代替 localhost，Linux 上加-network="host"；
- 传 proto 文件时需用-v $(pwd):/protos把目录挂进容器，并把导入路径改成容器内路径；
- 用-d @从标准输入读请求体时，docker 命令要加-i。