一套設計良好的RESTful API如何成為前后端的橋梁？

移動互聯網時代，RESTful API成為越來越重要的移動端和服務器端交互的形式。尤其是在很多互聯網公司或者傳統行業擁抱移動互聯網的時候，一套設計良好的Restful API能夠幫助互聯網產品支持單服務端＋多客戶端的場景。RESTful架構本身是一個風格而不是一個標準，這也就意味著在具體設計時會有不同的實現。那么什么是好的RESTful API呢？筆者認為適合的是最好的，能夠根據本身產品的業務場景和階段設計出結構清晰，易于理解，擴展方便的Restful API 就是最好的。本文將圍繞筆者對Restful架構的理解展開討論。

1、 什么是RESTful API

表征性狀態傳輸（Representational State Transfer,簡稱REST ）是Roy Fielding博士于2000年在他的博士論文中提出來的一種軟件架構風格。如果一個架構符合REST原則，就稱它為RESTful架構。說到Roy Fielding幾乎可以稱之為HTTP協議之父，他是HTTP1.0和1.1的主要設計者，這篇基于HTTP協議的軟件架構風格一出世就引起了關注并對互聯網開發產生了深遠的影響。發展到今日主流開源框架都提供了對REST的支持，大多數互聯網公司都采用了RESTful架構。

2、 資源（Resources）是REST的核心

REST開發又被稱作“面向資源的開發”，這說明對于資源的抽象是設計RESTful API的核心內容。RESTful API建模的過程與面向對象建模類似，是以名詞為核心的。這些名詞就是資源，任何可命名的抽象概念都可以定義為一個資源。對于業務的抽象是設計一套好的RESTful API的基礎，這就好比建房子打地基，如果地基沒有打好，后面建的樓就很容易歪掉，其美觀度，可維護性，可擴展性就會大大折扣。筆者會建議在設計初期一定要在資源的定義上多花功夫，抽象出適合業務發展的資源。也就是說一開始要把產品的RESTful風格定義下來，后面的擴展都可以基于這樣的風格延續下去。

下面是幾條小的建議：

-理清資源的層次結構，比如業務針對的范圍是學校，那么學校會是一級資源(/school)，老師(/school/teachers)，學生(school/students)就是二級資源。

-資源盡量用準確的英文名詞去表達，資源組都用復數來表達。一個好的資源定義一定是自解釋的，也就是說你只需要很少的先驗信息就能理解這個resource資源代表什么意思。

3、 資源的狀態轉化（State Transfer)

訪問一個網站，代表的就是客戶端和服務器的一個互動過程，這個過程中勢必就涉及到數據和狀態的變化。而廣為使用的HTTP協議又恰恰是無狀態的協議，這就意味這所有的狀態都保存在服務器端。如果某個客戶端想要操作服務器端必須通過某種手段讓服務器發生狀態轉換。那么客戶端可以操作的就是上文所定義的資源，而資源的狀態轉化就轉化為對資源的各種操作。這些操作是通過HTTP協議的四種常用的方法來實現：GET，POST，PUT，DELETE。他們分別對應四種基本操作：GET－獲取資源，POST－新建或者更新資源，PUT－更新資源，DELETE-刪除資源。還有其它不常用的HTTP方法：PATCH/HEAD/OPTIONS方法。

對于HTTP方法的應用業界一直有兩種聲音：

-一種是盡量使用所有的HTTP方法去操作資源，請求里面只能帶資源不能出現任何動詞，如果發現資源上的操作過多以至于HTTP的方法不夠用，應該考慮設計出更多的資源。這種方式適用于新產品的開發，產品是從建模開始的，可以充分的考慮各種業務場景定義出相應的資源。

-另一種是就是靈活適用，用GET去獲取資源，其它涉及更改的操作都用POST，并當POST不能表達相應的動作時在URL中添加動詞。比如在二手商品市場我發布了一個售賣手機的資源。那么對于這個資源，賣家本人可以對這個商品有取消的操作：POST /resources/123/cancel;買家可以對這個商品有購買的操作：POST /resources/123/buy。這種方式適用于對現有非RESTful架構進行升級改造而修改模型影響更大的業務產品。當然這種選擇也有可能是前后端程序猿們協商的結果，畢竟用一種最自然的溝通方式去架起前后端的橋梁才是目的所在。

4、 合理使用URL路徑參數和請求

在URL路徑里的參數一定是代表某個資源的ID，路徑參數也可以是多個代表幾級資源的IDs，例如獲取一個老師所帶班級的詳情/teachers/#teacher_id/classes/#class_id。

對于HTTP GET，請求參數一般是作為可選參數獲取某個資源列表的子集，例如獲取年青老師的列表/teachers?group=young。

對于HTTP POST，請求參數是在消息體里，代表需要新建或者更新的資源。

5、 合理使用HTTP響應代碼

HTTP響應狀態代碼，是HTTP協議這個統一接口中用來表達出錯情況的標準機制。響應狀態代碼分成兩部分：狀態碼和原因。兩部分都是可定制的，也可以使用標準的狀態碼，只定制出錯原因。在實際應用中也是兩種選擇：

?一種是對于應用出錯的情況擴展狀態碼，定制出錯原因。

?一種是對于容器處理的出錯情況默認使用容器返回的錯誤碼，例如tomcat容器返回的503，404；而對于應用本身返回的狀態碼一律返回200，對于應用出錯碼和原因都反應在返回消息體中。

6、 定義一套標準的返回體數據結構

對于所有的RESTful HTTP請求定義一套標準的返回結構體，前端可以根據這樣的固定格式做標準化的解析，對于系統的可維護性起到很大的幫助。這個結構體里應該包含返回的具體資源，結果狀態碼和錯誤原因（如果有的話）。對于返回的資源，數據類型也盡量做到統一，比如日期，枚舉類型都返回統一的數據類型避免不同的API對同一種數據有不同的處理方式。資源屬性盡量做到可讀也能大大減少前后端的溝通成本。

7、 RESTful API的版本控制

一個簡單的做法是直接在URL中插入版本號，這樣可以允許多個版本的API同時運行。在已經發布的版本中盡量做到向后兼容，包括URL和參數，對于返回值也是盡量增加新的冗余參數以兼容不同客戶端不同的升級頻率。等到所有的客戶端升級以后再去除冗余的過程。

8、 RESTful API的安全性

安全性也是一個很大的話題，如果展開來講又將是另外一篇文章。簡單來講主要是要考慮下面幾個方面：

-對客戶端做身份認證

-保證每個用戶只能操作自己的資源，而不會CRUD屬于別人的資源

-對于敏感數據做加密防止串改

-對于POST請求添加冪等機制以保證對資源的增加或者修改是安全的。

結語

最后作為結束語，想說明的是一套設計良好的RESTful一定是前后端反復溝通協商并不斷迭代的過程。因為RESTful API作為前后端的橋梁我們需要同時考慮前后端的需求并達成一致的一個結果，橋梁之所以成為橋梁一定是雙方都認可的溝通方式。架構是一門科學，也是一種藝術。

 

 

來自：http://www.jianshu.com/p/f5c1bc2ac8a5