前后端对接规范

开发流程规范
接口规范原则
请求规范
响应规范
- HTTP Code
- 普通接口返回
{
“code”: 0,
“message”: “success”,
“data”: {
“userId”: “jin”
}
}
登录模块规范
- CAS 登录流程规范
- 飞书登录规范
其他规范
- 前端水印规范

后端编写和维护就扣文档：https://infra.mioffice.cn/mapi/groups/1941

开发流程规范

强制后端在 MAPI 编写和维护接口文档
推荐前后端对接口定义需达成一致，在 API 变化时更新接口文档，并通知到前端
推荐后端根据接口文档进行接口开发
推荐前端根据 MAPI 接口文档进行开发 + 调用 MAPI Mock 接口
推荐开发完成后联调和提交测试

不支持在 Docs 外粘贴 block

接口规范原则

推荐接口返回数据即显示：前端仅做渲染逻辑处理；
推荐前端关注交互、渲染逻辑，尽量避免业务逻辑处理的出现；
推荐请求响应传输数据格式：JSON，JSON数据尽量简单轻量，避免多级JSON的出现；
强制 GET、DELETE 请求参数只能使用 query，POST、PUT 可以同时使用query和body
请求规范
请求体
| 事项 | 现状 | 规范 | 级别 | | —- | —- | —- | —- | | 请求 header | Content-Type: application/json | //普通请求
Content-Type: application/json
//文件上传
Content-Type: multipart/form-data | 强制 | | 请求方法 |
- GET：列表，查询
- POST：创建
- PUT：更新
- DELETE：删除
|
- GET：列表，查询
- POST：创建
- PUT：更新
- DELETE：删除
| 推荐 | | 接口 PATH 格式 | 例如：infra.mioffice.cn/sonar/info-arch
- 下划线(info_arch)
- 中划线(info-arch)
- 驼峰(infoArch)
| 中划线(info-arch) | 强制 | | 接口字段命名 |
- 下划线(info_arch)
- 驼峰(infoArch)
| 驼峰(infoArch) | 强制 |

请求参数类型

字段类型	现状	规范	级别
boolean	使用 true, false，使用 0 1？	true,false	强制
日期	使用10位的时间戳，例如：1617762907	ISO8601: 2016-10-24T20:39:46Z 符合 ISO8601 的『后端时间处理』实践	强制
数组	使用逗号隔开，例如：60,70,80	使用逗号隔开	强制
浮点数	字符串，数字	字符串	强制

GET 请求参数字典

字段类型	含义	默认值	级别
pageSize	分页大小	10	强制
pageNum	页码	1	强制
sortBy	排序字段	-	推荐
orderBy	顺序: asc, desc	asc	推荐

响应规范

HTTP Code

http code 规范	- 200: 请求处理成功 - 400: 请求错误 - 401: 请求未认证，跳转登录页 - 403: 请求未授权，跳转未授权提示页 - 409: 请求保存数据冲突 - 500: 请求处理失败	强制

普通接口返回

必备字段	- code: 业务返回码 - message: 服务端给用户的提示信息 - data: 接口的主数据传递	强制
code 规范	- 请求返回的业务返回码，接口正常情况下返回值为 0 - 接口异常返回非 0 情况时候，需要在 MAPI 上维护具体错误码字典 - (新) 后端错误码规范：错误码规范（草案）错误码项目	强制
message 规范	- http_code: 200 and code:0: 成功消息提示: 请求处理成功 - http_code:400 and code: !=0: 请求处理失败，警告消息提示：message 内容 - http_code:403 and code: !=0: 请求没有权限，警告消息提示：message 内容 - http_code:409 and code: !=0: 保存数据冲突，警告消息提示：message 内容 - http_code:500 and code: !=0: 请求处理失败，错误消息提示：message 内容	强制
接口返回格式	- 返回对象

{
“code”: 0,
“message”: “success”,
“data”: {
“userId”: “jin”
}
}

返回对象(对象为空，返回 null)
{
“code”: 0,
“message”: “success”,
“data”: null
}

返回列表
{
“code”: 0,
“message”: “success”,
“data”: {
“list”: [],
}
}

返回列表(列表为空，返回 [])
{
“code”: 0,
“message”: “success”,
“data”: {
“list”: [],
}
} | 强制 |

分页接口返回

接口返回格式	{ “code”: 0, “message”: “success”, “data”: { “list”: [ ], “pageSize”: 10, “pageNum”: 1, “pageTotal”: 2, “total”: 100 } }	强制

下拉框、复选框返回

接口返回格式	{ “code”: 0, “message”: “success”, “data”: { “list”: [ {}, {}, ] } }	强制

响应参数类型

字段类型	默认值	级别
Boolean	使用 true，false	强制
日期	ISO8601: 2016-10-24T20:39:46Z 符合 ISO8601 的『后端时间处理』实践	强制
浮点数	字符串	强制
大数(Long)	字符串 (例如: 返回 JSON 数据 {“id”: 362909601374617692} 前端拿到的值却是: 362909601374617660)	强制

登录模块规范

后端鉴权协议使用 JWT，使用：infra-auth-spring-boot-starter
前端通过 Cookie: token

CAS 登录流程规范

强制
前端 401 直接跳转后端 login 接口，并添加 followUp

if (error.response.status === 401) { 
    if (__env__ !== 'development') { 
        window.location.href = 
            config('loginUrl') + 
            '?followUp=' + 
            encodeURIComponent(self.location.href) 
    } else { 
        Notification.open({ 
            type: 'warning', 
            title: '开发环境，先设置Cookie Token' 
        }) 
    } 
    return Promise.reject(error) 
}

前后端对接规范 - 图1

飞书登录规范

强制
小程序通过 login 接口获取 code，后端通过 code 获取用户信息，生成 jwt token
前后端对接规范 - 图2

其他规范

前端水印规范

强制 Web 端默认添加水印，水印内容：邮箱 (例如：xx@xiaomi.com)