fullstorydev/grpcurl

grpcurl Docker镜像文档

镜像概述

grpcurl是一款用于与gRPC服务器交互的命令行工具，功能类似于HTTP客户端工具cURL，但专门针对gRPC协议设计。该工具支持探索gRPC服务定义及调用gRPC方法，适用于gRPC服务的开发调试、监控与测试场景。

源码地址：https://github.com/fullstorydev/grpcurl

核心功能与特性

• 服务探索：支持列出gRPC服务器提供的所有服务、方法及消息类型，自动解析服务定义。
• 方法调用：支持调用各类gRPC方法，包括Unary RPC、Server Streaming、Client Streaming及Bidirectional Streaming。
• 协议支持：基于HTTP/2协议，兼容标准gRPC通信流程，支持TLS加密与非加密（plaintext）连接。
• 灵活输入：支持通过命令行参数或文件传入请求数据，支持JSON格式请求体。
• Proto文件解析：可通过本地Proto文件或反射服务（gRPC Reflection）获取服务定义，无需预编译Proto。

使用场景与适用范围

• 开发调试：开发人员快速验证gRPC服务接口功能，排查方法调用异常。
• 服务监控：定期调用健康检查或状态查询类gRPC方法，监控服务可用性。
• 自动化测试：集成至CI/CD流程，通过脚本调用gRPC方法验证服务部署后功能正确性。
• 学习与分析：解析第三方gRPC服务的接口定义，了解服务结构与通信协议。

使用方法与配置说明

基本使用方式

grpcurl Docker镜像以grpcurl可执行文件为入口，使用时通过docker run命令传递参数。基础语法：

bash
docker run --rm fullstorydev/grpcurl [全局参数] <服务器地址> <命令> [命令参数]

说明：--rm确保容器退出后自动清理；fullstorydev/grpcurl为官方镜像（假设，实际需替换为具体镜像名）。

常用命令示例

1. 探索gRPC服务（需服务启用Reflection）

列出目标服务器上所有gRPC服务：

bash
docker run --rm fullstorydev/grpcurl --plaintext grpc-server:50051 list

参数：--plaintext：禁用TLS（适用于开发环境非加密连接）；list：命令，列出服务。

列出指定服务的所有方法：

bash
docker run --rm fullstorydev/grpcurl --plaintext grpc-server:50051 list myservice.UserService

查看方法详细定义（包括请求/响应消息结构）：

bash
docker run --rm fullstorydev/grpcurl --plaintext grpc-server:50051 describe myservice.UserService.GetUser

2. 调用Unary RPC方法

调用myservice.UserService.GetUser方法，传入JSON格式请求数据：

bash
docker run --rm fullstorydev/grpcurl --plaintext -d '{"user_id": "123"}' grpc-server:50051 myservice.UserService.GetUser

参数：-d：指定请求数据（JSON格式）；最后一个参数为<服务名>.<方法名>。

3. 使用本地Proto文件（服务未启用Reflection时）

若服务未启用Reflection，需通过本地Proto文件指定服务定义：

bash
docker run --rm -v $(pwd)/protos:/protos fullstorydev/grpcurl \
  --plaintext \
  -import-path /protos \
  -proto user_service.proto \
  grpc-server:50051 \
  myservice.UserService.GetUser

参数：-v $(pwd)/protos:/protos：挂载本地protos目录至容器内/protos；-import-path：指定Proto文件导入路径；-proto：指定Proto文件名。

4. 调用Server Streaming方法

调用返回流式响应的方法（如实时日志推送）：

bash
docker run --rm fullstorydev/grpcurl --plaintext -d '{"stream_id": "log-stream-1"}' grpc-server:50051 myservice.LogService.StreamLogs

配置参数说明

Docker Compose示例

若需频繁使用本地Proto文件或固定配置，可通过docker-compose.yml简化命令：

yaml
version: '3'
services:
  grpcurl:
    image: fullstorydev/grpcurl
    volumes:
      - ./protos:/protos  # 挂载本地Proto文件目录
    command: >
      --plaintext
      -import-path /protos
      -proto user_service.proto
      grpc-server:50051
      myservice.UserService.GetUser

运行：

bash
docker-compose run --rm grpcurl

说明：grpc-server需与当前Compose网络中的gRPC服务容器名一致。