bavix/gripmock

GripMock

概述

GripMock 是一个 gRPC 服务的 mock 服务器，通过 .proto 文件或编译后的 .pb 描述符生成 gRPC 服务实现。您可以使用它搭建端到端测试环境，或在软件开发阶段作为虚拟服务器使用。服务器使用 Go 语言实现，客户端可支持任何编程语言的 gRPC 客户端。

本项目是 https://github.com/tokopedia/gripmock 的分支版本，具有更优的性能和更多增强功能，包括更新依赖、支持 YAML 静态存根、健康检查端点等。

核心功能

• 多源输入支持：通过 .proto 文件、包含多个 .proto 文件的文件夹或编译后的 .pb 描述符启动服务
• 灵活存根机制：支持动态存根（REST API 实时管理）和静态存根（文件初始化），静态存根兼容 JSON 和 YAML 格式
• 健康检查：提供 /api/health/liveness 和 /api/health/readiness 端点
• 高级匹配规则：输入和请求头支持 equals（精确匹配）、contains（包含匹配）、matches（正则匹配），支持嵌套字段和 ignoreArrayOrder（忽略数组顺序）
• 增强特性：支持 gRPC 请求头、自定义错误码、gzip 编码，修复 int64/uint64 处理问题，为未找到的存根返回 404 错误
• 轻量高效：减小镜像体积，支持二进制 .pb 描述符以加快启动速度

适用场景

• 端到端测试：为 gRPC 客户端提供模拟服务，验证完整业务流程
• 开发阶段虚拟服务：在后端服务未就绪时，为前端/客户端开发提供可用的 gRPC 服务
• 跨语言兼容性测试：支持任何语言的 gRPC 客户端连接，验证多语言交互场景

安装与部署

安装方式

Docker 镜像（推荐）

bash
docker pull bavix/gripmock

其他安装方式

• Homebrew（macOS/Linux）：

  bash
  brew tap bavix/homebrew-gripmock
  brew install gripmock
  

• 预编译二进制：从 https://github.com/bavix/gripmock/releases 下载对应平台的二进制文件并添加到 PATH

• Go 直接安装：

  bash
  go install github.com/bavix/gripmock/v3@latest
  

编译 .pb 描述符（可选）

对于复杂项目，推荐编译 .pb 描述符以加快启动速度：

使用 protoc：

bash
protoc --proto_path=. --descriptor_set_out=service.pb --include_imports hello.proto

使用 buf：

bash
buf build -o service.pb

使用方法

本地运行

基础启动

bash
# 通过 .pb 文件启动
gripmock service.pb

# 通过 .proto 文件启动
gripmock service.proto

# 通过包含 .proto 文件的文件夹启动
gripmock protofolder/

静态存根启动

指定包含静态存根文件的文件夹：

bash
# 文件夹中的 proto 文件
gripmock --stub stubfolder/ protofolder/

# 单个 proto 文件
gripmock --stub stubfolder/ service.proto

# 预编译 .pb 文件
gripmock --stub stubfolder/ service.pb

Docker 运行

文件夹中的 proto 文件

bash
docker run -p 4770:4770 -p 4771:4771 \
  -v /本地存根文件夹:/stubs \
  -v /本地proto文件夹:/proto \
  bavix/gripmock /proto/

单个 proto 文件

bash
docker run -p 4770:4770 -p 4771:4771 \
  -v /本地存根文件夹:/stubs \
  -v /本地proto文件夹:/proto \
  bavix/gripmock /proto/service.proto

预编译 .pb 文件

bash
docker run -p 4770:4770 -p 4771:4771 \
  -v /本地存根文件夹:/stubs \
  -v /本地pb文件路径:/proto \
  bavix/gripmock /proto/service.pb

端口说明：

• 4770：gRPC 服务端口（客户端连接）
• 4771：HTTP 管理端口（Web UI 和 REST API）

存根配置详解

动态存根管理

通过 HTTP 存根服务器（端口 4771）管理存根，支持以下接口：

• GET /api/stubs：列出所有存根
• POST /api/stubs：添加新存根
• POST /api/stubs/search：搜索匹配的存根
• DELETE /api/stubs：清除所有存根

存根格式（JSON）

json
{
  "service": "Greeter",          // proto 中定义的服务名
  "method": "SayHello",          // 要模拟的方法名
  "headers": {                   // 可选，请求头匹配规则
    "equals": { "authorization": "token" }
  },
  "input": {                     // 输入匹配规则
    "ignoreArrayOrder": true,    // 可选，忽略数组顺序
    "equals": { "name": "gripmock" }
  },
  "output": {                    // 匹配成功的输出
    "data": { "message": "Hello" },  // 响应数据
    "headers": { "x-resp": "ok" },   // 可选，响应头
    "error": "错误信息",             // 可选，错误消息（指定则返回错误）
    "code": "2"                     // 可选，gRPC 错误码（非 0 则返回错误）
  }
}

添加动态存根示例

bash
curl -X POST -H "Content-Type: application/json" -d '{
  "service": "Greeter",
  "method": "SayHello",
  "input": { "equals": { "name": "gripmock" } },
  "output": { "data": { "message": "Hello GripMock" } }
}' http://localhost:4771/api/stubs

静态存根

将存根文件（JSON/YAML 格式）放置在文件夹中，通过 --stub 参数指定：

yaml
# stub.yaml 示例
- service: Greeter
  method: SayHello
  input:
    equals:
      name: gripmock
  output:
    data:
      message: Hello GripMock

启动命令：

bash
# 本地
gripmock --stub ./stubfolder ./service.proto

# Docker
docker run -p 4770:4770 -p 4771:4771 \
  -v /本地存根文件夹:/stubs \
  -v /本地proto文件夹:/proto \
  bavix/gripmock --stub /stubs /proto/service.proto

匹配规则详解

输入匹配规则

支持三种匹配方式，可作用于嵌套字段和数组：

equals（精确匹配）

匹配输入中指定字段的精确值（默认检查数组顺序）：

json
"input": {
  "equals": {
    "name": "gripmock",
    "greetings": { "english": "Hello" },
    "numbers": [1, 2, 3],
    "active": true
  }
}

contains（包含匹配）

匹配输入中包含指定字段及值：

json
"input": {
  "contains": {
    "user": { "id": "123" },
    "tags": ["test"]
  }
}

matches（正则匹配）

使用正则表达式匹配字符串字段：

json
"input": {
  "matches": {
    "email": "^[a-z]+@example\\.com$",
    "id": "^\\d{6}$"
  }
}

ignoreArrayOrder（忽略数组顺序）

配合 equals 使用，忽略数组元素顺序：

json
"input": {
  "ignoreArrayOrder": true,
  "equals": { "numbers": [3, 1, 2] }  // 匹配 [1,2,3]、[2,1,3] 等
}

请求头匹配规则

与输入匹配规则类似，支持 equals、contains、matches：

json
"headers": {
  "equals": { "authorization": "Bearer token" },
  "contains": { "x-version": "v1" },
  "matches": { "request-id": "^[a-f0-9-]+$" }
}

许可证

本项目采用 MIT 许可证，详情参见 https://github.com/bavix/gripmock/blob/master/LICENSE%E3%80%82