adven27/grpc-wiremock

grpc-wiremock 镜像文档

概述

grpc-wiremock 是一个 GRPC服务模拟服务器，作为 WireMock HTTP服务器的封装实现。它通过提供的proto文件生成GRPC服务器，将GRPC请求转换为JSON格式后转发至WireMock，再将WireMock返回的HTTP响应转换回GRPC proto格式，实现GRPC服务的模拟。

工作原理

!https://github.com/Adven27/grpc-wiremock/raw/master/doc/overview.png

1. GRPC服务器运行在 tcp://localhost:50000
2. WireMock服务器运行在 http://localhost:8888
3. 流程：GRPC请求 → 转换为JSON → 作为POST请求发送至WireMock → WireMock返回HTTP响应 → 转换为GRPC格式响应

核心功能和特性

• 基于proto文件动态生成GRPC服务器
• 支持通过WireMock JSON API配置存根（Stub）
• 自动映射HTTP状态码至GRPC状态码，支持自定义映射
• 支持GRPC服务器端流（Server-side Streaming）模拟
• 可配置GRPC服务器参数（端口、消息大小等）
• 可通过环境变量配置WireMock服务器选项
• 支持Snappy压缩编码（默认支持gzip）
• 提供负载测试优化配置（load profile）
• 支持保留proto字段名（默认使用lowerCamelCase）

使用场景

• GRPC服务开发过程中的本地测试
• 前端/客户端与GRPC服务集成时的API模拟
• 第三方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. 创建存根（Stub）

通过WireMock JSON API创建存根：

posh
curl -X POST http://localhost:8888/__admin/mappings \
  -d '{
    "request": {
        "method": "POST",
        "url": "/BalanceService/getUserBalance",
        "headers": {"withAmount": {"matches": "\\d+\\.?\\d*"} },
        "bodyPatterns" : [ {
            "equalToJson" : { "userId": "1", "currency": "EUR" }
        } ]
    },
    "response": {
        "status": 200,
        "jsonBody": { 
            "balance": { 
                "amount": { "value": { "decimal" : "{{request.headers.withAmount}}" }, "value_present": true },
                "currency": { "value": "EUR", "value_present": true }
            } 
        }
    }
}'

3. 验证GRPC请求

使用grpcurl发送GRPC请求验证：

posh
grpcurl -H 'withAmount: 100.0' -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 完成。

错误映射

默认HTTP状态码到GRPC状态码的映射基于 https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto%EF%BC%9A

自定义错误映射：通过环境变量覆盖或扩展映射，格式为GRPC_ERRORCODEBY_HTTP_STATUSCODE_<HTTP状态码>=<GRPC状态>。

示例：

posh
docker run \
    -e GRPC_ERRORCODEBY_HTTP_STATUSCODE_400=OUT_OF_RANGE \
    -e GRPC_ERRORCODEBY_HTTP_STATUSCODE_510=DATA_LOSS \
    adven27/grpc-wiremock

配置指南

1. 配置GRPC服务器

支持以下环境变量配置GRPC服务器：

示例：

posh
docker run -e GRPC_SERVER_MAXHEADERLISTSIZE=1000 adven27/grpc-wiremock

2. 配置WireMock服务器

通过环境变量传递WireMock命令行选项，选项需添加WIREMOCK_前缀。

示例：

posh
docker run -e WIREMOCK_DISABLE-REQUEST-LOGGING -e WIREMOCK_PORT=0 adven27/grpc-wiremock

完整WireMock命令行选项参见 WireMock文档

3. 模拟服务器端流（Server-side Streaming）

对于返回流的GRPC服务，通过response.headers.streamSize指定流中返回的响应数量（默认1），当前迭代序号可通过request.headers.streamCursor获取。

示例：

假设proto定义：

protobuf
service WalletService {
  rpc searchTransaction (SearchTransactionRequest) returns (stream SearchTransactionResponse) {}
}

创建存根：

posh
curl -X POST http://localhost:8888/__admin/mappings \
  -d '{
  "request": {
    "method": "POST",
    "url": "/WalletService/searchTransaction"
  },
  "response": {
    "fixedDelayMilliseconds": 1000,
    "headers": {"streamSize": "5" },
    "jsonBody": {
      "transactions": [
        {
          "id": "{{request.headers.streamCursor}}",
          "userId": "1",
          "currency": "EUR",
          "amount": {
            "decimal": "{{request.headers.streamCursor}}00"
          }
        },
        {
          "id": "100{{request.headers.streamCursor}}",
          "userId": "2",
          "currency": "EUR",
          "amount": {
            "decimal": "200"
          }
        }
      ]
    }
  }
}'

4. 加速容器启动

若无需修改proto文件，可构建包含预编译proto的自定义镜像，示例Dockerfile参见 https://github.com/Adven27/grpc-wiremock/tree/master/example/Dockerfile%E3%80%82

5. 使用Snappy压缩编码

通过EXTERNAL_CODECS环境变量启用Snappy压缩（默认支持gzip）：

Docker运行示例：

posh
docker run -e EXTERNAL_CODECS="snappy" adven27/grpc-wiremock

Docker Compose示例：

yaml
services:
  grpc-wiremock:
    image: adven27/grpc-wiremock
    ports:
      - "12085:50000"  # GRPC端口
      - "8088:8888"    # WireMock HTTP端口
    volumes:
      - ./example/proto:/proto
    environment:
      - EXTERNAL_CODECS=snappy

6. 负载测试配置

启用load配置文件可优化WireMock性能，等价于设置多个性能相关选项：

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

等价于：

posh
docker run \
  -e WIREMOCK_NO-REQUEST-JOURNAL \
  -e WIREMOCK_DISABLE-REQUEST-LOGGING \
  -e WIREMOCK_ASYNC-RESPONSE-ENABLED \
  -e WIREMOCK_ASYNC-RESPONSE-THREADS=10 \
  adven27/grpc-wiremock

7. 保留Proto字段名

默认存根中需使用lowerCamelCase引用proto字段（如proto字段user_id需写为userId）。设置JSON_PRESERVING_PROTO_FIELD_NAMES=true可保留原始字段名：

posh
docker run -e JSON_PRESERVING_PROTO_FIELD_NAMES=true adven27/grpc-wiremock