gguridi/mockserver

mockserver

镜像概述和主要用途

mockserver是namshi/mockserver的重新实现，旨在解决原项目缺乏维护和功能不足的问题。它允许通过文件目录结构和命名规则模拟API响应，支持多文件导入、代码评估、中间件等扩展功能，适用于API开发测试、前端与后端并行开发时的接口模拟场景。

核心功能和特性

• 多文件导入：可组合不同文件数据，轻松创建REST端点同时保持数据一致性。
• 多代码评估：在响应体、头或状态中支持多次代码评估，可访问请求和文件路径信息。
• 中间件支持：可添加before或after中间件，为所有请求添加通用功能或实现复杂逻辑。
• 改进的请求匹配：支持 headers 与查询参数组合匹配，JSON 请求体自动序列化为URL参数以便文件名匹配。
• 灵活的日志级别：基于winston日志库，支持调整日志详细程度（debug、info、error等）。
• 响应延迟控制：通过Response-Delay头设置响应延迟时间（毫秒）。
• 多种请求体解析器：支持json、text、raw、urlencoded等解析方式，适应不同API类型。

使用场景和适用范围

• API接口开发初期，前端需要模拟后端响应进行开发。
• 单元测试或集成测试中，需要模拟第三方API或数据库响应。
• 演示环境中，无需真实后端服务即可展示API功能。
• 前后端并行开发时，前端可基于约定的接口规范提前开发。

详细使用方法和配置说明

Docker部署示例

基本运行命令

bash
docker run -p 8080:8080 -v $(pwd)/mocks:/mocks gguridi/mockserver -m /mocks

自定义端口和日志级别

bash
docker run -p 9000:9000 -v $(pwd)/mocks:/mocks gguridi/mockserver -m /mocks -p 9000 -l debug

启用特定headers匹配

bash
docker run -e MOCK_HEADERS=Content-Type,Accept -p 8080:8080 -v $(pwd)/mocks:/mocks gguridi/mockserver -m /mocks

挂载中间件目录

bash
docker run -p 8080:8080 -v $(pwd)/mocks:/mocks -v $(pwd)/middlewares:/middlewares gguridi/mockserver -m /mocks -w /middlewares

docker-compose配置示例

yaml
version: '3'
services:
  mockserver:
    image: gguridi/mockserver
    ports:
      - "8080:8080"
    volumes:
      - ./mocks:/mocks           # 挂载mock文件目录
      - ./middlewares:/middlewares # 挂载中间件目录
    environment:
      - MOCK_HEADERS=Content-Type,Accept  # 设置用于匹配的headers
    command: -m /mocks -w /middlewares -p 8080 -l info  # 启动参数

核心配置参数

环境变量

Mock文件规则

文件命名格式

$REQUEST-PATH/${HTTP-METHOD}--${BODY}--${QUERY PARAMS}_${HEADERS}.mock

示例场景

当请求为：

• POST方法
• URL: /path/subpath/item?param1=value1
• 请求体: {"key":"value"}
• Headers: X-H1=h1, X-H2=h2（已通过-h X-H1,X-H2启用）

mockserver将按优先级检查以下文件（部分示例）：

/path/subpath/item/POST--param1=value1--key=value_X-H1=h1,X-H2=h2.mock
/path/subpath/item/POST--param1=value1--key=value_X-H1=h1.mock
/path/subpath/item/POST--param1=value1--key=value.mock
/path/subpath/item/POST--param1=value1.mock
/path/subpath/__/POST.mock  # 通配符目录匹配

通配符目录

使用__作为目录名可匹配动态路径片段，例如：

• 目录users/__可匹配/users/1、/users/2等路径
• 文件users/__/GET.mock将响应所有/users/*的GET请求

高级功能

多文件导入

在.mock文件中使用#import语法导入其他文件内容：

#import ./data.json;  # 导入JSON数据
#import ./utils.js;   # 导入并执行JS文件，注入返回值

示例：

json
{
  "user": #import ./user.json;,
  "orders": #import ./load-orders.js;
}

代码评估

使用{{ }}包裹代码片段，在响应中动态生成内容：

{{ request.body.id ? 200 : 404 }}  # 动态状态码
X-Request-ID: {{ Math.random().toString(36).substr(2, 9) }}  # 动态头

{{ 
  // 多行代码
  const now = new Date();
  `Current time: ${now.toISOString()}`;
}}

中间件

在中间件目录中创建before.js（请求处理前执行）和after.js（请求处理后执行）：

before.js示例：

javascript
const addTimestamp = (req, res, next) => {
  req.headers["X-Request-Time"] = new Date().toISOString();
  next();
};

module.exports = { addTimestamp };

中间件按导出顺序执行，可修改请求/响应对象，影响后续处理。

响应延迟

在.mock文件或中间件中添加Response-Delay头设置延迟：

Response-Delay: 2000  # 延迟2秒响应