前端规范三（前后端协助规范）

5 前后端协助规范

对于前端来说，API文档可作为开发工具，好的API文档可以减少不必要的沟通成本，有效的提升开发效率。

5.1 API设计

RESTful是目前使用最为广泛的API设计规范, 基于HTTP本身的机制来实现.

5.2 API 安全：

Token验证表单验证字段加密/签名校验

5.3 API管理方式：

传统方式：手写文档、离线API文档、代码生成文档

互联网模式：mock server

5.4 API接口文档规范：

1).版本号

2).文档描述

3).服务器地址：测试服务器，正式服务器

4).安全和认证: token信息

5).全局接口通用配置参数，必须说明类型(数据类型、字段含义、是否可选，默认值等)

简单使用示例：

| 字段            | 类型             | 含义         | 是否必要     | 示例          |    
| order_by       | string           | 按字段排序    | 否              |   order_by=-id    | 
| page           | int              | 指定页数      | 否          |  page=1           | 
| size           | int              | 指定每页条数     | 否          | size=20     |

6).接口请求状态：

200: "服务器成功返回请求的数据"

400: "发出的请求有错误，服务器没有进行新建或修改数据的操作"

401: "用户没有权限（令牌、用户名、密码错误）"

403: "用户得到授权，但是访问是被禁止的"

404: "发出的请求针对的是不存在的记录，服务器没有进行操作"

406: "请求的格式不可得"

410: "请求的资源被永久删除，且不会再得到的"

500: "服务器发生错误，请检查服务器"

502: "网关错误。",

503: "服务不可用，服务器暂时过载或维护。",

504: "网关超时。"

7).通用响应参数格式 ,必须说明类型(数据类型、字段含义, 值的说明)

简单使用示例：

{
  data: []
    errmsg: ""
    errno: 0
    total: 3
}
| 字段            | 类型             | 含义         | 是否必要     | 说明          |    
| data           | object           | 请求数据     | 否              |                               | 
| errmsg         | string           | 提示信息     | 是              |                               | 
| errno          | int              | 数据返回状态    | 是          | 0 成功 非0 失败 |    
| total          | int                  | 数据总数     | 否              |                               |

8).具体接口定义

API接口地址
API接口请求类型：get/post/patch/delect
API接口描述
请求参数及其描述，必须说明类型(数据类型、字段含义、是否可选、值的说明（1：是 2:否）、默认值等)
响应参数及其描述, 必须说明类型(数据类型、字段含义、值的说明（1：是 2:否）等)
可能的异常情况、错误代码、以及描述

请求参数示例

| 字段            | 类型             | 含义        | 示例 | 是否必要 |
| rule_name       | string           | 规则名称    |      | 否       |
| key_word        | string           | 关键字      |      | 是       |
| reply_type      | int              | 回复类型    |      | 是       |
| reply_content   | string           | 回复内容    |      | 否       |
| reply_image_url | string           | 回复图片url |      | 否       |

响应数据示例

{
      "errno": 0,
      "errmsg": "success",
    "data": {
        "created_at": "2019-01-02 15:55:01",
        "id": 15,
        "key_word": "",
        "reply_content": "",
        "reply_image_url": "",
        "reply_type": 320931,
        "rule_name": "zonst",
        "updated_at": "2019-01-02 15:55:01"
    }
}

| 字段            | 类型              | 含义        | 说明           |
| rule_name       | string           | 规则名称    |               |
| key_word        | string           | 关键字      |               |
| reply_type      | int              | 回复类型    | 1：文字 2：图片 | 
| reply_content   | string           | 回复内容    |               | 
| reply_image_url | string           | 回复图片url |               | 
| created_at      | string, datetime | 创建时间    |               | 
| updated_at      | string, datetime | 更新时间    |               |

异常情况示例

{
    "errno": -1
      "errmsg": "err"
}

5.5 接口测试与模拟

为了做到高效率的前后端并行开发，接口的测试与模拟是必要的。

前端要求后端在联调之前，需要测试验证好自己的接口是否可以正常工作。而不是在联调期间，把前端当‘接口测试员’，阻塞接口联调进度
另外前端需要在后端接口未准备好之前，通过接口模拟的方式，来编写业务逻辑代码。

针对接口测试与模拟，存在下图这样一个理想的模型:

mock server.png

一切从定义良好的接口文档出发，生成Mock Server和Mock Client, Mock Server给前端提供模拟数据，而Mock Client则辅助后端对它们的接口进行测试.

5.6 YApi 管理工具

YApi.png

YApi使用示例截图：

YApi预览.png

mock配置1.png

返回数据1.png