005- 整体框架设计

基于json的数据传输设计 - 整体框架设计

---

1. 脱离贫困 - 满足基本需求
2. 走向小康 - 丰满格式设计
3. 提升精神 - 添加容错机制
4. 加强品质 - 加固安全机制
5. 开放眼界 - 整体框架设计

---

1. 需求说明:
   总结一整个基于json的数据传输架构的设计

2. 命名规范

   • 使用英文,不要出现拼音,尽量不要出现数字
   • 语义化,使用最常用的英文单词
   • 英文单词之间用下划线隔开
   • 如果value是数字或者字符串,使用名词,比如:data,name
   • 如果value是boolean,使用is_开头,比如:is_open

3. 发送数据格式

   {
       "data":{
           "param1":"value",
           "param2":"value"
       },
       "timestamp":"10位Unix时间戳",
       "sign":"参数校验"
   }
   

   • 将要发送的业务参数放在data中
   • timestamp为发送请求的时间戳
   • sign为参数校验,加密规则
     • 将参数按照字母顺序排序组成formdata:param1=value&param2=value
     • 将timestamp拼接到末尾:param1=value&param2=value&timestamp=1498783683
     • 将上一步骤拼接的参数用md5加盐加密:md5({token}+md5(param1=value&param2=value&timestamp=1498783683))
     • 这里token先为和后端约定好的一个字符串即可

4. 返回参数格式

   • 时间戳校验
     • 获取客户端发送的timestamp和当前时间戳做对比,如果超过1分钟,则视为无效请求
   • 参数校验
     • 获取客户端请求的数据,遵循sign加密策略,验证sign是否相同,不相同则视为无效请求
   • code机制:
     • code summary
     • 200 : get resource success
     • 201 - 299 : 业务错误码
     • 403 : forbidden : {developer ? error_msg : error_info}
     • 404 : not found this api , please sure your server url
     • 500 : system error : {developer ? error_msg : error_info}
   • 两套环境
     在实际开发中,一直都存在着两种环境,对于这两种环境,api应当有着不一样的反应
     • 开发环境
       开发环境中应当详细的写出错误位置和解决方案,让整个api对客户端开发者友好

     // 参数不正确
     {
         "code":"403",
         "summary":"`tel` could not be empty"
     }
     // 服务器错误
     {
         "code":"500",
         "summary":"array empty"
     }
     

     • 部署环境
       在部署环境中,应当隐藏一切对产品安全不理的信息

     // 参数不正确
     {
         "code":"403",
         "summary":"forbidden"
     }
     // 服务器错误
     {
         "code":"500",
         "summary":"error"
     }
     

   • 面向对象数据格式
     以文章和文章分组为例子,一篇文章有一个分组,一个分组有多篇文章,所以是一对多的关系
     好处:
     • 避免键名重复导致的修改和命名复杂 : 比如article.id和group.id
     • 扩展性强 : 如果需要添加group信息和功能,可直接添加,无需修改格式
     • 格式友好 : 符合面向对象思想 , 同时利于实体复用

   // 有返回值型接口,在`data`中放置数据
   {
       "code":"200",
       "summary":"get resource success",
       "data":{
           "id":1,
           "title":"文章标题",
           "content":"文章内容",
           "group":{
               "id":1,
               "name":"分组名称"
           }
       }
   }
   // 操作型接口,将data赋值为-1
   {
       "code":"200",
       "summary":"get resource success",
       "data":-1
   }
   

---

有空再细细修改完善