手把手教你用Whistle给SSE/流式接口做Mock：从复制URL到完整响应的保姆级配置

从零构建SSE接口Mock环境Whistle流式数据模拟实战指南当你在开发一个实时聊天应用或AI对话界面时Server-Sent Events (SSE)技术能提供持续的数据流但测试环境的搭建往往令人头疼。想象一下你的前端代码需要处理/api/chat这样的流式接口而后端还在开发中——这正是Whistle大显身手的时刻。本文将带你从安装配置到完整模拟打造一个逼真的SSE测试环境。1. 环境准备与基础配置在开始模拟SSE接口前我们需要确保Whistle已正确安装并运行。通过npm全局安装是最快捷的方式npm install -g whistle w2 start安装完成后访问http://localhost:8899即可进入Whistle控制面板。这里有几个关键区域需要熟悉Network实时监控所有网络请求Rules编写Mock规则的核心区域Values管理Mock数据文件提示建议安装Whistle的Chrome插件可以更方便地捕获和修改请求对于SSE接口模拟我们需要特别注意两个技术要点正确的Content-Type头部text/event-stream分块传输编码如果需要模拟真正的流式响应2. 捕获与分析目标接口假设我们要模拟的接口是https://api.example.com/chat首先需要了解它的典型响应。即使没有真实后端我们也可以设计一个合理的SSE数据格式event: message data: {id:1,content:Hello,timestamp:1630000000} event: message data: {id:2,content:How are you?,timestamp:1630000005} event: close data: {reason:end_of_conversation}在Whistle的Network面板中你可以右键点击请求选择Copy → URL获取完整接口地址观察正常SSE接口的响应头和数据结构3. 创建Mock数据文件进入Values面板新建一个专门存放SSE模拟数据的文件。点击按钮创建文件命名为sse-mock-data.txt虽然内容是JSON格式但使用.txt扩展名更符合SSE规范。文件内容应该遵循SSE格式规范每个事件由三部分组成event:行可选指定事件类型data:行实际数据空行表示事件结束示例内容event: status data: {status:connected} data: {message:Welcome to the chat} event: message data: {id:1,content:First message,timestamp:1630000000} event: message data: {id:2,content:Second message,timestamp:1630000005} event: close data: {reason:session_end}注意SSE规范要求每个消息后必须有一个空行这是很多开发者容易忽略的细节4. 配置完整的Mock规则现在进入Rules面板我们需要配置两条关键规则来完整模拟SSE接口# 设置响应头 https://api.example.com/chat resHeaders://{sse-headers.json} # 设置mock数据 https://api.example.com/chat file://{sse-mock-data.txt}在Values中创建sse-headers.json文件内容为{ content-type: text/event-stream; charsetutf-8, cache-control: no-cache, connection: keep-alive, access-control-allow-origin: * }关键点说明content-type必须准确设置为text/event-streamno-cache和keep-alive是SSE连接的常见设置CORS头确保前端可以正常访问5. 高级技巧与调试对于更复杂的场景Whistle提供了多种高级功能动态数据模拟使用resScript可以动态生成SSE数据https://api.example.com/chat resScript://{sse-dynamic.js}对应的JavaScript文件示例let count 0; const maxMessages 5; const interval 1000; module.exports (options) { return (ctx) { ctx.setHeader(Content-Type, text/event-stream); ctx.setHeader(Cache-Control, no-cache); ctx.setHeader(Connection, keep-alive); const timer setInterval(() { if (count maxMessages) { ctx.write(event: close\ndata: {reason:max_messages_reached}\n\n); clearInterval(timer); ctx.end(); } else { count; ctx.write(data: {id:${count},content:Message ${count},timestamp:${Date.now()}}\n\n); } }, interval); ctx.on(close, () { clearInterval(timer); }); }; };规则优先级管理当有多个规则可能匹配同一接口时Whistle按照以下顺序处理精确URL匹配的规则通配符匹配的规则按添加顺序插件提供的规则确保你的SSE Mock规则具有足够高的优先级必要时可以使用符号提升优先级# 高优先级规则 https://api.example.com/chat resHeaders://{sse-headers.json} https://api.example.com/chat file://{sse-mock-data.txt}常见问题排查遇到SSE Mock不生效时可以检查以下几点响应头是否正确设置了content-type数据格式是否符合SSE规范特别是空行浏览器开发者工具中查看网络请求和响应Whistle规则是否被其他规则覆盖6. 真实场景应用案例让我们看一个AI聊天界面的完整Mock方案。假设前端需要以下功能连接状态通知分块接收AI回复错误处理会话结束通知对应的Mock配置如下Values/sse-ai-chat.txt:event: status data: {status:connecting} event: status data: {status:connected} data: {message:AI助手已就绪} event: chunk data: {content:思考,finished:false} event: chunk data: {content:思考中,finished:false} event: chunk data: {content:思考中...,finished:false} event: message data: {content:你好我是AI助手有什么可以帮你的吗,finished:true} event: close data: {reason:inactivity_timeout}Rules配置:# AI聊天接口Mock https://api.ai-service.com/chat resHeaders://{sse-headers.json} https://api.ai-service.com/chat file://{sse-ai-chat.txt}这种配置可以完美模拟AI聊天的典型交互模式包括连接状态变化思考过程中的中间状态完整的最终回复超时自动关闭7. 性能优化与最佳实践对于长期维护的Mock环境建议遵循以下实践模块化管理为不同功能模块创建独立的Values文件使用注释组织Rules规则# AI模块 # 聊天接口 https://api.example.com/ai/chat file://{ai-chat.txt} # 状态接口 https://api.example.com/ai/status file://{ai-status.json}版本控制将Whistle配置纳入Git仓库特别是Values中的Mock数据文件团队共享使用w2 export导出配置通过w2 import在团队成员间共享性能考虑对于大量数据的模拟考虑使用resScript动态生成避免在Mock数据中包含不必要的大文件文档记录在Values文件中添加注释说明用例维护一个简单的接口文档说明Mock数据格式# sse-ai-chat.txt # 格式说明 # event: 事件类型 (status|chunk|message|close) # data: JSON格式数据 # # 使用场景模拟AI聊天界面SSE流 # 最后更新2023-10-15