mock-restful-api

依赖 express 框架实现的接口 mock 服务，参照 django-rest-framework 实现。支持列表刷选、模糊搜索、排序，增删改查等操作。

The interface mock service is implemented by the express framework, and is implemented with reference to django-rest-framework. It supports list selection, fuzzy search, sorting, addition, deletion, modification, and other operations.

可查看版本变更记录ChangeLog

1. 安装

安装

npm install mock-restful-api --save-dev

启动 mock 服务执行 npx mock-restful-api --path <fixtures dir>

全局安装

npm install -g mock-restful-api

启动 mock 服务执行 mock-restful-api --path <fixtures dir>

命令行参数支持

mock-restful-api -h 可查看支持的参数：

1Usage: mock-restful-api [options]
2
3Options:
4  -p, --port <number>  mock服务端口，mock service's port number (default: 3001)
5  --host <string>      mock服务监听的IP地址，mock service's ip (default: "0.0.0.0")
6  --path <string>      mock数据文件的路径/目录，mock json file path (default: "fixtures")
7  --prefix <string>    接口path的前缀，api path prefix (default: "/")
8  --ignore_watch       忽略监听path参数目录下文件变动而重启服务，ignore watch path for reload app (default: false)
9  --delay <number>     延迟响应时间(ms)，在[0,delay]之间随机延迟，mock service's delay time (default: 0)
10  -l --level <string>  日志级别: debug/info/notice/warn/error (default: "debug")
11  -h, --help           display help for command

其中 --path 参数定义的目录必须存在，且会自动监听目录下文件变化进而重启 mock 服务。

2. fixtures 配置文件说明

mcok 数据配置示例：users.json

注： + 代表数据格式深度。

字段	类型	说明	举例
restful	string	restful 接口 path 定义	"web/users/"
page_size	integer	list 接口默认分页大小，默认值：20	20
filter_fields	object	定义可以刷选的字段	{"username": ["exact", "startswith"]}
search_fields	array	定义用于模糊搜索的字段	["username"]
ordering_fields	array	定义用于排序的字段	["id"]
ordering	array	定义默认排序，+递增(默认); -递减	["id"]
pk_field	string	定义数据记录的主键，默认id	"id"
rules	object	定义 POST 提交数据校验要求	{ "username": { "type":"string" } }
rows	array	定义 mock 数据初始列表数据	[{...}, {...}]
actions	array	基于 restful 定义的其他操作
+method	string	请求方法, GET/POST 等
+url_path	string	action 路径	eg: "cancel"，则 path 为 /web/users/cancel/
+detail	bool	是否是详情 action，默认 false	为 true 时 path 为 /web/users/:pk/cancel/
+response	object	定义返回值	{ "code": 200,"json": { "message": "success" } }
apis	array	定义其他普通接口
+path	string	定义接口 path
+method	string	请求方法, GET/POST 等
+response	object	定义返回值

以下按照单个字段配置举例说明.

restful

例如配置 web/users/ 后，基础列表数据用 rows 定义， 服务将支持以下接口：(依赖命令行参数 --prefix="/")

• GET /web/users/ 200 获取列表数据
  • 允许刷选字段由 filter_fields 定义
  • 模糊搜索，接口使用参数 search，允许模糊搜索的字段由 search_fields 定义
  • 排序接口传递参数 ordering，允许排序的字段由 ordering_fields 定义
• POST /web/users/ 201 新建记录, 若配置了 rules ，将会按照 rules 定义对数据进行校验
• GET /web/users/:pk([\\w-]+)/ 200 按照 pk_field 定义主键，根据键值 pk 获取详情
• PATCH /web/users/:pk([\\w-]+)/ 200 更新部分数据
• UPDATE /web/users/:pk([\\w-]+)/ 200 提交完整数据以更新记录
• DELETE /web/users/:pk([\\w-]+)/ 204 根据主键删除记录

需要注意的是：

• 刷选条件对 详情接口的操作也都生效，先根据 query 参数进行刷选，然后再寻找 pk 的记录
• 新增、修改、删除数据，会实际对 rows 数据操作生效，mock 服务重启后数据重置；
• 若是启动 mock 服务的参数 --prefix=openapi 则生成接口示例为 GET /openapi/web/users/

filter_fields

对列表数据刷选，能够筛选的字段必须在该字段中明确定义，示例如下：

1{
2  "filter_fields": {
3    "id": ["exact", "in"],
4    "username": ["exact", "in", "contains", "startswith", "endswith", "regex"],
5    "age": ["exact", "range", "lt", "lte", "gt", "gte", "isnull"],
6    "created_at": ["range"],
7    "city__name": ["exact", "in"]
8  }
9}

其中 field 作为配置数据的键, lookup 作为值，定义筛选的字段。

• 基本的查找关键字参数采用形式 field__lookup=value （使用双下划线）
  • exact 完全匹配，实现的是 == 运算；eg: username=skyler 等价于 username__exact=skyler
  • isnull 刷选数据是否为空的记录
    • age__isnull=1 筛选数据为 undefined/null 的数据，值为 "" 不符合条件
    • age__isnull=0 熟宣数据不为空的数据
  • in 参数是列表值，可用英文逗号 , 隔开；eg: id__in=1,2,3，返回 username 值在 [1,2,3] 内的数据
  • startswith 前缀匹配，eg: username__startswith=sky
  • endswith 后缀匹配，eg: username__endswith=ler
  • contains 字符串包含，eg: username__contains=ky
  • regex 字符串正则, eg: username__regex=sk.*ler
  • range 区间范围，用于日期、数字甚至字符，传递 2 个值时使用逗号 , 隔开
    • age__range=1,100 刷选 age 值在 [1,100] 内的记录，即 0 <= age <= 100
    • age__range=1 筛选 age >= 1 的记录，等价于 age__gte=100
    • age__range=,100 筛选 age <= 100 的记录，等价于 age__lte=100
  • lt 小于， eg: age__lt=100 刷选 age < 100 的记录
  • lte 小于等于， eg: age__lte=100 刷选 age <= 100 的记录
  • gt 大于， eg: age__gt=1 刷选 age > 1 的记录
  • gte 大于等于， eg: age__gte=1 刷选 age >= 1 的记录
• 若是 query 参数中对应值为空字符串，则查询条件不生效；例如 username=&search= 这两个条件都是无效刷选；
• 可用 __ （使用双下划线）定义多级深度的数据查找; eg: city__name__in="beijing" 可帅选出以下数据

1[
2  {
3    "id": 1,
4    "username": "admin",
5    "city": {
6      "name": "beijing"
7    }
8  }
9]

search_fields

定义模糊搜索的字段，示例：

1{
2  "search_fields": ["username", "nickname", "city__name"]
3}

通过 query 传递参数 search=sky 从 rows 记录中按照字段 username / nickname / city.name 判断是否包含 sky 的记录，其中任意一个字段匹配成功即符合条件。

ordering_fields

定义可以用于排序的字段，示例:

1{
2  "ordering_fields": ["id", "name"],
3  "ordering": ["id"]
4}

通过 query 传递参数 ordering=-id,+name ，表示返回的列表数据 按照 id 降序 且 name 升序 的顺序返回。

若 query 没有传递 ordering 参数，则按照默认的配置 "ordering": ["id"] 对 id 升序 返回数据，无符号 +/-时默认为 +升序。

pk_field

定义 rows 列表数据的主键，默认为 id。详情接口中 pk 值与该字段值匹配。

请求 GET /web/users/1/ 则是返回 rows 中数据 id=1 的记录。

rules

定义 新增/修改 数据的校验规则，示例：

1{
2  "rules": {
3    "username": { "type": "string", "pattern": "\\w+", "required": true },
4    "is_active": { "type": "boolean" },
5    "age": { "type": "number", "integer": true, "min": 0, "max": 100 },
6    "gender": { "type": "string", "valid": ["male", "female"] }
7  }
8}

• username 字符串正则，且是必须的字段
• is_active 定义 bool 类型
• age 数值定义取值范围
• gender 字符串，valid 定义枚举值范围

校验规则通过 joi 实现，将 json 配置转成成 Joi 的校验类。具体支持的类型和方法参照 https://joi.dev/api/

actions

actions 是对 restful 的扩展，依赖 restful 的定义，示例：

1{
2  "actions": [
3    {
4      "method": "POST",
5      "url_path": "create/",
6      "response": {}
7    },
8    {
9      "method": "get",
10      "url_path": "releated/",
11      "detail": true,
12      "response": {}
13    }
14  ]
15}

以上配置根据拼接规则 {restful}/{url_path} 会生成以下接口：

• POST /web/users/create/
• GET /web/users/:pk([\\w-]+)/releated/ 因为定义了 detail=true，所以路由支持传递 pk
  • 需要注意的是，pk 只要符合正则定义，无论何值，返回结果都按照 response 定义返回
  • 即 GET /web/users/1/releated/ 和 /web/users/2/releated/ 返回值一样

注意：生成的接口 path 是否 / 结尾，取决于 restful 的配置是否 / 结尾。

apis

定义其他扩展的接口，不依赖 restful ，可单独存在，示例：

1{
2  "apis": [
3    {
4      "method": "get",
5      "path": "web/enums/",
6      "response": {
7        "code": 200,
8        "text": "text"
9      }
10    }
11  ]
12}

response 返回值配置

actions 和 apis 中的配置格式一样，接口都按照配置的数据返回结果。

字段	类型	说明	举例
code	intrger	定义返回状态码	默认值 200
headers	object	定义返回 Header 键值对	{"Content-Type": "image/png"}
json	any	定义返回的 json 数据
text	string	定义返回的文本数据
file	string	定义实现下载文件	配置文件相对(当前运行路径)/绝对路径, eg: ./test.jpg
delay	int	支持单个接口写死一个 delay 延迟返回，单位 ms

3. 接口请求示例

列表接口

1curl "http://0.0.0.0:3001/web/users/?is_active=1&ordering=-id&city__name=anhui&search=sky"

返回状态码为 200：

1{
2  "count": 1,
3  "results": [
4    {
5      "id": 2,
6      "username": "skyler",
7      "nickname": "Skyler",
8      "is_active": true,
9      "age": 18,
10      "gender": "male",
11      "score": 99.9,
12      "created_at": "2024-08-19 21:33:26",
13      "groups": [
14        {
15          "id": "2",
16          "name": "dev"
17        }
18      ],
19      "city": {
20        "id": 2,
21        "name": "anhui"
22      }
23    }
24  ]
25}

创建记录

1curl -XPOST "http://0.0.0.0:3001/web/users/" -H "Content-Type: application/json" -d '{"username":"test"}'

返回状态码为 201：

1{
2  "id": 6,
3  "username": "test"
4}

修改接口

1curl -XPATCH "http://0.0.0.0:3001/web/users/6/" -H "Content-Type: application/json" -d '{"username":"test2"}'

返回状态码为 200：

1{
2  "id": 6,
3  "username": "test2"
4}

详情接口

1curl "http://0.0.0.0:3001/web/users/6/"

返回状态码为 200：

1{
2  "id": 6,
3  "username": "test2"
4}

删除接口

1curl -XDELETE "http://0.0.0.0:3001/web/users/6/"

返回状态码为 204，无返回值。

4. 项目中配置接口 Proxy

以 React 项目为例，在 src/setupProxy.js 文件中增加如下配置：

1const createProxyMiddleware = require("http-proxy-middleware");
2
3module.exports = function (app) {
4  if (process.env.NODE_ENV !== "production") {
5    app.use(
6      createProxyMiddleware("/web/users", {
7        target: "http://0.0.0.0:3001",
8        changeOrigin: true,
9        logLevel: "debug",
10      })
11    );
12  }
13};

proxy 更多配置参考 http-proxy-middleware