wiremock-standalone-docker

WireMock 独立 Docker 技能

概述

介绍如何将 WireMock 作为独立的 Docker 容器运行，在集成测试和端到端测试期间模拟外部 API。将 WireMock 作为单独的服务运行，模拟真实 API 的行为，以便测试 HTTP 客户端、重试逻辑和错误处理。

何时使用

适用于以下场景：

• 在集成测试或端到端测试期间模拟外部 API
• 无需真实服务即可模拟错误情况（超时、5xx、速率限制）
• 测试 HTTP 客户端配置、重试逻辑和错误处理
• 创建可移植、可复现的测试环境
• 在实现真实服务之前验证 API 契约

说明

步骤 1：设置 Docker Compose

创建一个 docker-compose.yml，使用 WireMock 3.5.2，配置端口映射，并为映射和文件挂载卷：

version: "3.8"
services:
  wiremock:
    image: wiremock/wiremock:3.5.2
    ports:
      - "8080:8080"
    volumes:
      - ./wiremock:/home/wiremock
    command: ["--global-response-templating"]

步骤 2：创建目录结构

创建 WireMock 配置目录：

wiremock/
├── mappings/   # JSON stub definitions
└── __files/   # Response body files

步骤 3：定义 API 映射

在 wiremock/mappings/ 中为每种场景创建 JSON 桩文件：

• 成功：返回状态码 200 和 JSON 正文
• 未找到：返回状态码 404
• 服务器错误：返回状态码 500
• 超时：使用 fixedDelayMilliseconds
• 速率限制：返回状态码 429，并附带 Retry-After 标头

步骤 4：启动 WireMock

docker compose up -d

步骤 5：验证 WireMock 正在运行

curl http://localhost:8080/__admin/mappings

预期结果：如果未加载任何桩，则返回空数组 {"mappings":[]}；否则返回你的桩定义。如果遇到连接被拒绝，请检查容器是否正在运行：docker compose ps

步骤 6：配置 HTTP 客户端

将应用程序指向 http://localhost:8080（或 Docker 网络中的 http://wiremock:8080），而不是实际的 API。

步骤 7：测试边缘情况

务必测试：200、400、401、403、404、429、500、超时和格式错误的响应。

示例

示例 1：模拟成功的 GET 请求

{
  "request": { "method": "GET", "url": "/api/users/123" },
  "response": {
    "status": 200,
    "jsonBody": { "id": 123, "name": "Mario Rossi" }
  }
}

示例 2：模拟服务器错误

{
  "request": { "method": "GET", "url": "/api/error" },
  "response": { "status": 500, "body": "Internal Server Error" }
}

示例 3：模拟超时

{
  "request": { "method": "GET", "url": "/api/slow" },
  "response": {
    "status": 200,
    "fixedDelayMilliseconds": 5000,
    "jsonBody": { "message": "delayed" }
  }
}

示例 4：包含应用程序的 Docker Compose

services:
  wiremock:
    image: wiremock/wiremock:3.5.2
    ports:
      - "8080:8080"
    volumes:
      - ./wiremock:/home/wiremock

  app:
    build: .
    environment:
      - API_BASE_URL=http://wiremock:8080
    depends_on:
      - wiremock

最佳实践

1. 按功能组织映射：使用 users/、products/ 等子目录
2. 对映射进行版本控制：将映射保存在 git 中，以便复现测试
3. 测试所有错误场景：401、403、404、429、500、超时
4. 在每次测试运行之间重置：curl -X POST http://localhost:8080/__admin/reset
5. 使用描述性文件名：get-user-success.json、post-user-error.json

限制和警告

• 确保端口 8080 可用，或映射到其他端口
• 运行多个容器时配置 Docker 网络
• 启用 --global-response-templating 以使用动态响应
• 容器重启时，WireMock 会重置映射

故障排除

请求与桩不匹配？ 检查 WireMock 收到的内容：curl http://localhost:8080/__admin/requests——此命令会显示未匹配的请求，以及实际发送内容的详细信息。

桩文件未加载？ 验证文件位置：将 JSON 桩放在 wiremock/mappings/ 中，将响应文件放在 wiremock/__files/ 中。检查文件权限。

连接被拒绝？ 运行 docker compose ps，确认容器正在运行。使用 lsof -i :8080 检查端口冲突。

参考资料

完整示例见 references/：

• docker-compose.yml - 完整的 Docker Compose 配置
• wiremock/mappings/ - 涵盖所有场景的完整桩示例