002-丰满格式设计

基于json的数据传输设计 - 丰满格式设计

1. 脱离贫困 - 满足基本需求
2. 走向小康 - 丰满格式设计

1. 需求说明

   • 用户登录接口
   • 用户通过客户端发送tel和pwd两个字段来登录客户端
   • 后台根据tel和pwd来判断用户是否有权限来登录客户端,并返回相应结果

2. 发送数据
   get方式太危险,抛弃,改用post方式,并且不用formdata,而直接使用htpp协议的body并构成json

   {
       "tel":"12345678901",
       "pwd":"md5(pwd)"
   }
   

3. 接受数据并返回
   当账户登录失败的时候,返回的数据为空,这样的设计导致接口的返回可能形式只有两种,这种设计的可扩展性太差,所以这里模仿http协议引入code机制

   //情况1:登录成功
   {
       "code":"200",
       "id":"1001",
       "nickaname":"冬追夏赶",
       "icon":"http://img_url"
   }
   //情况2:账户或者密码错误
   {
       "code":"201",
   }
   

   这时候,客户端开发人员便可以根据返回时数据中的code来做相应的逻辑操作,比如200说明账户密码没有错误,便可以使客户端转入主页面,如果code为201,则说明账户密码有误,可以提示用户再次输入密码,如果需要扩展接口的情况,则可以添加更过的code便可

   //情况3:账户遭到管理员封锁
   {
       "code":"203"
   }
   //情况4:账户登录失败次数过多
   {
       "code":"204"
   }
   

4. 添加开发信息提示
   虽然我们有了code机制,接口的扩展性增强了,但是同时也带来了一个问题,那就是过多的code对开发者带来的混乱,不够清晰的说明到底是什么错了,所以需要添加一个字段:summary,

   //情况1:登录成功
   {
       "code":"200",
       "summary":"login success",
       "id":"1001",
       "nickaname":"冬追夏赶",
       "icon":"http://img_url"
   }
   //情况1:登录成功
   {
       "code":"201",
       "summary":"tel or pwd error",
   }
   

5. 面向对象的数据格式设计
   我们观察步骤4可以发现,在服务端返回的数据格式中,可以分为两类,一类是开发信息,比如code和summary,另一类是数据信息,比如id,nickname和icon,所以我们应当封装一下:

   {
       "code":"200",
       "summary":"login success",
       "data":{
           "id":"1001",
           "nickaname":"冬追夏赶",
           "icon":"http://img_url"
      }
   }
   

有空再细细修改完善