FE-problem-collection
FE-problem-collection copied to clipboard
XIANFESchool
关于前后端接口定义
最近在项目开发过程中，作为前端leader，发现前后端联调的时候，花费的时间特别多，按理说在接口定义清楚的前提下，联调是非常快速的。
然而事实上，当我仔细阅读接口文档后，发现很多东西，并未定义清楚，或者压根没有。
那么一个完善的接口文档应该是什么样的？
1.首先接口的设计，需要遵循REST原则，如果有同学不懂REST，可以看看这篇文章 https://github.com/ShuyunXIANFESchool/FE-problem-collection/issues/4 2.接口的名称及作用描述。 3.接口的URL和请求时使用的HTTP Method。 4.接口的请求格式及参数包括参数类型，参数默认值，参数描述。 5.接口可能返回的状态码，及每个状态码下的响应类型和格式。
以下是一个接口文档的示例：
ticket列表
用于获取ticket列表，带分页功能
接口：
GET /tickets
请求参数：
名称 类型 定义 必需 默认值(default) 说明 name string 查询name "" 作用于name pageNum number 页码 1 pageSize number 每页大小 10 status number ticket状态 -1 参考ticket状态枚举说明 orderBy string 排序字段名称 "id" 可以使用"id"或"name" order string 排序方式 "asc" 可以为"asc"或"desc" 其他说明 ticket状态枚举 {-1: '全部'，0: '关闭'，1: '开启'}
响应：
成功：200
响应格式：JSON
{ "pageNum"：{number} {default: 从请求获得}，// 页码 "pageSize": {number} {default: 从请求获得}，// 每页大小 "totalCount": {number} {default: 0}, // 总数 "results": [ // {number} 结果集 { "id": {number}, // 必填 "name": {string} {default: null}, // ticket name "status": {number} {default: null}, // ticket状态 参考ticket枚举说明 "createTime": {number} {default: null}, // 使用timestamp，方便前端转换 }, ... ] }登录超时 / 未登录: 403
参考标准403响应
服务器内部错误: 500
参考标准500响应
另外我们还需要提供一些标准响应格式约定：
- 分页列表格式, 不分页列表格式
{
"pageNum": {number} {default: 从请求获得}, // 页码, 不分页列表 为 null
"pageSize": {number} {default: 从请求获得}, // 每页大小，不分页列表 为 null
"totalCount": {number} {default: 0}, // 总数， 不分页列表 为 null
"results": [ // {number} 结果集
... ...
]
}
- 删除，更改和添加后响应格式:
- 成功: 返回操作实体的简单信息，方便前端通知用户
- 失败: 用 HTTP 状态码 表示, 返回错误 message 和 errorCode 参见 500 相应格式
{
"id": {number},
"name": {string}
}
- 403响应
- 500响应
{
"message": {string}, // 友好的错误信息，可选，如不提供前端应当使用默认的提示信息
"errorCode": {number} // 可选择性提供 errorCode 便于后续问题排查，可选
}
后端可以针对不同的响应格式创建不同Java类，其他同学只需继承对应的class，而前端同学针对500和403可以使用AngularJS拦截器统一处理。
最后再强调一点，接口如果一旦定义清楚后，如果需要改动，一定要及时通知到相关同学，所以建议将修改接口权限控制在专门人手里。
关于接口的设计，可以参考 https://github.com/ecomfe/ub-ria/wiki
推荐一个接口定义工具 https://github.com/thx/RAP
