系列14-前后端分离联调：Mock 网关精确匹配、match_rules 边界与 AI 生成响应体

前后端并行时的经典矛盾前端要联调后端 Swagger 未定测试用 Postman Mock规则在个人账号里别人用不了有人用 nginx 写死 JSON版本一变全员改配置BrickCore 把 Mock 收成项目级资产方法 字面 path 可选 match_rules 响应经统一网关/api-module/mock-call/...对外。本文重点不是「点哪里新建」而是匹配语义容易踩的坑——这直接决定你能不能用 Mock 支撑多场景联调。/api-module/mock-call/...无 / 通过不通过草稿响应体前端 / 联调客户端Mock 网关mocks.pyMockApi 规则库method 字面 pathmatch_rules?status headers body可选 delay404mock_ai_service演示与源码地址功能演示http://180.76.142.97/showcase/ 文档「接口自动化 → Mock」平台 admin / BrickCore123456开源仓库https://gitee.com/BanZhuanKeOrz/BrickCore线上路径接口自动化 → Mock 服务菜单名不是「Mock 管理」。实现backend/app/routers/http/mocks.pyAIcore/llm/mock_ai_service.py。一、Mock 在测试体系里的位置适合不适合下游/第三方未就绪验证真实业务逻辑与事务前端并行、演示环境稳定返回压测 / 容量必须打真环境固定异常码、延迟、空列表复杂有状态会话机需专用 Mock Server契约草稿、异常分支演示替代全部契约测试 / CDC分工建议按阶段选型联调期前端 baseURL → mock-call契约期可选用例打 mock-call 做结构校验回归期环境 Host → 真测试服 Token容量期压测 Worker → 真 SUT禁止打 Mock文字版联调期 → 前端 baseURL 指向平台 mock-call 契约期 → 可选接口用例故意打 mock-call 做结构校验 回归期 → 环境 Host 切真测试服 Token 授权 容量期 → 压测 Worker 打真 SUT禁止打 Mock二、规则模型你真正在配置什么模型MockApi核心字段字段含义methodGET/POST/PUT/DELETE/PATCH…path字面路径精确字符串match_rules可选二次校验header / query / bodyresponse_status / headers / body返回内容response_delay延迟毫秒模拟慢接口is_enabled关闭则不参与匹配call_count / last_call_time运维排错利器{name:查询用户列表-空数据,method:GET,path:/api/users,response_status:200,response_body:{code:0,data:{list:[],total:0}}}2.1 path 不是 OpenAPI 模板要 mockGET /api/orders/1001path 就写/api/orders/1001。写/api/orders/{id}不会自动匹配任意 id——引擎做的是字符串相等兼容有无前导/。动态资源 ID 的常见做法前端联调写死演示 id如 1001或为每个演示 id 建一条 Mock需要模式匹配时应上专业 Mock Server / 网关而不是指望当前引擎三、mock-call 网关一次请求的完整路径3.1 调用形态GET /api-module/mock-call/api/users?_project_id1 Host: 180.76.142.97前端开发环境示例VITE_API_BASEhttp://180.76.142.97/api-module/mock-call请求/api/products实际命中http://180.76.142.97/api-module/mock-call/api/products?_project_id1多项目同平台时强烈建议始终带_project_id否则可能命中其它项目同 methodpath 的启用规则。3.2 匹配算法务必读懂否是无有是否mock-call 请求过滤 method is_enabled is_del可选 _project_id按顺序找 path 字面相等的【第一条】找到?404有 match_rules?delay → call_count → 返回响应header/query/body全部符合?直接 404不回退同 path 下一条源码逻辑文字版1. filters method is_enabled is_del 若有合法 _project_id → 再过滤 project_id 2. 取出候选列表按遍历顺序找 path 精确相等的【第一条】 3. 若该条有 match_rules header / query / body 任一不符 → 直接 404 不会回退试同 path 的下一条 4. response_delay → asyncio.sleep(ms/1000) 5. call_count写 last_call_time 6. 返回 status headers body关键推论错误预期真实行为同 path 多条靠 body 不同「择优」只认第一条 path 命中rules 失败即 404{id}通配不支持query 里的_project_id参与业务匹配内部弹出不进 match_rules.querybody 深层 JSONPath仅顶层字段相等比较非 JSON body 当{}因此 UI 里 match_rules 示例文案若让人以为「多规则路由」要以源码为准match_rules 是命中后的门禁不是路由器。3.3 多场景怎么建模推荐场景推荐做法登录成功 / 密码错误不同 path如/api/loginvs/api/login/error或保证同 path 仅一条启用同一资源不同状态不同 path或前端联调约定固定 query并接受「仅一条规则」必须带某 Header 才算合法调用单条 Mock match_rules.header临时下线某 Mockis_enabledfalse而不是删掉异常场景示例独立 path最稳场景method path响应登录成功POST /api/login200 token密码错误POST /api/login/wrong401 错误码列表为空GET /api/users200 list:[]服务端错误GET /api/users/boom500 message3.4 响应构造细节response_body为 dict/list →json.dumps默认Content-Type: application/json; charsetutf-8用户配置的response_headers覆盖/合并到默认头response_delay适合测 loading / 超时提示不适合当压测四、联调实操从前端到回归Step 1建 MockMock 服务 → 新建method、path、body、可选 delay。保存后看对话框里的调用说明{baseUrl}/api-module/mock-call/匹配路径。Step 2前端改 baseURL指向 mock-call联调请求带_project_id。跨域则配开发代理或平台 CORS。Step 3用 call_count 验证是否打中改完前端后看 Mock 列表call_count / last_call_time不涨 → path/method/_project_id/是否启用涨但仍 404 → 多半是match_rules 二次校验失败看响应 detailStep 4切真环境回归后端就绪后接口自动化环境 Host → 真测试服Token 授权按真环境配置不要继续把回归 Host 指到 mock-call除非刻意做「契约打 Mock」的用例用例结构path、断言、extractors可以复用换的是环境与鉴权。五、AI 生成响应体草稿不是契约真理入口Mock 编辑对话框 →AI 生成响应体POST .../mock/ai-generate。输入 method、path、业务描述、期望 status → LLM 生成 JSON 草稿 →人工核对字段名→ 保存。实现要点generate_mock_response_body走平台 AI 场景配置与 usage 日志从模型输出中抽取 JSON含 code fence 容错需要ai_test:execute权限适合快速起量字段契约以前端/Swagger 为准AI 只减少空白页时间。小测 / MCP 可问「项目有哪些 Mock」→list_mock_apis只读列表不替代联调。六、与接口用例、计划、压测的边界能力和 Mock 的关系接口调试可对 mock-call 地址发送验证规则测试计划回归应打真环境Mock 联调期辅助Token 授权真环境用Mock 联调常返回固定 token 即可压测禁止把目标指到 Mock——测的是假吞吐Header 模板真接口用例复用头与 Mock 规则无关七、排错清单现象处理404 Mock 未找到或未启用path 完全一致method启用开关_project_id404 且 detail 含 header/query/body 匹配失败放宽或清空 match_rules核对大小写与类型query 会转 str 比改了规则仍像旧响应同 methodpath 是否还有更靠前的启用记录call_count 不涨请求根本没到平台baseURL / 代理错误CORS开发代理或网关放行AI 字段离谱人工改 body补业务描述对照 Swagger回归仍打到 Mock环境 Host 未切真服八、设计取舍为什么现在这样实现当前引擎选择精确匹配 可选门禁而不是完整路由 DSL换来的是规则可预期、易排错call_count detail实现简单、CE 可维护逼着联调约定「演示数据形状」清晰代价是不能把 BrickCore Mock 当成 WireMock/Hoverfly 的完整替代。复杂状态机、正则 path、优先级路由——应明确边界避免过度承诺。九、小结Mock 项目资产 mock-call 网关解决「规则在个人 Postman」问题。path精确匹配match_rules 是二次门禁不是多规则路由器。多场景优先拆 path或保证同 path 仅一条启用。联调走 Mock回归切真环境压测打真 SUT。AI 只产草稿契约靠人审。附录 A源码文件索引顺序文件关注点1routers/http/mocks.pyCRUD、mock_call、match_rules、delay、统计2models/http.pyMockApi3schemas/http.pyMockApiCreate等4core/llm/mock_ai_service.pyAI 生成 body5mcp/tools.pytool_list_mock_apis6前端ApiModule/components/MockDialog.vue支持与交流演示http://180.76.142.97/showcase/ · 源码https://gitee.com/BanZhuanKeOrz/BrickCore觉得有用欢迎Star⭐问题评论区留言或 Gitee Issues交流群文末上传微信群二维码或 CSDN 私信联系