接口定义（REST full）规范总结

ZXF测试系统

为风格统一、便于理解，本接口文档遵循以下原则：

一. 返回json数据结构定义
消息结构体：

 {  
       "errno" : XXXX, // int数值
       "errmsg" : "XXXXXX", // 描述信息
       "data" : XXXXXXX， // 可能是一个值，可能是数组，也有可能是map，视具体情况而定
    }
    // 2000返回示例
    {  
       "errno" : 2000, 
       "errmsg" : "", 
       "data" : {}
    }
    // 4001返回示例
    {  
       "errno" : 4001, 
       "errmsg" : "获取当前用户信息失败，请重新登录", 
       "data" : {}
    }

二. 错误码定义标注
定义规则：

错误码由四位组成：前两位标识类型，后两位标识具体错误

	20XX  :  服务正常，并返回。最常使用的是2000
	40XX  :  客户端问题，接口参数、权限等
	50XX  :  服务端问题。最常使用的是5000
	60XX  :  未知异常，服务端问题。最常使用6000

具体错误码注释：

  2000 ： 服务正常，且返回数据
  4000 ： 参数错误
  4001 ： 用户登陆认证失败
  4002 ： 数据不是最新，需刷新
  4003 ： 无权限操作
  4004 ： 找不到资源
  5000 ： 服务端异常
  6000 ： 未知异常

三. 特别说明
一般规则

  1、使用下划线+变量名方式命名变量 user_name
  2、路由命名统一 “/zxfTest” 打头，便于代理转发
  3、数值空的表示：int->null, string->"", list->[], dict->{}
  4、接口内容写法： 变量名：变量值 // 注释  （示例：user_name: 'zxf' // 用户名） 尽可能地提供实际数据， 便于前端对数据的展示规划
  5、页面显示内容分“填充值”跟“选项值”，分别与后端交互获取 （选项无需拆分成多个接口返回的就不拆，否则前后端接口连调比较辛苦，具体还是看接口常用与否决定。个人建议）
  6、值是什么类型就是什么类型，不要都是string，合理利用boolean、int
  7、非2000返回的结果，也要列出接口返回，以及说明前端可能要做的流程跳转
  8、后端接口要做字段校验，接口文档必填非必填、类型要清晰（json schema）
  9、所有接口调用都需要传auth （auth：字符串 + 时间戳的md5，其中字符串前后端可以约定，而时间戳的话作为一个参数也进行传递）
  10、params 方式不好描述的请求参数，requst body 方式描述
  11、所有更新的操作都需要通过update_time校验数据是否最新， 避免多人同时操作覆盖