测试、用例与 Mock
ApiGo 提供三层验证手段，分别解决「这一次能不能跑通」「以后改动有没有回归」「依赖没就绪时怎么联调」：
| 能力 | 作用 | 数据是否持久化 | 适用环境 |
|---|---|---|---|
| 在线测试 | 用当前编辑器内容发一次请求，查看响应与执行过程 | 否 | 开发中 |
| 测试用例 | 保存请求快照与期望结果，随时单条回放 | 是（接口维度） | dev |
| Mock 规则 | 用固定响应替代真实执行，供前端/调用方联调 | 是（独立缓存） | dev 隔离入口 |
测试用例与 Mock 规则都依附于已保存的接口。若接口尚未保存，页面会提示「请先保存接口」。
在线测试
入口与前置条件
在开发模式的工作台完成接口配置后，点击右侧面板的「测试」按钮打开测试弹窗。弹窗标题为「测试：接口名称」。
在线测试直接使用当前编辑器中的 SQL、代理配置或编排规则，不需要先保存或发布。这适合边改边验证。
构造请求
弹窗顶部按位置分为多个页签，仅展示当前接口实际支持的参数：
| 页签 | 内容 |
|---|---|
| Header | 请求头键值对，可逐行添加 |
| Query | 查询参数键值对，测试时会附加分页参数 |
| Path | 路径参数，按参数名与目标名映射 |
| Body | 请求体，按接口的 Body 模式输入 |
Body 的处理方式取决于模式：
- JSON：必须是合法 JSON，否则无法发送。
- 表单 / urlencoded：按参数 表逐项填写，自动组装为表单数据。
- 无 Body：接口不接收请求体，页签会提示「该请求没有 Body」。
请求地址栏展示当前接口地址占位，点击「发送」执行测试。
查看响应
发送后右侧展示响应结果：
| 信息 | 说明 |
|---|---|
| HTTP 状态 | 实际响应状态码；执行异常时展示错误码 |
| 响应耗时 | 从发送到收到结果的毫秒数 |
| 响应大小 | 响应内容的字节数并换算为 KB / MB |
| 响应体 | JSON 自动格式化；文本按原文展示 |
| 文件响应 | 二进制或下载类响应展示文件名、Content-Type、Base64 内容，可下载 |
测试成功提示「测试成功！」，失败时展示后端返回的错误信息。
编排执行轨迹
编排模式测试完成后，响应区下方会出现「执行轨迹」面板，按执行顺序列出节点：
| 字段 | 说明 |
|---|---|
| 状态 | 成功、失败、跳过 |
| 节点 | 节点名称或节点 ID |
| 迭代 | 循环节点的第几次迭代 |
| 耗时偏移 | 相对本次测试开始的毫秒偏移 |
| 输入 / 输出快照 | 展开后查看该节点的输入与输出 JSON |
轨迹用于定位「哪个节点没执行」「循环第几轮失败」「条件分支走了哪条」。未进入的分支节点会标记为「跳过」。
在线测试由管理端直接调用执行引擎，不经过网关的认证、限流、缓存与日志链路。它验证的是接口本身能否正确执行；网关治理效果需要用已发布接口的真实调用验证。
测试用例
测试用例把一次请求固化为可重复执行的断言，适合接口改动后的回归检查。
管理用例
在开发工作台右侧点击「测试用例」打开抽屉。列表按更新时间倒序展示：
| 列 | 说明 |
|---|---|
| 用例名称 | 便于识别的名称 |
| 启用 | 启用 / 停用状态 |
| 期望状态 | 期望的 HTTP 状态码 |
| 最近结果 | 未执行、success、fail |
| 最近执行时间 | 上一次执行的时间 |
| 操作 | 编辑、执行、删除 |
用例字段
| 字段 | 必填 | 说明 |
|---|---|---|
| 用例名称 | 是 | 不能为空 |
| 期望 HTTP 状态 | 否 | 100–599，默认 200 |
| 期望断言 | 否 | 响应内容包含该字符串时视为通过，可为空 |
| 请求 Header JSON | 否 | JSON 对象，默认 {} |
| Query 参数 JSON | 否 | JSON 对象，默认 {} |
| Path 参数 JSON | 否 | JSON 对象，默认 {} |
| 请求 Body | 否 | 合法 JSON；无 Body 时可留空 |
| 启用 | 否 | 停用后不参与回归 |
四个请求字段在保存前都会校验 JSON 合法性，非法时提示「请求参数必须是合法JSON」。
执行与判定
点击「执行」后，平台直接调用运行时回放该用例，判定规则为：
- 实际 HTTP 状态必须等于「期望 HTTP 状态」；
- 若填写了「期望断言」，响应体 JSON 中必须包含该字符串；
- 两项都满足记为 success，否则记为 fail，并记录「响应状态或断言不匹配」。
执行结果写回用例的「最近结果」「最近执行时间」，同时保存响应体快照。执行过程抛出的异常也记为 fail，错误信息写入最近结果。
测试用例的 envCode 固定为 dev，不区分其他环境。发布到测试/生产后，应通过真实调用或外部自动化工具验证。
从在线测试保存用例
在线测试成功后可直接点击「保存用例」，平台会把当前请求的 Header、Query、Path、Body 与响应状态保存为一条默认用例，用例名形如「接口名 默认用例」。这条用例随后可在测试用例抽屉中编辑和回放。
Mock 规则
Mock 用固定响应替代真实执行，适合数据库未就绪、第三方接口不稳定或前端需要提前联调的场景。
隔离入口
Mock 只服务独立的隔离入口，不占用正式 API 地址：
/mock/{envCode}{apiPath}
例如接口路径为 /user/detail，dev 环境的 Mock 地址为 /mock/dev/user/detail。工作台抽屉会直接展示该地址。
调用 Mock 入口需要满足：
- 请求头携带有效的
X-AppKey； - 应用处于启用状态。
缺少凭证或应用被禁用时返回 HTTP 401 与错误码，不会进入正式接口链路。
规则字段
| 字段 | 说明 |
|---|---|
| 启用 | 开关；停用后该规则不参与匹配 |
| 优先级 | 1–9999，默认 100；数值越小越先匹配 |
| 方法 | 取接口的请求方式 |
| 路径 | 取接口的接口地址 |
| 状态码 | 100–599，默认 200 |
| 延迟 | 0–60000 毫秒，默认 0；只延迟 Mock 响应 |
| 响应 Header | JSON 对象，如 {"Content-Type":"application/json;charset=UTF-8"} |
| 响应 Body | JSON 内容；留空时自动使用默认预览响应 |
点击「使用默认响应预览」会根据接口的响应参数定义生成示例：
- 优先使用参数的「示例值」；
- 其次使用「默认值」；
- 都没有时按类型生成：数值为 0、布尔为 false、数组为
[]、对象为{}、字符串为空串。
匹配顺序
网关按以下条件筛选规则：
- 规则已启用；
- 环境编码一致；
- 请求方法一致；
- 请求路径与规则路径精确相等；若规则配置了 Ant 风格匹配表达式，则按表达式匹配；
- 多条规则命中时取优先级最小的那条，优先级为空视为最低。
规则变更保存后会刷新网关缓存；网关侧还有 30 秒本地缓存，极短时间内可能读到旧规则。
发布限制
启用 Mock 的接口只能用于开发环境联调。把接口同步到其他环境时会被拒绝，并提示：
接口启用了 Mock 数据，仅允许发布到开发环境联调，请关闭 Mock 后再同步到目标环境
因此上线前必须关闭该接口的全部 Mock 规则。
使用建议
- Mock 响应体保持为合法 JSON，便于前端按正式结构解析。
- 用多条规则覆盖同一接口的不同路径或不同场景，通过优先级控制兜底规则。
- Mock 只验证调用方与契约，不验证 SQL、代理或编排逻辑；真实逻辑仍需在线测试与用例覆盖。
- Mock 规则不进入正式发布快照，也不会同步到其他环境。
常见问题
| 现象 | 可能原因 | 处理 |
|---|---|---|
| 点击测试用例 / Mock 提示先保存接口 | 接口还是未持久化的临时页签 | 先保存接口 |
| 在线测试 Body 无法发送 | JSON 非法 | 修正 JSON 或切换为表单模式 |
| 用例执行失败但接口在线测试正常 | 期望状态或断言不匹配 | 核对期望状态、断言字符串与响应体 |
| Mock 返回 401 | 缺少 X-AppKey 或应用被禁用 | 携带有效应用凭证并确认应用启用 |
| Mock 未命中，落到真实接口 | 环境、方法、路径不一致或规则未启用 | 核对隔离地址、请求方法与规则状态 |
| 同步到测试环境被拒绝 | 接口仍有启用的 Mock 规则 | 关闭全部 Mock 规则后重试 |
| 编排轨迹缺少某节点 | 条件分支未命中或节点被跳过 | 展开轨迹确认分支与「跳过」状态 |