如何使用 Evans：一款终极的通用 gRPC 客户端工具

【免费下载链接】evans Evans: more expressive universal gRPC client 项目地址: https://gitcode.com/gh_mirrors/ev/evans

Evans 是一款更富表达力的通用 gRPC 客户端，旨在让 gRPC API 测试和交互变得简单直观。无论是手动检查 gRPC API，还是通过脚本自动化任务，Evans 都能满足你的需求，它提供了两种强大的操作模式：REPL 模式和 CLI 模式，让开发者能够轻松与 gRPC 服务进行交互。

Evans 核心功能概览

Evans 主要解决了两个核心使用场景：

• 手动 gRPC API 检查：通过 REPL 模式提供强大的自动补全功能，无需记忆复杂的包名、服务名和 RPC 名称
• 任务自动化：通过 CLI 模式实现单次命令发送单个请求，遵循 UNIX 哲学，支持标准输入输出和管道操作

REPL 模式：交互式 gRPC 客户端体验

REPL（Read-Eval-Print Loop）模式是 Evans 最具特色的功能之一，它提供了一个交互式环境，让你可以轻松探索和测试 gRPC 服务。

图：Evans REPL 模式界面展示，显示了交互式 gRPC 调用过程

在 REPL 模式中，你可以：

• 查看可用的 protobuf 包和服务
• 检查消息结构和字段类型
• 交互式构建请求消息
• 设置请求头和元数据
• 调用各种类型的 RPC 方法（Unary、Client Streaming、Server Streaming、Bidirectional Streaming）

CLI 模式：自动化 gRPC 测试工具

CLI 模式提供了一种无状态的、命令行驱动的方式来调用 gRPC 服务，非常适合集成到脚本和自动化测试流程中。

图：Evans CLI 模式使用示例，展示了如何通过命令行调用 gRPC 服务

CLI 模式的主要特点：

• 支持从文件或标准输入读取请求数据
• 输出 JSON 格式的响应，便于后续处理（如使用 jq 工具）
• 支持单次命令完成 gRPC 调用
• 适合集成到 CI/CD 流程中

快速安装 Evans

从 GitHub Releases 安装（推荐）

访问 Evans 的 GitHub Releases 页面，根据你的操作系统下载相应的二进制文件：

• macOS
• Linux
• Windows

macOS 安装

使用 Homebrew 安装：

brew tap ktr0731/evans
brew install evans

Docker 镜像

你也可以使用 Docker 镜像运行 Evans：

docker run --rm -v "$(pwd):/mount:ro" \
    ghcr.io/ktr0731/evans:latest \
      --path ./proto/files \
      --proto file-name.proto \
      --host example.com \
      --port 50051 \
      repl

源码安装（不推荐）

如果你有 Go 环境（v1.20 或更高版本），可以通过以下命令安装：

go install github.com/ktr0731/evans@latest

REPL 模式使用指南

基本用法

启动 REPL 模式非常简单。如果你的 gRPC 服务启用了 gRPC 反射，只需运行：

evans -r repl

如果需要指定 proto 文件：

evans --proto api/api.proto repl

探索 gRPC 服务

进入 REPL 后，你可以使用以下命令探索服务：

查看可用的包：

> show package

选择包：

> package api

查看服务和方法：

> show service

查看消息类型：

> show message

查看消息详情：

> desc SimpleRequest

调用 gRPC 方法

设置请求头：

> header foo=bar

调用 Unary RPC：

> service Example
> call Unary
name (TYPE_STRING) => ktr
{
  "message": "hello, ktr"
}

处理特殊字段类型

重复字段（Repeated Fields）：

> call UnaryRepeated
<repeated> name (TYPE_STRING) => foo
<repeated> name (TYPE_STRING) => bar
<repeated> name (TYPE_STRING) => baz
<repeated> name (TYPE_STRING) =>
{
  "message": "hello, foo, bar, baz"
}

枚举字段（Enum Fields）：

> call UnaryEnum
? UnaryEnumRequest  [Use arrows to move, type to filter]
> Male
  Female
{
  "message": "M"
}

字节类型字段（Bytes Fields）：

> call UnaryBytes
data (TYPE_BYTES) => SGVsbG8gV29ybGQh
{
  "message": "received: (bytes) 48 65 6c 6c 6f 20 57 6f 72 6c 64 21, (string) Hello World!"
}

处理流式 RPC

客户端流式 RPC：

> call ClientStreaming
name (TYPE_STRING) => ktr
name (TYPE_STRING) => ktr
name (TYPE_STRING) => ktr
name (TYPE_STRING) =>
{
  "message": "ktr, you greet 3 times."
}

服务端流式 RPC：

> call ServerStreaming
name (TYPE_STRING) => ktr
{
  "message": "hello ktr, I greet 0 times."
}

{
  "message": "hello ktr, I greet 1 times."
}

双向流式 RPC：

> call BidiStreaming
name (TYPE_STRING) => foo
{
  "message": "hello foo, I greet 0 times."
}

name (TYPE_STRING) => bar
{
  "message": "hello bar, I greet 0 times."
}

CLI 模式使用指南

基本用法

列出服务：

evans -r cli list

列出服务的方法：

evans -r cli list api.Example

描述服务或消息：

evans -r cli desc api.Example

调用 RPC 方法：

echo '{ "name": "ktr" }' | evans -r cli call api.Example.Unary

使用配置文件简化命令：

创建 .evans.toml 文件：

[default]
protoFile = ["api/api.proto"]
package = "api"
service = "Example"

然后可以简化命令：

echo '{ "name": "ktr" }' | evans cli call Unary

处理流式 RPC

客户端流式 RPC：

echo '{ "name": "ktr" } { "name": "ktr" }' | evans -r cli call api.Example.ClientStreaming

服务端流式 RPC：

echo '{ "name": "ktr" }' | evans -r cli call api.Example.ServerStreaming

高级功能

富化响应（Enriched Response）

使用 --enrich 选项获取更详细的响应信息，包括头信息、尾信息和状态码：

echo '{"name": "ktr"}' | evans -r cli call --enrich api.Example.Unary

gRPC-Web 支持

Evans 还支持 gRPC-Web 协议，可以与 gRPC-Web 服务器交互：

evans --web --host example.com --port 8080 -r repl

重复调用

在 REPL 模式中，使用 --repeat 选项重复上一次调用：

> call --repeat Unary

总结

Evans 是一款功能强大的 gRPC 客户端工具，通过 REPL 和 CLI 两种模式满足了不同的使用场景需求。无论是交互式探索 gRPC API，还是构建自动化测试脚本，Evans 都提供了简单直观的操作方式。它支持各种 gRPC 特性，包括流式 RPC、元数据设置、枚举和重复字段处理等，是 gRPC 开发者不可或缺的工具。

如果你还在为 gRPC 测试工具的选择而烦恼，不妨试试 Evans，它可能会成为你日常开发工作中的得力助手！

【免费下载链接】evans Evans: more expressive universal gRPC client 项目地址: https://gitcode.com/gh_mirrors/ev/evans