1、URI

在了解RESTful接口規(guī)范之前，我們先來了解一下什么是URI。

1、URI

它是一種通一的資源標志符，大致的意思就是在web上的每一個可用的資源，例如 HTML、圖片、程序等都有一個URI進行唯一標識,而這些資源一般對應(yīng)的是服務(wù)器端中的實體類。

2、規(guī)范

• 字母無需大寫

• 多個單詞連接在一起作為一個整體時，中間可以用-分割，不推薦使用__

• URI中名詞表示資源的集合且要使用復(fù)數(shù)形式

3、樣例

/schools //表示所有的學校 /schools/1/classes //表示第一個學校的所有班級

4、注意

在使用URI表示層級的時候應(yīng)該避免層級過深，因為這會使得URI非常長，不容易維護，例如 GET /schools/1/classes/4/students/2 ，像這個就可以用 GET /students?school=1 & class=4 來替代

2、RESTful 的特性

1、C-S架構(gòu)

這個特性其實想要表達的意思就是前后端分離，兩端單獨開發(fā)，互不影響

2、無狀態(tài)

簡單來說就是服務(wù)端可以根據(jù)客戶端的各種請求參數(shù)，來將正確的結(jié)果響應(yīng)給客戶端，無需保存客戶端的狀態(tài)

3、統(tǒng)一的接口

客戶端只需要關(guān)注接口即可，這個也是實現(xiàn)前后端分離的一個重要條件

3、RESTful 規(guī)范

1、URL中不能有動詞

在RESTful規(guī)范中，每一個網(wǎng)址代表的都是一個資源，在網(wǎng)址當中不能包含動作，只可以使用名詞且名詞也應(yīng)該使用復(fù)數(shù)形式。

錯誤寫法

https://example.com/api/getallUsers GET 獲取所有用戶 https://example.com/api/getuser/1 GET 獲取標識為1用戶信息 https://example.com/api/user/delete/1 GET/POST 刪除標識為1用戶信息 https://example.com/api/updateUser/1 POST 更新標識為1用戶信息 https://example.com/api/User/add POST 添加新的用戶

正確寫法

https://example.com/api/users GET 獲取所有用戶信息 https://example.com/api/users/1 GET 獲取標識為1用戶信息 https://example.com/api/users/1 DELETE 刪除標識為1用戶信息 https://example.com/api/users/1 Patch 更新標識為1用戶部分信息,包含在body中 https://example.com/api/users POST 添加新的用戶

通過上面的兩個例子我們也可以看出，如果URL中出現(xiàn)一些動詞，這樣很容易造成接口的形式不固定，需要了解文檔后才可以調(diào)用，但是如果我們規(guī)范了我們的寫法后，我們的URL可讀性也大大的增強了。

那么上面的操作是怎么實現(xiàn)的呢？

實際上在http協(xié)議中有一些動詞，可以替代URL中的動詞來表示一些動作

例如:

GET : 就表示從服務(wù)器中檢索特定的資源，或資源列表（相當于數(shù)據(jù)庫中的SELECT操作）

POST : 在服務(wù)器上創(chuàng)建一個新的資源 （相當于數(shù)據(jù)庫中INSERT操作）

PUT : 更新服務(wù)器上的資源，更改整個資源的屬性 （相當于數(shù)據(jù)庫中UPDATE操作）

PATCH : 更新服務(wù)器上的資源，更改資源的部分屬性（相當于數(shù)據(jù)庫中UPDATE操作）

DELETE : 從服務(wù)器中刪除資源。（相當于數(shù)據(jù)庫中DELETE操作）

2、多表查詢，多參查詢該如果設(shè)計URL

例如我想查詢一個獲取在6月份的訂單中大于500元的且用戶地址是北京，用戶年齡在22歲到40歲、購買金額降序排列的訂單列表

https://example.com/api/orders?order_month=6&order_amount_greater=500&address_city=北京&sort=order_amount_desc&age_min=22&age_max=40

這個URL參數(shù)很多，導(dǎo)致不容易進行維護，遇見這種問題，我們可以采取下面的方式來解決

我們可以使用屬性路由，大致的操作就是在特定的控制器或者操作方法上用Controller進行裝飾并使用[Route]屬性來定義路由的方法，好處就是可以精確的控制URL

[Route(“api/orders/{address}/{month}”)]

那么上面的那個URL就可以寫成

https://example.com/api/orders/beijing/6?order_amount_greater=500&sort=order_amount_desc&age_min=22&age_max=40

查詢參數(shù)就只有金額、排序、年齡。減少了查詢參數(shù)、API的可讀性和可維護行增強了。

3、統(tǒng)一返回的數(shù)據(jù)格式

• code —— Http的響應(yīng)狀態(tài)碼

• message —— 當狀態(tài)值為”fail”和”error”時有效，用于顯示錯誤信息。

• data——包含響應(yīng)的body。當狀態(tài)值為”fail”或”error”時，data僅包含錯誤原因或異常名稱、或者null也是可以的

成功響應(yīng)的json返回格式

{"code": 200,"message": "success","data": {"userName": "123456","age": 16,"address": "beijing"} }

失敗響應(yīng)的json返回格式

{"code": 401,"message": "error message","data": null }

4、Http狀態(tài)碼

1、常見的狀態(tài)碼

200 —— OK // 成功返回 201 —— Created // 成功創(chuàng)建 204 —— No Content // 成功銷毀 400 —— Bad Request // 語法錯誤 401 —— Unauthorized // 沒有權(quán)限 403 —— Forbidden // 請求被拒 404 —— Not Found // 找不到資源 500 —— Internal Server Error // 內(nèi)部服務(wù)器錯誤 501 —— Not Implemented // 服務(wù)器無法受理

2、完整的狀態(tài)碼

1XX（平常基本上用不到）

2xx（Success）

200 —— OK // 成功返回了資源 201 —— Created // 成功創(chuàng)建了資源 202 —— Accepted // 請求接受但未處理 203 —— Non-Authoritative Information // 返回資源未授權(quán) 204 —— No Content // 成功銷毀了資源 205 —— Reset Content // 重置內(nèi)容，無任何資源返回 206 —— Partial Content // 處理了部分請求

3xx（redirect）

300 —— Multiple Choice // 選擇服務(wù)器提供的多種操作 301 —— Moved Permanently // 永久移除，自動轉(zhuǎn)跳到新的資源 302 —— Found // 自動轉(zhuǎn)跳到新的資源 303 —— See Other // 查看資源位置 304 —— Not Modified // 請求資源未修改 305 —— Use Proxy // 需要代理 307 —— Temporary Redirect // 臨時重定向 308 —— Permanent Redirect // 永久重定向

4xx（error）

400 —— Bad Request // 請求字段語法錯誤 401 —— Unauthorized // 請求未經(jīng)授權(quán) 403 —— Forbidden // 請求被服務(wù)器拒絕 404 —— Not Found // 找不到資源 405 —— Method Not Allowed // 請求方法不允許 406 —— Not Acceptable // 請求不可接受 407 —— Proxy Authentication Required // 服務(wù)器代理需要授權(quán) 408 —— Request Timeout // 請求超時 409 —— Conflict // 請求沖突 410 —— Gone // 請求的資源已銷毀 411 —— Length Required // 指定有效內(nèi)容長度標頭 412 —— Precondition Failed // 請求條件無法滿足 413 —— Payload Too Large // 請求體過大 414 —— URI Too Long // 請求URL過長 415 —— Unsupported Media Type // 請求的類型不支持 416 —— Requested Range Not Satisfiable // 請求的范圍不符合要求 417 —— Expectation Failed // 服務(wù)器未滿足請求標頭的要求 426 —— Upgrade Required // 升級所需 428 —— Precondition Required // 要求先決條件 429 —— Too Many Requests // 太多的要求 431 —— Request Header Fields Too Large // 請求頭字段太大 451 —— Unavailable For Legal Reasons // 因法律原因不可用

5xx（fail）

500 —— Internal Server Error // 內(nèi)部服務(wù)器錯誤 501 —— Not Implemented // 服務(wù)器無法受理 502 —— Bad Gateway // 服務(wù)器網(wǎng)關(guān)錯誤 503 —— Service Unavailable // 服務(wù)器不可用 504 —— Gateway Timeout // 服務(wù)器代理超時 505 —— HTTP Version Not Supported // 不支持的HTTP版本 511 —— Network Authentication Required // 網(wǎng)絡(luò)認證要求

參考資料:https://blog.csdn.net/kebi007/article/details/102927209

總結(jié)

以上是生活随笔為你收集整理的RESTful接口规范（学习笔记）的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。