第3章 配置Mock Server基础：启动WireMock实例、静态JSON响应配置、端口与SSL设置

3.1 原理概述

WireMock 是一个基于 HTTP 的模拟服务库，能够在测试环境中代替真实 API 端点。其核心原理是在本地或远程启动一个轻量级 HTTP 服务器，通过预定义的请求匹配规则（URL、方法、Header、Body 等）返回对应的静态或动态响应。本章聚焦于 WireMock 最基础的使用模式：独立运行模式（Standalone）下的实例启动、静态 JSON 文件映射以及端口与 SSL 的初始配置。

静态 JSON 响应配置指的是将 Mock 响应内容预先写入 JSON 文件，WireMock 根据请求自动匹配并返回文件中的内容，无需编写额外的 Java 或 Python 代码。这种方式非常适合测试团队中不熟悉编程的成员参与 Mock 数据维护。

教学提示：学习本章前，请确保已从 wiremock.org 下载 wiremock-standalone 最新 JAR 包，并确认本地 JDK 版本为 11 或更高。

3.2 实现流程

配置 WireMock Mock Server 的完整流程分为以下 5 个步骤：

  1. 下载 Standalone JAR — 从 WireMock 官网或 Maven 中央仓库获取 wiremock-standalone-{version}.jar。
  2. 规划目录结构 — 在项目根目录下创建 __files（存放静态响应文件）和 mappings（存放匹配规则 JSON）两个文件夹。
  3. 编写静态 JSON 响应文件 — 在 __files 目录中创建实际的 JSON 响应内容。
  4. 编写映射规则文件 — 在 mappings 目录中创建 JSON 描述文件，定义请求如何匹配以及指向哪个响应文件。
  5. 启动 WireMock 实例 — 通过命令行指定端口、SSL 参数等启动服务，验证 Mock 是否正常工作。
核心原则：WireMock 启动时会自动扫描 mappings 目录下的所有 JSON 文件并注册为桩（Stub）。推荐将每个 Mock 端点拆分为独立的映射文件，便于团队并行维护。
WireMock独立模式启动与静态JSON响应流程 WireMock 独立模式 — 静态 JSON 响应流程 ① 下载 Standalone JAR ② 创建 __files + mappings ③ 编写 JSON 响应文件 (__files/xxx.json) ④ 映射规则 JSON (mappings/*.json) ⑤ 启动 WireMock 实例 --port 8080 --https-port 8443 验证方法 curl http://localhost:8080/api/vi/user

3.3 目录结构与静态 JSON 响应配置

WireMock 独立模式下，工作目录的约定结构如下：

project-root/
├── wiremock-standalone-3.3.1.jar
├── __files/                        # 存放静态响应文件
│   ├── api/vi/user.json
│   └── api/vi/products.json
└── mappings/                       # 存放请求映射规则
    ├── user-get-stub.json
    └── product-list-stub.json

3.4 静态 JSON 响应文件示例

在 __files/api/vi/user.json 中编写如下内容：

{
    "id": 1001,
    "name": "张三",
    "email": "zhangsan@example.com",
    "role": "developer",
    "created_at": "2025-03-01T10:30:00Z"
}

在 mappings/user-get-stub.json 中定义匹配规则，指向上述响应文件：

{
    "request": {
        "method": "GET",
        "url": "/api/vi/user"
    },
    "response": {
        "status": 200,
        "headers": {
            "Content-Type": "application/json; charset=utf-8"
        },
        "bodyFileName": "api/vi/user.json"
    }
}
常见错误： bodyFileName 的值是相对于 __files 目录的路径，不要写成路径或包含 __files 前缀。如果响应文件找不到，WireMock 会返回 500 并在控制台输出 File not found 警告。

3.5 启动 WireMock 实例：端口与 SSL 设置

以下为三种典型启动场景的命令行示例：

场景 命令 说明
默认端口 (8080) java -jar wiremock-standalone-3.3.1.jar HTTP 监听 0.0.0.0:8080
自定义 HTTP 端口 java -jar wiremock-standalone-3.3.1.jar --port 9090 HTTP 监听 0.0.0.0:9090
启用 HTTPS java -jar wiremock-standalone-3.3.1.jar --port 8080 --https-port 8443 HTTP 8080 + HTTPS 8443

启动成功后，控制台输出类似以下日志：

WireMock server started at http://0.0.0.0:8080
HTTPS server started at https://0.0.0.0:8443
Using current directory as root: /path/to/project-root

3.6 SSL 证书与安全配置

WireMock 默认使用自签名证书启用 HTTPS。如果测试客户端需要信任该证书，可以导出证书并添加到信任库中：

# 导出 WireMock 自签名证书（默认别名 wiremock）
keytool -export -alias wiremock -keystore ~/.wiremock/wiremock-ssl.p12 \
        -storepass password -file wiremock-cert.cer

# 导入到测试环境的信任库
keytool -import -alias wiremock -file wiremock-cert.cer \
        -keystore /path/to/truststore.jks -storepass changeit
生产建议：在持续集成（CI）环境中，推荐使用 --https-keystore 和 --https-keystore-password 参数指定自定义 PKCS12 密钥库，避免使用默认自签名证书导致的 SSL 握手警告。

3.7 调试：验证 Mock 是否生效

使用 curl 或 Postman 发送请求，验证 WireMock 是否按预期返回静态 JSON：

# 测试 HTTP 端点
curl -i http://localhost:8080/api/vi/user

# 测试 HTTPS 端点（忽略证书验证）
curl -ik https://localhost:8443/api/vi/user

预期响应示例（HTTP 200）：

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Matched-Stub-Id: 6a3f2e1c-8d4b-4f7a-9c2e-1b0d5e8f7a3b

{"id":1001,"name":"张三","email":"zhangsan@example.com","role":"developer","created_at":"2025-03-01T10:30:00Z"}

响应头中的 Matched-Stub-Id 是 WireMock 自动添加的调试标识，可用于确认匹配到了哪个映射规则。

3.8 常见错误与解决方案

错误现象 原因 解决方案
启动时端口占用 端口已被其他进程使用 使用 --port 指定其他可用端口，或终止占用进程
请求返回 500 Internal Server Error bodyFileName 指向的文件不存在或路径错误 检查 __files 下的相对路径是否与实际文件一致
HTTPS 连接被拒绝 未启用 --https-port 参数 启动时添加 --https-port 8443
SSL 握手失败/证书不信任 客户端不信任 WireMock 自签名证书 添加 -k 标志（curl）或导入证书到信任库
中文响应内容乱码 未正确设置 Content-Type 中的 charset 在映射规则 response.headers 中明确指定 charset=utf-8

3.9 性能与稳定性优化

虽然 WireMock 独立模式本身已是轻量级服务，但在高频测试场景或 CI 流水线中仍需关注以下几点：

  • 限制最大连接数：使用 --max-http-connections 200 参数控制并发连接数，防止瞬时高负载导致服务无响应。
  • 启用异步日志：添加 --async-response-enabled true 可减少同步 I/O 阻塞，提升响应吞吐量。
  • 使用内存文件系统：在 Docker 或 Linux 环境下，将 __files 和 mappings 挂载到 tmpfs，可降低磁盘 I/O 延迟。
  • 固定 JVM 堆内存：启动时设置 -Xms128m -Xmx256m，避免 JVM 动态调整堆大小带来的性能抖动。
  • 预热桩（Warm-up）：在测试套件执行前，先发送一次请求让 WireMock 完成映射规则的类加载和缓存，消除首次请求的冷启动延迟。
稳定性最佳实践：在 CI 流水线中，建议为每个测试任务启动独立的 WireMock 实例（分配不同端口），任务结束后强制终止进程。这比复用同一个实例更可靠，能有效避免映射冲突和端口泄漏。

3.10 本章小结

通过本章的学习，你已经掌握了：

  • WireMock 独立模式的启动原理与目录约定
  • 如何编写静态 JSON 响应文件以及对应的映射规则 JSON
  • 通过 --port 和 --https-port 参数配置 HTTP/HTTPS 监听地址
  • 如何使用 curl 验证 Mock 响应并进行基本故障排查
  • 生产环境下的性能调优与稳定性加固措施
← 上一章 📖 返回目录 下一章 →