RESTful設計中的常見疑問
阿新 • • 發佈：2020-05-15
最近寫了幾個有關RESTful的API相關內容，也談談對常見問題的自己的理解。
## 1.什麼是RESTful
詳情可以看[http://www.ruanyifeng.com/blog/2011/09/restful.html](http://www.ruanyifeng.com/blog/2011/09/restful.html)。
簡單可以這麼理解，使用`URI`去代表資源，使用HTTP VERB（GET PUT等）對資源的操作。
## 2.為什麼要用RESTful
使用RESTful，優點有很多，也方便不同的請求方去請求資料。列舉兩個：
* HTTP方法語義都很明確，使用GET去獲得資料，使用DELETE去刪除資料。
* 返回值也是很明確的HTTP RESPONSE，200就是執行成功，400就是請求錯誤。
那是不是每一個API都需要使用REST風格呢？我覺得不是，這要看團隊、專案而定，不必一味強求。
## 3.在URI資源地址中使用v1之類的版本號符不符合RESTful？
這個涉及到RESTful的版本管理，常見的方法有這麼幾種。
### URL Path
```html
/api/v1/helloworld
```
很多公開的API地址裡面，都帶有version資訊，如果非要去扣符不符合RESTful，估計要吵起來。但是這個方式很便捷、明確，呼叫方一看就明白，也沒有額外的工作量去做。不過缺點也很明顯，由於已經限定死了版本號在URI中，無法實現同一個URI地址版本的靈活切換，也不能指定預設版本。
### Query String
```html
/api/helloworld?api-version=1.0
```
這個方式沒有改變URI本身，但是需要呼叫方去額外處理Query string，不過好在這個可以指定預設的。
### Media Types
```html
POST api/helloworld HTTP/1.1
host: localhost
content-type: text/plain;v=2.0
content-length: 12
Hello there!
```
在Content-Type裡面新增v=x.x的版本號也是一個不錯的選擇，可以實現QueryString類似的功能。
> 有一些現成的庫可以幫助我們實現上面的Versioning方法，常見的是[aspnet-api-versioning](https://github.com/microsoft/aspnet-api-versioning)
## 4.什麼是安全性？
無論請求多少次，伺服器的狀態（資源）都不會改變，那麼這個方法就是安全的。
> GET HEAD都應該設計成安全的。
## 5.什麼是冪等性？
無論對資源操作多少次，**伺服器資源結果**總是一樣的，那麼這個方法就是冪等的。注意這裡的說法，是伺服器的資源結果是一樣的，不代表請求的返回結果是一樣的。比如DELETE請求，它是冪等的，但是刪除一個資源很多次的情況（多次執行`DELETE api/student/1`，第一次返回成功，第二次返回失敗，但是不影響伺服器上對應的記錄已經刪除的狀態。
> GET、HEAD、PUT和DELETE請求都應該設計成是冪等的。
## 6.新增資料用POST還是PUT？
資源新增可以用POST也可以用PUT，但是設計上有幾個區別。
### 冪等性
PUT是冪等的，POST不是，如果設計上需要不應用冪等性，那麼使用POST。比如POST計數器的應用，每次POST，計數器都增長1。
### 請求目標
POST一般請求的是資源集合，而PUT一般請求是一個具體的資源。
```
PUT /students/{id}
POST /students
```
這也意味著，語義上，POST是請求在**集合**中新增資源。
### 主動權
* 如果id不是由呼叫方生成的情況下，需要指定的資源ID的PUT方法就不好實現了。這種情況，使用POST到資源更合理，主動權在伺服器方，伺服器建立資源之後，返回201攜帶新生成的物件URI。
* 如果id是由呼叫方生成的情況下（比如一些硬體裝置產生的資料），使用POST和PUT都可以，但是PUT有冪等性，顯得更加明確，這種時候我一般選擇使用PUT。
### 覆蓋
PUT語義是要求覆蓋的，如果資料已經存在，就必須覆蓋。POST的沒有這個要求，可以有別的行為。
## 7.修改資料應該使用PUT還是PATCH？
不一定，要看情況。PUT是覆蓋性的修改，而PATCH是追加性的修改。
* 使用PUT的時候，需要將資料完整返回，如果有的欄位沒有賦值，那麼將保持為預設值。
* PUT是冪等的，PATCH不是，因此多次執行PUT請求，結果是一樣的；執行PATCH有可能不一樣。
```json
{
"value":
{
"id": "235314",
"deviceId": "123",
"type": "低溫"
}
}
```
如果傳送的資料只含有deviceId，執行PUT之後，資源變成：
```json
{
"value":
{
"id": "235314",
"deviceId": "111"
}
}
```
執行PATCH，資源變成：
```json
{
"value":
{
"id": "235314",
"deviceId": "111",
"type": "低溫"
}
}
```
## 8.沒有資料返回204還是404？
問題：
如果請求一個這樣的資源
```html
GET api/sutudents/homework
```
在沒有homework的情況下應該返回HTTP 204 NoContent還是返回HTTP 404 NotFound？
乍看一眼，覺得好像都差不多，沒內容和沒找到反正都是沒有。但深入想想，還是有很大的區別的。
1. 404返回的更傾向於表述**不存在**的性質，而204返回表述沒有內容，也就是存在，但是沒有內容。
2. 4xx返回表述大體是請求有問題，而2xx返回表述大體是請求沒有問題。
所以，對於上面的問題，這麼理解，如果homework是已經建立的資源，但是內容為空，那麼返回204是可以的，但是如果homework這個東西就不存在，那麼應該返回404。
> 個人認為直接返回200，攜帶對應的空內容會比204要對呼叫方更加友好，至少和有資料的情況是一樣處理。
## 9.寫給前端
有很多前端同學需要伺服器返回固定的成功資訊（比如200）或者錯誤資訊（比如400）。但HTTP CODE很多，一個一個判斷效率很低，好在HTTP CODE是分類的，比如2xx大體是OK的，4xx都是有問題的。可以通過`CODE / 100 == 2`之類的方法去大體確定返回的狀