travix/gozzmock

gozzmock Docker镜像文档

镜像概述

gozzmock是一个基于Golang开发的Mock服务器，灵感来源于mock-server.com。Travix公司使用该工具在测试环境中隔离第三方服务依赖，实现"透明"Mock功能——部分请求可被模拟，其他请求则转发至真实端点。

核心功能与特性

• 透明代理：可配置将特定请求转发至真实服务端点
• 自定义响应：通过期望(expectation)配置返回自定义响应内容、状态码和头信息
• 灵活匹配：支持基于HTTP方法、路径（含查询参数）、请求体和头信息的匹配，路径支持正则表达式和子字符串匹配
• API管理：提供REST API用于添加、删除和查询期望规则
• 优先级控制：支持为期望设置优先级，决定匹配顺序
• 延迟响应：可配置响应延迟，模拟网络延迟场景

使用场景

• 测试环境隔离第三方服务依赖，避免外部服务不稳定影响测试
• API契约测试，模拟各种响应场景（成功、错误、超时等）
• 前端开发时无后端服务依赖，使用模拟数据进行开发
• 模拟第三方API的特定行为，验证系统在不同响应下的表现

安装与基本使用

安装镜像

bash
docker pull travix/gozzmock

基本运行

bash
docker run -it -p 8080:8080 travix/gozzmock

详细使用示例

示例1：配置请求转发

目标：将访问/user的请求转发至GitHub API（https://api.github.com/user%EF%BC%89

1. 添加转发期望：

bash
curl -d '{"forward":{"host":"api.github.com","scheme":"https"},"key":"forwardExpectation"}' -X POST http://<主机IP>:8080/gozzmock/add_expectation

2. 验证转发效果：

bash
curl http://<主机IP>:8080/user

返回GitHub API的真实响应：

json
{
  "message": "Requires authentication",
  "documentation_url": "https://developer.github.com/v3"
}

示例2：配置自定义响应

目标：对包含"mocked"路径的请求返回自定义文本响应

1. 添加响应期望：

bash
curl -d '{"key":"responseExpectation","request":{"method":"GET","path":"mocked"},"response":{"body":"response from gozzmock","headers":[{"Content-Type":"text/plain; charset=utf-8"}],"httpcode":200},"priority":1}' -X POST http://<主机IP>:8080/gozzmock/add_expectation

2. 验证自定义响应：

以下请求均会返回自定义响应：

bash
curl http://<主机IP>:8080/user?arg=mocked
curl http://<主机IP>:8080/user?mocked
curl http://<主机IP>:8080/user/mocked

响应内容：

response from gozzmock

示例3：删除期望

删除上述"responseExpectation"期望：

bash
curl -d '{"key":"responseExpectation"}' -X POST http://<主机IP>:8080/gozzmock/remove_expectation

配置参数

运行参数

• loglevel：日志级别，可选值：debug、info、warn、error、fatal、panic，默认值：debug
• expectations：启动时加载的期望规则JSON数组，默认值：空

示例：带参数运行

bash
docker run -it -p 8080:8080 travix/gozzmock --expectations="[{\"key\": \"k1\"},{\"key\": \"k2\"}]" --loglevel=info

期望规则结构

根级别字段

• key：期望的唯一标识符，重复key会覆盖原有规则
• priority（可选）：优先级，数值越小优先级越高，决定匹配顺序
• delay（可选）：响应延迟时间（秒）
• request：请求匹配条件块
• response：响应内容块（与forward二选一）
• forward：转发配置块（与response二选一）

注意：response和forward只能配置一个

Request块（请求匹配条件）

• method：HTTP方法（如GET、POST等）
• path：请求路径，支持正则表达式（如".*"）或子字符串匹配（如"abc"）
• body：请求体内容
• headers：请求头信息

Forward块（转发配置）

• scheme：目标协议（HTTP或HTTPS）
• host：目标主机名，替换原始请求的主机
• headers：转发时添加或替换的头信息

Response块（响应配置）

• body：响应体内容
• headers：响应头信息（数组形式）
• httpcode：HTTP状态码

管理端点

• /gozzmock/status：状态检查端点，用于健康检查
• /gozzmock/add_expectation：添加或更新期望规则（POST请求）
• /gozzmock/remove_expectation：按key删除期望规则（POST请求）
• /gozzmock/get_expectations：获取所有已配置的期望规则（GET请求）