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
网友评论