Spring+SpringMVC+MyBatis+easyUI整合進階篇(一)設計一套好的RESTful API

寫在前面的話

看了一下博客目錄，距離上次更新這個系列的博文已經有兩個多月，並非由於不想繼續寫博客，因爲中間這段時間更新了幾篇其餘系列的文章就暫時中止了，現在已經講述的差很少，也就繼續抽時間更新《Spring+SpringMVC+MyBatis+easyUI整合》這個系列了。

也看到github上有人催更教程，這個真的是沒想到，也謝謝大家的確定和支持了。

因爲《整合優化篇》中關於代碼優化及數據層優化的文章佔了較大的篇幅，致使遺漏了幾篇原計劃要更新在《整合優化篇》中的文章，關於RESTful的改造和緩存功能的整合並無作，這段時間會補充進來。

理解RESTful

REST（Representational State Transfer）,中文翻譯叫"表述性狀態轉移",它首次出如今2000年Roy Fielding的博士論文中，Roy Fielding是 HTTP 規範的主要編寫者之一。他在論文中提到:"我這篇文章的寫做目的，就是想在符合架構原理的前提下，理解和評估以網絡爲基礎的應用軟件的架構設計，獲得一個功能強、性能好、適宜通訊的架構。REST指的是一組架構約束條件和原則。"若是一個架構符合REST的約束條件和原則，咱們就稱它爲RESTful架構，REST其實並無創造新的技術、組件或服務，在個人理解中，它更應該是一種理念、一種思想，利用Web的現有特徵和能力，更好地詮釋和體現現有Web標準中的一些準則和約束。

看完這段理論性的介紹可能並不會使你對於RESTful有任何的想法，甚至只是一掃而過，那就經過實際的案例來說解吧。

ssm項目中有文章管理這個模塊，文章列表頁面刪除文章請求的服務端API地址爲：
http://ssm-demo.hanshuai.xin/article/delete.do,
這個URL並非RESTful風格的API，稍加修改，URL變成：
http://ssm-demo.hanshuai.xin/article/delete/12,
這樣是否是就是RESTful風格了？

首先，這兩個URL都不是RESTful API，由於這兩個URL中都有delete的動做指示，RESTful API是面向資源的架構，所以其URL就應該是一個資源，並且不該該包含任何動做，對於資源的具體操做類型應該由HTTP動詞表示，而不該該是動詞存在於URL中，delete是一個動詞，所以不符合該特色，對於文章刪除功能其對應的RESTful API應該是：
[DELETE] http://ssm-demo.13blog.site/articles/12

常見的RESTful誤區

再講一下一開始接觸RESTful時你們均可能存在的誤區：

• 一些僞靜態的URL，如http://ssm-demo.13blog.site/contents/12,咱們能夠經過瀏覽器訪問該URL而獲取信息，可是這並不表明着它就是RESTful API。
• URL裏含有queryString就不是RESTful Api，如http://ssm-demo.13blog.site/articles/?page=1&rows=10，RESTful API能夠包含queryString。
• HTTP + JSON = RESTful API,HTTP和JSON不等於RESTful，RESTful特性更加豐富，不能將RESTful簡單的等同於HTTP和JSON。

良好RESTful API的設計原則

關於RESTful API設計的具體實現能夠到個人GitHub中查看，如下爲整理的一些設計原則：

基本原則一：URI

• 應該將API部署在專用域名之下：ssm-demo.13blog.site;
• URL中儘可能不用大寫;
• URI中不該該出現動詞,動詞應該使用HTTP方法表示可是若是沒法表示,也可以使用動詞,例如：search沒有對應的HTTP方法,能夠在路徑中使用search,更加直觀;
• URI中的名詞表示資源集合，使用複數形式;
• URI能夠包含queryString,避免層級過深。

基本原則二：HTTP動詞

對於資源的具體操做類型，由HTTP動詞表示，經常使用的HTTP動詞有下面五個：

• GET：從服務器取出資源（一項或多項）。
• POST：在服務器新建一個資源。
• PUT：在服務器更新資源（客戶端提供改變後的完整資源）。
• PATCH：在服務器更新資源（客戶端提供改變的屬性）。
• DELETE：從服務器刪除資源。

還有兩個不經常使用的HTTP動詞：

• HEAD：獲取資源的元數據。
• OPTIONS：獲取信息，關於資源的哪些屬性是客戶端能夠改變的。

例子：

文章管理模塊：

1. [POST]   http://ssm-demo.13blog.site/articles   // 新增
2. [GET]    http://ssm-demo.13blog.site/articles?page=1&rows=10 // 列表查詢
3. [PUT]    http://ssm-demo.13blog.site/articles/12 // 修改
4. [DELETE] http://ssm-demo.13blog.site/articles/12 // 刪除

基本原則三：狀態碼（Status Codes）

處理請求後，服務端需向客戶端返回的狀態碼和提示信息。

常見狀態碼(狀態碼可自行設計，只需開發者約定好規範便可)：

• 200:SUCCESS,請求成功;
• 401:Unauthorized,無權限;
• 403:Forbidden,禁止訪問;
• 410:Gone,無此資源;
• 500:INTERNAL SERVER ERROR,服務器發生錯誤。
  ...

基本原則四：錯誤處理

若是服務器發生錯誤或者資源不可達，應該向用戶返回出錯信息。

基本原則五：服務端數據返回

後端的返回結果最好使用JSON格式。

基本原則六：版本控制

• 規範的API應該包含版本信息，在RESTful API中，最簡單的包含版本的方法是將版本信息放到url中，如：

[GET]    http://ssm-demo.13blog.site/v1/articles?page=1&rows=10 
[PUT]    http://ssm-demo.13blog.site/v1/articles/12

• 另外一種作法是，使用HTTP header中的accept來傳遞版本信息。

ssm項目較爲簡單，所以暫時沒有加入版本信息。

如下爲參考內容，借鑑了一位博主關於安全原則的整理：

安全原則一：Authentication和Permission

Authentication指用戶認證，Permission指權限機制，這兩點是使RESTful API強大、靈活和安全的基本保障。

經常使用的認證機制是Basic Auth和OAuth，RESTful API開發中，除非API很是簡單，且沒有潛在的安全性問題，不然，認證機制是必須實現的，並應用到API中去。Basic Auth很是簡單，不少框架都集成了Basic Auth的實現，本身寫一個也能很快搞定，OAuth目前已經成爲企業級服務的標配，其相關的開源實現方案很是豐富（更多）。

安全原則二：CORS

CORS即Cross-origin resource sharing，在RESTful API開發中，主要是爲js服務的，解決javascript調用RESTful API時的跨域問題。

因爲固有的安全機制，js的跨域請求時是沒法被服務器成功響應的。如今先後端分離日益成爲web開發主流方式的大趨勢下，後臺逐漸趨向指提供API服務，爲各客戶端提供數據及相關操做，而網站的開發所有交給前端搞定，網站和API服務不多部署在同一臺服務器上並使用相同的端口，js的跨域請求時廣泛存在的，開發RESTful API時，一般都要考慮到CORS功能的實現，以便js能正常使用API。

目前各主流web開發語言都有不少優秀的實現CORS的開源庫，咱們在開發RESTful API時，要注意CORS功能的實現，直接拿現有的輪子來用便可。

安全原則三：SSL

http改成https，加強安全驗證。

總結

以上作了一些簡單的總結，可能並非十分的準確，若有錯誤，但願可以指出我會及時修改，謝謝了。

推薦一下本身的達人課，感興趣的朋友能夠看一下：SSM搭建精美實用的管理系統

首發於個人我的博客，新的項目演示地址：perfect-ssm。

若是有問題或者有一些好的創意，歡迎給我留言，也感謝向我指出項目中存在問題的朋友，具體的功能實現及代碼邏輯將在以後的文章中介紹。

若是你想繼續瞭解該項目能夠查看整個系列文章Spring+SpringMVC+MyBatis+easyUI整合系列文章,也能夠到個人GitHub倉庫或者開源中國代碼倉庫中查看源碼及項目文檔。