nanomock

nanomock 是一个基于Go语言开发的、轻量级的HTTP模拟（Mock）服务器。它通过一个简单的JSON配置文件，即可实现高度定制化的API响应，是前端开发、API集成测试和微服务解耦的理想工具。

✨ 功能特性

动态配置：所有行为均由 config.json 文件定义，无需重新编译即可修改API行为。
灵活的路由：支持精确路径匹配、路径变量（如 /users/{id}）和子树通配符（如 /static/）。
完全自定义响应：可为每个路由独立配置HTTP状态码、响应头部（Headers）和响应体（Body）。
动态响应体：支持将URL中的路径参数动态注入到响应体中。
环境变量支持：可通过 PORT 环境变量覆盖配置文件中的端口设置。
轻量与高效：基于Go标准库构建，无任何第三方依赖，保证了极低的内存占用和飞快的启动速度。
容器化友好：提供多阶段构建的 Dockerfile，可生成数十兆大小的极小镜像，便于部署。

🚀 快速开始

环境要求

Go: 1.22 或更高版本
OpenSSL: (可选) 用于生成本地开发证书
Docker: (可选) 用于容器化部署

本地运行

构建应用

在项目根目录下，运行以下命令编译生成可执行文件：
```
go build -o nanomock ./cmd/nanomock
```
运行服务 (HTTP)

如果你的 config.json 端口不是 443，服务将以普通HTTP模式启动。
```
./nanomock
```
运行服务 (HTTPS)

自动模式 (推荐):
- 将 config.json 中的端口设置为 "443"。
- 确保 certs/ 目录下存在 cert.pem 和 key.pem 文件。
- 直接运行 ./nanomock，服务会自动以HTTPS模式启动。
手动模式 (高级):
- 使用 --cert-file 和 --key-file 标志指定证书和密钥路径，可用于在任意端口启动HTTPS服务。
```
./nanomock --port=8443 --cert-file=/path/to/your/cert.pem --key-file=/path/to/your/key.pem
```

如何生成本地证书

如果你没有证书，可以使用 openssl 在 certs/ 目录下生成一个用于本地开发的自签名证书：


openssl req -x509 -newkey rsa:2048 -nodes -keyout certs/key.pem -out certs/cert.pem -days 36500 -subj "/C=US/ST=CA/L=SF/O=Nanomock/CN=localhost"

Docker 运行

构建Docker镜像
```
docker build -t nanomock .
```
运行Docker容器

以下命令将启动一个容器，并将容器的 3000 端口映射到主机的 8080 端口。（假设你的 config.json 中端口设置为 3000）
```
docker run --rm -p 8080:3000 nanomock
```
你也可以通过 -e 标志来覆盖端口配置：
```
docker run --rm -p 8888:8888 -e PORT=8888 nanomock
```

⚙️ 配置文件 (`config.json`)

这是 nanomock 的核心，用于定义服务的全部行为。


{
  "port": "3000",
  "defaultResponse": {
    "statusCode": 404,
    "headers": {
      "Content-Type": "application/json"
    },
    "body": "{\"error\": \"Not Found\"}"
  },
  "routes": [
    // ... 路由规则列表
  ]
}

port: (字符串) 服务监听的端口。
defaultResponse: (对象) 当没有匹配到任何路由时返回的默认响应。

路由规则 (`routes`)

routes 是一个数组，其中每个对象定义了一条路由规则。

1. 精确匹配


{
  "path": "/api/health",
  "method": "GET",
  "response": {
    "statusCode": 200,
    "headers": {"Content-Type": "application/json"},
    "body": "{\"status\": \"ok\"}"
  }
}

path: 必须精确匹配URL路径。
method: 必须匹配HTTP请求方法。

2. 路径参数匹配


{
  "path": "/api/users/{id}",
  "method": "GET",
  "response": {
    "statusCode": 200,
    "headers": {"X-Custom-Header": "Mocked-Response"},
    "body": "{\"user_id\": \"__PARAM_id__\", \"message\": \"...\"}"
  }
}

path 中的 {id} 可以匹配路径中的任意单个段，例如 /api/users/123。
body 中的 __PARAM_id__ 会被URL中 id 位置的实际值（123）动态替换。

3. 子树通配符匹配


{
  "path": "/api/v1/test/",
  "method": "GET",
  "response": {
    "statusCode": 200,
    "body": "{\"message\": \"Caught by subtree wildcard\"}"
  }
}

path 以 / 结尾，可以匹配其下的所有子路径，无论层级多深。例如，/api/v1/test/a 和 /api/v1/test/a/b/c 都会被此规则捕获。

🧪 测试

项目内置了一个全面的测试脚本，可以验证所有核心功能和健壮性。

测试用例概览

测试类别	测试项	请求	预期行为
功能测试	健康检查	`GET /api/health`	返回 200 OK 和 `{"status":"ok"}`
功能测试	路径参数	`GET /api/users/42`	返回 200 OK, 自定义Header, 且响应体中包含 `"user_id":"42"`
功能测试	子树通配符	`POST /api/v2/some/path`	返回 201 Created
功能测试	未找到的路由	`GET /non/existent/route`	返回 404 Not Found 和默认错误体
健壮性测试	配置文件格式错误	`N/A`	服务启动失败，并打印 `FATAL` 日志
健壮性测试	配置文件缺失	`N/A`	服务启动失败，并打印 `FATAL` 日志