前端 Mock 数据体系的工程演进：从 JSON Server 到 MSW 的完整方案

一、Mock 数据体系的演进动力

前端开发对 Mock 数据的需求经历了三个阶段的变化：早期阶段（2015-2018）——后端接口未就绪时，前端需要静态 JSON 文件替代真实接口，工具以 JSON Server 为代表；中期阶段（2019-2021）——前后端分离成为标配，需求从"替代缺失的接口"升级为"模拟接口的各种边界状态"（超时、错误、空数据、长列表），工具以 Mock.js 和 YApi 的 Mock 功能为代表；当前阶段（2022-至今）——前端测试体系逐渐完善，需求进一步升级为"同一套 Mock 定义在开发、测试、Storybook 三个环境复用"，工具以 MSW（Mock Service Worker）为代表。

二、各阶段方案的优劣分析

2.1 JSON Server 时代

JSON Server 将 JSON 文件映射为 RESTful API，极大降低了 Mock 的搭建成本。但其局限同样明显：

• 不支持请求校验：无法验证前端发送的参数格式是否正确
• 无边界状态模拟：始终返回 200 OK 和完整数据，无法模拟网络错误、超时或分页边界
• 与前端代码耦合：Mock 数据与组件逻辑在两个独立仓库中管理，接口变更时经常遗忘同步

2.2 Mock.js 时代

Mock.js 通过拦截 XMLHttpRequest 在浏览器端生成随机数据，解决了动态数据生成问题。但在测试环境中，它无法拦截 Node.js 端的请求（如 SSR 或测试运行器中的 API 调用），导致单元测试和集成测试需要另外准备 Mock 方案。

2.3 MSW：统一拦截层

MSW 的核心优势在于通过 Service Worker（浏览器端）和 Node.js 请求拦截（服务端）提供了统一的 API 拦截层，使得同一套 Mock 定义可以在三种环境下工作：

三、MSW 的工程化实践

3.1 基于 OpenAPI 的自动 Mock 生成

从 Swagger/OpenAPI 规范自动生成 MSW Handler，确保 Mock 数据与接口定义始终保持同步：

// openapi-to-msw.ts — 从 OpenAPI 规范生成 MSW Handler interface OpenAPISpec { paths: Record<string, Record<string, { operationId?: string; parameters?: Array<{ name: string; in: 'query' | 'path' | 'header'; required?: boolean; schema: { type: string; example?: unknown }; }>; responses: Record<string, { content?: Record<string, { schema: Record<string, unknown> }>; }>; }>>; } /** * MSW Handler 工厂 * 根据 OpenAPI 规范和响应策略生成 Handler 数组 */ export function generateHandlers(spec: OpenAPISpec) { const handlers: ReturnType< typeof import('msw').http.get >[] = []; const { http, HttpResponse } = require('msw') as typeof import('msw'); for (const [path, methods] of Object.entries(spec.paths)) { for (const [method, operation] of Object.entries(methods)) { const httpMethod = method.toLowerCase() as 'get' | 'post' | 'put' | 'delete' | 'patch'; const okResponse = operation.responses['200'] ?? operation.responses['201']; if (!okResponse?.content?.['application/json']) continue; const schema = okResponse.content['application/json'].schema; // 为每个接口生成标准成功的 Handler handlers.push( http[httpMethod](path, ({ request }) => { // 校验必填参数 const requiredParams = operation.parameters?.filter(p => p.required) ?? []; const url = new URL(request.url); for (const param of requiredParams) { if (param.in === 'query') { if (!url.searchParams.has(param.name)) { return HttpResponse.json( { error: 'VALIDATION_ERROR', message: `缺少必填参数: ${param.name}`, }, { status: 400 } ); } } } // 返回符合 Schema 结构的成功响应 return HttpResponse.json(generateResponse(schema)); }) ); } } return handlers; } /** 根据 Schema 递归生成响应数据 */ function generateResponse(schema: Record<string, unknown>): unknown { const type = schema.type as string | undefined; const properties = schema.properties as Record<string, Record<string, unknown>> | undefined; switch (type) { case 'object': if (!properties) return {}; const obj: Record<string, unknown> = {}; for (const [key, propSchema] of Object.entries(properties)) { obj[key] = generateResponse(propSchema); } return obj; case 'array': const items = schema.items as Record<string, unknown> | undefined; // 生成 3 条示例数据 return Array.from({ length: 3 }, () => items ? generateResponse(items) : null ); case 'string': return schema.example ?? 'mock_string'; case 'integer': case 'number': return schema.example ?? 0; case 'boolean': return schema.example ?? false; default: return null; } }

3.2 Server 层：统一环境适配

通过环境变量控制 MSW 的启动方式，确保开发、测试、Storybook 三种场景无感知切换：

// msw-server.ts — MSW 多环境集成入口 /** * 环境枚举 */ type MockEnvironment = 'browser' | 'node' | 'storybook'; /** * 初始化 MSW（根据运行环境自动选择启动方式） */ export async function initMSW(env: MockEnvironment): Promise<void> { const { handlers } = await import('./handlers'); switch (env) { case 'browser': await initBrowser(handlers); break; case 'node': await initNode(handlers); break; case 'storybook': await initStorybook(handlers); break; default: { const _exhaustive: never = env; throw new Error(`未知的 Mock 环境类型: ${_exhaustive}`); } } } /** 浏览器环境初始化（开发模式） */ async function initBrowser(handlers: ReturnType<typeof import('msw').http.get>[]): Promise<void> { const { setupWorker } = await import('msw/browser'); const worker = setupWorker(...handlers); try { await worker.start({ onUnhandledRequest: 'warn', // 未拦截的请求仅警告（不阻塞） serviceWorker: { url: '/mockServiceWorker.js', }, }); } catch (err) { console.error('[MSW] Service Worker 启动失败:', err); // 降级：在浏览器环境中 MSW 启动失败时不影响应用运行 } } /** Node.js 环境初始化（测试模式） */ async function initNode(handlers: ReturnType<typeof import('msw').http.get>[]): Promise<void> { const { setupServer } = await import('msw/node'); const server = setupServer(...handlers); // 测试前后生命周期钩子 beforeAll(() => server.listen({ onUnhandledRequest: 'error' })); afterEach(() => server.resetHandlers()); afterAll(() => server.close()); } /** Storybook 环境初始化 */ async function initStorybook(handlers: ReturnType<typeof import('msw').http.get>[]): Promise<void> { const { initialize, mswLoader } = await import('msw-storybook-addon'); initialize({ onUnhandledRequest: 'bypass', }); // 导出 loader 供 Storybook preview 使用 // @ts-expect-error Storybook addon 的类型声明由插件内部处理 return { mswLoader }; }

3.3 边界状态与错误场景的覆盖

Mock 数据的真正价值不在于模拟"一切正常"的流程，而在于覆盖那些人工难以手动构造的边界状态。以下是基于 MSW 的边界场景 Handler 实现：

// error-scenario-handlers.ts — 边界与错误场景 Handler import { http, HttpResponse, delay } from 'msw'; /** 为单个接口生成多种边界场景的 Handler */ export function createScenarioHandlers( path: string, method: 'get' | 'post' | 'put' | 'delete' = 'get' ): Record<string, ReturnType<typeof http[typeof method]>> { return { // 场景 1：网络超时（模拟弱网/服务端无响应） timeout: http[method](path, async () => { await delay(60000); // 60 秒延迟，触发前端超时逻辑 return HttpResponse.json({ error: 'timeout' }); }), // 场景 2：服务端 500 错误 serverError: http[method](path, () => { return HttpResponse.json( { error: 'INTERNAL_SERVER_ERROR', message: '服务内部错误' }, { status: 500 } ); }), // 场景 3：服务端 429 限流 rateLimited: http[method](path, () => { return new HttpResponse(null, { status: 429, headers: { 'Retry-After': '30', 'X-RateLimit-Remaining': '0', }, }); }), // 场景 4：空数组响应（测试列表为空时的 UI 状态） emptyList: http[method](path, () => { return HttpResponse.json({ data: [], total: 0, page: 1 }); }), // 场景 5：大数据量响应（测试虚拟列表/分页加载性能） largeDataset: http[method](path, () => { const items = Array.from({ length: 10000 }, (_, i) => ({ id: i + 1, title: `Item ${i + 1}`, description: `这是第 ${i + 1} 条数据的详细描述信息`, createdAt: new Date(Date.now() - i * 3600000).toISOString(), })); return HttpResponse.json({ data: items, total: 10000 }); }), // 场景 6：慢速响应（模拟高延迟网络） slowResponse: http[method](path, async () => { await delay(3000); // 3 秒延迟 return HttpResponse.json({ data: { id: 1, name: 'slow-response-data' }, }); }), }; }

四、类型安全的深度集成

MSW 的另一个优势是可以与 TypeScript 深度集成。通过从 OpenAPI 规范生成类型定义，可以在请求/响应两个方向获得类型提示和自动补全：

// typed-handlers.ts — 类型安全的 MSW Handler import { http, HttpResponse } from 'msw'; /** 从 OpenAPI 自动生成的请求/响应类型 */ interface GetUsersRequest { query: { page?: number; pageSize?: number; keyword?: string; }; } interface GetUsersResponse { /** 状态码 */ code: number; data: { list: Array<{ id: number; name: string; email: string; role: string; }>; total: number; }; } /** * 类型安全的用户列表 Handler * 通过类型系统确保 Mock 数据与接口定义一致 */ export const getUsersHandler = http.get<never, GetUsersRequest['query'], GetUsersResponse>( '/api/users', ({ request }) => { const url = new URL(request.url); const page = Number(url.searchParams.get('page') ?? '1'); const pageSize = Number(url.searchParams.get('pageSize') ?? '10'); const keyword = url.searchParams.get('keyword') ?? ''; // 模拟分页逻辑 const totalItems = keyword ? 42 : 156; const totalPages = Math.ceil(totalItems / pageSize); if (page > totalPages) { // 超出页数范围时返回空列表而非报错 return HttpResponse.json({ code: 0, data: { list: [], total: totalItems }, }); } // 生成示例用户数据 const startId = (page - 1) * pageSize + 1; const list = Array.from({ length: pageSize }, (_, i) => ({ id: startId + i, name: keyword ? `${keyword}_用户${startId + i}` : `用户${startId + i}`, email: `user${startId + i}@example.com`, role: i % 3 === 0 ? 'admin' : i % 3 === 1 ? 'editor' : 'viewer', })); return HttpResponse.json({ code: 0, data: { list, total: totalItems }, }); } );

五、总结

前端 Mock 数据体系的演进本质上是工程复杂度从"手动维护 JSON 文件"向"自动化生成 + 多环境复用"的迁移。在以下三个决策点上给出建议：

Mock 工具选型：2026 年的项目中，MSW 应该是默认选择。JSON Server 和 Mock.js 的历史遗留场景可以逐步迁移，但新项目不应再使用——前者缺乏测试环境支持，后者在 Node.js 侧的拦截能力受限。

Mock 数据维护：优先从 OpenAPI 规范自动生成 Handler，而非手动维护。即使起初没有完整的 API 规范，也应将手工编写的 Handler 结构化组织（按域划分、边界场景独立文件），避免单个文件膨胀到 500+ 行。

边界场景覆盖：需将边界状态的 Handler 作为 CI 流程的一个检查项。建议的覆盖清单包括：超时、500 错误、429 限流、空列表、大数据量（≥ 1000 条）、认证过期（401）。

Mock 不是"后端接口没写好时的临时替代"，而是前端质量体系的基础设施——它决定了开发效率的下限和测试覆盖的上限。