你真的会用 YApi 来做 Mock 吗？

前言

越来越多的企业、团队在接口文档，mock上都替换为了 YApi，不得不说这真的是一款非常不错的开源框架，不仅起到了文档的作用，也同时兼具着 mock 的能力，以及自动化测试的能力。

但是，如果不做任何处理，mock 的数据全部都是杂乱的基本数据，如果希望随机的数据可以相对符合我们的预期，应该怎么做呢？

YApi 的 mock 可以做那些事？

在我们平常的开发工作中，我们都是通过 YApi 的 Mock 地址来进行模拟请求的

它不仅可以帮我们随机生成文档中描述的数据结构

还可以按照我们的需求返回相当仿真的数据，用来做一些上线前的演示工作再合适不过

我们还可以用它来模拟一些可控的极端数据情况，帮助我们做一些边界性测试

甚至可以指定入参来返回特定的出参，让我们的演示项目足以以假乱真

那么，上面说的这些 mock 场景，我们应该怎么来操作呢？

YApi Mock 操作指南

这里默认大家已经对 YApi 开源系统有了基本的了解和使用经验，重点分享 mock 的操作方式及注释说明

基本操作：返回仿真数据

选择任一接口，选择【编辑】，我们可以看到返回数据设置

而红框的部分，就是我们重点需要关注的地方，我们尝试在这里输入 @，会发现下拉菜单有很多以 @ 开头的选项，这些选项究竟是什么，我们得好好了解了解。

在介绍之前，需要先和大家简单说一说大名鼎鼎的 Mock.js。

Mock.js 是一个开源的 JavaScript 库，它提供了模拟接口请求和生成随机数据的能力，为前端开发者提供了便利。内部提供了丰富的数据生成规则，用于生成各种类型的随机数据。

而 YApi 的数据生成规则就是基于 Mock.js 来实现的，所以我们在配置之前，需要好好学习一下数据生成规则。

Mock.js 的语法规范包括两部分，一个是数据模板定义规范（Data Template Definition，DTD） ，一个是数据占位符定义规范（Data Placeholder Definition，DPD）

这里我们重点展开介绍一下第二条数据占位符（详见数字占位符参考手册）

学习了数据占位符后，我们基本上可以利用这些占位符随机出我们想要的内容，它的种类及其丰富，基本涵盖了我们所需要的各式各样的数据

高级定制：期望

有了仿真数据之后，肯定也有小伙伴会提出更离谱的需求

我们能不能按某些条件返回一些特定的结果呢？比如说，模拟查询之类的？

答案是：当然可以！

我们可以利用 YApi 的 高级Mock-期望 来完成

点击添加期望，我们能够自定义参数的数量和值

并以此来决定返回值

同时我们可以按这种方式添加多个期望，来达到我们预想的更换查询条件返回不同的查询结果

对于一些演示项目来说，这效果足以媲美真实项目

高级定制：自定义 Mock 脚本

在某些前端开发场景，一些接口逻辑、业务相对复杂，UI也需要根据不同的返回做不同的处理，YApi 提供了自定义脚本的方式，让我们可以根据请求参数修改返回的内容

Mock 脚本就是用 JavaScript 对 mockJson 变量修改，请避免被全局变量(httpCode, resHeader, delay)的修改

举例说明：

通过不同的 type， 返回不同的结果。

if(params.type == 1){
  mockJson.errcode = 400;
  mockJson.errmsg = 'error';
}

if(header.token == 't'){
  mockJson.errcode = 300;
  mockJson.errmsg = 'error';
}

if(cookie.type == 'a'){
  mockJson.errcode = 500;
  mockJson.errmsg = 'error';
}

如何使用

1. 在 js 代码中直接配置好相关的 baseUrl 地址

let baseUrl = 'http://xxxx:xxxx/mock/123'
const prefix = '/api'
$.post(baseUrl + prefix + '/path', { username: 'xxx' }, function(res){
    console.log(res) //返回上图预览部分的数据
})

1. 不用修改项目代码，通过 Nginx 反向代理完成 Mock

location /api
{
    proxy_pass  http://xxxx:xxxx/mock/123; #baseapi后面没有"/"
}

Mock优先级说明

请求 Mock 数据时，规则匹配优先级：Mock 期望 > 自定义 Mock 脚本 > 项目全局 mock 脚本 > 普通 Mock。

如果前面匹配到 Mock 数据，后面 Mock 则不返回。

数字占位符速查手册

@boolean

返回一个随机的布尔值。

• @boolean()
• @boolean( min, max, current )

参数	说明
min	指示参数 current 出现的概率。概率计算公式为 min / (min + max)。该参数的默认值为 1，即有 50% 的概率返回参数 current
max	指示参数 current 的相反值 !current 出现的概率。概率计算公式为 max / (min + max)
current	可选值为布尔值 true 或 false。如果未传入任何参数，则返回 true 和 false 的概率各为 50%。该参数没有默认值

// 下面写法表示：false 出现的概率为 0.1，true 出现的概率为 0.9
@boolean(1, 9, false)

@string

返回一个随机字符串。

• @string()
• @string( length )
• @string( pool, length )
• @string( min, max )
• @string( pool, min, max )

参数	说明
pool	表示字符池'lower' 或 'upper'、'number'、'symbol'，将从中选择一个字符返回
min	随机字符串的最小长度。默认值为 3
max	随机字符串的最大长度。默认值为 7

@string()
// => "pJjDUe"
@string( 5 )
// => "GaadY"
@string( 'lower', 5 )
// => "jseqj"
@string( 7, 10 )
// => "UuGQgSYk"
@string( 'aeiou', 1, 3 )
// => "ea"
@string( '壹贰叁肆伍陆柒捌玖拾', 3, 5 )
// => "肆捌伍叁"

@natural

返回一个随机的自然数（大于等于 0 的整数）。

• @natural()
• @natural( min )
• @natural( min, max )

参数	说明
min	指示随机自然数的最小值。默认值为 0
max	指示随机自然数的最大值。默认值为 9007199254740992

@natural()
// => 1002794054057984
@natural(10000)
// => 71529071126209
@natural(60, 100)
// => 77

@integer

返回一个随机的整数。

• @integer()
• @integer( min )
• @integer( min, max )

参数	说明
min	指示随机整数的最小值。默认值为 -9007199254740992
max	指示随机整数的最大值。默认值为 9007199254740992

@integer()
// => -3815311811805184
@integer(10000)
// => 4303764511003750
@integer(60,100)
// => 96

@float

返回一个随机的浮点数

• @float()
• @float( min )
• @float( min, max )
• @float( min, max, dmin )
• @float( min, max, dmin, dmax )

参数	说明
min	整数部分的最小值。默认值为 -9007199254740992
max	整数部分的最大值。默认值为 9007199254740992
dmin	小数部分位数的最小值。默认值为 0
dmax	小数部分位数的最大值。默认值为 17

@float()
// => -1766114241544192.8
@float(0)
// => 556530504040448.25
@float(60, 100)
// => 82.56779679549358
@float(60, 100, 3)
// => 61.718533677927894
@float(60, 100, 3, 5)
// => 70.6849

@character

返回一个随机字符。

• @character()
• @character( 'lower/upper/number/symbol' )
• @character( pool )

参数	说明
pool	表示字符池'lower' 或 'upper'、'number'、'symbol'，将从中选择一个字符返回

@character()
// => "P"
@character('lower')
// => "y"
@character('upper')
// => "X"
@character('number')
// => "1"
@character('symbol')
// => "&"
@character('aeiou')
// => "u"

@range

返回一个整型数组。

• @range( stop )
• @range( start, stop )
• @range( start, stop, step )

参数	说明
start	数组中整数的起始值。
stop	数组中整数的结束值（不包含在返回值中）。
step	数组中整数之间的步长。默认值为 1。

@range(10)
// => [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
@range(3, 7)
// => [3, 4, 5, 6]
@range(1, 10, 2)
// => [1, 3, 5, 7, 9]
@range(1, 10, 3)
// => [1, 4, 7]

@date、@datetime、@time、@now

返回随机时间字符串，区别在于默认值的不同

参数	说明
format	yyyy-MM-dd hh:mm:ss

@datetime()
// => "1977-11-17 03:50:15"
@date()
// => "2002-10-23"
@time()
// => "00:14:47"
@now()
// => "2023-09-07 20:08:38 "

@image

生成一个随机的图片地址

• @image()
• @image( size )
• @image( size, background )
• @image( size, background, text )
• @image( size, background, foreground, text )
• @image( size, background, foreground, format, text )

参数	说明
size	宽x高 ，默认会从图片尺寸池中提取
background	图片的背景色
foreground	图片的前景色（文字）
format	图片格式，默认值为png，可选值：png、gif、jpg
text	图片上的文字

@image()
// => "http://dummyimage.com/125x125"
@image('200x100')
// => "http://dummyimage.com/200x100"
@image('200x100', '#fb0a2a')
// => "http://dummyimage.com/200x100/fb0a2a"
@image('200x100', '#02adea', 'Hello')
// => "http://dummyimage.com/200x100/02adea&text=Hello"
@image('200x100', '#00405d', '#FFF', 'Mock.js')
// => "http://dummyimage.com/200x100/00405d/FFF&text=Mock.js"
@image('200x100', '#ffcc33', '#FFF', 'png', '!')
// => "http://dummyimage.com/200x100/ffcc33/FFF.png&text=!"

@color、@hex、@rgb、@rgba、@hsl

随机生成一个有吸引力的颜色，不同前缀为不同颜色格式，@color === @hex

• @color()
• @hex()
• @rgb()
• @rgba()
• @hsl()

@color()
// => "#3538B2"
@hex()
// => "#3538B2"
@rgb()
// => "rgb(242, 198, 121)"
@rgba()
// => "rgba(242, 198, 121, 0.13)"
@hsl()
// => "hsl(345, 82, 71)"

@paragraph、@ccparagraph、@word、@cword

随机生成一段文本或单词，前缀 c 标识中文，后续规则类似

• @paragraph()
• @paragraph( len )
• @paragraph( min, max )
• @cparagraph()
• @cparagraph( len )
• @cparagraph( min, max )
• @word()
• @word( len )
• @word( min, max )
• @cword()
• @cword( pool )
• @cword( length )
• @cword( pool, length )
• @cword( min, max )
• @cword( pool, min, max )

参数	说明
len	长度
min	最小长度
max	最大长度
pool	汉字字符串，可从中选择一个字符返回

@name、@cname

随机生成一个英文名或中文名

• @name()
• @cname()

@name()
// => "Larry Wilson"
@cname()
// => "袁军"

@url、@protocol、@domain、@ip、@email

随机生成一个网址、URL协议、域名、ip地址、邮箱地址

• @url()
• @url( protocol, host )
• @protocol()
• @host()
• @domain()
• @ip()
• @email()

参数	说明
protocol	URL协议，http、https
host	域名

@region、@province、@city、@county、@zip

随机生成一个中国大区、省（直辖市、自治区、特别行政区）、市、县、邮政编码

• @region()
• @province()
• @city()
• @county()
• @zip()

@region()
// => "华北"
@province()
// => "黑龙江省"
@city()
// => "唐山市"
@county()
// => "上杭县"
@zip()
// => "908812"

@pick

从数组中随机取一个元素返回

• @pick( arr )

参数	说明
arr	随机数组池

@pick(['a', 'e', 'i', 'o', 'u'])
// => "o"

@guid

随机生成一个GUID，生成方式参考UUID 规范

• @guid()

@guid()
// => "662C63B4-FD43-66F4-3328-C54E3FF0D56E"

@id

随机生成一个18为身份证

• @id()

@id()
// => "420000200710091854"

附录:

字符池描述

{
    lower: "abcdefghijklmnopqrstuvwxyz",
    upper: "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    number: "0123456789",
    symbol: "!@#$%^&*()[]"
}

图片尺寸池描述

[    '300x250', '250x250', '240x400', '336x280',     '180x150', '720x300', '468x60', '234x60',     '88x31', '120x90', '120x60', '120x240',     '125x125', '728x90', '160x600', '120x600',     '300x600']