最完整的grpcurl使用指南：从安装到高级功能全解析-优快云博客

最完整的grpcurl使用指南：从安装到高级功能全解析

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

你还在为无法像调试HTTP接口那样轻松测试gRPC服务而烦恼吗？还在为protobuf的二进制格式难以调试而头疼吗？本文将带你全面掌握grpcurl——这款被誉为"gRPC界的curl"的命令行工具，从基础安装到高级功能，让你一文搞定gRPC服务调试。

读完本文你将学会：

多种方式安装grpcurl
探索gRPC服务的三种方法
发送各类gRPC请求（包括流请求）
配置TLS安全连接
处理复杂的请求参数与元数据

什么是grpcurl？

grpcurl是一个命令行工具，它允许你与gRPC服务器进行交互，就像使用curl与HTTP服务器交互一样简单。gRPC服务器使用二进制编码的协议缓冲区（Protocol Buffers，简称protobuf）进行通信，这使得使用常规curl工具直接交互变得困难。而grpcurl则通过JSON格式接收输入并将其转换为二进制protobuf格式，大大简化了gRPC服务的调试过程。

主要功能包括：

调用gRPC服务器上的RPC方法
浏览gRPC服务的模式（schema）
支持JSON格式的请求和响应
处理各种TLS配置和认证方式

安装grpcurl

二进制安装

从项目的发布页面下载适合你系统的二进制文件，解压后即可使用。

Homebrew安装（macOS）

brew install grpcurl

Docker安装

# 下载镜像
docker pull fullstorydev/grpcurl:latest
# 运行工具
docker run fullstorydev/grpcurl api.grpc.me:443 list

使用Docker时需要注意：

如需访问主机环回网络，Mac或Windows用户需使用host.docker.internal代替localhost
Linux用户可使用-network="host"参数让容器使用主机网络
如需提供proto文件，需使用-v参数挂载本地目录
如需通过标准输入提供请求数据，需使用-i参数

Snap安装

snap install grpcurl

源码安装

如果你已经安装了Go SDK，可以使用go工具直接安装：

go install gitcode.com/gh_mirrors/gr/grpcurl/cmd/grpcurl@latest

这会将命令安装到$GOPATH/bin目录下（如未设置GOPATH，默认位置为$HOME/go/bin）。

如果你已经克隆了仓库，也可以在仓库目录下运行：

make install

基础使用方法

命令格式

grpcurl的基本命令格式如下：

grpcurl [flags] [server address] [command] [arguments]

可以通过以下命令查看所有可用选项：

grpcurl -help

探索gRPC服务

列出所有服务

要列出服务器上所有可用的gRPC服务，使用list命令：

# 带TLS的服务器
grpcurl grpc.server.com:443 list

# 不带TLS的服务器
grpcurl -plaintext grpc.server.com:80 list

这个功能依赖于服务器支持服务器反射。如果服务器不支持反射，你需要提供proto文件或protoset文件。

列出服务的所有方法

要查看特定服务提供的方法，可以将服务名作为参数传递给list命令：

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

描述服务或方法

使用describe命令可以获取服务、方法或消息类型的详细信息：

# 描述服务
grpcurl localhost:8787 describe my.custom.server.Service

# 描述方法
grpcurl localhost:8787 describe my.custom.server.Service.MethodOne

调用RPC方法

基本调用

调用gRPC方法的基本语法如下：

grpcurl [flags] server.address package.Service/Method

例如，调用一个不需要参数的方法：

# 使用TLS
grpcurl grpc.server.com:443 my.custom.server.Service/Method

# 不使用TLS
grpcurl -plaintext grpc.server.com:80 my.custom.server.Service/Method

传递请求参数

使用-d选项传递JSON格式的请求参数：

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

如果请求体比较复杂，可以将JSON内容保存到文件中，然后使用-d @从标准输入读取：

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

或者使用Here Document语法：

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

添加请求头/元数据

使用-H选项可以添加请求头或元数据：

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

高级功能

处理没有反射的服务器

如果要访问的gRPC服务器不支持反射，grpcurl需要通过其他方式获取服务定义。有两种主要方法：使用proto源文件或使用protoset文件。

使用proto源文件

使用-import-path指定proto文件的导入路径，使用-proto指定proto文件：

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

使用protoset文件

Protoset文件是包含编码文件描述符的二进制文件。首先需要使用protoc编译proto文件生成protoset：

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

然后在grpcurl中使用-protoset选项指定protoset文件：

grpcurl -protoset myservice.protoset list

导出proto文件和protoset

grpcurl还支持将服务定义导出为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配置

grpcurl提供了丰富的TLS配置选项，以适应不同的安全需求：

# 禁用TLS（使用纯文本）
grpcurl -plaintext server:port service/method

# 指定CA证书
grpcurl -cacert ca.pem server:port service/method

# 提供客户端证书和密钥
grpcurl -cert client.pem -key client.key server:port service/method

# 跳过服务器证书验证（不推荐用于生产环境）
grpcurl -insecure server:port service/method

流处理

grpcurl支持所有类型的gRPC流：

服务端流：服务器返回多个响应
客户端流：客户端发送多个请求
双向流：客户端和服务器都可以发送多个消息

对于流请求，可以使用交互式终端输入多个请求消息，每个消息占一行，以JSON格式表示。

代码实现解析

grpcurl的核心功能由几个关键函数实现：

ListServices (grpcurl.go): 列出所有可用服务
ListMethods (grpcurl.go): 列出特定服务的所有方法
InvokeRpc (invoke.go): 调用RPC方法

这些函数通过DescriptorSource获取服务元数据，然后使用该元数据将JSON请求转换为二进制protobuf格式，并将响应从二进制格式转换回JSON。

总结与最佳实践

grpcurl是一个功能强大的gRPC调试工具，掌握它可以极大提高你的开发效率。以下是一些最佳实践：

优先使用服务器反射：如果服务器支持反射，无需额外配置即可使用大部分功能
为生产环境准备protoset：在生产环境中，建议使用预编译的protoset文件以提高性能
安全处理敏感数据：避免在命令行参数中传递敏感信息，可使用文件或环境变量
使用JSON验证工具：复杂请求可先使用JSON验证工具确保格式正确
结合jq使用：对于复杂响应，可以使用jq工具进行解析和处理

掌握grpcurl将使你能够更轻松地调试和测试gRPC服务，无论是简单的一元RPC还是复杂的流处理。

希望本文能帮助你快速掌握grpcurl的使用。如果你有任何问题或建议，欢迎在评论区留言讨论！

点赞+收藏+关注，获取更多gRPC调试技巧！下期我们将介绍如何使用grpcurl进行自动化测试。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考