類Restful接口設計規範

 

  
  -- 引言 -- 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  Restful是一種很是優美的http接口設計風格及設計規範。使用restful原理來設計接口，能夠很是顯著地下降多個系統之間的耦合性，也可使得接口變得很是一致，不只美觀，並且容易理解和上手。 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  然而在實際工做中，彷佛很難真正用上徹底的Restful，理想和現實老是有差距的- - 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  經過不斷地實踐概括，結合restful的核心原理，我小結出了一套類Restful接口規範。它基本上解決了我在項目中遇到的90%的問題，自我感受良好，哈哈。 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  -- 正文 -- 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  == 請求/響應規範 == 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  請求 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  GET: 使用url傳參，如：?a=1&b=2 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  POST: 使用Json傳參，從request.body中獲取此Json，如：'{"a": 1, "b": 2}' 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  響應 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  返回值格式爲json，分爲成功返回（ok_json）和失敗返回（fail_json） 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  ok_json示例： 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  {"ok": True, data: {"user_id": 1}, "echo": "", "error": "", "reason": ""} 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  fail_json示例： 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  {"ok": False, data: {}, "echo": "COMM_INVALID_ARGS", "error": "1001", "reason": "請求參數錯誤"} 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  == 接口規範 == 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  假設咱們的數據模型叫作「User」 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  注意： 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  一、如下接口中的「返回值」均爲請求成功時的返回值，存在ok_json中的data裏 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  二、在參數前面加上:的（如:user_id），說明此參數非必須；在參數前面加*的（如*user_id），說明此參數必須 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  三、列表返回值的結果，默認使用id逆序排序，即新建的數據在前。若是你在數據模型中本身定義了display_order，你就使用你的order進行排序 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【新增】/user/add/ 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【請求方式】POST 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【描述】提供新建一個User對象所須要的全部屬性，新建成功後，將新建數據的id返回 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【參數】新建user所須要的全部參數，依據業務不一樣有所不一樣 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【返回值】：{"id": 3} 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【更新】/user/update/ 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【請求方式】POST 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【描述】根據提供的id更新對應記錄的屬性 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【參數】*user_id，*其餘待更新的屬性值（不包括刪除標記） 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【返回值】{} 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【查看】/user/view/ 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【請求方式】GET 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【描述】提供記錄id，返回對象的json化數據 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【參數】*user_id 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【返回值】{"id": "1", "username": "swpu-lee", "real_name": "lee", "gender": 0, ...} 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【刪除】/user/delete/ 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【請求方式】GET 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【描述】刪除一條數據。在個人實際項目中，每每只是對記錄標記如下is_deleted爲True。對於全部查詢接口來講，被標記爲is_deleted的數據都應該查不到（也就是說這些接口在作數據查詢時都要加上「is_deleted爲False」這個條件） 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【參數】*user_id 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【返回值】{} 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【查詢】/user/query/ 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【請求方式】GET 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【描述】得到知足指定過濾條件的數據，這個接口返回知足條件記錄的id列表。此接口與實際使用相關，須要本身定義一個查詢協議。 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【參數】依據實際需求有所不一樣，如：{"age": "11-20", "eye_color": "red", ...} 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【返回值】[1, 2, 3, 5, 78, 121, ...] 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【批量查看】/user/view/bulk/ 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【請求方式】GET 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【描述】根據提供的ids批量查看數據。此接口能夠配合Query接口進行批量查看 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【參數】*user_ids（格式爲："1,2,3,4,5"，用逗號隔開） 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【返回值】{"1": {用戶1的數據}, "2": {用戶2的數據}, "3": {用戶3的數據}, ...} 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  ### 如下兩個接口在這個user的例子中，不是很好體現這個接口的價值，因此我改用「用戶相冊」的例子 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【列表】/photo/album/list/ 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【請求方式】GET 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【描述】查看照片列表，當請求參數中有user_id時，得到指定用戶的相冊的列表，不然返回全體用戶的相冊列表。另外此接口須要返回記錄總數，這樣能夠供其餘應用作分頁使用 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【參數】:user_id默認爲None，:offset默認0，:limit默認20，返回數據的json列表以及總數據量 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【返回值】{"total_count": 101, "list": [{相冊1}, {相冊2}, {相冊3}, ...]} 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【所有】/phtot/album/all/ 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【請求方式】GET 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【描述】返回指定用戶的全部相冊 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【參數】*user_id 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【返回值】[{相冊1}, {相冊2}, {相冊3}, ...] 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  -- 結束語 -- 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  不是每個接口都必須存在於每個項目，具體須要哪些接口，根據實際業務需求來添加。 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  此種規範的提供的操做全是原子級別的操做，當你要實現某個複雜的需求時，能夠經過組合這幾個接口實現你須要的功能。 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  以上規範並不能解決開發過程當中的所有問題（好比密碼檢查接口，你不可能在數據庫中存明文密碼吧？）。個人建議是，在遇到問題時，應優先使用這些接口來解決你的問題，不能解決時再考慮開發特殊接口處理。