mock-server/.claude/rules/mock-spec.md

paths

paths
mocks/**/*.json

JSON 配置规范

AI 在生成 Mock 规则时必须遵循以下格式。

字段说明

字段	类型	必填	说明
name	string	是	规则唯一标识
request.method	string	是	HTTP 方法 (GET/POST/PUT/DELETE...)
request.path	string	是	请求路径，精确匹配
request.query_params	object	否	查询参数匹配
request.headers	object	否	请求头匹配（大小写不敏感）
request.body	any	否	请求体匹配，支持 JSON 对象或字符串
response.status	number	是	HTTP 状态码
response.headers	object	否	响应头
response.body	string	是	响应体，支持 file:// 前缀
settings.delay_ms	number	否	延迟响应（毫秒）

匹配规则

1. 路径精确匹配（非前缀匹配）
2. 请求头匹配大小写不敏感
3. Body 匹配支持 JSON 对象或字符串比较

配置示例

基础示例：

{
  "name": "login",
  "request": {
    "method": "POST",
    "path": "/v1/auth/login",
    "body": {
      "username": "user001",
      "password": "password123"
    }
  },
  "response": {
    "status": 200,
    "headers": {
      "Content-Type": "application/json"
    },
    "body": "{\"token\": \"xxx\"}"
  },
  "settings": {
    "delay_ms": 100
  }
}

带查询参数和请求头：

{
  "name": "search_users",
  "request": {
    "method": "GET",
    "path": "/v1/users",
    "query_params": {
      "role": "admin"
    },
    "headers": {
      "Authorization": "Bearer token"
    }
  },
  "response": {
    "status": 200,
    "headers": {
      "X-Total-Count": "100"
    },
    "body": "{\"users\": []}"
  }
}

文件响应：

{
  "name": "download_pdf",
  "request": {
    "method": "GET",
    "path": "/v1/download"
  },
  "response": {
    "status": 200,
    "headers": {
      "Content-Type": "application/pdf"
    },
    "body": "file://./storage/data/report.pdf"
  }
}

字符串格式 Body（兼容格式）：

{
  "name": "string_body_example",
  "request": {
    "method": "POST",
    "path": "/v1/api/test",
    "body": "{\"username\":\"user001\",\"password\":\"password123\"}"
  },
  "response": {
    "status": 200,
    "body": "{\"success\": true}"
  }
}

file:// 支持两种路径：

• 相对路径：file://./data/file.pdf（相对于项目根目录）
• 绝对路径：file:///C:/path/to/file.pdf