先交代一下背景。我是在一个中型前端团队日常要对接三个后端服务、两套测试环境很多需求明明代码一上午就能写完真正耗时间的是“接口还没好”“数据和文档对不上”“本地能跑一上测试环境就挂”这些破事。后来我们内部开始使用 XinServer一个基于 Node.js 的本地开发服务器工具专门做接口转发、Mock 注入、多环境切换和请求日志记录。它不是什么新语言也不是重量级框架就是跑在开发机上的一个小服务但这个小工具让我的开发效率提升显著省下来的时间非常可观。这篇文章不是官网文档翻译而是我把这套玩法的思路、核心设计、具体配置和踩坑记录完整整理出来适合正在做前后端分离、经常被联调和测试数据折磨的同学参考。不管你是前端、后端还是测试只要平时需要本地起服务、造数据、转发代理XinServer 的这套用法都能直接抄作业。1. 为什么需要 XinServer从一次前后端联调痛点说起1.1 传统开发模式下的效率瓶颈之前我们的开发流程大概是这样的前端根据接口文档写页面后端按排期开发接口两者在联调阶段才真正碰头。听起来很顺实际上到处都是坑。第一个坑是等待。接口文档早早就写好了但是后端要处理权限、缓存、消息队列这些事情不可能完全按文档时间交付。前端模块排期排在前面页面逻辑都写完了接口还没就绪只能对着文档干等。第二个坑是数据。就算接口能调通测试环境的数据往往也乱七八糟。比如订单列表接口我想测“列表为空”“单条订单金额异常”“分页已到最后一页”这三个分支测试环境里根本没有这么多可控的数据我只能临时改代码、写死返回测完再改回来。改来改去很容易把改错的文件提交上去。第三个坑是环境。有人用测试环境有人用本地后端有人直连生产或预发库。配置文件里的接口地址经常被改得烟花缭乱git pull 下来还总冲突。一个新人入职光是把接口地址配明白就可能花掉半天。第四个坑是排查。联调阶段报了一个接口问题前端说参数是后端要求的格式后端说数据已经到了只是前端展示有问题。两边都没有完整的请求和响应记录就在聊天工具里来回截图效率极低。这些坑不是某一个人的问题而是开发模式下“本地环境”没有被认真对待造成的。我们需要一个能统一管理本地接口、Mock、代理和日志的东西。1.2 XinServer 解决的四个核心问题XinServer 就是我们被逼出来的答案。它本质上是一个本地 HTTP Server但把开发中最常遇到的需求都做成了开箱即用的能力。接口 Mock 就地在本地注入不需要改业务代码不需要注释掉真实请求。接口代理转发本地请求可以一键切到测试环境、预发环境或者同事的本地服务。完整的请求日志进来的 URL、请求头、响应体、耗时都能看到排查问题不再靠猜。配置文件可以入库分享新同事拉下仓库就知道API怎么配、Mock 有哪些团队协作的成本大大降低。2. XinServer 的整体设计与核心特性拆解2.1 核心架构路由、Mock、代理三层分离XinServer 的运行逻辑并不复杂核心是“先匹配路由再按规则决定是走 Mock 还是走代理”。你可以把这个结构理解成三层。第一层是路由匹配。所有进到 XinServer 的请求会先根据 method、path、query 去匹配配置好的 routes。匹配方式支持精确匹配、前缀匹配和正则匹配。这一层决定了请求“去哪个处理器”。第二层是 Mock 分发。如果路由配置指向一个 mock 文件XinServer 就会读文件内容按导出的函数或对象生成响应。这个过程中可以人为加延迟、设置响应头、动态拼接参数用来模拟真实接口的各种表现。第三层是代理转发。如果路由配置指向一个 target比如测试环境域名XinServer 就会把请求原样转发过去然后把响应接回给浏览器。这一层最像 Nginx 的反向代理但妙就妙在它可以和 Mock 规则混用。一个典型的配置文件大致长这个样子。// xinserver.config.js module.exports { server: { port: 8080, }, envs: { dev: http://192.168.1.100:3000, test: http://test-api.example.com, }, routes: [ { match: /api/user/:id, method: GET, mock: ./mocks/user/detail.js, }, { match: /api/order/list, method: POST, proxy: ${envs.test}, }, ], };这里有个细节值得注意proxy 目标里用了${envs.test}这种占位写法而不是直接写死域名。这样做的原因是同一个配置在不同环境、不同人手里跑起来只需要通过环境变量切换envs对象不需要改动 routes 本身。2.2 为什么用 Node.js 而不是 Nginx 或者现成脚手架有人可能会问代理和 Mock 这种事 Nginx 不是也能做吗Nginx 的proxy_pass确实可以转发但要在 Nginx 里做动态 Mock、延迟注入、根据请求参数返回不同数据就得搭配 Lua 或者 OpenResty配置复杂度直接拉满。XinServer 选择基于 Node.js是因为前端团队人人都能看懂 JS。一个 mock 文件就是一个普通的 CommonJS 模块写得下去函数表达式完全不需要再学一套 DSL。而且 Node.js 在本地启动服务非常轻不依赖额外的环境连 Docker 都可以不装。另外现成的脚手架工具也有不少但它们大多定位在“接口 Mock 平台”重量级需要连数据库、起管理后台。XinServer 走的是轻量级路线目标就是本地开发这一个场景怎么简单怎么来。它不保存历史数据不搞用户体系Mock 文件就在项目目录里用 Git 管理本身就够了。这个取舍在团队里是最实用的。2.3 环境切换与扩展机制XinServer 支持给每个环境配置独立的全局变量比如各自的接口前缀、鉴权 token、自定义响应头。启动的时候指定当前环境即可。XIN_ENVtest xinserver start也可以在配置文件里设置envs后通过路由模板动态引用。这样做最大的好处是所有环境相关的东西都收敛到了一个文件里而不是散落在几十个业务代码文件中的fetch地址中。扩展机制方面XinServer 支持插件形式的中间件。比如我们团队在内部加了一个“响应改写”插件专门处理那些后端返回结构不统一的老接口在中间层把data和message字段规范化后再返回给前端页面。这个能力非常有用因为它让你的本地开发环境可以比真实环境更理想又不影响后端的真实实现。3. 落地实操从安装到第一个 Mock 接口3.1 安装与初始化我们团队用的 XinServer 是发布在私有 npm 仓库里的包所以安装方式和普通包一致。如果你是自己维护一套也可以按同样的方式发包。安装命令大概是这样的。npm i -g xinserver xinserver init my-project cd my-project xinserver start初始化之后目录结构会比较清爽。my-project ├── xinserver.config.js └── mocks ├── user │ └── detail.js └── order └── list.js这里我按团队常用写法整理不同版本的命令可能略有差异但核心思想不变。init 会自动生成一个可用的基础配置把port、mockDir、routes都预留好你只需要把真实接口往里面填。3.2 配置一个带延迟和动态数据的 Mock 接口Mock 接口最简单的形式就是返回一个固定的 JSON。但实际开发中我更推荐用函数形式因为函数可以读取请求参数模拟更真实的行为。// mocks/user/detail.js module.exports { delay: 300, // 模拟网络延迟 ctx: { mock: true, }, handler(req, res) { const userId req.params.id; const query req.query; res.json({ code: 0, data: { id: userId, name: query.from list ? 列表页进来的用户 : 详情页用户, age: 28, level: userId % 2 0 ? vip : normal, }, }); }, };写完之后运行xinserver start路由只要在配置里指向这个文件即可。{ match: /api/user/:id, method: GET, mock: ./mocks/user/detail.js, }然后在浏览器访问http://localhost:8080/api/user/10086就能看到对应的 JSON。这里我刻意加了delay: 300因为很多前端 bug 都出在接口慢的场景比如 loading 状态没处理好、重复点击没有防抖。Mock 里模拟延迟有助于在开发阶段就把这些体验问题暴露出来。3.3 代理到测试环境与多环境切换到了联调阶段接口已经由后端提供Mock 就不需要了。这时候可以在路由上把 mock 替换成 proxy或者准备一份新的配置文件。// xinserver.config.js module.exports { server: { port: 8080 }, envs: { dev: http://192.168.1.100:3000, test: http://test-api.example.com, staging: http://staging-api.example.com, }, routes: [ { match: /api/order/list, method: POST, proxy: ${envs.test}, }, ], };启动时指定环境。XIN_ENVtest xinserver start这时访问http://localhost:8080/api/order/listXinServer 就会把 POST 请求完整转发到http://test-api.example.com/api/order/list。转发过程中会保留 request body、query、headers所以大多数接口直接切过去就能工作。这里我要强调一个对前端特别友好、对后端也省事的点代理模式下后端看到的是来自 XinServer 的请求而不是浏览器的跨域请求。因为 XinServer 是服务端转发CORS 问题天然不存在。我们在本地页面里请求的永远是http://localhost:8080/...页面和接口同源不需要额外开启浏览器的跨域插件。3.4 请求日志与故障排查XinServer 的请求日志是我用得最频繁的功能之一。默认启动后会打印一张表格每一行包含请求方法、完整路径、是否命中 Mock、目标环境、响应状态码、耗时毫秒。GET /api/user/10086 mock:true env:local status:200 cost:58ms POST /api/order/list mock:false env:test status:200 cost:312ms GET /api/goods/list mock:false env:test status:500 cost:1200ms这个日志看起来简单排查问题的时候却非常好用。之前前后端联调遇到一个“后端报错了”的问题你只需要把这条日志复制发给后端告诉他“我这边请求已经到测试环境了耗时 1200ms状态 500”基本就能定位到是后端服务问题。如果日志显示mock:true说明请求根本没出本地那就是 Mock 配置或前端参数的问题。排查范围一下子缩小了很多省掉了大量无谓的来回沟通。4. 真实场景中的效率提升数据与使用心得4.1 场景一前端页面开发不再等后端我们最近做了一个用户中心改造前端要提前一周开发。按照以前的做法这一周大概率是空转的因为接口文档虽然有了但真实接口一个都没好。用上 XinServer 之后我们第一天就把所有页面需要的接口全部 Mock 出来了。Mock 文件直接按接口文档字段编写字段类型、嵌套关系、错误码都对齐。前端开发时候每个页面都能真实拉到数据渲染逻辑、空态、错误提示、loading 状态全都能测。开发到第三天页面基本完型。等后端接口就绪我们没做大规模改动只需要把对应路由的 mock 换成 proxy再全局跑一遍回归。之前那种“前端等后端、后端等前端”的情况被彻底切开了。4.2 场景二自动化测试数据的稳定供给我们团队有部分接口自动化测试之前最头疼的是测试数据不稳定。比如一个支付下单流程测试环境里很难保证每次都有足够的库存、固定的优惠券、没有重复订单。为了测某个分支测试同学常常要去数据库里手工造数据造完还要手工清理。后来我们把这一整套测试数据写成了 XinServer 的 Mock 文件自动化测试时直接指向本地 Mock每次跑的返回数据完全一致。不再依赖测试环境的脏数据也不再担心别的同事把测试数据改坏了。当然这种做法只适合测试前端逻辑和业务流程不适合验证后端真实接口的正确性。后端的集成测试还是要连真实环境跑这一点得分开。4.3 场景三多人协作时接口约定的在线验证XinServer 的配置文件可以提交到 Git 仓库所以团队每个人都共用同一套 Mock。新同学入职只要拉下仓库、安装依赖、执行xinserver start本地环境就搭好了。我们后来更进一步把 Mock 文件里导出的数据结构当成了“可执行的接口文档”。后端同学在开发接口之前可以先看一下 Mock 文件里前端期望的字段名、嵌套结构和示例值发现不一致的地方提前沟通不用等到联调阶段再返工。接口文档更新后顺手把 Mock 文件同步掉前端本地跑的就是最新约定降低了“文档和实现脱节”的风险。4.4 我看到的效率提升变化以下数据来自我们团队内部一段时间的使用统计不一定对所有团队成立但可以作为参考。事项使用前使用后接口等待导致的空窗期经常出现每天平均 1-2 小时基本消失可按计划开发测试数据准备时间手工造数单场景半小时以上改 Mock 文件几分钟完成联调环境问题排查两边截图沟通常常半天看 XinServer 日志定位半小时内新人本地环境搭建半天起步约 20 分钟最直观的变化是需求交付时间变快。以前一个联调阶段需要三天现在后端接口完成度比较高的情况下一天就能搞定。这中间不是因为每个人写代码更快了而是把等待、返工、排查这些隐性时间砍掉了。4.5 注意事项和避坑经验使用 XinServer 过程中我也踩过一些坑这里直接分享几个我认为最重要的经验。第一Mock 数据不能和接口文档脱节。我们有过一次很惨的教训前端照着 Mock 数据写了一版页面结果后端真实接口返回的字段名完全不同导致页面大面积报错。后来我们要求每次接口文档变更必须同步更新 Mock 文件并且把字段类型写清楚。第二不要把 Mock 文件变成“隐藏业务逻辑”的地方。如果某个接口的返回结果要依赖复杂的计算你可能会想在 Mock 里实现一套简化版逻辑。短时间看方便但时间一长Mock 和真实逻辑的差距会越来越大可能误导联调。建议 Mock 只负责“稳定返回预设数据”复杂逻辑交给真实验证。第三代理和 Mock 混用时要明确路由优先级。XinServer 默认是第一个匹配到的路由生效。有一次我们把/api/user/:id的 Mock 放在/api/user/role的代理前面结果/api/user/role永远命中了前面的:idMock返回了一堆奇怪数据。后来我们约定精确路径优先带参数的通配规则往后放。5. 常见问题与排查技巧实录5.1 热更新失效问题XinServer 正常情况下支持监听 Mock 文件变化改完保存自动生效。但你会发现有时候改了文件刷新页面还是旧数据。这一般不是 XinServer 的问题而是文件路径大小写不一致或者监听范围没覆盖到 mocks 目录。排查思路是先确认mockDir配置的路径正确再确认文件确实保存到了被监听的目录里。如果用的是 macOS 或 Linux还要注意文件名大小写userDetail.js和userdetail.js是不同文件。我们团队内部约定所有 Mock 文件一律使用小驼峰命名避免在 windows 和 mac 之间切换时踩坑。5.2 Mock 数据生效但是接口跨域虽然 XinServer 作为代理服务时不存在跨域问题但如果你把前端页面直接跑到另一个端口比如用 Vite 起在 5173 端口页面里请求的是http://localhost:8080这仍然是跨域请求。解决办法有两种。第一种是在前端构建工具里配置代理把/api转发到http://localhost:8080。第二种是让 XinServer 开启 CORS 响应头。// xinserver.config.js module.exports { server: { port: 8080, cors: { origin: [http://localhost:5173], credentials: true, }, }, };我一般推荐第二种因为开起来简单而且只在开发环境生效。如果你需要携带 Cookie记得把credentials设为true。5.3 代理到测试环境时怎么保留 Cookie联调阶段经常遇到一个需求本地页面要访问测试环境的接口同时要带上测试环境登录后的 Cookie。代理转发是服务端行为浏览器只会看到 XinServer 返回的响应而 Set-Cookie 的域名是测试环境的域名本地 session 很可能存不下来。XinServer 的解决办法是支持 cookie 域名重写。在代理配置里加一个cookieDomainRewrite字段把测试环境域名改写成localhost。{ match: /api/auth/login, method: POST, proxy: ${envs.test}, proxyOptions: { cookieDomainRewrite: { test-api.example.com: localhost, }, }, }这个配置有点小众但在真实联调中非常管用。我之前为了处理 Cookie甚至在页面里写了一个临时劫持逻辑后来发现 XinServer 原生支持省了不少事。5.4 HTTPS 本地证书问题有些接口是 HTTPS 的尤其是登录和支付相关。如果你本地通过http://localhost去代理一个 HTTPS 接口浏览器控制台可能会报 Mixed Content也就是“混合内容”问题。XinServer 支持在本地启用 HTTPS只需要在配置里指定证书文件。module.exports { server: { port: 8443, https: { key: ./certs/localhost-key.pem, cert: ./certs/localhost-cert.pem, }, }, };生成本地证书可以用mkcert把它加到系统信任列表里浏览器就不会报不安全提示了。这个步骤第一次配置比较烦但做完之后本地 HTTPS 开发体验和线上环境完全一致。5.5 性能与内存占用优化XinServer 的设计目标是轻量但如果 Mock 文件非常多或者路由规则写得太宽泛启动时的路由编译和监听开销还是会变大。我们团队曾经把整个 Mock 目录塞了两百多个文件启动要等好几秒保存一次要卡一下。后来优化方式很简单把不常用的 Mock 目录拆出来通过环境变量控制是否加载。module.exports { mockDir: process.env.ENABLE_FULL_MOCK true ? ./mocks/full : ./mocks/lite, };日常开发用 lite 版只包含当前需求相关的 Mock做全量回归或者需要完整场景时再切到 full 版。这样本地响应速度和启动速度都快了很多。6. 扩展玩法把 XinServer 接入更多工作流6.1 接入前端构建工具XinServer 并不排斥 Vite、Webpack 等构建工具。最常见的使用方式是Vite 负责前端页面的 HMRXinServer 负责接口 Mock 和代理两者通过代理配置连接。// vite.config.js export default { server: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true, }, }, }, };这样前端代码里请求/api/...到了浏览器会先交给 Vite 开发服务器再由 Vite 转发给 XinServerXinServer 再决定走 Mock 还是测试环境。整个过程前端代码里不需要写完整域名切环境时只改 XinServer 的环境变量就够了。6.2 配合接口文档生成Mock 文件里写的数据往往比文档更贴近实际甚至包含了各种边界值示例。我们后来写了一个小脚本扫描 XinServer 的 Mock 文件自动生成一份简单的接口字段说明。虽然不能替代专业文档平台但胜在实时、和代码同步不会出现文档已经改了但 Mock 还是旧数据的情况。具体做法是在 Mock 文件顶部加一段 JSDoc 注释把字段含义写清楚。/** * api {get} /api/user/:id 获取用户详情 * param {number} id 用户ID * return {number} code 0表示成功 * return {string} data.name 用户昵称 */ module.exports { ... };脚本读取注释后输出 Markdown 表格再接入 CI 自动更新到内部文档站。这个玩法属于二次开发但实现成本很低对团队的知识沉淀很有帮助。6.3 沉淀为团队统一开发入口现在我越来越觉得XinServer 真正的价值不只是“一个 Mock 工具”它其实可以变成团队统一开发入口。新同学入职后不再需要去问师兄“测试环境地址是啥”“本地连哪个库”“这个接口有没有 Mock”所有信息都写在仓库里的配置文件中。我们还在配置里加了一个health路由启动后可以访问http://localhost:8080/health返回当前环境、路由数量、Mock 文件数量等信息。这样无论是个人开发还是 CI 检查都能快速判断本地环境是否正常。如果未来团队规模再大我可能会在这个基础上加一个共享的远端配置中心让不同项目的开发环境和接口约定统一起来。但就目前阶段来说一个配置文件加一套 Mock 目录已经足够解决绝大部分开发效率问题了。我个人在实际操作中的体会是真正提升效率的不是某个魔法功能而是把本地开发环境里的变量尽量收拢到一套可配置、可回放、可共享的规则里。XinServer 恰好把这几点做得很顺手。如果你也被接口等待、环境切换、问题复现搞得很烦我建议先别急着换框架试试把开发服务器这一层管理好很多时间自然就省下来了。
XinServer：Node.js 本地开发服务器如何用接口 Mock 与代理转发提升前后端联调效率
先交代一下背景。我是在一个中型前端团队日常要对接三个后端服务、两套测试环境很多需求明明代码一上午就能写完真正耗时间的是“接口还没好”“数据和文档对不上”“本地能跑一上测试环境就挂”这些破事。后来我们内部开始使用 XinServer一个基于 Node.js 的本地开发服务器工具专门做接口转发、Mock 注入、多环境切换和请求日志记录。它不是什么新语言也不是重量级框架就是跑在开发机上的一个小服务但这个小工具让我的开发效率提升显著省下来的时间非常可观。这篇文章不是官网文档翻译而是我把这套玩法的思路、核心设计、具体配置和踩坑记录完整整理出来适合正在做前后端分离、经常被联调和测试数据折磨的同学参考。不管你是前端、后端还是测试只要平时需要本地起服务、造数据、转发代理XinServer 的这套用法都能直接抄作业。1. 为什么需要 XinServer从一次前后端联调痛点说起1.1 传统开发模式下的效率瓶颈之前我们的开发流程大概是这样的前端根据接口文档写页面后端按排期开发接口两者在联调阶段才真正碰头。听起来很顺实际上到处都是坑。第一个坑是等待。接口文档早早就写好了但是后端要处理权限、缓存、消息队列这些事情不可能完全按文档时间交付。前端模块排期排在前面页面逻辑都写完了接口还没就绪只能对着文档干等。第二个坑是数据。就算接口能调通测试环境的数据往往也乱七八糟。比如订单列表接口我想测“列表为空”“单条订单金额异常”“分页已到最后一页”这三个分支测试环境里根本没有这么多可控的数据我只能临时改代码、写死返回测完再改回来。改来改去很容易把改错的文件提交上去。第三个坑是环境。有人用测试环境有人用本地后端有人直连生产或预发库。配置文件里的接口地址经常被改得烟花缭乱git pull 下来还总冲突。一个新人入职光是把接口地址配明白就可能花掉半天。第四个坑是排查。联调阶段报了一个接口问题前端说参数是后端要求的格式后端说数据已经到了只是前端展示有问题。两边都没有完整的请求和响应记录就在聊天工具里来回截图效率极低。这些坑不是某一个人的问题而是开发模式下“本地环境”没有被认真对待造成的。我们需要一个能统一管理本地接口、Mock、代理和日志的东西。1.2 XinServer 解决的四个核心问题XinServer 就是我们被逼出来的答案。它本质上是一个本地 HTTP Server但把开发中最常遇到的需求都做成了开箱即用的能力。接口 Mock 就地在本地注入不需要改业务代码不需要注释掉真实请求。接口代理转发本地请求可以一键切到测试环境、预发环境或者同事的本地服务。完整的请求日志进来的 URL、请求头、响应体、耗时都能看到排查问题不再靠猜。配置文件可以入库分享新同事拉下仓库就知道API怎么配、Mock 有哪些团队协作的成本大大降低。2. XinServer 的整体设计与核心特性拆解2.1 核心架构路由、Mock、代理三层分离XinServer 的运行逻辑并不复杂核心是“先匹配路由再按规则决定是走 Mock 还是走代理”。你可以把这个结构理解成三层。第一层是路由匹配。所有进到 XinServer 的请求会先根据 method、path、query 去匹配配置好的 routes。匹配方式支持精确匹配、前缀匹配和正则匹配。这一层决定了请求“去哪个处理器”。第二层是 Mock 分发。如果路由配置指向一个 mock 文件XinServer 就会读文件内容按导出的函数或对象生成响应。这个过程中可以人为加延迟、设置响应头、动态拼接参数用来模拟真实接口的各种表现。第三层是代理转发。如果路由配置指向一个 target比如测试环境域名XinServer 就会把请求原样转发过去然后把响应接回给浏览器。这一层最像 Nginx 的反向代理但妙就妙在它可以和 Mock 规则混用。一个典型的配置文件大致长这个样子。// xinserver.config.js module.exports { server: { port: 8080, }, envs: { dev: http://192.168.1.100:3000, test: http://test-api.example.com, }, routes: [ { match: /api/user/:id, method: GET, mock: ./mocks/user/detail.js, }, { match: /api/order/list, method: POST, proxy: ${envs.test}, }, ], };这里有个细节值得注意proxy 目标里用了${envs.test}这种占位写法而不是直接写死域名。这样做的原因是同一个配置在不同环境、不同人手里跑起来只需要通过环境变量切换envs对象不需要改动 routes 本身。2.2 为什么用 Node.js 而不是 Nginx 或者现成脚手架有人可能会问代理和 Mock 这种事 Nginx 不是也能做吗Nginx 的proxy_pass确实可以转发但要在 Nginx 里做动态 Mock、延迟注入、根据请求参数返回不同数据就得搭配 Lua 或者 OpenResty配置复杂度直接拉满。XinServer 选择基于 Node.js是因为前端团队人人都能看懂 JS。一个 mock 文件就是一个普通的 CommonJS 模块写得下去函数表达式完全不需要再学一套 DSL。而且 Node.js 在本地启动服务非常轻不依赖额外的环境连 Docker 都可以不装。另外现成的脚手架工具也有不少但它们大多定位在“接口 Mock 平台”重量级需要连数据库、起管理后台。XinServer 走的是轻量级路线目标就是本地开发这一个场景怎么简单怎么来。它不保存历史数据不搞用户体系Mock 文件就在项目目录里用 Git 管理本身就够了。这个取舍在团队里是最实用的。2.3 环境切换与扩展机制XinServer 支持给每个环境配置独立的全局变量比如各自的接口前缀、鉴权 token、自定义响应头。启动的时候指定当前环境即可。XIN_ENVtest xinserver start也可以在配置文件里设置envs后通过路由模板动态引用。这样做最大的好处是所有环境相关的东西都收敛到了一个文件里而不是散落在几十个业务代码文件中的fetch地址中。扩展机制方面XinServer 支持插件形式的中间件。比如我们团队在内部加了一个“响应改写”插件专门处理那些后端返回结构不统一的老接口在中间层把data和message字段规范化后再返回给前端页面。这个能力非常有用因为它让你的本地开发环境可以比真实环境更理想又不影响后端的真实实现。3. 落地实操从安装到第一个 Mock 接口3.1 安装与初始化我们团队用的 XinServer 是发布在私有 npm 仓库里的包所以安装方式和普通包一致。如果你是自己维护一套也可以按同样的方式发包。安装命令大概是这样的。npm i -g xinserver xinserver init my-project cd my-project xinserver start初始化之后目录结构会比较清爽。my-project ├── xinserver.config.js └── mocks ├── user │ └── detail.js └── order └── list.js这里我按团队常用写法整理不同版本的命令可能略有差异但核心思想不变。init 会自动生成一个可用的基础配置把port、mockDir、routes都预留好你只需要把真实接口往里面填。3.2 配置一个带延迟和动态数据的 Mock 接口Mock 接口最简单的形式就是返回一个固定的 JSON。但实际开发中我更推荐用函数形式因为函数可以读取请求参数模拟更真实的行为。// mocks/user/detail.js module.exports { delay: 300, // 模拟网络延迟 ctx: { mock: true, }, handler(req, res) { const userId req.params.id; const query req.query; res.json({ code: 0, data: { id: userId, name: query.from list ? 列表页进来的用户 : 详情页用户, age: 28, level: userId % 2 0 ? vip : normal, }, }); }, };写完之后运行xinserver start路由只要在配置里指向这个文件即可。{ match: /api/user/:id, method: GET, mock: ./mocks/user/detail.js, }然后在浏览器访问http://localhost:8080/api/user/10086就能看到对应的 JSON。这里我刻意加了delay: 300因为很多前端 bug 都出在接口慢的场景比如 loading 状态没处理好、重复点击没有防抖。Mock 里模拟延迟有助于在开发阶段就把这些体验问题暴露出来。3.3 代理到测试环境与多环境切换到了联调阶段接口已经由后端提供Mock 就不需要了。这时候可以在路由上把 mock 替换成 proxy或者准备一份新的配置文件。// xinserver.config.js module.exports { server: { port: 8080 }, envs: { dev: http://192.168.1.100:3000, test: http://test-api.example.com, staging: http://staging-api.example.com, }, routes: [ { match: /api/order/list, method: POST, proxy: ${envs.test}, }, ], };启动时指定环境。XIN_ENVtest xinserver start这时访问http://localhost:8080/api/order/listXinServer 就会把 POST 请求完整转发到http://test-api.example.com/api/order/list。转发过程中会保留 request body、query、headers所以大多数接口直接切过去就能工作。这里我要强调一个对前端特别友好、对后端也省事的点代理模式下后端看到的是来自 XinServer 的请求而不是浏览器的跨域请求。因为 XinServer 是服务端转发CORS 问题天然不存在。我们在本地页面里请求的永远是http://localhost:8080/...页面和接口同源不需要额外开启浏览器的跨域插件。3.4 请求日志与故障排查XinServer 的请求日志是我用得最频繁的功能之一。默认启动后会打印一张表格每一行包含请求方法、完整路径、是否命中 Mock、目标环境、响应状态码、耗时毫秒。GET /api/user/10086 mock:true env:local status:200 cost:58ms POST /api/order/list mock:false env:test status:200 cost:312ms GET /api/goods/list mock:false env:test status:500 cost:1200ms这个日志看起来简单排查问题的时候却非常好用。之前前后端联调遇到一个“后端报错了”的问题你只需要把这条日志复制发给后端告诉他“我这边请求已经到测试环境了耗时 1200ms状态 500”基本就能定位到是后端服务问题。如果日志显示mock:true说明请求根本没出本地那就是 Mock 配置或前端参数的问题。排查范围一下子缩小了很多省掉了大量无谓的来回沟通。4. 真实场景中的效率提升数据与使用心得4.1 场景一前端页面开发不再等后端我们最近做了一个用户中心改造前端要提前一周开发。按照以前的做法这一周大概率是空转的因为接口文档虽然有了但真实接口一个都没好。用上 XinServer 之后我们第一天就把所有页面需要的接口全部 Mock 出来了。Mock 文件直接按接口文档字段编写字段类型、嵌套关系、错误码都对齐。前端开发时候每个页面都能真实拉到数据渲染逻辑、空态、错误提示、loading 状态全都能测。开发到第三天页面基本完型。等后端接口就绪我们没做大规模改动只需要把对应路由的 mock 换成 proxy再全局跑一遍回归。之前那种“前端等后端、后端等前端”的情况被彻底切开了。4.2 场景二自动化测试数据的稳定供给我们团队有部分接口自动化测试之前最头疼的是测试数据不稳定。比如一个支付下单流程测试环境里很难保证每次都有足够的库存、固定的优惠券、没有重复订单。为了测某个分支测试同学常常要去数据库里手工造数据造完还要手工清理。后来我们把这一整套测试数据写成了 XinServer 的 Mock 文件自动化测试时直接指向本地 Mock每次跑的返回数据完全一致。不再依赖测试环境的脏数据也不再担心别的同事把测试数据改坏了。当然这种做法只适合测试前端逻辑和业务流程不适合验证后端真实接口的正确性。后端的集成测试还是要连真实环境跑这一点得分开。4.3 场景三多人协作时接口约定的在线验证XinServer 的配置文件可以提交到 Git 仓库所以团队每个人都共用同一套 Mock。新同学入职只要拉下仓库、安装依赖、执行xinserver start本地环境就搭好了。我们后来更进一步把 Mock 文件里导出的数据结构当成了“可执行的接口文档”。后端同学在开发接口之前可以先看一下 Mock 文件里前端期望的字段名、嵌套结构和示例值发现不一致的地方提前沟通不用等到联调阶段再返工。接口文档更新后顺手把 Mock 文件同步掉前端本地跑的就是最新约定降低了“文档和实现脱节”的风险。4.4 我看到的效率提升变化以下数据来自我们团队内部一段时间的使用统计不一定对所有团队成立但可以作为参考。事项使用前使用后接口等待导致的空窗期经常出现每天平均 1-2 小时基本消失可按计划开发测试数据准备时间手工造数单场景半小时以上改 Mock 文件几分钟完成联调环境问题排查两边截图沟通常常半天看 XinServer 日志定位半小时内新人本地环境搭建半天起步约 20 分钟最直观的变化是需求交付时间变快。以前一个联调阶段需要三天现在后端接口完成度比较高的情况下一天就能搞定。这中间不是因为每个人写代码更快了而是把等待、返工、排查这些隐性时间砍掉了。4.5 注意事项和避坑经验使用 XinServer 过程中我也踩过一些坑这里直接分享几个我认为最重要的经验。第一Mock 数据不能和接口文档脱节。我们有过一次很惨的教训前端照着 Mock 数据写了一版页面结果后端真实接口返回的字段名完全不同导致页面大面积报错。后来我们要求每次接口文档变更必须同步更新 Mock 文件并且把字段类型写清楚。第二不要把 Mock 文件变成“隐藏业务逻辑”的地方。如果某个接口的返回结果要依赖复杂的计算你可能会想在 Mock 里实现一套简化版逻辑。短时间看方便但时间一长Mock 和真实逻辑的差距会越来越大可能误导联调。建议 Mock 只负责“稳定返回预设数据”复杂逻辑交给真实验证。第三代理和 Mock 混用时要明确路由优先级。XinServer 默认是第一个匹配到的路由生效。有一次我们把/api/user/:id的 Mock 放在/api/user/role的代理前面结果/api/user/role永远命中了前面的:idMock返回了一堆奇怪数据。后来我们约定精确路径优先带参数的通配规则往后放。5. 常见问题与排查技巧实录5.1 热更新失效问题XinServer 正常情况下支持监听 Mock 文件变化改完保存自动生效。但你会发现有时候改了文件刷新页面还是旧数据。这一般不是 XinServer 的问题而是文件路径大小写不一致或者监听范围没覆盖到 mocks 目录。排查思路是先确认mockDir配置的路径正确再确认文件确实保存到了被监听的目录里。如果用的是 macOS 或 Linux还要注意文件名大小写userDetail.js和userdetail.js是不同文件。我们团队内部约定所有 Mock 文件一律使用小驼峰命名避免在 windows 和 mac 之间切换时踩坑。5.2 Mock 数据生效但是接口跨域虽然 XinServer 作为代理服务时不存在跨域问题但如果你把前端页面直接跑到另一个端口比如用 Vite 起在 5173 端口页面里请求的是http://localhost:8080这仍然是跨域请求。解决办法有两种。第一种是在前端构建工具里配置代理把/api转发到http://localhost:8080。第二种是让 XinServer 开启 CORS 响应头。// xinserver.config.js module.exports { server: { port: 8080, cors: { origin: [http://localhost:5173], credentials: true, }, }, };我一般推荐第二种因为开起来简单而且只在开发环境生效。如果你需要携带 Cookie记得把credentials设为true。5.3 代理到测试环境时怎么保留 Cookie联调阶段经常遇到一个需求本地页面要访问测试环境的接口同时要带上测试环境登录后的 Cookie。代理转发是服务端行为浏览器只会看到 XinServer 返回的响应而 Set-Cookie 的域名是测试环境的域名本地 session 很可能存不下来。XinServer 的解决办法是支持 cookie 域名重写。在代理配置里加一个cookieDomainRewrite字段把测试环境域名改写成localhost。{ match: /api/auth/login, method: POST, proxy: ${envs.test}, proxyOptions: { cookieDomainRewrite: { test-api.example.com: localhost, }, }, }这个配置有点小众但在真实联调中非常管用。我之前为了处理 Cookie甚至在页面里写了一个临时劫持逻辑后来发现 XinServer 原生支持省了不少事。5.4 HTTPS 本地证书问题有些接口是 HTTPS 的尤其是登录和支付相关。如果你本地通过http://localhost去代理一个 HTTPS 接口浏览器控制台可能会报 Mixed Content也就是“混合内容”问题。XinServer 支持在本地启用 HTTPS只需要在配置里指定证书文件。module.exports { server: { port: 8443, https: { key: ./certs/localhost-key.pem, cert: ./certs/localhost-cert.pem, }, }, };生成本地证书可以用mkcert把它加到系统信任列表里浏览器就不会报不安全提示了。这个步骤第一次配置比较烦但做完之后本地 HTTPS 开发体验和线上环境完全一致。5.5 性能与内存占用优化XinServer 的设计目标是轻量但如果 Mock 文件非常多或者路由规则写得太宽泛启动时的路由编译和监听开销还是会变大。我们团队曾经把整个 Mock 目录塞了两百多个文件启动要等好几秒保存一次要卡一下。后来优化方式很简单把不常用的 Mock 目录拆出来通过环境变量控制是否加载。module.exports { mockDir: process.env.ENABLE_FULL_MOCK true ? ./mocks/full : ./mocks/lite, };日常开发用 lite 版只包含当前需求相关的 Mock做全量回归或者需要完整场景时再切到 full 版。这样本地响应速度和启动速度都快了很多。6. 扩展玩法把 XinServer 接入更多工作流6.1 接入前端构建工具XinServer 并不排斥 Vite、Webpack 等构建工具。最常见的使用方式是Vite 负责前端页面的 HMRXinServer 负责接口 Mock 和代理两者通过代理配置连接。// vite.config.js export default { server: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true, }, }, }, };这样前端代码里请求/api/...到了浏览器会先交给 Vite 开发服务器再由 Vite 转发给 XinServerXinServer 再决定走 Mock 还是测试环境。整个过程前端代码里不需要写完整域名切环境时只改 XinServer 的环境变量就够了。6.2 配合接口文档生成Mock 文件里写的数据往往比文档更贴近实际甚至包含了各种边界值示例。我们后来写了一个小脚本扫描 XinServer 的 Mock 文件自动生成一份简单的接口字段说明。虽然不能替代专业文档平台但胜在实时、和代码同步不会出现文档已经改了但 Mock 还是旧数据的情况。具体做法是在 Mock 文件顶部加一段 JSDoc 注释把字段含义写清楚。/** * api {get} /api/user/:id 获取用户详情 * param {number} id 用户ID * return {number} code 0表示成功 * return {string} data.name 用户昵称 */ module.exports { ... };脚本读取注释后输出 Markdown 表格再接入 CI 自动更新到内部文档站。这个玩法属于二次开发但实现成本很低对团队的知识沉淀很有帮助。6.3 沉淀为团队统一开发入口现在我越来越觉得XinServer 真正的价值不只是“一个 Mock 工具”它其实可以变成团队统一开发入口。新同学入职后不再需要去问师兄“测试环境地址是啥”“本地连哪个库”“这个接口有没有 Mock”所有信息都写在仓库里的配置文件中。我们还在配置里加了一个health路由启动后可以访问http://localhost:8080/health返回当前环境、路由数量、Mock 文件数量等信息。这样无论是个人开发还是 CI 检查都能快速判断本地环境是否正常。如果未来团队规模再大我可能会在这个基础上加一个共享的远端配置中心让不同项目的开发环境和接口约定统一起来。但就目前阶段来说一个配置文件加一套 Mock 目录已经足够解决绝大部分开发效率问题了。我个人在实际操作中的体会是真正提升效率的不是某个魔法功能而是把本地开发环境里的变量尽量收拢到一套可配置、可回放、可共享的规则里。XinServer 恰好把这几点做得很顺手。如果你也被接口等待、环境切换、问题复现搞得很烦我建议先别急着换框架试试把开发服务器这一层管理好很多时间自然就省下来了。
