MSW.js 在 Node.js 环境中拦截 Undici Fetch 请求的技术解析

在 Node.js 生态系统中，Mock Service Worker (MSW) 是一个广受欢迎的 API 模拟工具，它通过在网络层面拦截请求来实现无侵入式的 API 模拟。然而，当开发者尝试将 MSW 与 Undici 这个高性能 HTTP 客户端结合使用时，会遇到请求无法被拦截的问题。

问题本质

MSW 在 Node.js 环境中主要通过拦截 node:http 模块的请求来实现功能。而 Undici 作为一个独立的 HTTP 客户端，其设计上直接使用了 net.Socket 进行底层网络通信，绕过了 Node.js 标准的 HTTP 模块。这种架构差异导致了 MSW 无法感知到通过 Undici 发出的请求。

技术背景

Undici 作为 Node.js 官方维护的高性能 HTTP 客户端，相比 Node.js 内置的 fetch 实现（基于较旧版本的 Undici）具有以下优势：

1. 支持直接传递 dispatcher 参数
2. 包含了更多已修复的 bug
3. 提供更精细的控制能力

这些特性使得许多开发者选择直接使用 Undici 包而非 Node.js 内置的 fetch 实现。

解决方案

对于需要同时使用 MSW 和 Undici 的场景，目前有以下几种解决方案：

1. 使用 Undici 自带的 MockAgent

Undici 本身提供了 MockAgent 功能，可以满足基本的请求模拟需求。虽然相比 MSW 的语法可能略显繁琐，但这是一个可靠的选择。

import { MockAgent, setGlobalDispatcher } from 'undici'

const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)

const mockPool = mockAgent.get('https://example.com')
mockPool.intercept({
  path: '/',
  method: 'GET'
}).reply(200, 'Hello World')

2. 结合使用 MSW 和 Undici MockAgent

如果既想使用 MSW 的 handler 语法，又需要 Undici 的特性，可以通过 MSW 的 getResponse() 方法将两者结合：

import { setupServer } from 'msw/node'
import { MockAgent, setGlobalDispatcher } from 'undici'
import { http, HttpResponse } from 'msw'

const server = setupServer(
  http.get('https://example.com', () => {
    return new HttpResponse('Hello World')
  })
)

const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)

const mockPool = mockAgent.get('https://example.com')
mockPool.intercept({
  path: '/',
  method: 'GET'
}).reply(async () => {
  const response = await server.getResponse(
    new Request('https://example.com')
  )
  return {
    statusCode: response.status,
    body: await response.text()
  }
})

3. 全局使用 Undici 的 fetch

如果项目允许，可以将 Undici 的 fetch 设置为全局变量，这样 MSW 就能正常拦截：

import { fetch } from 'undici'
globalThis.fetch = fetch

技术展望

虽然 MSW 核心团队目前没有计划直接支持 Undici 的底层 Socket 通信拦截（因为这可能干扰非 HTTP 的 Socket 通信），但未来可能会通过以下方式改进 Node.js 环境的支持：

1. 增强对 net.Socket 层级的拦截能力
2. 提供更灵活的拦截器架构
3. 优化与各种 HTTP 客户端的兼容性

最佳实践建议

对于新项目，如果不需要 Undici 的特定功能，建议直接使用 Node.js 内置的 fetch 实现，这样可以获得最佳的 MSW 兼容性。而对于需要 Undici 特定功能（如 dispatcher）的项目，则建议采用 Undici 自带的 MockAgent 方案。

在架构设计上，可以考虑将 HTTP 客户端相关的代码集中管理，这样在测试时可以更容易地在不同模拟方案之间切换，保持测试套件的灵活性和可维护性。