java的RESTful規(guī)范有哪些

本篇內(nèi)容主要講解“java的RESTful規(guī)范有哪些”，感興趣的朋友不妨來(lái)看看。本文介紹的方法操作簡(jiǎn)單快捷，實(shí)用性強(qiáng)。下面就讓小編來(lái)帶大家學(xué)習(xí)“java的RESTful規(guī)范有哪些”吧!

什么是RESTful

一種軟件架構(gòu)風(fēng)格、設(shè)計(jì)風(fēng)格，而不是標(biāo)準(zhǔn)，只是提供了一組設(shè)計(jì)原則和約束條件。它主要用于客戶端和服務(wù)器交互類的軟件。基于這個(gè)風(fēng)格設(shè)計(jì)的軟件可以更簡(jiǎn)潔，更有層次，更易于實(shí)現(xiàn)緩存等機(jī)制。

一、URI規(guī)范

1.不用大寫(xiě)；

2.用中杠 - 不用下杠 _ ；

3.參數(shù)列表要encode；

4.URI中的名詞表示資源集合，使用復(fù)數(shù)形式。

5.在RESTful架構(gòu)中，每個(gè)網(wǎng)址代表一種資源（resource），所以網(wǎng)址中不能有動(dòng)詞，只能有名詞（特殊情況可以使用動(dòng)詞），而且所用的名詞往往與數(shù)據(jù)庫(kù)的表格名對(duì)應(yīng)。

資源集合 vs單個(gè)資源

URI表示資源的兩種方式：資源集合、單個(gè)資源。

資源集合：

       /zoos //所有動(dòng)物園

       /zoos/1/animals //id為1的動(dòng)物園中的所有動(dòng)物

單個(gè)資源：

       /zoos/1//id為1的動(dòng)物園

       /zoos/1;2;3//id為1，2，3的動(dòng)物園

避免層級(jí)過(guò)深的URI

在url中表達(dá)層級(jí)，用于 按實(shí)體關(guān)聯(lián)關(guān)系進(jìn)行對(duì)象導(dǎo)航 ，一般根據(jù)id導(dǎo)航。

過(guò)深的導(dǎo)航容易導(dǎo)致url膨脹，不易維護(hù)，如 GET /zoos/1/areas/3/animals/4 ，盡量使用查詢參數(shù)代替路徑中的實(shí)體導(dǎo)航，如 GET/animals?zoo=1&area=3 ；

二、   版本

應(yīng)該將API的版本號(hào)放入到URI中

https://api.example.com/v1/zoos

三、 Request

HTTP方法

通過(guò)標(biāo)準(zhǔn)HTTP方法對(duì)資源CRUD：

GET：查詢（從服務(wù)器取出資源一項(xiàng)或多項(xiàng)）

GET /zoos

GET /zoos/1

GET/zoos/1/employees

POST：創(chuàng)建單個(gè)新資源。 POST一般向“資源集合”型uri發(fā)起

POST/animals  //新增動(dòng)物

POST/zoos/1/employees //為id為1的動(dòng)物園雇傭員工

PUT：更新單個(gè)資源（全量），客戶端提供完整的更新后的資源。與之對(duì)應(yīng)的是 PATCH，PATCH負(fù)責(zé)部分更新，客戶端提供要更新的那些字段。 PUT/PATCH一般向“單個(gè)資源”型uri發(fā)起

PUT/animals/1

PUT /zoos/1

DELETE：刪除

DELETE/zoos/1/employees/2

DELETE/zoos/1/employees/2;4;5

DELETE/zoos/1/animals  //刪除id為1的動(dòng)物園內(nèi)的所有動(dòng)物

HEAD / OPTION/ PATCH用的不多，就不多解釋了。

HEAD：獲取資源的元數(shù)據(jù)

OPTIONS：獲取信息，關(guān)于資源的哪些屬性是客戶端可以改變的

PATCH：在服務(wù)器更新資源（客戶端提供改變的屬性）

安全性和冪等性

1.     安全性 ：不會(huì)改變資源狀態(tài)，可以理解為只讀的；

2.     冪等性 ：執(zhí)行1次和執(zhí)行N次，對(duì)資源狀態(tài)改變的效果是等價(jià)的。

安全性和冪等性均不保證反復(fù)請(qǐng)求能拿到相同的response。以 DELETE為例，第一次DELETE返回200表示刪除成功，第二次返回404提示資源不存在，這是允許的。

復(fù)雜查詢

查詢可以捎帶以下參數(shù)：

Bookmarker

經(jīng)常使用的、復(fù)雜的查詢標(biāo)簽化，降低維護(hù)成本。

如：GET /trades?status=closed&sort=created,desc

快捷方式：GET /trades#recently-closed或者GET /trades/recently-closed

狀態(tài)碼

    服務(wù)器向用戶返回的狀態(tài)碼和提示信息，常見(jiàn)的有以下一些（方括號(hào)中是該狀態(tài)碼對(duì)應(yīng)的HTTP動(dòng)詞）。

§200 OK - [GET]：服務(wù)器成功返回用戶請(qǐng)求的數(shù)據(jù)，該操作是冪等的（Idempotent）。

§201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數(shù)據(jù)成功。

§202 Accepted - [*]：表示一個(gè)請(qǐng)求已經(jīng)進(jìn)入后臺(tái)排隊(duì)（異步任務(wù)）

§204 NO CONTENT - [DELETE]：用戶刪除數(shù)據(jù)成功。

§400 INVALID REQUEST - [POST/PUT/PATCH]：用戶發(fā)出的請(qǐng)求有錯(cuò)誤，服務(wù)器沒(méi)有進(jìn)行新建或修改數(shù)據(jù)的操作，該操作是冪等的。

§401 Unauthorized - [*]：表示用戶沒(méi)有權(quán)限（令牌、用戶名、密碼錯(cuò)誤）。

§403 Forbidden - [*] 表示用戶得到授權(quán)（與401錯(cuò)誤相對(duì)），但是訪問(wèn)是被禁止的。

§404 NOT FOUND - [*]：用戶發(fā)出的請(qǐng)求針對(duì)的是不存在的記錄，服務(wù)器沒(méi)有進(jìn)行操作，該操作是冪等的。

§406 Not Acceptable - [GET]：用戶請(qǐng)求的格式不可得（比如用戶請(qǐng)求JSON格式，但是只有XML格式）。

§410 Gone -[GET]：用戶請(qǐng)求的資源被永久刪除，且不會(huì)再得到的。

§422 Unprocesable entity - [POST/PUT/PATCH] 當(dāng)創(chuàng)建一個(gè)對(duì)象時(shí)，發(fā)生一個(gè)驗(yàn)證錯(cuò)誤。

§500 INTERNAL SERVER ERROR - [*]：服務(wù)器發(fā)生錯(cuò)誤，用戶將無(wú)法判斷發(fā)出的請(qǐng)求是否成功。

狀態(tài)碼的完全列表參見(jiàn)這里

URI失效

隨著系統(tǒng)發(fā)展，總有一些API失效或者遷移，對(duì)失效的API，返回404 not found 或 410 gone；對(duì)遷移的API，返回 301重定向。

四、Response

1.    不要包裝：

response的 body 直接就是數(shù)據(jù)，不要做多余的包裝。錯(cuò)誤示例：

{

   "success":true,

   "data":{"id":1,"name":"xiaotuan"},

}

2.    各HTTP方法成功處理后的數(shù)據(jù)格式：

五、錯(cuò)誤處理

1.     不要發(fā)生了錯(cuò)誤但給2xx響應(yīng)，客戶端可能會(huì)緩存成功的http請(qǐng)求；

2.     正確設(shè)置http狀態(tài)碼，不要自定義；

3.     Response body提供

即:返回的信息中將error作為鍵名，出錯(cuò)信息作為鍵值即可

1)錯(cuò)誤的代碼（日志/問(wèn)題追查）；

2)錯(cuò)誤的描述文本（展示給用戶）。

對(duì)第三點(diǎn)的實(shí)現(xiàn)稍微多說(shuō)一點(diǎn)：

Java服務(wù)器端一般用異常表示 RESTful API的錯(cuò)誤。API 可能拋出兩類異常：業(yè)務(wù)異常和非業(yè)務(wù)異常。 業(yè)務(wù)異常 由自己的業(yè)務(wù)代碼拋出，表示一個(gè)用例的前置條件不滿足、業(yè)務(wù)規(guī)則沖突等，比如參數(shù)校驗(yàn)不通過(guò)、權(quán)限校驗(yàn)失敗。 非業(yè)務(wù)類異常 表示不在預(yù)期內(nèi)的問(wèn)題，通常由類庫(kù)、框架拋出，或由于自己的代碼邏輯錯(cuò)誤導(dǎo)致，比如數(shù)據(jù)庫(kù)連接失敗、空指針異常、除0錯(cuò)誤等等。

業(yè)務(wù)類異常必須提供2種信息：

1.     如果拋出該類異常，HTTP響應(yīng)狀態(tài)碼應(yīng)該設(shè)成什么；

2.     異常的文本描述；

在Controller層使用統(tǒng)一的異常攔截器：

1.     設(shè)置 HTTP響應(yīng)狀態(tài)碼：對(duì)業(yè)務(wù)類異常，用它指定的 HTTPcode；對(duì)非業(yè)務(wù)類異常，統(tǒng)一500；

2.     Response Body的錯(cuò)誤碼：異常類名

3.     Response Body的錯(cuò)誤描述：對(duì)業(yè)務(wù)類異常，用它指定的錯(cuò)誤文本；對(duì)非業(yè)務(wù)類異常，線上可以統(tǒng)一文案如“服務(wù)器端錯(cuò)誤，請(qǐng)稍后再試”，開(kāi)發(fā)或測(cè)試環(huán)境中用異常的 stacktrace，服務(wù)器端提供該行為的開(kāi)關(guān)。

常用的http狀態(tài)碼及使用場(chǎng)景：

六、其他

（1）API的身份認(rèn)證應(yīng)該使用OAuth3.0框架

（2）服務(wù)器返回的數(shù)據(jù)格式，應(yīng)該盡量使用JSON，避免使用XML

（3）比較復(fù)雜的接口不能確定是使用POST還是PUT時(shí)，要看具體的業(yè)務(wù)層代碼，看看接口產(chǎn)生的結(jié)果是否冪等，如果冪等用PUT，相反用POST

      如：接口接收到一資源，資源存在更新，不存在插入新數(shù)據(jù)，這個(gè)接口就要用PUT

到此，相信大家對(duì)“java的RESTful規(guī)范有哪些”有了更深的了解，不妨來(lái)實(shí)際操作一番吧！這里是億速云網(wǎng)站，更多相關(guān)內(nèi)容可以進(jìn)入相關(guān)頻道進(jìn)行查詢，關(guān)注我們，繼續(xù)學(xué)習(xí)！