Spring Boot開發RESTful介面與http協定狀態表述

2022-03-17 19:00:42

2.1、RESTful是面向資源的（名詞）
2.2、用HTTP方法體現對資源的操作（動詞）
2.3.HTTP狀態碼
2.4.Get方法和查詢引數不應該改變資料
2.5.使用複數名詞
2.6.複雜資源關係的表達
2.7.高階用法:HATEOAS
2.8.資源過濾、排序、選擇和分頁的表述
2.9.版本化你的API

參考：

一、RESTful風格API的好處

API（Application Programming Interface），顧名思義：是一組程式設計介面規範，使用者端與伺服器端通過請求響應進行資料通訊。REST（Representational State Transfer）表述性狀態傳遞，決定了介面的形式與規則。RESTful是基於http方法的API設計風格，而不是一種新的技術.

看Url就知道要什麼資源
看http method就知道針對資源幹什麼
看http status code就知道結果如何

對介面開發提供了一種可以廣泛適用的規範，為前端後端互動減少了介面交流的口舌成本，是約定大於設定的體現。通過下面的設計，大家來理解一下這三句話。

當然也不是所有的介面，都能用REST的形式來表述。在實際工作中，靈活運用，我們用RESTful風格的目的是為大家提供統一標準，避免不必要的溝通成本的浪費，形成一種通用的風格。就好比大家都知道：伸出大拇指表示“你很棒“的意思，絕大部分人都明白，因為你瞭解了這種風格習慣。但是不排除有些地區伸出大拇指表示其他意思，就不適合使用！

二、RESTful API的設計風格

2.1、RESTful是面向資源的（名詞）

REST 通過 URI 暴露資源時，會強調不要在 URI 中出現動詞。比如：

不符合REST的介面URI	符合REST介面URI	功能
GET /api/getDogs/{id}	GET /api/dogs/{id}	獲取一個小狗狗
GET /api/getDogs	GET /api/dogs	獲取所有小狗狗
GET /api/addDogs	POST /api/dogs	新增一個小狗狗
GET /api/editDogs/{id}	PUT /api/dogs/{id}	修改一個小狗狗
GET /api/deleteDogs/{id}	DELETE /api/dogs/{id}	刪除一個小狗狗

2.2、用HTTP方法體現對資源的操作（動詞）

GET ：獲取、讀取資源

POST ：新增資源

PUT ：修改資源

DELETE ：刪除資源

實際上，這四個動詞實際上就對應著增刪改查四個操作，這就利用了HTTP動詞來表示對資源的操作。

2.3. HTTP狀態碼

通過HTTP狀態碼體現動作的結果,不要自定義

200 OK 
400 Bad Request 
500 Internal Server Error

在 APP 與 API 的互動當中，其結果逃不出這三種狀態：

所有事情都按預期正確執行完畢 - 成功
APP 發生了一些錯誤 – 使用者端錯誤（如：校驗使用者輸入身份證，結果輸入的是軍官證，就是使用者端輸入錯誤）
API 發生了一些錯誤 – 伺服器端錯誤（各種編碼bug或服務內部自己導致的異常）

這三種狀態與上面的狀態碼是一一對應的。如果你覺得這三種狀態，分類處理結果太寬泛，http-status code還有很多。建議還是要遵循KISS(Keep It Stupid and Simple)原則，上面的三種狀態碼完全可以覆蓋99%以上的場景。這三個狀態碼大家都記得住，而且非常常用，多了就不一定了。

2.4. Get方法和查詢引數不應該改變資料

改變資料的事交給POST、PUT、DELETE

2.5. 使用複數名詞

/dogs 而不是 /dog

2.6. 複雜資源關係的表達

GET /cars/711/drivers/ 返回使用過編號711汽車的所有司機

GET /cars/711/drivers/4 返回使用過編號711汽車的4號司機

2.7. 高階用法:HATEOAS

HATEOAS:Hypermedia as the Engine of Application State 超媒體作為應用狀態的引擎。
RESTful API最好做到HATEOAS，即返回結果中提供連結，連向其他API方法，使得使用者不查檔案，也知道下一步應該做什麼。比如，當用戶向api.example.com的根目錄發出請求，會得到這樣一個檔案。

{"link": {
  "rel":   "collection https://www.example.com/zoos",
  "href":  "https://api.example.com/zoos",
  "title": "List of zoos",
  "type":  "application/vnd.yourformat+json"
}}

上面程式碼錶示，檔案中有一個link屬性，使用者讀取這個屬性就知道下一步該呼叫什麼API或者可以呼叫什麼API了。

2.8. 資源過濾、排序、選擇和分頁的表述

2.9. 版本化你的API

強制性增加API版本宣告，不要釋出無版本的API。如：/api/v1/blog

面向擴充套件開放，面向修改關閉：也就是說一個版本的介面開發完成測試上線之後，我們一般不會對介面進行修改，如果有新的需求就開發新的介面進行功能擴充套件。這樣做的目的是：當你的新介面上線後，不會影響使用老介面的使用者。如果新介面目的是替換老介面，也不要在v1版本原介面上修改，而是開發v2版本介面，並宣告v1介面廢棄！