kong/grpcbin

gRPC测试调试工具镜像文档

镜像概述

本镜像是一个类似httpbin的gRPC工具，专为gRPC服务的测试与调试设计。它提供了一系列预设的gRPC方法端点，可模拟各类请求处理场景，帮助开发者快速验证gRPC客户端功能、服务端交互逻辑及数据传输过程，简化gRPC应用的开发与调试流程。

核心功能和特性

主要功能

• 多类型gRPC端点：支持Unary RPC、Server Streaming、Client Streaming及Bidirectional Streaming等多种gRPC通信模式的端点。
• 请求信息获取：可返回客户端发送的请求参数、元数据（Metadata）、调用上下文等详细信息。
• 响应模拟：支持自定义响应数据、状态码、错误信息，可模拟成功、失败、超时等各类响应场景。
• 元数据操作：提供获取/设置请求元数据、响应元数据的端点，辅助调试元数据传递逻辑。
• 流量镜像：支持将接收到的gRPC请求转发至指定后端服务，用于流量复制与对比测试。

技术特性

• 轻量级设计，基于高效gRPC框架实现，资源占用低。
• 支持TLS加密通信（可通过配置启用）。
• 内置请求日志，记录关键调用信息便于问题排查。
• 兼容标准gRPC协议，支持主流gRPC客户端（如gRPC-Java、gRPC-Go、Python gRPC等）。

使用场景和适用范围

典型场景

• gRPC客户端开发测试：验证客户端是否正确构造请求（如参数、元数据、流式数据发送逻辑）。
• 服务端功能验证：模拟服务端响应，测试客户端对不同响应（成功、错误、流式数据）的处理能力。
• API文档辅助：作为示例服务，配合gRPC UI工具（如grpcui）生成可视化API文档。
• 中间件调试：测试gRPC网关、代理、负载均衡等中间件的请求转发与处理逻辑。
• 教学与学习：作为gRPC协议学习工具，直观展示不同RPC模式的通信过程。

适用人群

• gRPC应用开发者（客户端/服务端）
• 测试工程师（API测试、集成测试）
• 技术文档编写者（API示例构建）
• gRPC初学者（协议实践与理解）

使用方法和配置说明

基本部署（Docker Run）

通过以下命令启动镜像，默认暴露50051端口（gRPC标准端口）：

bash
docker run -d -p 50051:50051 --name grpcbin [镜像名称]:[标签]

说明：[镜像名称]需替换为实际镜像名称（如grpcbin），[标签]可指定版本（如latest）。

环境变量配置

支持通过环境变量自定义服务行为，常用配置如下：

示例（启用debug日志）：

bash
docker run -d -p 50051:50051 -e LOG_LEVEL=debug --name grpcbin [镜像名称]:[标签]

Docker Compose配置

通过docker-compose.yml管理服务部署：

yaml
version: '3'
services:
  grpcbin:
    image: [镜像名称]:[标签]
    ports:
      - "50051:50051"
    environment:
      - LOG_LEVEL=info
      - PORT=50051
    # 如需启用TLS，挂载证书文件
    # volumes:
    #   - ./tls:/etc/grpcbin/tls
    #   - TLS_ENABLED=true

常用gRPC端点示例

镜像提供的核心gRPC方法定义可通过反射服务获取（推荐使用grpcui工具探索），以下为典型端点示例：

1. Unary RPC：Echo（回声）

• 方法：grpcbin.EchoService/Echo
• 功能：返回客户端发送的请求消息
• 请求示例（Protobuf）：

  protobuf
  message EchoRequest {
    string message = 1;
  }
  

• 响应示例：

  protobuf
  message EchoResponse {
    string message = 1;  // 与请求message一致
    string timestamp = 2; // 服务器处理时间戳
  }
  

2. Server Streaming：StreamNumbers

• 方法：grpcbin.StreamService/StreamNumbers
• 功能：服务端流式返回指定范围的数字序列
• 请求参数：start: int32, count: int32（起始数字、返回数量）
• 响应：流式返回number: int32

3. 元数据调试：GetMetadata

• 方法：grpcbin.MetadataService/GetMetadata
• 功能：返回客户端发送的所有元数据
• 响应示例：

  protobuf
  message MetadataResponse {
    map<string, string> request_metadata = 1; // 客户端发送的元数据键值对
  }
  

工具集成建议

• grpcui：通过反射服务可视化调用gRPC方法，命令示例：

  bash
  grpcui -plaintext localhost:50051
  

• gRPCurl：命令行gRPC客户端，用于脚本化测试，示例：

  bash
  grpcurl -plaintext -d '{"message":"test"}' localhost:50051 grpcbin.EchoService/Echo
  

注意事项

• 默认未启用TLS，生产环境使用时建议通过TLS_ENABLED配置启用加密通信。
• 高并发测试场景下，可通过调整容器资源限制（如--cpus、--memory）优化性能。
• 镜像仅用于测试调试，不建议直接部署在生产环境处理真实业务流量。