🎯 规则管理

HTTP Mock 规则定义「什么请求命中、命中后返回什么」。管理后台「HTTP Mock → 规则」页面进行配置。

规则结构

字段	说明
名称	规则名称
方法	请求方法，可配置多个；空 / ANY 表示匹配所有方法
路径	可配置多个接口地址，支持 :id 路径参数（如 /api/user/:id）
请求头匹配	请求头条件列表（见下）
Query 匹配	查询参数条件列表
请求体匹配	请求体（JSON / 表单字段）条件列表
模式	mock / proxy / replay
录制	proxy 模式下是否录制请求 / 响应
响应状态码	mock 响应状态码
响应头	mock 响应头（支持模板）
响应体	mock 响应体（支持模板）
延迟	模拟响应延迟（毫秒）
优先级	数值越小越优先
启用	是否参与匹配

匹配流程

• 规则按 优先级（priority，越小越优先） 依次匹配，命中即返回
• 同优先级下按规则顺序匹配
• 服务必须为启用状态，其下规则才参与匹配

路径参数

路径中的 :name 会被解析为路径参数，可在模板中通过 {{ .pathParams.name }} 引用：

路径: /api/user/:id
请求: GET /api/user/1001   →  {{ .pathParams.id }} = "1001"

请求体匹配

matchBody 使用点号路径定位 JSON 嵌套字段：

matchBody:
    - name: user.name      # 匹配 {"user":{"name":"tom"}}
      value: tom
    - name: list.0.id      # 匹配 {"list":[{"id":"10"}]}
      value: "10"

三种响应模式

mock — 直接返回

命中后返回配置的状态码、响应头与响应体，不访问下游：

mode: mock
responseStatus: 200
responseHeaders:
    - name: Content-Type
      value: application/json
responseBody: '{"id":1,"name":"demo"}'

proxy — 透传转发

命中后将请求转发到服务配置的 upstreamUrl，返回下游真实响应。record: true 时录制请求与响应，供 录制与回放 使用。

replay — 重放历史响应

命中后返回该路径历史上录制的真实响应，用于「同一接口、换数据返回」的场景。

模拟延迟

delayMs 配置响应延迟毫秒数，模拟真实网络耗时。可用于联调超时 / 性能场景。

示例

示例 1：基础 Mock

name: 获取用户
methods: [GET]
paths: [/api/user/:id]
mode: mock
responseStatus: 200
responseHeaders:
    - name: Content-Type
      value: application/json
responseBody: '{"id":1,"name":"demo"}'

示例 2：请求体条件匹配

name: 多字段匹配
methods: [POST]
paths: [/api/test/multi]
matchBody:
    - name: user.name
      value: tom
    - name: list.0.id
      value: "10"
mode: mock
responseBody: '{"ok":true,"matched":"multi"}'

示例 3：模板变量

name: 模板变量示例
methods: [GET]
paths: [/api/echo/:id]
mode: mock
responseBody: '{"path":"{{ .pathParams.id }}","q":"{{ .query.name }}","uuid":"{{ uuid }}"}'

完整模板函数见 模板函数。

示例 4：透传并录制

name: 汇率查询
methods: [GET]
paths: [/api/exchange-rates]
mode: proxy
record: true

规则导入 / 导出

规则支持导出为 JSON 文件与导入，便于跨环境复用与备份：

• 导出：GET /api/rules/export
• 导入：POST /api/rules/import