Web API系列(一)設計經驗與總結

在移動互聯網的時代, Web服務已經成爲了異構系統之間的互聯與集成的主要手段，各類 Web服務幾乎都採用REST風格的Web Api來構建。 經過Http協議的形式來. 以Get/Post方式發送請求, 返回json格式(數據更小巧且自描述能力強)的數據。這裏就不在介紹REST API 的好處和不足。這些網上一大堆資料。今天就說說，如何構建優秀的REST API ？

　　目前，各大互聯網公司, 對自身的REST Api設計有各自的標準，他們的Api 的設計也很是成熟。 那麼，咱們應該如何更好的設計咱們的接口， 來提升咱們 API 的可用性，易用性，可維護性與可擴展性呢？

　　一. API 設計方案
　　1. Http的請求分爲URL約定規則、請求參數規則
　　　　URL規則: http://{server}/{product}/{version}/{logic}/{method}?{query_string}

　　　　server: 爲具體的服務域名
　　　　product: 爲應用工程名
　　　　version: 爲具體版本號, 便於未來的功能擴展, 能夠暫定爲 v1, v2
　　　　logic: 爲具體業務邏輯的初步劃分, 好比後端管理方法, app端的請求方法
　　　　method: 具體業務的方法

　　　　具體的請求參數, 由指定的method方法決定, 全都做爲HTTP GET/POST的參數列表。

　　　　這裏不少人會問爲何把 method 和 version 放到在URI中？

　　　　由於這樣可使API 版本化，方便版本控制，同時也便於往後API的分流。固然關因而否將版本信息放入url仍是放入請求頭裏面，曾經有過很激烈的爭論，各有各的道理。我我的認爲放到 URL 中會好一些。具體的你們仍是根據本身的業務場景，綜合考量吧。

　　2. Http的響應規則
　　　　HTTP響應碼爲200, 返回結果爲JSON字符串的形式:
　　　　若是響應結果正確,則返回結果以下所示:
　　　　{　　
　　　　　　data : { // 請求數據，對象或數組都可
　　　　　　　　user_id: 123,
　　　　　　　　user_name: "zwz",
　　　　　　　　user_avatar_url: "http://www.abc.com/1.jpg"
　　　　　　　　...
　　　　　　},
　　　　　　msg : "done", // 請求狀態描述，調試用
　　　　　　success : 1,
　　　　　　code" : 1001, // 業務自定義狀態碼
　　　　　　extra : { // 其餘擴展的數據，字段、內容不定
　　　　　　　　type: 1,
　　　　　　　　desc: "簽到成功！"
　　　　　　}
　　　　}

　　　　若是響應結果失敗,則返回以下結果:
　　　　{
　　　　　　data : { // 請求數據，對象或數組都可
　　　　　　},
　　　　　　msg : "Internal Server Error", // 請求狀態描述，調試用
　　　　　　success : 0,
　　　　　　code : 5001, // 業務自定義狀態碼
　　　　　　extra : {
　　　　　　}
　　　　}

 

　　3. Auth 權限驗證

　　　　API 的權限驗證，有不少方案，目前成熟的OAuth 2.0框架等，不過 ，最簡單的仍是利用 Http Header 來完成這一目標。 將token 經過 Header 傳遞。來實現權限驗證。

　　4. API 在設計的時候，最好不要將業務錯誤碼與HTTP狀態碼的綁定,從新定義一套業務錯誤碼，來區分HTTP 的狀態碼。
　　　　狀態碼的定義也最好有一套規範，相似於HTTP 的狀態碼，能夠按照用戶相關、受權相關、各類業務，作簡單的分類。
　　　　// Code 業務自定義狀態碼定義示例
　　　　// 受權相關
　　　　1001: 無權限訪問
　　　　1002: access_token過時
　　　　1003: unique_token無效
　　　　...

　　　　// 用戶相關
　　　　2001: 未登陸
　　　　2002: 用戶信息錯誤
　　　　2003: 用戶不存在

　　　　// 業務相關
　　　　3001: 業務XXX
　　　　3002: 業務XXX

　　　　// 系統異常
　　　　5001：Internal Server Error

　　　二. 其餘一些建議：

　　　　1. 規範統一的命名
　　　　　　使用駝峯式或者下劃線格式均可以，統一規範就行。不過，目前基本都是統一小寫加下劃線比較好。如：user_id，user_name，user_age等。

　　　　2. 語義清晰，遵照經常使用縮寫
　　　　　　字段的名字最好能體現字段的類型，遵照一些經常使用的縮寫，如：user_name, task_desc, date_str 等

　　　　3. 空值、空字段的處理
　　　　　　空值、空字段的處理也是比較容易出問題。統一空值用null 。除了布爾類型的，其他的空值統一用null表示，客戶端保證每種字段的null能夠被正常處理。　

　　　　4. 各個Action 儘可能符合CRUD操做的原則。　　　

　　　　5. 給不一樣類型設置默認空值
　　　　　　除了null，儘可能對字段設置「默認值」，如數字就是0，字符串就是空字符串""，數組就是空數組[]，對象就是空對象{}，這樣能夠避免客戶端處理空值產生的異常。
　　　　　　具體的要根據業務、先後端約定而定。
　　　　　　好比，bool 類型的值，統一成數字0和1 。時間日期類型強制只能傳標準GMT/UTC時間戳，而後由各自的客戶端根據本身的時區、顯示要求作處理後顯示。

　　　　6. 完整的URL
　　　　　　API裏面的數據也會有URL類型的，通常來講如用戶的頭像、各類圖片、音頻等資源，都是以URL連接的形式返回的。
　　　　　　返回的URL必定要「完整」，主要指的是不要忘記URL裏面的協議部分。應該是http://www.abc.com/1.jpg。

　　　　7. REST 安全
　　　　　　可使用固有的 HTTP 基本驗證，你還能夠考慮經過支持表單驗證，LTPA 驗證，Open ID 驗證等方式，來知足更多的企業安全要求。

　　　　8. 儘可能將API部署在專用域名之下。例如：https://api.example.com。

　　　　9. API返回的數據格式，應該儘可能使用JSON，避免使用XML。

　　　　10. 返回正確 HTTP 響應代碼,同時從新定義一套業務錯誤碼，來區分HTTP 的狀態碼。

　　　　11. 完善的文檔，最好能自動生成在線API文檔，這樣文檔能隨時保持最新。
　　　　　　目前有不少自動生成API 文檔的攻擊，例如：SwaggerUI。

 

 

本文來自：http://www.cnblogs.com/zhangweizhong/p/6196808.html