APISIX Mocking 插件实践：接口 Mock、临时降级与兜底响应

APISIX 的 mocking 插件可以让网关直接返回模拟响应，而不再把请求转发到真实上游服务。它常用于开发联调、接口临时兜底、故障演练和简单降级场景。

需要注意：mocking 插件不是完整意义上的熔断器。真正的熔断治理通常还需要结合限流、超时、健康检查、故障检测、fallback、告警和发布流程。mocking 更适合“我明确知道这个接口要临时返回一个固定响应”的场景。

相关系列文章：

• APISIX 入门指南：核心概念、Docker 部署与基础路由配置
• APISIX Dashboard 使用指南：路由、服务、上游与插件配置实践

适用场景

mocking 插件适合：

• 后端接口尚未开发完成，前端需要联调。
• 第三方接口异常，临时返回兜底数据。
• 大促或故障期间，对非核心接口返回简化响应。
• 压测或演示环境中模拟固定结果。
• 对某些接口进行临时降级。

不适合：

• 复杂业务补偿。
• 需要按用户、订单、状态动态计算响应。
• 需要完整熔断状态机的场景。
• 强一致交易链路。

配置入口

可以通过 Admin API 配置，也可以通过 APISIX Dashboard 可视化配置。

Dashboard 操作路径通常是：

路由 / 服务 -> 插件配置 -> mocking -> 启用 -> 填写配置 -> 提交

原操作截图如下：

配置示例

示例：返回一个固定 JSON 响应。

{
  "content_type": "application/json",
  "delay": 0,
  "response_status": 200,
  "response_example": "{\"code\":0,\"data\":[],\"msg\":\"操作成功\"}",
  "with_mock_header": false
}

参数说明：

旧配置中可能出现 disable 字段。实际使用时建议以当前 APISIX 官方文档的插件 Schema 为准，避免因版本差异导致配置不生效。

Admin API 示例

给某个路由启用 mocking：

curl -i "http://127.0.0.1:9180/apisix/admin/routes/mock-demo" \
  -H "X-API-KEY: your-admin-key" \
  -X PUT \
  -d '{
    "uri": "/mock/users",
    "plugins": {
      "mocking": {
        "content_type": "application/json",
        "response_status": 200,
        "response_example": "{\"code\":0,\"data\":[],\"msg\":\"mock success\"}",
        "with_mock_header": true
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "127.0.0.1:1980": 1
      }
    }
  }'

访问验证：

curl -i "http://127.0.0.1:9080/mock/users"

如果返回配置的 JSON，说明 mock 已生效。

与熔断降级的边界

很多人会把 mocking 当成“熔断降级”，但它们有边界差异：

因此，生产中可以把 mocking 作为兜底手段，但不要把它当成完整的故障治理方案。

生产使用建议

1. 明确启用范围

   • 优先绑定到具体 Route，不要随意全局启用。

2. 控制响应内容

   • 不要返回误导调用方的“假成功”，特别是交易、支付、库存类接口。

3. 设置变更记录

   • 记录谁在什么时候对哪个接口启用了 mock。

4. 设置恢复时间

   • 临时降级要有恢复计划，避免长期遗留。

5. 结合告警

   • 启用 mock 期间应有监控和告警，避免业务长期处于降级状态。

常见问题

1. 配置后仍然访问真实上游

检查：

• 插件是否启用。
• 插件绑定的是 Route、Service 还是其他层级。
• 当前请求是否命中该 Route。
• 是否存在优先级更高的路由。

2. 返回内容不是合法 JSON

检查：

• response_example 是否是字符串。
• 内部双引号是否正确转义。
• content_type 是否设置为 application/json。

3. 不知道是否命中 mock

可以开启 with_mock_header，让响应头包含 mock 标识，方便调试和排查。

总结

APISIX mocking 插件很适合做接口 Mock 和临时兜底，但它不是完整的熔断治理系统。生产使用时要明确启用范围、记录变更、控制返回内容，并设置恢复计划。

参考资料

• Apache APISIX mocking 插件官方文档
• Apache APISIX Plugins
• APISIX Dashboard 使用指南：路由、服务、上游与插件配置实践