# rspack-plugin-mock
在 [Rspack](https://rspack.dev) and [Rsbuild](https://rsbuild.dev) 中注入 API mock 服务。
在 `rspack` 和 `rsbuild` 中实现与 [vite-plugin-mock-dev-server](https://github.com/pengzhanbo/vite-plugin-mock-dev-server) 完全一致的模拟开发服务。
English | 简体中文
> [!IMPORTANT]
> 从插件 2.0 版本开始，仅支持 `rspack@2.x` 版本 和 `rsbuild@2.x` 版本.
>
> 如果您使用的是 `rspack@1.x` 或 `rsbuild@1.x` 版本，请使用 `rspack-plugin-mock@1.x` 版本.
## 特性
- ⚡️ 轻量，灵活，快速
- 🧲 非注入式，对客户端代码无侵入
- 💡 ESModule
- 🦾 Typescript
- 🔥 热更新
- 🏷 支持 `.[cm]?js`/ `.ts` / `json` / `json5` 编写 mock 数据
- 📦 自动加载 mock 文件
- 🎨 可选择你喜欢的任意用于生成mock数据库，如 `mockjs`，或者不使用其他库
- 📥 路径规则匹配，请求参数匹配
- ⚙️ 随意开启或关闭对某个接口的 mock配置
- 📀 支持多种响应体数据类型，包括 `text/json/buffer/stream`.
- ⚖️ rspack 中使用 `devServer.proxy` 配置, rsbuild 中使用 `server.proxy` 配置
- 🍕 支持在 mock 文件中使用 `define`配置
- ⚓️ 支持在 mock 文件中使用 `resolve.alias` 路径别名
- 📤 支持 multipart 类型，模拟文件上传
- 📥 支持模拟文件下载
- ⚜️ 支持模拟 `WebSocket` 和 `Server-Sent Events`
- 📝 支持 **请求录制** 和 **请求回放**
- 🗂 支持构建可独立部署的小型mock服务
## 安装
```sh
# npm
npm i -D rspack-plugin-mock
# yarn
yarn add rspack-plugin-mock
# pnp
pnpm add -D rspack-plugin-mock
```
## 使用
**In Rspack**
```ts
// rspack.config.js
import { MockServerPlugin } from 'rspack-plugin-mock'
export default {
devServer: {
// 插件将会读取 `proxy` 配置
proxy: [
{ context: '/api', target: 'http://example.com' },
],
},
plugins: [
new MockServerPlugin(/* pluginOptions */),
]
}
```
**In Rsbuild**
```ts
// rsbuild.config.ts
import { defineConfig } from '@rsbuild/core'
import { pluginMockServer } from 'rspack-plugin-mock/rsbuild'
export default defineConfig({
server: {
// 插件将会读取 `proxy` 配置
proxy: {
'/api': 'http://example.com',
},
},
plugins: [
pluginMockServer(/* pluginOptions */),
],
})
```
### 编写 mock 配置文件
插件默认会读取 项目根目录的 `mock` 目录：
`mock/**/*.mock.ts` :
```ts
import { defineMock } from 'rspack-plugin-mock/helper'
export default defineMock({
url: '/api/test',
body: { a: 1, b: 2 }
})
```
你可以使用 `.js, .mjs, .cjs, .ts, .json, .json5` 文件格式来编写 mock 配置。
## 方法
### MockServerPlugin(pluginOptions)
rspack mock 服务插件。
插件将会读取 `devServer.proxy` 配置，然后在 `@rspack/dev-server` 中注入中间件。
```js
import { MockServerPlugin } from 'rspack-plugin-mock'
export default {
devServer: {
// 插件将会读取 `proxy` 配置
proxy: [
{ context: '/api', target: 'http://example.com' },
],
},
plugins: [
new MockServerPlugin(/* 插件配置 */),
]
}
```
### pluginMockServer(pluginOptions)
rsbuild mock 服务插件. **仅适用于 `rsbuild`.**
```ts
// rsbuild.config.ts
import { defineConfig } from '@rsbuild/core'
import { pluginMockServer } from 'rspack-plugin-mock/rsbuild'
export default defineConfig({
server: {
// 插件将会读取 `proxy` 配置
proxy: {
'/api': 'http://example.com',
},
},
plugins: [
pluginMockServer(/* 插件配置 */),
],
})
```
### defineMock(options)
- **options:** [`MockOptions | MockOptions[]`](#mock-配置)
mock 配置类型帮助函数
```ts
import { defineMock } from 'rspack-plugin-mock/helper'
export default defineMock({
url: '/api/test',
body: { a: 1, b: 2 }
})
```
### createDefineMock(transformer)
- **transformer:** `(mock: MockOptions) => MockOptions`
返回一个自定义的 defineMock 函数，以支持对 mock 配置进行预处理。
```ts
import { createDefineMock } from 'rspack-plugin-mock/helper'
const definePostMock = createDefineMock((mock) => {
mock.url = `/api/post/${mock.url}`
})
export default definePostMock({
url: 'list', // => '/api/post/list'
body: [{ title: '1' }, { title: '2' }],
})
```
### createSSEStream(req, res)
创建一个 `Server-sent events` 写入流，用于支持模拟 `EventSource`。
``` ts
import { createSSEStream, defineMock } from 'rspack-plugin-mock/helper'
export default defineMock({
url: '/api/sse',
response: (req, res) => {
const sse = createSSEStream(req, res)
sse.write({ event: 'message', data: { message: 'hello world' } })
sse.end()
}
})
```
## 插件配置
- **类型：** `boolean`
- **默认值：** `true`
- **详情：**
是否开启 mock 服务。如果设置为 `false`，插件将不会生效。
### prefix
- **类型：** `string | string[]`
- **详情：**
为 http mock 服务配置 路径匹配规则，任何请求路径以 prefix 开头的都将被拦截代理。
如果 prefix 以 `^` 开头，将被识别为 `RegExp`。
### wsPrefix
- **类型：** `string | string[]`
- **详情：**
为 websocket mock 服务配置 路径匹配规则， 任何请求路径以 wsPrefix 开头的 ws/wss请求，都将被代理拦截。
如果 wsPrefix 以 `^` 开头，将被识别为 `RegExp`。
请避免在 `devServer.proxy` / `server.proxy` 中出现 `wsPrefix` 配置中相同的规则，因为这可能会导致规则冲突。
### cwd
- **类型：** `string`
- **默认值：** `process.cwd()`
- **详情：**
配置 `include` 和 `exclude` 的匹配上下文。
### dir
- **类型：** `string`
- **默认值：** `mock` (相对于 [`cwd`](#cwd))
- **详情：**
配置 mock 包的输出目录，相对于 [`cwd`](#cwd)
### include
- **类型：** `string | string[]`
- **默认值：** `[**/*.mock.{js,ts,cjs,mjs,json,json5}']` (相对于 [`dir`](#dir))
- **详情：**
glob 字符串匹配 mock 包含的文件。 查看 [picomatch](https://github.com/micromatch/picomatch#globbing-features)
### exclude
- **类型：** `string | string[]`
- **默认值：** `[]` (相对于 [`dir`](#dir))
- **详情：**
glob 字符串匹配 mock 排除的文件。 查看 [picomatch](https://github.com/micromatch/picomatch#globbing-features)
### log
- **类型：** `boolean | 'info' | 'warn' | 'error' | 'silent' | 'debug'`
- **默认值：** `info`
- **详情：**
开启日志，或配置 日志级别
### reload
- **类型：** `boolean`
- **默认值：** `false`
- **详情：**
mock资源热更新时，仅更新了数据内容，但是默认不重新刷新页面。
当你希望每次修改mock文件都刷新页面时，可以打开此选项。
### activeScene
- **类型：** `string | string[]`
- **默认值：** `''`
- **详情：**
当前激活的场景，用于过滤 mock。
只有 [`scene`](#optionsscene) 与此有交集的 mock（或未配置 `scene` 的 mock）才会被考虑匹配。可通过 `X-Mock-Scene` 请求头按请求覆盖。
### cors
- **类型：** `boolean | CorsOptions`
- **默认值：** `true`
- **详情：**
配置 [cors](https://github.com/expressjs/cors#configuration-options)
### formidableOptions
- **类型：** `FormidableOptions`
- **默认值：** `{ multiples: true }`
- **详情：**
配置 [formidable](https://github.com/node-formidable/formidable#options)
### cookiesOptions
- **类型：** `CookiesOptions`
- **详情：**
配置 [cookies](https://github.com/pillarjs/cookies#new-cookiesrequest-response--options)
### bodyParserOptions
- **类型：** `BodyParserOptions`
- **详情：**
配置 [co-body](https://github.com/cojs/co-body#options)
## build
- **类型：** `boolean | ServerBuildOption`
```ts
interface ServerBuildOption {
/**
* 服务启动端口
* @default 8080
*/
serverPort?: number
/**
* 构建输出目录，相对于 rspack/rsbuild 构建输出目录
* @default 'mockServer'
*/
dist?: string
/**
* 服务日志级别
* @default 'error'
*/
log?: LogLevel
}
```
- **默认值：** `false`
- **详情：**
当需要构建一个小型mock服务时，可配置此项。插件会在构建生产包时，额外生成一个可部署的node mock 服务包。
### record
- **类型：** `false | RecordOptions`
- **默认值：** `false`
- **详情：**
是否开启请求录制功能。开启后，插件会记录所有请求数据，用于后续的请求回放。
插件在 `proxy` 的基础上，记录被 `http-proxy` 代理的请求数据。
在获得响应后，插件会将请求数据和响应数据记录到指定的目录中。
```ts
interface RecordOptions {
/**
* 是否启用录制功能
* - true: 启用，自动录制 proxy 响应
* - false: 禁用（默认）
* @default false
*/
enabled?: boolean
/**
* 过滤要录制的请求
* - 函数：自定义过滤函数，返回 true 表示录制
* - 对象：包含/排除模式，支持 glob 或 path-to-regexp 模式
* @example
* ```ts
* // Record all requests
* filter: (req) => true
* // Record requests using glob pattern
* filter: { mode: 'glob', include: '/api/**' }
* // Record requests using path-to-regexp pattern
* filter: { mode: 'path-to-regexp', include: '/api/:id' }
* ```
*/
filter?: ((req: RecordedReq) => boolean) | {
/**
* 包含需要录制的请求链接
*
* glob 模式或 path-to-regexp 模式
* (使用 mode 选项设置模式，默认为 glob)
*/
include?: string | string[]
/**
* 排除不需要录制的请求链接
*
* glob 模式或 path-to-regexp 模式
* (使用 mode 选项设置模式，默认为 glob)
*/
exclude?: string | string[]
/**
* 包含/排除模式的匹配模式
* - 'glob': glob 模式匹配（默认）
* - 'path-to-regexp': path-to-regexp 模式匹配
*/
mode: 'glob' | 'path-to-regexp'
}
/**
* 录制数据存储目录
* 相对于项目根目录
* @default 'mock/.recordings'
*/
dir?: string
/**
* 是否覆盖已有录制数据
* - true: 相同请求覆盖旧数据（默认）
* - false: 保留旧数据，不录制新数据
* @default true
*/
overwrite?: boolean
/**
* 录制数据过期时间（秒）
* - 0: 永不过期（默认）
* - 正数：指定秒数后过期
* @default 0
*/
expires?: number
/**
* 要录制的状态码
* - 为空数组时记录所有状态码（默认）
* - 指定一个或多个状态码进行过滤
* @default []
*/
status?: number | number[]
/**
* 是否在录制目录中添加 .gitignore
* - true: 添加（默认）
* - false: 不添加
* @default true
*/
gitignore?: boolean
}
```
### replay
- **类型：** `boolean`
- **默认值：** `false`
- **详情：**
是否开启请求回放功能。开启后，插件会根据记录的请求数据，模拟响应。
### priority
- **类型：** `MockMatchPriority`
- **详情：**
自定义 路径匹配规则优先级。[查看更多](#自定义匹配优先级)
**默认值：** `undefined`
## Mock 配置
**http mock**
```ts
import { defineMock } from 'rspack-plugin-mock/helper'
export default defineMock({
url: '/api/test',
body: { message: 'hello world' }
})
```
**websocket mock**
```ts
import { defineMock } from 'rspack-plugin-mock/helper'
export default defineMock({
url: '/socket.io',
ws: true,
setup(wss) {
wss.on('connection', (ws, req) => {
console.log('connected')
})
}
})
```
### options.url
- **类型：** `string`
- **详情：**
需要进行 mock 的接口地址, 由 [path-to-regexp](https://github.com/pillarjs/path-to-regexp) 提供路径匹配支持。
### options.enabled
- **类型：** `boolean`
- **默认值：** `true`
- **详情：**
是否启动对该接口的mock，在多数场景下，我们仅需要对部分接口进行 mock，
而不是对所有配置了mock的请求进行全量mock，所以是否能够配置是否启用很重要
### options.scene
- **类型：** `string | string[]`
- **默认值：** `''`
- **详情：**
该 mock 的场景标识。
未配置时，该 mock 为全场景通用，不受 [activeScene](#activescene) 限制。
配置后，只有 `scene` 中任意一项与 [activeScene](#activescene) 中任意一项匹配时，该 mock 才会激活。
### options.method
- **类型：** `Method | Method[]`
```ts
type Method = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'OPTIONS' | 'HEAD' | 'PATCH'
```
- **默认值：** `['GET', 'POST']`
- **详情：**
该接口允许的 请求方法，默认同时支持 GET 和 POST
### options.type
- **类型：** `'text' | 'json' | 'buffer' | string`
- **详情：**
响应体数据类型。 还支持 [mime-db](https://github.com/jshttp/mime-db) 中的包含的类型。
当响应体返回的是一个文件，而你不确定应该使用哪个类型时，可以将文件名作为值传入，
插件内部会根据文件名后缀查找匹配的`content-type`。
### options.headers
- **类型：** `object | (request: MockRequest) => object | Promise