|
|
@@ -0,0 +1,193 @@
|
|
|
+# Web端前后端分离接口设计规范
|
|
|
+######版本号：V0.0.1
|
|
|
+
|
|
|
+## 基本规范
|
|
|
+参考链接：[RESTful API 最佳实践](http://www.ruanyifeng.com/blog/2018/10/restful-api-best-practices.html)
|
|
|
+
|
|
|
+* 统一使用RESTful风格的接口请求方式，前端需要模拟除`GET`，`POST`以外的请求:
|
|
|
+ - `GET`：读取请求，如列表，详情接口
|
|
|
+ - `POST`：创建请求，如新增一条数据
|
|
|
+ - `PUT`：更新（Update），通常更新整个实体
|
|
|
+ - `PATCH`：部分更新
|
|
|
+ - `DELETE`：删除
|
|
|
+* URI统一使用资源实体的方式定义，资源实体统一定为英文单词的复数形式，筛选参数使用查询字段，以用户(User)实体为例
|
|
|
+ - `GET /users`：读取用户列表
|
|
|
+ - `GET /users?page=1&size=10`：分页读取用户列表（第1页，每页10条数据）
|
|
|
+ - `GET /users/1`：读取id为1的用户详情
|
|
|
+ - `GET /users?source=wechat`：读取来自微信的用户
|
|
|
+ - `POST /users`: 创建用户
|
|
|
+ - `PATCH /users/1`:更新id为1的用户信息
|
|
|
+ - `DELETE /users/1`：删除id为1的用户信息
|
|
|
+ - `GET /users/1/followers`：读取id为1的用户的粉丝列表
|
|
|
+* 统一重写HTTP状态码标识请求状态成功或失败，返回数据里不再有字段表示成功或失败，也不再有字段标识错误代码，前端需要遵循ES6规范，构建Promise对象进行ajax请求，ES6 Promise对象实现示例如下：
|
|
|
+
|
|
|
+```Javascript
|
|
|
+var getJSON = function(url) {
|
|
|
+ var promise = new Promise(function(resolve, reject){
|
|
|
+ var client = new XMLHttpRequest();
|
|
|
+ client.open("GET", url);
|
|
|
+ client.onreadystatechange = handler;
|
|
|
+ client.responseType = "json";
|
|
|
+ client.setRequestHeader("Accept", "application/json");
|
|
|
+ client.send();
|
|
|
+
|
|
|
+ function handler() {
|
|
|
+ if (this.readyState !== 4) {
|
|
|
+ return;
|
|
|
+ }
|
|
|
+ if (this.status === 200) {
|
|
|
+ resolve(this.response);
|
|
|
+ } else {
|
|
|
+ reject(new Error(this.statusText));
|
|
|
+ }
|
|
|
+ };
|
|
|
+ });
|
|
|
+
|
|
|
+ return promise;
|
|
|
+};
|
|
|
+
|
|
|
+getJSON("http://rap.taobao.org/mockjs/9768/Rap/get").then(function(response) {
|
|
|
+ console.log('Contents: ',response);
|
|
|
+}, function(error) {
|
|
|
+ console.error('出错了', error);
|
|
|
+});
|
|
|
+```
|
|
|
+
|
|
|
+- 2XX均表示请求成功：
|
|
|
+ - `GET`：200，成功
|
|
|
+ - `POST`：201，创建成功
|
|
|
+ - `PUT`：200，成功
|
|
|
+ - `PATCH`：200，成功
|
|
|
+ - `DELETE`：204，已删除
|
|
|
+ - 异步处理：202，服务器已接收到请求，处于待处理状态（如异步操作）。
|
|
|
+- 3XX表示重定向：在前后端分离时由前端控制是否跳转
|
|
|
+ - `301`：永久重定向，浏览器直接跳转
|
|
|
+ - `302`、`307`：暂时重定向，浏览器直接跳转
|
|
|
+ - `303`：暂时重定向，指定跳转URL，前端询问用户是否跳转，如
|
|
|
+
|
|
|
+ ```
|
|
|
+ HTTP/1.1 303 See Other
|
|
|
+ Location: /users/1
|
|
|
+ ```
|
|
|
+
|
|
|
+- 4XX状态码，表示前端错误
|
|
|
+ - `400 Bad Request`:无效请求，服务器不理解前端请求
|
|
|
+ - `401 Unauthorized`：用户没有提供身份凭证凭据或没有通过身份验证（如未登录，登录信息失效）
|
|
|
+ - `403 Forbidden`：用户通过了验证，但是不具有访问资源所需的权限（数据权限）
|
|
|
+ - `404 Not Found`：请求资源不存在或不可用（如已删除资源）
|
|
|
+ - `405 Method Not Allowed`：用户已通过验证，但是所用的HTTP方法不在他的权限范围内（功能权限）
|
|
|
+ - `410 Gone`：资源已从该地址转移，不再可用（如文件转移）
|
|
|
+ - `415 Unsupported Media Type`：客户端要求的返回格式不支持，如只能返回JSON格式，客户端要求返回XML格式。
|
|
|
+ - `422 Unprocessed Entity`：客户端上传的附件无法处理，导致请求失败。
|
|
|
+ - `429 Too Many Requests`：客户端请求的次数超过限额。
|
|
|
+- 5XX状态码，服务端错误。要求服务端出错时要捕获异常，提供友好的信息给前端，不暴露异常信息到前端。
|
|
|
+ - `500 Internal Server Error`：客户端请求有效，服务器处理出现异常（如SQL执行错误，程序执行异常）
|
|
|
+ - `503 Service Unavailable`：服务器无法处理请求，通常用于网站维护状态
|
|
|
+
|
|
|
+## 参数约定
|
|
|
+### 请求参数约定
|
|
|
+__常用的请求参数必须使用下表约定的字段，不允许自定义。__
|
|
|
+
|
|
|
+| 名称 | 参数名 | 数据类型 | 备注 |
|
|
|
+|:-------------:|:----------:|:---------:|:----------------------------|
|
|
|
+| 分页页码 | page | int | 第一页从1开始 |
|
|
|
+| 分页大小 | size | int | 默认值为20，最大不能超过100 |
|
|
|
+| 性别 | gender | string | male=男，female=女 |
|
|
|
+| 模糊搜索关键字 | keywords | string | 仅针对同时支持多个字段模糊检索的，如同时从商品名称和商品详情中搜索的字段 |
|
|
|
+| 身份证号 | id_card | string | 特指中国大陆身份证号，前端对输入的身份证号要进行规则校验 |
|
|
|
+| 手机号 | mobile | string | 特指中国大陆手机号（支持加+86），前端对输入的手机号要进行规则校验 |
|
|
|
+| 电话号码 | telephone | string | 包括手机号，400，800，955xx，100xx，固定电话等号码，前端要对表单数据进行规则校验 |
|
|
|
+| 姓名 | name | string | 真实姓名 |
|
|
|
+| 昵称 | nickname | string | 网络昵称 |
|
|
|
+| 邮箱 | email | string | 前端需要针对邮箱地址进行校验 |
|
|
|
+| 验证码 | captcha | string | 包括短信验证码，输入校验验证码 |
|
|
|
+| 经度 | longitude | float | 精确到小数点后6位小数 |
|
|
|
+| 纬度 | latitude | float | 精确到小数点后6位小数 |
|
|
|
+| 唯一编号 | __实体名___id | int | 如用户编号，使用user_id，分类编号使用category_id |
|
|
|
+
|
|
|
+### 返回格式约定
|
|
|
+返回数据遵循ES6的规范，前端能够通过返回数据构建`Promise`对象进行处理。
|
|
|
+
|
|
|
+__常用的返回参数必须使用下表约定的字段，不允许自定义。__
|
|
|
+#### 成功返回数据
|
|
|
+
|
|
|
+| 名称 | 参数名 | 数据类型 | 备注 |
|
|
|
+|:-------------:|:----------:|:---------:|:----------------------------|
|
|
|
+| 数据集合 | data | Object | 返回的数据库实体数据及其业务相关数据，不同的实体分多个json对象返回 |
|
|
|
+| 其他数据 | meta | Object | 与业务不相关的数据，如分页信息 |
|
|
|
+
|
|
|
+示例数据如下：
|
|
|
+
|
|
|
+```
|
|
|
+{
|
|
|
+ data: {
|
|
|
+ user: {
|
|
|
+ id: 1,
|
|
|
+ real_name: "root",
|
|
|
+ gender_txt: "女士",
|
|
|
+ staff_code: "96582",
|
|
|
+ last_logined_endpoint_txt: "网站",
|
|
|
+ last_logined_at: {
|
|
|
+ date: "2018-12-26 11:21:40.000000",
|
|
|
+ timezone_type: 3,
|
|
|
+ timezone: "Asia/Shanghai"
|
|
|
+ },
|
|
|
+ staff_status_txt: "在职",
|
|
|
+ account_status_txt: "正常"
|
|
|
+ },
|
|
|
+ token: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC8xMjQuMjI1LjE1OS45Mzo4MDcwXC9hcGlcL2F1dGhlbnRpY2F0ZSIsImlhdCI6MTU0NTc5NDUwMCwiZXhwIjoxNTQ1OTAyNTAwLCJuYmYiOjE1NDU3OTQ1MDAsImp0aSI6Im5WTW52akU4VUhNeGJ5bk8iLCJzdWIiOjEsInBydiI6ImUwNjRlZTA4YjM3N2ZlM2I2NTVmZmJmZjBkODBkMzQzN2IwZmY1ZDAifQ.BmQTGJB_TOIoATaqGj799wJKIwjO7oevj1d8XpFAFo4"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+分页返回示例
|
|
|
+
|
|
|
+```
|
|
|
+ {
|
|
|
+ data: [
|
|
|
+ {
|
|
|
+ id: 10,
|
|
|
+ residence_name: "in placeat",
|
|
|
+ residence_logo: null,
|
|
|
+ buildings_count: 0,
|
|
|
+ units_count: 0,
|
|
|
+ houses_count: 0,
|
|
|
+ householders_count: 0
|
|
|
+ }
|
|
|
+ ],
|
|
|
+ meta: {
|
|
|
+ current_page: 1,
|
|
|
+ from: 1,
|
|
|
+ last_page: 1,
|
|
|
+ path: "http://124.225.159.93:8070/api/residences",
|
|
|
+ size: 10,
|
|
|
+ to: 1,
|
|
|
+ total: 1
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+#### 失败返回数据
|
|
|
+| 名称 | 参数名 | 数据类型 | 备注 |
|
|
|
+|:-------------:|:----------:|:---------:|:----------------------------|
|
|
|
+| 就绪状态 | readyState | int | 4=已就绪，服务端已完成响应 |
|
|
|
+| 请求状态码 | status | int | 参考http状态码返回 |
|
|
|
+| 状态码描述 | statusTest | String | http状态码返回对应的英文描述，如Unauthorized, Bad Request等 |
|
|
|
+| 响应文本 | responseText | String | 响应JSON数据的文本 |
|
|
|
+| 响应JSON数据 | responseJSON | Object | 响应JSON数据，其中必须包含message字段，标识错误提示信息 |
|
|
|
+
|
|
|
+示例数据如下：
|
|
|
+
|
|
|
+```
|
|
|
+ {
|
|
|
+ readyState: 4,
|
|
|
+ responseText: "{\"message\":\"\\u624b\\u673a\\u53f7\\u6216\\u5bc6\\u7801\\u9519\\u8bef\"}",
|
|
|
+ responseJSON: {
|
|
|
+ message: "手机号或密码错误"
|
|
|
+ },
|
|
|
+ status: 401,
|
|
|
+ statusText: "Unauthorized"
|
|
|
+}
|
|
|
+```
|
