AI应用API Mocking完全指南：APIMock-AI实战模式

构建可靠的AI应用，离不开对LLM API、向量数据库和第三方服务的高效模拟。APIMock-AI为这一场景提供了一套生产级的Mock模式，覆盖契约测试、混沌工程和本地开发全流程。

为什么AI应用尤其需要API Mocking

AI应用对外部API的依赖远超传统软件：LLM推理接口、Embedding服务、向量数据库、内容审核、工具调用……每一个外部依赖都是CI流水线中的潜在故障点。

没有Mock时，开发团队面临的是：不稳定的CI、频繁触发的速率限制、昂贵的API账单、无法离线开发、缓慢的反馈循环，以及对供应商的深度锁定。引入Mock后，这些问题被逐一消解——测试变得可靠可控、开发零成本、支持完全离线的本地工作流，反馈速度也从分钟级降到秒级。

Mock不是测试的奢侈品，而是AI开发的必需品。越早对外部依赖做Mock，越能更快交付、更轻松调试。

Mock服务器架构：六种策略覆盖全场景

APIMock-AI的核心是一个轻量级异步Mock服务器，内置六种响应策略：静态响应、序列响应、模板渲染、动态回调、代理转发和混沌注入。每条规则包含方法、路径模式、优先级、匹配条件与命中计数，支持按优先级排序和请求日志记录。

LLM API的专业Mock

针对OpenAI的/v1/chat/completions和/v1/embeddings、Anthropic的/v1/messages等主流接口，APIMock-AI提供了开箱即用的构建器。Embedding Mock采用基于输入哈希的确定性伪向量生成，保证相同输入总是返回相同向量，并做了L2归一化——这对需要向量相似度计算的测试至关重要。

流式响应也有专门支持。通过检测Accept: text/event-stream头，Mock服务器会以SSE格式逐块推送内容，完整模拟data: [DONE]结尾的流式协议。速率限制Mock则基于客户端IP和滑动窗口实现，返回标准的429状态码和Retry-After头。

SSE（Server-Sent Events） 是 HTTP 层面的一种单向流式推送协议，服务端通过 Content-Type: text/event-stream 声明响应类型，随后以 data: 前缀逐条发送事件块，每条消息以两个换行分隔。OpenAI、Anthropic 等 LLM 供应商的流式补全接口均基于 SSE 实现，客户端用 EventSource 或底层 fetch 流式读取来逐 token 渲染。Mock 流式接口时，除了要按 SSE 格式拼接 data: 块，还必须完整模拟结束信号——OpenAI 以 data: [DONE] 收尾，Anthropic 则以 message_stop 事件结束。若 Mock 遗漏结束符，客户端会一直等待到连接超时，测试中的表现是「卡住」而非「报错」，排查成本很高。此外，SSE 的 chunk 边界不代表消息边界，Mock 服务器要保证每个事件块本身是完整可解析的 JSON，才能被真实客户端正确消费。

契约测试：让API行为可验证、可演化

契约测试是APIMock-AI区别于普通Mock工具的关键能力。它用结构化的APIContract描述每个端点的参数、请求体Schema和响应Schema，并可直接导出为OpenAPI 3.0规范。

测试执行时，ContractTester会对真实或Mock服务发起请求，然后用JSON Schema验证请求体和响应体是否符合契约。这意味着：当供应商API发生破坏性变更时，测试会立即失败并给出具体的Schema差异；当你的客户端代码误传了不符合契约的参数时，同样会被拦截。

以OpenAI为例，契约中定义了Authorization头为必填、temperature的取值范围为0-2、messages为数组类型、响应必须包含id/object/created/model/choices/usage字段。任何偏离都会在CI中被捕获。

JSON Schema 是描述 JSON 数据结构的规范，通过 type、properties、required、enum、minimum/maximum、pattern 等关键字声明字段的形状与约束。契约测试的核心做法是：把供应商 API 的请求体和响应体各写一份 JSON Schema，然后用校验器对真实流量逐条验证。相比手写断言，Schema 的优点是声明式、可组合（$ref、allOf、oneOf）且能自动生成文档。OpenAPI 3.0 则是在 JSON Schema 之上的一层接口描述标准，额外定义了路径、方法、参数位置、安全方案与响应码，因此契约可以直接导出为 OpenAPI 文档，被 Swagger UI、Postman、代码生成器复用。理解这两层关系有助于看懂契约测试的定位：Schema 管「数据长什么样」，OpenAPI 管「接口怎么调用」，而破坏性变更检测本质上就是比对两个版本 Schema 的差异——删除必填字段、收窄枚举、改变类型都会被视为不兼容。

混沌工程：在受控环境中验证韧性

AI应用在生产环境中最怕的不是正常错误，而是超时、限流、响应损坏这类非预期故障。APIMock-AI的ChaosEngine提供了五种故障注入能力：延迟注入（可设定最小/最大毫秒范围和触发概率）、错误注入（按比例返回500/502/503/504）、超时模拟、响应损坏（返回非法JSON）和限流注入。

混沌实验可以定时运行：指定持续时间、目标服务、故障强度和测试函数，引擎会自动统计请求总数、成功率、错误率和P95延迟。这些指标可以直接用于CI中的质量门禁。

韧性模式：重试、熔断与降级

有了混沌注入，就可以验证应用的韧性策略是否生效。APIMock-AI配套的ResilientLLMClient实现了完整的弹性模式栈：

指数退避重试：最大尝试次数、基础延迟、指数因子、最大延迟上限和抖动（50%-150%随机化）均可配置。

断路器：失败次数超过阈值后熔断器打开，在超时窗口内直接走降级逻辑或抛出异常；窗口结束后进入半开状态，用少量请求探测服务是否恢复。

降级回退：提供缓存回退（返回上次缓存结果）、静态回退（返回友好提示）和降级回退（切换到更小的模型、限制token数、关闭流式）三种策略。

这套组合让团队可以在混沌环境中确认：延迟注入不会导致请求雪崩、错误注入不会让整个服务崩溃、熔断器能在正确时机介入。

断路器（Circuit Breaker） 模式借鉴自电气工程：当失败率超过阈值时，开关「跳闸」进入 Open 状态，后续请求不再真正发出，而是立刻失败或走降级逻辑，从而避免故障下游被持续压垮、也避免调用方线程被拖死。经过一个冷却窗口后进入 Half-Open 状态，放行少量探测请求；若成功则复位为 Closed，若仍失败则重新回到 Open。它和重试是互补而非替代关系：重试应对瞬时抖动，断路器应对持续性故障，二者叠加时应把断路器放在重试外层，否则每次重试都在冲击已经不可用的服务。生产实践中还需警惕抖动——冷却时间过短会导致断路器反复开合，因此常配合指数退避与**抖动（jitter）**使用，把大量客户端重试请求在时间轴上打散，防止「惊群」式同步重连再次打垮刚刚恢复的服务。

从Mock到录制回放：生产级工作流

APIMock-AI的MockRecorder支持录制真实API交互并回放为Mock规则。录制时记录请求方法、路径、头和体，以及响应的状态码、头和体。停止录制后，按端点分组：单一交互生成静态规则，多次交互生成序列规则。这意味着你可以先用真实API跑一轮完整流程，然后把录制的数据固化为可重复的Mock测试集。

CI/CD集成：让Mock成为流水线一环

GitHub Actions工作流展示了完整的集成方式：启动Mock服务器、配置各供应商的Mock规则、依次运行契约测试、单元测试和韧性测试，最后生成并上传测试报告。混沌工程作为定时任务（如每周一早上6点）独立运行，失败时通过Slack告警。

本地开发也有对应的启动脚本，同时拉起LLM Mock、向量数据库Mock和Embedding服务Mock三个实例，并输出各自的访问地址。配置文件采用YAML格式，支持定义序列响应和回调函数。

产品能力全景

APIMock-AI覆盖的能力清单包括：核心Mock（静态/序列/模板/回调/代理/混沌）、契约测试（OpenAPI 3.0、请求验证、响应验证、Schema演化检测、破坏性变更告警）、开发者体验（零配置启动、热重载、请求日志、验证API、VS Code扩展、CLI工具）、韧性测试（延迟/错误/超时/损坏/限流/熔断测试）、集成（OpenAI、Anthropic、Gemini、Qdrant、Pinecone、Weaviate、Milvus、GraphQL、gRPC）、部署（Docker、Kubernetes Operator、Helm Chart、GitHub Action、GitLab CI）。

总结

AI应用的复杂度来自外部依赖的不可控性。APIMock-AI把这种不可控转化为可编程的Mock规则：用契约测试锁定API行为边界，用混沌工程验证故障韧性，用录制回放固化真实交互，最终让整个AI生态在本地就能被完整模拟。对于任何依赖外部LLM和向量服务的团队，这都是一套值得纳入开发流程的工程实践。