Skip to content
On this page

mockConfig

type: MockOptionsItem | MockOptionsItem[]

ts
import { defineMock } from 'vite-plugin-mock-dev-server'

export default defineMock({
  url: '/api/test',
  body: {}
})
import { defineMock } from 'vite-plugin-mock-dev-server'

export default defineMock({
  url: '/api/test',
  body: {}
})

url

  • Type: string
  • 必填

请求地址。

通过 path-to-regexp 库路径匹配,支持 静态url匹配和动态url匹配。

ts
export default defineMock([
  {
    url: '/api/post/list',
  }, 
  {
    url: '/api/post/:postId',
  }
])
export default defineMock([
  {
    url: '/api/post/list',
  }, 
  {
    url: '/api/post/:postId',
  }
])

method

  • Type: Method | Method[]
  • 选填
  • 默认值: ['POST', 'GET']

接口支持的请求方法。

仅符合的请求方法返回 mock data,否则忽略。可通过数组配置接口支持多种请求方法。

ts
type Method = 
  | 'GET' | 'POST' | 'PUT' | 'DELETE' 
  | 'PATCH' | 'HEAD' | 'TRACE' | 'OPTIONS'
type Method = 
  | 'GET' | 'POST' | 'PUT' | 'DELETE' 
  | 'PATCH' | 'HEAD' | 'TRACE' | 'OPTIONS'

enabled

  • Type: boolean
  • 选填
  • 默认值: true

是否开启当前 mock config。

ts
export default defineMock({
  url: 'api/test',
  enabled: false, // 关闭当前 mock,api/test 将不会生效
})
export default defineMock({
  url: 'api/test',
  enabled: false, // 关闭当前 mock,api/test 将不会生效
})

status

  • Type: number
  • 选填
  • 默认值: 200

响应状态码。

statusText

  • Type: string
  • 选填
  • 默认值: 'OK'

响应状态文本。

delay

  • Type: number | [number, number]
  • 选填
  • 单位: ms
  • 默认值: 0,表示不延迟

接口延迟响应。

延迟接口一段时间后再返回响应数据。 如果传入的是一个数组,则表示延迟响应的时间范围。

type

  • Type: 'text' | 'json' | 'buffer' | string
  • 选填
  • 默认值: 'json'

设置 content-type 类型,如果是响应一个文件类型,可以将 文件名 作为值传给 type

插件内部由 mime-types 判断获取真实的 content-type

headers

  • Type: Record<string, string> | (request: RequestOptions) => Record<string, string>

  • 选填

  • 默认值:

    默认值根据 type 的值确定:

    type默认值
    text{ 'Content-Type': 'text/plain' }
    json{ 'Content-Type': 'application/json' }
    buffer{'Content-Type': 'application/octet-stream' }
    其他值根据传入值由 mime-types 判断获取

配置请求响应头

ts
// 请求接口包含的信息
interface RequestOptions {
  query: Record<string, string> // query string parse
  params: Record<string, string> // params parse
  headers: Record<string, string> // request headers
  body: any // request body
  getCookie: (name: string, option?: Cookies.GetOption) => string | void
}
// 请求接口包含的信息
interface RequestOptions {
  query: Record<string, string> // query string parse
  params: Record<string, string> // params parse
  headers: Record<string, string> // request headers
  body: any // request body
  getCookie: (name: string, option?: Cookies.GetOption) => string | void
}

cookies

  • Type: ResponseCookies | ResponseCookiesFn
  • 选填
  • 默认值: undefined

设置响应体 cookies

ts
type CookieValue = string | [string, Cookies.SetOption]
type ResponseCookies = Record<string, CookieValue>
type ResponseCookiesFn = (
  request: RequestOptions,
) => ResponseCookies | Promise<ResponseCookies>
type CookieValue = string | [string, Cookies.SetOption]
type ResponseCookies = Record<string, CookieValue>
type ResponseCookiesFn = (
  request: RequestOptions,
) => ResponseCookies | Promise<ResponseCookies>

body

  • Type: ResponseBody | ((request: RequestOptions) => ResponseBody | Promise<ResponseBody>)
  • 选填
  • 默认值: {}

响应体数据。

定义返回的响应体内容。

支持使用 mockjs 等第三方库生成 mock data body。

ts
type ResponseBody = string | number | array | object | Buffer | ReadableStream
type ResponseBody = string | number | array | object | Buffer | ReadableStream

response

  • Type: (req, res, next) => void | Promise<void>
  • 选填
  • 默认值: null

如果通过 body 配置不能解决mock需求,那么可以通过 配置 response,暴露http server 的接口,实现完全可控的自定义配置。 在 req 参数中,已内置了 query、body、params、refererQuery 的解析,以及 getCookie 方法, 在 res中添加了 setCookie 方法, 你可以直接使用它们。

别忘了,需要通过 res.end() 返回响应体数据,或者需要跳过mock,那么别忘了调用 next()

validator

  • Type: Validator | ValidatorFn
    ts
    interface Validator {
      header?: object
      body?: object
      query?: object
      params?: object
      refererQuery?: object
    }
    interface ValidatorFn {
      (request: RequestOptions): boolean
    }
    interface Validator {
      header?: object
      body?: object
      query?: object
      params?: object
      refererQuery?: object
    }
    interface ValidatorFn {
      (request: RequestOptions): boolean
    }
  • 选填
  • 默认值: null

请求验证器,通过验证器则返回 mock数据,否则不使用当前mock。

这对于一些场景中,某个接口需要通过不同的入参来返回不同的数据, 验证器可以很好的解决这一类问题,将同个 url 分为多个 mock配置, 根据 验证器来判断哪个mock配置生效。

如果 validator 传入的是一个对象,从 v1.1.14 版本开始,将会判断 validator 配置 的 headers/query/params/body/refererBody 对象,是否是当前请求的对应的请求数据的子集,比较是深度比较,如果属性值是数组,则需要数组的所有项都在请求数据的对应的数据的数组中。

如果 validator 传入的是一个函数,那么会将 请求的接口相关数据作为入参,提供给使用者进行自定义校验,并返回一个 boolean。

在插件内,会解析请求该mock api 的来源页面地址,通过获取 request.referer,提取 url 中 query部分,解析为refererQuery 。这使得可以通过直接在浏览器地址栏中,修改页面 queryString, 根据不同的 queryString 来决定 mock api 返回的数据内容。

ts
export default defineMock([
  {
    url: 'api/list',
    validator: { query: { p: 1 } },
    body: {
      result: [ { title: 'p1' } ],
      page: 1,
    }
  },
  {
    url: 'api/list',
    validator: { query: { p: 2 } },
    body: {
      result: [ { title: 'p2' } ],
      page: 2,
    }
  }
])
export default defineMock([
  {
    url: 'api/list',
    validator: { query: { p: 1 } },
    body: {
      result: [ { title: 'p1' } ],
      page: 1,
    }
  },
  {
    url: 'api/list',
    validator: { query: { p: 2 } },
    body: {
      result: [ { title: 'p2' } ],
      page: 2,
    }
  }
])

ws

  • 选填
  • 类型 Boolean
  • 默认值: false

如果需要配置 模拟 Websocket ,必须显式的指定 ws 的值为 true

setup

  • 选填, 如果 ws值为true, 则该选项必填
  • 类型:(wss: WebSocketServer) => Destroy | void
    ts
    type Destroy = () => void
    type Destroy = () => void

该选项仅用于 模拟 Websocket

ts
export default {
  ws: true,
  setup(wss, { onCleanup }) {
    // wss 是 WebSocketServer 的实例,在服务器端,一个请求地址对应一个 wss
    // 但是允许多个客户端同时请求该地址建立 ws连接。
    // 在 `connection` 事件监听中, 回调参数 `ws` 表示其中一个 客户端的 `ws` 连接。

    wss.on('connection', (ws, res) => {
      ws.on('message', (raw) => {
        console.log(raw)
      })
      const timer = setInterval(() => {
        ws.send('data')
      }, 2000)
      // 在该函数中 清除 自动执行任务、或者终止其他方法执行
      // 但是无需在此函数内 删除 wss、ws 的监听事件,
      // 插件内部在热更新时,会自动处理,避免重复的事件监听
      onCleanup(() => clearInterval(timer))
    })
  }
}
export default {
  ws: true,
  setup(wss, { onCleanup }) {
    // wss 是 WebSocketServer 的实例,在服务器端,一个请求地址对应一个 wss
    // 但是允许多个客户端同时请求该地址建立 ws连接。
    // 在 `connection` 事件监听中, 回调参数 `ws` 表示其中一个 客户端的 `ws` 连接。

    wss.on('connection', (ws, res) => {
      ws.on('message', (raw) => {
        console.log(raw)
      })
      const timer = setInterval(() => {
        ws.send('data')
      }, 2000)
      // 在该函数中 清除 自动执行任务、或者终止其他方法执行
      // 但是无需在此函数内 删除 wss、ws 的监听事件,
      // 插件内部在热更新时,会自动处理,避免重复的事件监听
      onCleanup(() => clearInterval(timer))
    })
  }
}

注意

WARNING

如果使用 json/json5 编写 mock文件,则不支持使用 response 方法,以及不支持使用其他字段的函数形式。

Released under the MIT License.