关于前后端接口定义

[hjzheng]

最近在项目开发过程中，作为前端leader，发现前后端联调的时候，花费的时间特别多，按理说在接口定义清楚的前提下，联调是非常快速的。

然而事实上，当我仔细阅读接口文档后，发现很多东西，并未定义清楚，或者压根没有。

那么一个完善的接口文档应该是什么样的？

1.首先接口的设计，需要遵循REST原则，如果有同学不懂REST，可以看看这篇文章 #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

[kuitos]

不要用status标明 成功/失败 的状态，状态短语统一用 状态码 表明，错误信息以响应体方式给出。
公司有一篇写的非常棒的rest规范，建议看这个：REST规范

[hjzheng]

OK，其实这几个接口定义也是参考老客服的设计。

[Knight-ZXW]

@kuitos 你这个是公司的吧，看不了