javiyt/grpc-wiremock

grpc-wiremock Docker镜像文档

概述

grpc-wiremock是一个GRPC服务模拟服务器，作为WireMock HTTP服务器的包装器实现。它允许开发人员轻松模拟GRPC服务，通过将GRPC请求转换为JSON格式与WireMock交互，再将WireMock的HTTP响应转换回GRPC协议格式。

工作原理

1. 根据提供的proto文件生成GRPC服务器，监听tcp://localhost:50000
2. GRPC服务器接收请求后，将其转换为JSON格式
3. 以POST请求形式将JSON数据转发至WireMock服务器（监听http://localhost:8888）
4. WireMock处理请求并返回HTTP响应
5. GRPC服务器将HTTP响应转换回GRPC协议格式并返回给客户端

核心功能与特性

• 支持基于proto文件动态生成GRPC服务器
• 与WireMock无缝集成，可使用WireMock的存根配置能力
• 支持GRPC请求/响应与JSON格式的双向转换
• 可配置GRPC服务器参数（如消息大小限制等）
• 支持gzip压缩（默认）和snappy压缩
• 提供负载测试优化配置

使用场景

• GRPC服务开发过程中的本地测试
• 依赖GRPC服务的应用程序集成测试
• 模拟第三方GRPC服务进行独立开发
• 负载测试环境中的GRPC服务模拟

快速使用

1. 启动容器

posh
docker run -p 8888:8888 -p 50000:50000 -v $(pwd)/example/proto:/proto -v $(pwd)/example/wiremock:/wiremock adven27/grpc-wiremock

• -p 8888:8888: 映射WireMock HTTP服务器端口
• -p 50000:50000: 映射GRPC服务器端口
• -v $(pwd)/example/proto:/proto: 挂载proto文件目录
• -v $(pwd)/example/wiremock:/wiremock: 挂载WireMock配置目录

2. 配置存根

通过WireMock API创建存根：

json
curl -X POST http://localhost:8888/__admin/mappings \
  -d '{
    "request": {
        "method": "POST",
        "url": "/BalanceService/getUserBalance",
        "bodyPatterns" : [ {
            "equalToJson" : { "id": "1", "currency": "EUR" }
        } ]
    },
    "response": {
        "status": 200,
        "jsonBody": { 
            "balance": { 
                "amount": { "value": { "decimal" : "100.0" }, "value_present": true },
                "currency": { "value": "EUR", "value_present": true }
            } 
        }
    }
}'

3. 测试GRPC服务

使用grpcurl发送GRPC请求：

posh
grpcurl -plaintext -d '{"id": 1, "currency": "EUR"}' localhost:50000 api.wallet.BalanceService/getUserBalance

预期响应：

json
{
  "balance": {
    "amount": {
      "value": {
        "decimal": "100.0"
      },
      "value_present": true
    },
    "currency": {
      "value": "EUR",
      "value_present": true
    }
  }
}

存根配置

存根配置需通过WireMock JSON API进行，可配置请求匹配规则、响应内容、状态码等。

高级配置

1. 修改GRPC服务器属性

支持以下GRPC服务器属性配置：

properties
GRPC_SERVER_MAXHEADERLISTSIZE
GRPC_SERVER_MAXMESSAGESIZE
GRPC_SERVER_MAXINBOUNDMETADATASIZE
GRPC_SERVER_MAXINBOUNDMESSAGESIZE

注：前两个属性已被后两个取代，建议使用后者

使用示例：

posh
docker run -e GRPC_SERVER_MAXINBOUNDMESSAGESIZE=1048576 adven27/grpc-wiremock

2. 加速容器启动

若无需修改proto文件，可构建包含预编译proto的自定义镜像，示例Dockerfile：

dockerfile
FROM adven27/grpc-wiremock
COPY ./proto /proto

3. 启用snappy压缩

通过EXT_CODECS环境变量启用snappy压缩：

posh
docker run -e EXT_CODECS=snappy adven27/grpc-wiremock

docker-compose配置示例：

yaml
version: '3'
services:
  grpc-mock:
    image: adven27/grpc-wiremock
    ports:
      - "50000:50000"  # GRPC端口
      - "8888:8888"    # WireMock HTTP端口
    volumes:
      - ./proto:/proto
    environment:
      - EXT_CODECS=snappy

注：gzip压缩默认已支持

4. 负载测试配置

启用"load"配置文件可优化性能，等价于设置多个WireMock参数：

posh
docker run -e SPRING_PROFILES_ACTIVE=load adven27/grpc-wiremock

等价于手动设置以下参数：

posh
docker run \
    -e WIREMOCK_SERVER_DISABLEREQUESTJOURNAL=true \
    -e WIREMOCK_SERVER_ASYNCHRONOUSRESPONSEENABLED=true \
    -e WIREMOCK_SERVER_ASYNCHRONOUSRESPONSETHREADS=10 \
    -e WIREMOCK_SERVER_STUBREQUESTLOGGINGDISABLED=true \
    -e WIREMOCK_SERVER_VERBOSE=false \
    adven27/grpc-wiremock

错误码映射

HTTP状态码与GRPC状态码映射关系如下：

错误模拟示例

创建返回403状态码的存根：

json
curl -X POST http://localhost:8888/__admin/mappings \
  -d '{
    "request": {
        "method": "POST",
        "url": "/BalanceService/getUserBalance",
        "bodyPatterns" : [ {
            "equalToJson" : { "id": "1", "currency": "EUR" }
        } ]
    },
    "response": {
        "status": 403,
        "body": "you can't access here"
    }
}'

GRPC请求响应：

json
{
  "error": "7 PERMISSION_DENIED: "
}