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

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