基于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
   }
   

有空再細細修改完善