RESTful 接口设计规范与mock的完美结合

小灰灰 2021-04-17 17:32 607阅读 0赞

最近在做一个后台项目，因为后台也刚开始开发，因此，需要前端组现行，毕竟不能一直等着他们吧，后来，在项目初期我们就自己写数据，但是为了高效开发，也希望能够直接生成api 文档，后来选用了[yapi][]，这个很不错的，我采用的是内网部署，有需要的可以自己搭建一套，文档说的很详细。

现在记录下mock 数据写法以及接口规范：

### 1. mock 数据 ###

/**
     * 接口返回数据示例
     */
    {
      "current":1,
      "msg":"成功",
      "code":0,
      "pageSize":10,
      "total":null,
      "data|1-100": [
            {
                "id|+1": 1,
                "code|+1": 1, // 活动编码
                "activityName": "@ctitle", // 活动名称
                "activityType|1":["reduce","timeLimit"], // 活动类型
                "activityDescription": "@csentence(10,20)", // 活动描述
                "status|1": ["create","issue", "end"],  // 状态 
                "startTime": "@datetime", // 开始时间
                "endTime": "@datetime",  // 结束时间
            }
       ]
    }

> 基础语法跟[mock.js][]一致的，有点区别就是不能写函数，不过问题不大，可以通过高级mock去修改写配置，比如可以动态获取`current,pageSize`参数。

如图:

具体的mock语法文档写的很健全，可以参考，这时候又要增加一个添加的接口，就需要restful 规范写法了

### 2. 接口规范 ###

先说http 操作类型主要有有如下几种：

*  GET（SELECT）：从服务器取出资源（一项或多项）。
 *  POST（CREATE）：在服务器新建一个资源。
 *  PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
 *  PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
 *  DELETE（DELETE）：从服务器删除资源。

具体场景如下所示

其中id 的意思是动态的，可以是某个活动的id，根据此id 来删除修改等操作，这样一个看起来就清晰多了。

具体js 用法的话如下

// 活动删除
    export function query (params) {
      return request({
        url: `/Api/activity/reduce/${params.id}`,
        method: 'delete',
    // data: params,
      })
    }

写法也很清晰明了

有时间在更新。

[yapi]: https://github.com/nuysoft/Mock
[mock.js]: https://link.juejin.im?target=https%3A%2F%2Fgithub.com%2Fnuysoft%2FMock