花5分鐘看這篇之前,你才發(fā)現你不懂RESTful
在學習RESTful 風格接口之前，即使你不知道它是什么，但你肯定會好奇它能解決什么問題？有什么應用場景？聽完下面描述我想你就會明白：
在互聯網并沒有完全流行的初期，移動端也沒有那么盛行，頁面請求和并發(fā)量也不高，那時候人們對接口的要求沒那么高，一些動態(tài)頁面(jsp)就能滿足絕大多數的使用需求。
但是隨著互聯網和移動設備的發(fā)展，人們對Web應用的使用需求也增加，傳統(tǒng)的動態(tài)頁面由于低效率而漸漸被HTML+JavaScript(Ajax)的前后端分離所取代，并且安卓、IOS、小程序等形式客戶端層出不窮，客戶端的種類出現多元化，而客戶端和服務端就需要接口進行通信，但接口的規(guī)范性就又成了一個問題：
所以一套結構清晰、符合標準、易于理解、擴展方便讓大部分人都能夠理解接受的接口風格就顯得越來越重要，而RESTful風格的接口(RESTful API)剛好有以上特點，就逐漸被實踐應用而變得流行起來。
現在，RESTful是目前最流行的接口設計規(guī)范，在很多公司有著廣泛的應用，其中Github 的API設計就是很標準的RESTful API，你可以參考學習。
在開發(fā)實踐中我們很多人可能還是使用傳統(tǒng)API進行請求交互，很多人其實并不特別了解RESTful API，對RESTful API的認知可能會停留在：
面向資源類型的
是一種風格
(誤區(qū))接口傳遞參數使用斜杠(/)分割而不用問號(?)傳參。
而其實一個很大的誤區(qū)不要認為沒有查詢字符串就是RESTful API，也不要認為用了查詢字符串就不是RESTful API，更不要認為用了JSON傳輸的API就是RESTful API。
本篇將帶你了解RESTful并用SpringBoot實戰(zhàn)RESTful API.
一、REST介紹
REST涉及一些概念性的東西可能比較多，在實戰(zhàn)RESTful API之前，要對REST相關的知識有個系統(tǒng)的認知。
REST的誕生
REST（英文：Representational State Transfer，簡稱REST，直譯過來表現層狀態(tài)轉換）是一種軟件架構風格、設計風格，而不是標準，只是提供了一組設計原則和約束條件。它主要用于客戶端和服務器交互類的軟件?；谶@個風格設計的軟件可以更簡潔，更有層次，更易于實現緩存等機制。
它首次出現在 2000 年 Roy Thomas Fielding 的博士論文中，這篇論文定義并詳細介紹了表述性狀態(tài)轉移（Representational State Transfer，REST）的架構風格，并且描述了 如何使用 REST 來指導現代 Web 架構的設計和開發(fā)。用他自己的原話說：
我寫這篇文章的目的是：在符合架構原理前提下，理解和評估基于網絡的應用軟件的架構設計，得到一個功能強、性能好、適宜通信的架構。
需要注意的是REST并沒有一個明確的標準，而更像是一種設計的風格，滿足這種設計風格的程序或接口我們稱之為RESTful(從單詞字面來看就是一個形容詞)。所以RESTful API 就是滿足REST架構風格的接口。
Fielding博士當時提出的是REST架構在很久的時間內并沒有被關注太多，而近些年REST在國內才變得越來越流行。下面開始詳細學習REST架構特征。
REST架構特征
既然知道REST和RESTful的聯系和區(qū)別，現在就要開始好好了解RESTful的一些約束條件和規(guī)則，RESTful是一種風格而不是標準，而這個風格大致有以下幾個主要特征：
以資源為基礎?：資源可以是一個圖片、音樂、一個XML格式、HTML格式或者JSON格式等網絡上的一個實體，除了一些二進制的資源外普通的文本資源更多以JSON為載體、面向用戶的一組數據(通常從數據庫中查詢而得到)。
統(tǒng)一接口: 對資源的操作包括獲取、創(chuàng)建、修改和刪除，這些操作正好對應HTTP協(xié)議提供的GET、POST、PUT和DELETE方法。換言而知，使用RESTful風格的接口但從接口上你可能只能定位其資源，但是無法知曉它具體進行了什么操作，需要具體了解其發(fā)生了什么操作動作要從其HTTP請求方法類型上進行判斷。具體的HTTP方法和方法含義如下：
GET（SELECT）：從服務器取出資源（一項或多項）。
POST（CREATE）：在服務器新建一個資源。
PUT（UPDATE）：在服務器更新資源（客戶端提供完整資源數據）。
PATCH（UPDATE）：在服務器更新資源（客戶端提供需要修改的資源數據）。
DELETE（DELETE）：從服務器刪除資源。
當然也有很多在具體使用的時候使用PUT表示更新。從請求的流程來看，RESTful API和傳統(tǒng)API大致架構如下：
URI指向資源：URI = Universal Resource Identifier 統(tǒng)一資源標志符，用來標識抽象或物理資源的一個緊湊字符串。URI包括URL和URN，在這里更多時候可能代指URL(統(tǒng)一資源定位符)。RESTful是面向資源的，每種資源可能由一個或多個URI對應，但一個URI只指向一種資源。
無狀態(tài)：服務器不能保存客戶端的信息， 每一次從客戶端發(fā)送的請求中，要包含所有必須的狀態(tài)信息，會話信息由客戶端保存， 服務器端根據這些狀態(tài)信息來處理請求。當客戶端可以切換到一個新狀態(tài)的時候發(fā)送請求信息， 當一個或者多個請求被發(fā)送之后, 客戶端就處于一個狀態(tài)變遷過程中。每一個應用的狀態(tài)描述可以被客戶端用來初始化下一次的狀態(tài)變遷。
REST架構限制條件
Fielding在論文中提出REST架構的6個限制條件，也可稱為RESTful 6大原則， 標準的REST約束應滿足以下6個原則：
客戶端-服務端（Client-Server）: 這個更專注客戶端和服務端的分離，服務端獨立可更好服務于前端、安卓、IOS等客戶端設備。
無狀態(tài)（Stateless）：服務端不保存客戶端狀態(tài)，客戶端保存狀態(tài)信息每次請求攜帶狀態(tài)信息。
可緩存性（Cacheability）?：服務端需回復是否可以緩存以讓客戶端甄別是否緩存提高效率。
統(tǒng)一接口（Uniform Interface）：通過一定原則設計接口降低耦合，簡化系統(tǒng)架構，這是RESTful設計的基本出發(fā)點。當然這個內容除了上述特點提到部分具體內容比較多詳細了解可以參考這篇REST論文內容。
分層系統(tǒng)（Layered System）：客戶端無法直接知道連接的到終端還是中間設備，分層允許你靈活的部署服務端項目。
按需代碼（Code-On-Demand，可選）：按需代碼允許我們靈活的發(fā)送一些看似特殊的代碼給客戶端例如JavaScript代碼。
REST架構的一些風格和限制條件就先介紹到這里，后面就對RESTful風格API具體介紹。
二、RESTful API設計規(guī)范
既然了解了RESTful的一些規(guī)則和特性，那么具體該怎么去設計一個RESTful API呢？要從URL路徑、HTTP請求動詞、狀態(tài)碼和返回結果等方面詳細考慮。至于其他的方面例如錯誤處理、過濾信息等規(guī)范這里就不詳細介紹了。
URL設計規(guī)范
URL為統(tǒng)一資源定位器 ,接口屬于服務端資源，首先要通過URL這個定位到資源才能去訪問，而通常一個完整的URL組成由以下幾個部分構成：
URI?=?scheme?"://"?host??":"??port?"/"?path?[?"?"?query?][?"#"?fragment?]
scheme: 指底層用的協(xié)議，如http、https、ftp
host: 服務器的IP地址或者域名
port: 端口，http默認為80端口
path: 訪問資源的路徑，就是各種web 框架中定義的route路由
query: 查詢字符串，為發(fā)送給服務器的參數，在這里更多發(fā)送數據分頁、排序等參數。
fragment: 錨點，定位到頁面的資源
我們在設計API時URL的path是需要認真考慮的，而RESTful對path的設計做了一些規(guī)范，通常一個RESTful API的path組成如下：
/{version}/{resources}/{resource_id}
version：API版本號，有些版本號放置在頭信息中也可以，通過控制版本號有利于應用迭代。
resources：資源，RESTful API推薦用小寫英文單詞的復數形式。
resource_id：資源的id，訪問或操作該資源。
當然，有時候可能資源級別較大，其下還可細分很多子資源也可以靈活設計URL的path，例如：
/{version}/{resources}/{resource_id}/{subresources}/{subresource_id}
此外，有時可能增刪改查無法滿足業(yè)務要求，可以在URL末尾加上action，例如
/{version}/{resources}/{resource_id}/action
其中action就是對資源的操作。
從大體樣式了解URL路徑組成之后，對于RESTful API的URL具體設計的規(guī)范如下：
不用大寫字母，所有單詞使用英文且小寫。
連字符用中杠
"-"而不用下杠"_"正確使用?
"/"表示層級關系,URL的層級不要過深，并且越靠前的層級應該相對越穩(wěn)定結尾不要包含正斜杠分隔符
"/"URL中不出現動詞，用請求方式表示動作
資源表示用復數不要用單數
不要使用文件擴展名
HTTP動詞
在RESTful API中，不同的HTTP請求方法有各自的含義，這里就展示GET,POST,PUT,DELETE幾種請求API的設計與含義分析。針對不同操作，具體的含義如下：
GET /collection：從服務器查詢資源的列表（數組）
GET /collection/resource：從服務器查詢單個資源
POST /collection：在服務器創(chuàng)建新的資源
PUT /collection/resource：更新服務器資源
DELETE?/collection/resource：從服務器刪除資源
在非RESTful風格的API中，我們通常使用GET請求和POST請求完成增刪改查以及其他操作，查詢和刪除一般使用GET方式請求，更新和插入一般使用POST請求。從請求方式上無法知道API具體是干嘛的，所有在URL上都會有操作的動詞來表示API進行的動作，例如：query，add，update，delete等等。
而RESTful風格的API則要求在URL上都以名詞的方式出現，從幾種請求方式上就可以看出想要進行的操作，這點與非RESTful風格的API形成鮮明對比。
在談及GET,POST,PUT,DELETE的時候，就必須提一下接口的安全性和冪等性，其中安全性是指方法不會修改資源狀態(tài)，即讀的為安全的，寫的操作為非安全的。而冪等性的意思是操作一次和操作多次的最終效果相同，客戶端重復調用也只返回同一個結果。
上述四個HTTP請求方法的安全性和冪等性如下：
| HTTP Method | 安全性 | 冪等性 | 解釋 |
|---|---|---|---|
| GET | 安全 | 冪等 | 讀操作安全，查詢一次多次結果一致 |
| POST | 非安全 | 非冪等 | 寫操作非安全，每多插入一次都會出現新結果 |
| PUT | 非安全 | 冪等 | 寫操作非安全，一次和多次更新結果一致 |
| DELETE | 非安全 | 冪等 | 寫操作非安全，一次和多次刪除結果一致 |
狀態(tài)碼和返回數據
服務端處理完成后客戶端也可能不知道具體成功了還是失敗了，服務器響應時，包含狀態(tài)碼和返回數據兩個部分。
狀態(tài)碼
我們首先要正確使用各類狀態(tài)碼來表示該請求的處理執(zhí)行結果。狀態(tài)碼主要分為五大類：
1xx：相關信息
2xx：操作成功
3xx：重定向
4xx：客戶端錯誤
5xx：服務器錯誤
每一大類有若干小類，狀態(tài)碼的種類比較多，而主要常用狀態(tài)碼羅列在下面：
200?OK - [GET]：服務器成功返回用戶請求的數據，該操作是冪等的（Idempotent）。
201?CREATED - [POST/PUT/PATCH]：用戶新建或修改數據成功。
202?Accepted - [*]：表示一個請求已經進入后臺排隊（異步任務）
204?NO CONTENT - [DELETE]：用戶刪除數據成功。
400?INVALID REQUEST - [POST/PUT/PATCH]：用戶發(fā)出的請求有錯誤，服務器沒有進行新建或修改數據的操作，該操作是冪等的。
401?Unauthorized - [*]：表示用戶沒有權限（令牌、用戶名、密碼錯誤）。
403?Forbidden - [*]?表示用戶得到授權（與401錯誤相對），但是訪問是被禁止的。
404?NOT FOUND - [*]：用戶發(fā)出的請求針對的是不存在的記錄，服務器沒有進行操作，該操作是冪等的。
406?Not Acceptable - [GET]：用戶請求的格式不可得（比如用戶請求JSON格式，但是只有XML格式）。
410?Gone -[GET]：用戶請求的資源被永久刪除，且不會再得到的。
422?Unprocesable entity - [POST/PUT/PATCH]?當創(chuàng)建一個對象時，發(fā)生一個驗證錯誤。
500?INTERNAL SERVER ERROR - [*]：服務器發(fā)生錯誤，用戶將無法判斷發(fā)出的請求是否成功。
返回結果
針對不同操作，服務器向用戶返回數據，而各個團隊或公司封裝的返回實體類也不同，但都返回JSON格式數據給客戶端。
第三關 一個RESTful API案例
上面講了RESTful理論知識，下面動手實現一個小案例吧！
預備
在本案例的實戰(zhàn)中，我們訪問的RESTful接口都是對數據庫真實的操作，新建數據庫，創(chuàng)建一個數據庫和表(根據自己喜好)。
選擇Maven依賴的時候，只需要勾選其中Spring的Web模塊、MySQL驅動以及MyBatis框架。
本案例的POJO創(chuàng)建Dog.java實體對象，其具體構造為：
package?com.restfuldemo.pojo;
public?class?Dog?{
????private?int?id;//唯一id標識
????private?String?name;//名稱
????private??int?age;//年齡
????//省略get?set
}
上面創(chuàng)建好了項目，我們就開始構建RESTful風格的API。在具體構建RESTful API的時候，需要對各種請求有更細致的認知，當然，本案例在實現各種請求的時候為了演示的便捷并沒有完全遵循RESTful API規(guī)范，例如版本號等信息這里就不添加了，案例更側重于使用SpringBoot實現這個接口。
本案例實現對dog資源的增刪改查，如下是非RESTful 和RESTful接口對比：
| API name | 非 RESTful | RESTful |
|---|---|---|
| 獲取dog | /dogs/query/{dogid} | GET：?/dogs/{dogid} |
| 插入dog | /dogs/add | POST：?/dogs |
| 更新dog | /dogs/update/{dogid} | PUT：/dogs/{dogid} |
| 刪除dog | /dods/delete/{dogid} | DELETE：/dogs/{dogid} |
另外在使用postman進行發(fā)送請求的時候，有三種常用的文件類型傳遞到后端：
form-data?：就是form表單中的multipart/form-data，會將表單數據處理為一條信息，用特定標簽符將一條條信息分割開，而這個文件類型通常用來上傳二進制文件。
x-www-form-urlencoded：就是application/x-www-form-urlencoded，是form表單默認的encType，form表單會將表單內的數據轉換為鍵值對，這種格式不能上傳文件。
raw：可以上傳任意格式的文本，可以上傳Text，JSON，XML等，但目前大部分還是上傳JSON格式數據。當后端需要接收JSON格式數據處理的時候，可以采用這種格式來測試。
因為GET請求查詢參數在URL上，其他類型請求使用x-www-form-urlencoded方式向后端傳值。
GET POST PUT DELETE請求
GET請求用來獲取資源：GET請求會向數據庫發(fā)索取數據的請求，從而來獲取資源，該請求就像數據庫的select操作一樣，只是用來查詢數據，不會影響資源的內容。無論進行多少次操作，結果都是一樣的。
并且GET請求會把請求的參數附加在URL后面，但是不同的瀏覽器對其有不同的大小長度限制。
在本案例中，我們設計兩個GET請求的API。GET /dogs?：用來返回dog資源的列表。GET /dogs/{dogid}?：用來查詢此id的單個dog資源。
POST請求用來新增一個資源?: POST請求向服務器發(fā)送數據，但是該請求會改變數據的內容(新添)，就像數據庫的insert操作一樣，會創(chuàng)建新的內容。且POST請求的請求參數都是請求體中，其大小是沒有限制的。
在本案例中，我們設計以下POST請求的API。POST /dogs?：服務端新增一個dog資源。
PUT請求用來更新資源，PUT請求是向服務器端發(fā)送數據的， 與POST請求不同的是，PUT請求側重于數據的修改?,就像數據庫中update一樣，而POST請求側重于數據的增加。
在本案例中，我們設計以下POST請求的API。PUT /dogs/{dogid}?：用來更新此id的單個dog資源。
DELETE 請求用來刪除資源，DELETE請求用途和它字面意思一致，用來刪除資源。和數據庫中delete相對應。
在本案例中，我們設計以下DELETE請求的API。DELETE /dogs/{dogid}?：用來刪除此id的單個dog資源。
對應的Mapper文件為：
package?com.restfuldemo.mapper;
import?com.restfuldemo.pojo.Dog;
import?org.apache.ibatis.annotations.*;
import?java.util.List;
@Mapper
public?interface?DogMapper?{
????@Select("select?*?from?dog")
????List?getAllDog() ;
????@Select("select?*?from?dog?where?id=#{id}")
????Dog?getDogById(@Param("id")?int?id);
????@Insert("insert?into?dog?(name,age)?values?(#{name},#{age})")
????boolean?addDog(Dog?dog);
????@Update("update?dog?set?name=#{name},age=#{age}?where?id=#{id}")
????boolean?updateDog(Dog?dog);
????@Delete("delete??from?dog?where?id=#{id}")
????boolean?deleteDogById(int?id);
}
對應controller文件為：
package?com.restfuldemo.controller;
import?com.restfuldemo.mapper.DogMapper;
import?com.restfuldemo.pojo.Dog;
import?org.springframework.beans.factory.annotation.Autowired;
import?org.springframework.web.bind.annotation.*;
import?java.util.Arrays;
import?java.util.List;
@RestController
public?class?TestController?{
????@Autowired(required?=?false)
????DogMapper?dogMapper;
????@GetMapping("dogs")
????public?List?getDogs()
???? {
????????return??dogMapper.getAllDog();
????}
????@GetMapping("dogs/{id}")
????public?Dog?getDogById(@PathVariable("id")?int?id)
????{
????????Dog?dog=dogMapper.getDogById(id);
????????return??dog;
????}
????@PostMapping("dogs")
????public?boolean?addDog(Dog?dog)
????{
????????return?dogMapper.addDog(dog);
????}
????@PutMapping("dogs/{id}")
????public?boolean?updateDog(@PathVariable("id")int?id,@RequestParam("name")String?name,@RequestParam("age")int?age)
????{
????????Dog?dog=dogMapper.getDogById(id);
????????dog.setName(name);
????????dog.setAge(age);
????????return??dogMapper.updateDog(dog);
????}
????@DeleteMapping("dogs/{id}")
????public?boolean?deleteDog(@PathVariable("id")?int?id)
????{
????????return??dogMapper.deleteDogById(id);
????}
}
經過筆者測試一切都是ok的，如果要項目源文件請聯系筆者發(fā)你哈！
總結
RESTful風格的API 固然很好很規(guī)范，但大多數互聯網公司并沒有按照或者完全按照其規(guī)則來設計，因為REST是一種風格，而不是一種約束或規(guī)則，過于理想的RESTful API 會付出太多的成本。
比如RESTful API也有一些缺點
比如操作方式繁瑣，RESTful API通常根據GET、POST、PUT、DELETE 來區(qū)分操作資源的動作，而HTTP Method 本身不可直接見，是隱藏的，而如果將動作放到URL的path上反而清晰可見，更利于團隊的理解和交流。
并且有些瀏覽器對GET,POST之外的請求支持不太友好，還需要特殊額外的處理。
過分強調資源，而實際業(yè)務API可能有各種需求比較復雜，單單使用資源的增刪改查可能并不能有效滿足使用需求，強行使用RESTful風格API只會增加開發(fā)難度和成本。
所以，當你或你們的技術團隊在設計API的時候，如果使用場景和REST風格很匹配，那么你們可以采用RESTful 風格API。但是如果業(yè)務需求和RESTful風格API不太匹配或者很麻煩，那也可以不用RESTful風格API或者可以借鑒一下，畢竟無論那種風格的API都是為了方便團隊開發(fā)、協(xié)商以及管理，不能墨守成規(guī)。
到這里RESTful API的介紹和實戰(zhàn)就結束啦，本篇首先從RESTful的一些特點進行介紹，再到SpringBoot實戰(zhàn)RESTful API，最后也說了一些RESTful API并不完美的地方，相信睿智的你對RESTful 一定有了很深刻的理解。在以后項目的API設計上定能有所優(yōu)化。
不同的人對RESTful API可能有著不同的理解，但存在即合理，RESTful API有著其鮮明的優(yōu)勢和特點，目前也是一種API設計的主要選型之一，所以掌握和理解RESTful API還是相當重要的!
