1. 理解 REST
??REST 全稱是 Representational State Transfer,中文意思是表征性狀態(tài)轉(zhuǎn)移脓规。它首次出現(xiàn)在2000年Roy Fielding的博士論文中,Roy Fielding是HTTP規(guī)范的主要編寫者之一。值得注意的是REST并沒(méi)有一個(gè)明確的標(biāo)準(zhǔn)涕刚,而更像是一種設(shè)計(jì)的風(fēng)格晓避。如果一個(gè)架構(gòu)符合REST的約束條件和原則簇捍,我們就稱它為RESTful架構(gòu)。
??理論上REST架構(gòu)風(fēng)格并不是綁定在HTTP上俏拱,只不過(guò)目前HTTP是唯一與REST相關(guān)的實(shí)例暑塑。
1.1. REST 原則
- 資源 可通過(guò)目錄結(jié)構(gòu)樣式的 URIs 暴露
- 表述 可以通過(guò) JSON 或 XML 表達(dá)的數(shù)據(jù)對(duì)象或?qū)傩詠?lái)傳遞
- 消息 使用統(tǒng)一的 HTTP 方法(例如:GET、POST彰触、PUT 和 DELETE)
- 無(wú)狀態(tài) 客戶端與服務(wù)端之間的交互在請(qǐng)求之間是無(wú)狀態(tài)的梯投,從客戶端到服務(wù)端的每個(gè)請(qǐng)求都必須包含理解請(qǐng)求所必需的信息
1.2. HTTP 方法
??使用 HTTP 將 CRUD(create, retrieve, update, delete <創(chuàng)建、獲取况毅、更新分蓖、刪除—增刪改查>)操作映射為 HTTP 請(qǐng)求。如果按照HTTP方法的語(yǔ)義來(lái)暴露資源尔许,那么接口將會(huì)擁有安全性和冪等性的特性么鹤,例如GET和HEAD請(qǐng)求都是安全的, 無(wú)論請(qǐng)求多少次味廊,都不會(huì)改變服務(wù)器狀態(tài)蒸甜。而GET、HEAD余佛、PUT和DELETE請(qǐng)求都是冪等的柠新,無(wú)論對(duì)資源操作多少次, 結(jié)果總是一樣的辉巡,后面的請(qǐng)求并不會(huì)產(chǎn)生比第一次更多的影響恨憎。
1.2.1. GET
- 安全且冪等
- 獲取信息
1.2.2. POST
- 不安全且不冪等
- 使用請(qǐng)求中提供的實(shí)體執(zhí)行操作,可用于創(chuàng)建資源或更新資源
1.2.3. PUT
- 不安全但冪等
- 使用請(qǐng)求中提供的實(shí)體執(zhí)行操作,可用于創(chuàng)建資源或更新資源
1.2.4. DELETE
- 不安全但冪等
- 刪除資源
??POST和PUT在創(chuàng)建資源的區(qū)別在于憔恳,所創(chuàng)建的資源的名稱(URI)是否由客戶端決定瓤荔。 例如為我的博文增加一個(gè)java的分類,生成的路徑就是分類名/categories/java钥组,那么就可以采用PUT方法输硝。不過(guò)很多人直接把POST、GET程梦、PUT点把、DELETE直接對(duì)應(yīng)上CRUD,例如在一個(gè)典型的rails實(shí)現(xiàn)的RESTful應(yīng)用中就是這么做的作烟。
1.3. HTTP status codes
??狀態(tài)碼指示 HTTP 請(qǐng)求的結(jié)果:
- 1XX:信息
- 2XX:成功
- 3XX:轉(zhuǎn)發(fā)
- 4XX:客戶端錯(cuò)誤
- 5XX:服務(wù)端錯(cuò)誤
1.4. 媒體類型
??HTTP頭中的 Accept 和 Content-Type 可用于描述HTTP請(qǐng)求中發(fā)送或請(qǐng)求的內(nèi)容愉粤。如果客戶端請(qǐng)求JSON響應(yīng),那么可以將 Accept 設(shè)為 application/json拿撩。相應(yīng)地衣厘,如果發(fā)送的內(nèi)容是XML,那么可以設(shè)置 Content-Type 為 application/xml 压恒。
2. REST API 設(shè)計(jì)最佳實(shí)踐
??這里介紹一些設(shè)計(jì) REST API 的最佳實(shí)踐影暴,大家先記住下面這句話:
URL 是個(gè)句子,其中資源是名詞探赫、HTTP 方法是動(dòng)詞型宙。
2.1. 使用名詞來(lái)表示資源
??下面是一些例子:
- GET - /users:返回用戶列表
- GET - /users/100:返回一個(gè)特定用戶
- POST - /users:創(chuàng)建一個(gè)新用戶
- PUT - /users/200:更新一個(gè)特定用戶
- DELETE - /users/711:刪除一個(gè)特定用戶
??不要使用動(dòng)詞: /getAllsers/getUserById/createNewUser/updateUser/deleteUser
2.2 在 HTTP 頭中使用適當(dāng)?shù)男蛄谢袷?/h2>
??客戶端和服務(wù)端都需要知道通信所用的格式,這個(gè)格式要在 HTTP 頭中指定:
- Content-Type 定義請(qǐng)求格式
- Accept 定義一個(gè)可接受的響應(yīng)格式列表
2.3 Get 方法和查詢參數(shù)不應(yīng)當(dāng)改變狀態(tài)
??使用 PUT, POST 和 DELETE 方法來(lái)改變狀態(tài)伦吠,不要使用 GET 方法來(lái)改變狀態(tài):
- GET
/users/711?activate或 - GET
/users/711/activate
2.4. 使用子資源表示關(guān)聯(lián)
??如果一個(gè)資源與另一個(gè)資源關(guān)聯(lián)妆兑,使用子資源:
- GET /cars/711/drivers/ 返回711號(hào)汽車的駕駛員列表
- GET /cars/711/drivers/4 返回711號(hào)汽車的第4號(hào)駕駛員
2.5. 使用適當(dāng)?shù)?HTTP 方法 (動(dòng)詞)
??再回顧一下這句話:
URL 是個(gè)句子,其中資源是名詞毛仪、HTTP 方法是動(dòng)詞搁嗓。
- GET:獲取在URI資源中指定的表述,響應(yīng)消息體包含所請(qǐng)求資源的細(xì)節(jié)箱靴。
- POST:創(chuàng)建一個(gè)URI指定的新資源腺逛,請(qǐng)求消息體提供新資源的細(xì)節(jié)。注意衡怀,POST也可以觸發(fā)一些操作棍矛,而不一定是要?jiǎng)?chuàng)建新資源。
- PUT:創(chuàng)建或替代指定URI的資源抛杨。請(qǐng)求消息體指定要?jiǎng)?chuàng)建或更新的資源够委。
- DELETE:移除指定URI的資源。
2.6. HTTP 響應(yīng)狀態(tài)碼
??當(dāng)客戶端通過(guò)API向服務(wù)端發(fā)起一個(gè)請(qǐng)求時(shí)怖现,客戶端應(yīng)當(dāng)知道反饋:是否失敗慨绳、通過(guò)或者請(qǐng)求錯(cuò)誤。HTTP 狀態(tài)碼是一批標(biāo)準(zhǔn)化代碼,在不同的場(chǎng)景下有不同的解釋脐雪。服務(wù)器應(yīng)當(dāng)總是返回正確的狀態(tài)碼。
??下面是重要的HTTP代碼分類:
- 2xx (成功分類):這些狀態(tài)碼代碼請(qǐng)求動(dòng)作被接收且被服務(wù)器成功處理恢共。
- 200:Ok 表示 GET战秋、PUT 或 POST 請(qǐng)求的標(biāo)準(zhǔn)狀態(tài)碼。
- 201:Created(已創(chuàng)建)表示實(shí)例已被創(chuàng)建讨韭,多用于 POST 方法脂信。
- 204:No Content(無(wú)內(nèi)容)表示請(qǐng)求已被成功處理但沒(méi)有返回任何內(nèi)容。常用于 DELETE 方法返回透硝。
- 3xx (轉(zhuǎn)發(fā)分類)
- 304:Not Modified(無(wú)修改)表示客戶端已經(jīng)緩存此響應(yīng)狰闪,無(wú)須再次傳輸相同內(nèi)容。
- 4xx (客戶端錯(cuò)誤分類):這些狀態(tài)碼代表客戶端提交了一個(gè)錯(cuò)誤請(qǐng)求濒生。
- 400:Bad Request(錯(cuò)誤請(qǐng)求)表示客戶端請(qǐng)求沒(méi)被處理埋泵,因?yàn)榉?wù)端無(wú)法理解客戶端請(qǐng)求。
- 401:Unauthorized(無(wú)授權(quán))表示客戶端無(wú)權(quán)訪問(wèn)資源罪治,應(yīng)當(dāng)加上所需的認(rèn)證信息后再次請(qǐng)求丽声。
- 403:Forbidden(禁止訪問(wèn))表示請(qǐng)求有效且客戶端已獲授權(quán),但客戶端無(wú)權(quán)訪問(wèn)該資源觉义。
- 404:Not Found(沒(méi)發(fā)現(xiàn))表示所請(qǐng)求的資源現(xiàn)在不可用雁社。
- 410:Gone(移除)表示所請(qǐng)求的資源已被移除。
- 5xx (服務(wù)端錯(cuò)誤分類)
- 500:Internal Server Error(內(nèi)部服務(wù)器錯(cuò)誤)表示請(qǐng)求有效晒骇,但是服務(wù)端發(fā)生了異常霉撵。
- 503:Service Unavailable(服務(wù)不可用)表示服務(wù)器關(guān)閉或不可用,通常是指服務(wù)器處于維護(hù)狀態(tài)洪囤。
2.7. 名稱規(guī)約
??你可以遵循任何名稱規(guī)約徒坡,只要保持跨應(yīng)用一致性即可。如果請(qǐng)求體和響應(yīng)體是 JSON 類型箍鼓,那么請(qǐng)遵循駝峰名稱規(guī)約崭参。
2.8. 搜索、排序款咖、過(guò)濾與分頁(yè)
??上面一些示例都是在一個(gè)數(shù)據(jù)集上的簡(jiǎn)單查詢何暮,對(duì)于復(fù)雜的數(shù)據(jù),我們需要在 GET 方法 API 上加一些參數(shù)來(lái)處理铐殃。下面是一些示例:
- 排序:這個(gè)例子中海洼,客戶想獲取排序的公司列表,GET /companies 應(yīng)當(dāng)在查詢時(shí)接受多種排序參數(shù)富腊。譬如 GET /companies?sort=rank_asc 將以等級(jí)升序的方式對(duì)公司進(jìn)行排序坏逢。
- 過(guò)濾:要過(guò)濾數(shù)據(jù)集,我們可以通過(guò)查詢參數(shù)傳遞不同的選項(xiàng)。比如 GET /companies?category=banking&location=india 將過(guò)濾分類為銀行且位于印度的公司是整。
- 搜索:在公司列表中搜索公司名的 API 端點(diǎn)應(yīng)當(dāng)是 GET /companies?search=Digital肖揣。
- 分頁(yè):當(dāng)數(shù)據(jù)集太大時(shí),我們應(yīng)當(dāng)將數(shù)據(jù)集分割成小的數(shù)據(jù)塊浮入,這樣有利于提升服務(wù)端性能龙优,也方便客戶端處理響應(yīng)。如 GET /companies?page=23 意味著獲取公司列表的第 23 頁(yè)數(shù)據(jù)事秀。
2.9. Restful API 版本
??一般使用不帶點(diǎn)的簡(jiǎn)單數(shù)字表示版本彤断,數(shù)字前加字母v代表版本號(hào),如下所示:
- /blog/api/v1
- http://api.yourservice.com/v1/companies/34/employees
2.10. 處理 JSON 錯(cuò)誤體
??API 錯(cuò)誤處理機(jī)制是很重要的易迹,而且要好好規(guī)劃宰衙。極力推薦總是在返回字段中包含錯(cuò)誤消息。一個(gè) JSON 錯(cuò)誤體應(yīng)當(dāng)為開(kāi)發(fā)者提供一些有用的信息:錯(cuò)誤消息睹欲、錯(cuò)誤代碼以及詳細(xì)描述供炼。下面是一個(gè)較好的示例:
{
"code": 1234,
"message": "Something bad happened :(",
"description": "More details about the error here"
}
2.11. 如何創(chuàng)建 Rest API URL
??推薦使用下面格式的 URL:
- http(s)://{域名(:端口號(hào))}/{表示REST API的值}/{API版本}/{識(shí)別資源的路徑}
- http(s)://{表示REST API的域名(:端口號(hào))}/{API 版本}/{識(shí)別資源的路徑}
??如下所示: - http://example.com/api/v1/members/M000000001
- http://api.example.com/v1/members/M000000001
3. 開(kāi)發(fā)基于 Spring Boot 的 Restful Web 服務(wù)
??Spring Boot 提供了構(gòu)建企業(yè)應(yīng)用中 RESTful Web 服務(wù)的極佳支持。
3.1. 引入依賴
??要構(gòu)建 RESTful Web 服務(wù)句伶,我們需要在構(gòu)建配置文件中加上 Spring Boot Starter Web 依賴劲蜻。
??對(duì)于 Maven 用戶,使用以下的代碼在 pom.xml 文件中加入依賴:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
??對(duì)于 Gradle 用戶考余,使用以下的代碼在 build.gradle 文件中加入依賴:
compile('org.springframework.boot:spring-boot-starter-web')
3.2. Rest 相關(guān)注解
??在繼續(xù)構(gòu)建 RESTful web 服務(wù)前先嬉,建議你先要熟悉下面的注解:
Rest Controller
??@RestController 注解用于定義 RESTful web 服務(wù)。它提供 JSON楚堤、XML 和自定義響應(yīng)疫蔓。語(yǔ)法如下所示:
@RestController
public class ProductServiceController {
}
Request Mapping
??@RequestMapping 注解用于定義請(qǐng)求 URI 以訪問(wèn) REST 端點(diǎn)。我們可以定義 Request 方法來(lái)消費(fèi) produce 對(duì)象身冬。默認(rèn)的請(qǐng)求方法是 GET:
@RequestMapping(value = "/products")
public ResponseEntity<Object> getProducts() { }
Request Body
@RequestBody 注解用于定義請(qǐng)求體內(nèi)容類型衅胀。
public ResponseEntity<Object> createProduct(@RequestBody Product product) {
}
Path Variable
??@PathVariable 注解被用于定義自定義或動(dòng)態(tài)的請(qǐng)求 URI,Path variable 被放在請(qǐng)求 URI 中的大括號(hào)內(nèi)酥筝,如下所示:
public ResponseEntity<Object> updateProduct(@PathVariable("id") String id) {
}
Request Parameter
??@RequestParam 注解被用于從請(qǐng)求 URL 中讀取請(qǐng)求參數(shù)滚躯。缺省情況下是必須的,也可以為請(qǐng)求參數(shù)設(shè)置默認(rèn)值嘿歌。如下所示:
public ResponseEntity<Object> getProduct(
@RequestParam(value = "name", required = false, defaultValue = "honey") String name) {
}
3.3. 編寫 REST API
GET API
??下面的示例代碼定義了 HTTP GET 請(qǐng)求方法掸掏。在這個(gè)例子里,我們使用 HashMap 來(lái)在存儲(chǔ) Product宙帝。注意我們使用了 POJO 類來(lái)存儲(chǔ)產(chǎn)品丧凤。
??在這里,請(qǐng)求 URI 是 /products步脓,它會(huì)從 HashMap 倉(cāng)儲(chǔ)中返回產(chǎn)品列表愿待。下面的控制器類文件包含了 GET 方法的 REST 端點(diǎn):
package com.tutorialspoint.demo.controller;
import java.util.HashMap;
import java.util.Map;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import com.tutorialspoint.demo.model.Product;
@RestController
public class ProductServiceController {
private static Map<String, Product> productRepo = new HashMap<>();
static {
Product honey = new Product();
honey.setId("1");
honey.setName("Honey");
productRepo.put(honey.getId(), honey);
Product almond = new Product();
almond.setId("2");
almond.setName("Almond");
productRepo.put(almond.getId(), almond);
}
@RequestMapping(value = "/products")
public ResponseEntity<Object> getProduct() {
return new ResponseEntity<>(productRepo.values(), HttpStatus.OK);
}
}
POST API
??HTTP POST 請(qǐng)求用于創(chuàng)建資源浩螺。這個(gè)方法包含請(qǐng)求體。我們可以通過(guò)發(fā)送請(qǐng)求參數(shù)和路徑變量來(lái)定義自定義或動(dòng)態(tài) URL仍侥。
??下面的示例代碼定義了 HTTP POST 請(qǐng)求方法要出。在這個(gè)例子中,我們使用 HashMap 來(lái)存儲(chǔ) Product农渊,這里產(chǎn)品是一個(gè) POJO 類厨幻。
??這里,請(qǐng)求 URI 是 /products腿时,在產(chǎn)品被存入 HashMap 倉(cāng)儲(chǔ)后,它會(huì)返回字符串饭宾。
package com.tutorialspoint.demo.controller;
import java.util.HashMap;
import java.util.Map;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import com.tutorialspoint.demo.model.Product;
@RestController
public class ProductServiceController {
private static Map<String, Product> productRepo = new HashMap<>();
@RequestMapping(value = "/products", method = RequestMethod.POST)
public ResponseEntity<Object> createProduct(@RequestBody Product product) {
productRepo.put(product.getId(), product);
return new ResponseEntity<>("Product is created successfully", HttpStatus.CREATED);
}
}
PUT API
??HTTP PUT 請(qǐng)求用于更新已有的資源批糟。這個(gè)方法包含請(qǐng)求體。我們可以通過(guò)發(fā)送請(qǐng)求參數(shù)和路徑變量來(lái)定義自定義或動(dòng)態(tài) URL看铆。
??下面的例子展示了如何定義 HTTP PUT 請(qǐng)求方法徽鼎。在這個(gè)例子中,我們使用 HashMap 更新現(xiàn)存的產(chǎn)品弹惦。此處否淤,產(chǎn)品是一個(gè) POJO 類。
??這里棠隐,請(qǐng)求 URI 是 /products/{id}石抡,在產(chǎn)品被存入 HashMap 倉(cāng)儲(chǔ)后,它會(huì)返回字符串助泽。注意我們使用路徑變量 {id} 定義需要更新的產(chǎn)品 ID:
package com.tutorialspoint.demo.controller;
import java.util.HashMap;
import java.util.Map;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import com.tutorialspoint.demo.model.Product;
@RestController
public class ProductServiceController {
private static Map<String, Product> productRepo = new HashMap<>();
@RequestMapping(value = "/products/{id}", method = RequestMethod.PUT)
public ResponseEntity<Object> updateProduct(@PathVariable("id") String id, @RequestBody Product product) {
productRepo.remove(id);
product.setId(id);
productRepo.put(id, product);
return new ResponseEntity<>("Product is updated successsfully", HttpStatus.OK);
}
}
DELETE API
??HTTP Delete 請(qǐng)求用于刪除存在的資源啰扛。這個(gè)方法不包含任何請(qǐng)求體。我們可以通過(guò)發(fā)送請(qǐng)求參數(shù)和路徑變量來(lái)定義自定義或動(dòng)態(tài) URL嗡贺。
??下面的例子展示如何定義 HTTP DELETE 請(qǐng)求方法隐解。這個(gè)例子中,我們使用 HashMap 來(lái)移除現(xiàn)存的產(chǎn)品诫睬,用 POJO 來(lái)表示煞茫。
??請(qǐng)求 URI 是 /products/{id} 在產(chǎn)品被從 HashMap 倉(cāng)儲(chǔ)中刪除后,它會(huì)返回字符串摄凡。 我們使用路徑變量 {id} 來(lái)定義要被刪除的產(chǎn)品 ID续徽。
package com.tutorialspoint.demo.controller;
import java.util.HashMap;
import java.util.Map;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import com.tutorialspoint.demo.model.Product;
@RestController
public class ProductServiceController {
private static Map<String, Product> productRepo = new HashMap<>();
@RequestMapping(value = "/products/{id}", method = RequestMethod.DELETE)
public ResponseEntity<Object> delete(@PathVariable("id") String id) {
productRepo.remove(id);
return new ResponseEntity<>("Product is deleted successsfully", HttpStatus.OK);
}
}