1 概述

針對(duì)目前項(xiàng)目中使用的前后端分離開發(fā)，越來越感覺到API設(shè)計(jì)的重要性，而不好的API設(shè)計(jì)通常讓使用者通過URL無(wú)法明確知道這個(gè)URL到底是干什么用的，并且會(huì)顯得設(shè)計(jì)混亂，在此將使用Restful風(fēng)格設(shè)計(jì)API進(jìn)行總結(jié)袁稽，并對(duì)在SpringBoot中具體實(shí)現(xiàn)Restful API的設(shè)計(jì)給出一定示例。

2 Restful API設(shè)計(jì)

使用Restful API是一種面向資源的設(shè)計(jì)風(fēng)格擒抛，因此我們每一個(gè)URL對(duì)應(yīng)的都是一個(gè)資源推汽。從而針對(duì)資源的操作我們就可以使用HTTP的相應(yīng)的請(qǐng)求方式來進(jìn)行體現(xiàn)。

2.1 版本

應(yīng)該將API的版本號(hào)放入U(xiǎn)RL中歧沪，例如http://localhost:8080/v1/歹撒。

2.2 URL定義為名詞

在之前我們通常看見/addUser诊胞、/editUser這樣的URL定義暖夭，那么如果我們使用這樣的定義就相當(dāng)于我們放棄了HTTP請(qǐng)求方式（GET,POST,PUT,PATCH,DELETE）等的表達(dá)作用。并且我們也知道Restful提倡面向資源的URL路徑撵孤，所以URL使用名詞來進(jìn)行定義迈着，并且URL路徑都是小寫。例如：

操作用戶資源：http://localhost:8080/v1/user邪码，

操作多個(gè)用戶資源：http://localhost:8080/v1/users寥假，

操作財(cái)務(wù)部下的用戶資源：http://localhost:8080/v1/accounting-department/user，從這里我們可以學(xué)到一點(diǎn)霞扬，針對(duì)某個(gè)資源需要兩個(gè)單詞來進(jìn)行表達(dá)的時(shí)候我們可以使用“-”將兩個(gè)單詞連接起來。

2.3 使用HTTP請(qǐng)求方法來表達(dá)對(duì)資源的操作

上面我們知道了Restful API的URL定義是面向資源的，也就是每一個(gè)URL表示的是一種資源喻圃，那我我們要表達(dá)對(duì)資源的相關(guān)操作怎么辦呢萤彩？而且Restful風(fēng)格也強(qiáng)調(diào)了URL必須為名詞構(gòu)成。

這里我們就可以使用HTTP的請(qǐng)求方式來表達(dá)對(duì)資源的操作了斧拍。

GET：獲取資源雀扶。

POST:創(chuàng)建資源。

PUT:修改資源肆汹。

PATCH:修改資源愚墓，這里的修改資源和PUT的區(qū)別在于這里只向后臺(tái)傳遞了修改資源的部分內(nèi)容，而PUT傳遞的是全部?jī)?nèi)容昂勉。

DELETE：刪除資源浪册。

還有兩個(gè)不常用的HTTP動(dòng)詞。
HEAD：獲取資源的元數(shù)據(jù)岗照。
OPTIONS：獲取信息村象，關(guān)于資源的哪些屬性是客戶端可以改變的。

2.4 數(shù)據(jù)傳遞格式

JSON閱讀性更高攒至，擴(kuò)展性更強(qiáng)厚者，適合各種環(huán)境和語(yǔ)言進(jìn)行解析，現(xiàn)在大的互聯(lián)網(wǎng)公司迫吐，對(duì)外提供的API基本都使用JSON库菲。

2.5 使用HTTP狀態(tài)碼

針對(duì)請(qǐng)求的響應(yīng)，我們可以直接利用Http的狀態(tài)碼來表達(dá)錯(cuò)誤信息志膀，這樣也可以很形象地得知每次請(qǐng)求的結(jié)果熙宇，而不是每次請(qǐng)求都是200，然后再去響應(yīng)體中獲取是否有錯(cuò)誤信息梧却，這樣響應(yīng)體沒有結(jié)果封裝奇颠，沒有額外的傳輸負(fù)擔(dān)。

針對(duì)Http狀態(tài)碼無(wú)法表示的異常信息放航，我們可以增加自定義異常碼烈拒。增加自定義頭字段，Error-Message 表示錯(cuò)誤信息广鳍，只在出現(xiàn)異常的時(shí)候返回荆几。下面的表格內(nèi)容參考自菜鳥教程。

HTTP狀態(tài)碼共分為5種類型：

分類 分類描述

• 1** 信息赊时，服務(wù)器收到請(qǐng)求吨铸，需要請(qǐng)求者繼續(xù)執(zhí)行操作
• 2** 成功，操作被成功接收并處理
• 3** 重定向祖秒，需要進(jìn)一步的操作以完成請(qǐng)求
• 4** 客戶端錯(cuò)誤诞吱，請(qǐng)求包含語(yǔ)法錯(cuò)誤或無(wú)法完成請(qǐng)求
• 5** 服務(wù)器錯(cuò)誤舟奠，服務(wù)器在處理請(qǐng)求的過程中發(fā)生了錯(cuò)誤

HTTP狀態(tài)碼列表:

狀態(tài)碼 狀態(tài)碼英文名稱 中文描述

• 100 Continue 繼續(xù)》课客戶端應(yīng)繼續(xù)其請(qǐng)求

• 101 Switching Protocols 切換協(xié)議沼瘫。服務(wù)器根據(jù)客戶端的請(qǐng)求切換協(xié)議。只能切換到更高級(jí)的協(xié)議咙俩，例如耿戚，切換到HTTP的新版本協(xié)議

• 200 OK 請(qǐng)求成功。一般用于GET與POST請(qǐng)求

• 201 Created 已創(chuàng)建阿趁。成功請(qǐng)求并創(chuàng)建了新的資源

• 202 Accepted 已接受膜蛔。已經(jīng)接受請(qǐng)求，但未處理完成

• 203 Non-Authoritative Information 非授權(quán)信息脖阵。請(qǐng)求成功皂股。但返回的meta信息不在原始的服務(wù)器，而是一個(gè)副本

• 204 No Content 無(wú)內(nèi)容独撇。服務(wù)器成功處理屑墨，但未返回內(nèi)容。在未更新網(wǎng)頁(yè)的情況下纷铣，可確保瀏覽器繼續(xù)顯示當(dāng)前文檔

• 205 Reset Content 重置內(nèi)容卵史。服務(wù)器處理成功，用戶終端（例如：瀏覽器）應(yīng)重置文檔視圖搜立∫郧可通過此返回碼清除瀏覽器的表單域

• 206 Partial Content 部分內(nèi)容。服務(wù)器成功處理了部分GET請(qǐng)求

• 300 Multiple Choices 多種選擇啄踊。請(qǐng)求的資源可包括多個(gè)位置忧设，相應(yīng)可返回一個(gè)資源特征與地址的列表用于用戶終端（例如：瀏覽器）選擇

• 301 Moved Permanently 永久移動(dòng)。請(qǐng)求的資源已被永久的移動(dòng)到新URI颠通，返回信息會(huì)包括新的URI址晕，瀏覽器會(huì)自動(dòng)定向到新URI。今后任何新的請(qǐng)求都應(yīng)使用新的URI代替

• 302 Found 臨時(shí)移動(dòng)顿锰。與301類似谨垃。但資源只是臨時(shí)被移動(dòng)∨鹂兀客戶端應(yīng)繼續(xù)使用原有URI

• 303 See Other 查看其它地址刘陶。與301類似。使用GET和POST請(qǐng)求查看

• 304 Not Modified 未修改牢撼。所請(qǐng)求的資源未修改匙隔，服務(wù)器返回此狀態(tài)碼時(shí)，不會(huì)返回任何資源熏版》自穑客戶端通常會(huì)緩存訪問過的資源捍掺，通過提供一個(gè)頭信息指出客戶端希望只返回在指定日期之后修改的資源

• 305 Use Proxy 使用代理。所請(qǐng)求的資源必須通過代理訪問

• 306 Unused 已經(jīng)被廢棄的HTTP狀態(tài)碼

• 307 Temporary Redirect 臨時(shí)重定向碰逸。與302類似乡小。使用GET請(qǐng)求重定向

• 400 Bad Request 客戶端請(qǐng)求的語(yǔ)法錯(cuò)誤，服務(wù)器無(wú)法理解

• 401 Unauthorized 請(qǐng)求要求用戶的身份認(rèn)證

• 402 Payment Required 保留饵史，將來使用

• 403 Forbidden 服務(wù)器理解請(qǐng)求客戶端的請(qǐng)求，但是拒絕執(zhí)行此請(qǐng)求

• 404 Not Found 服務(wù)器無(wú)法根據(jù)客戶端的請(qǐng)求找到資源（網(wǎng)頁(yè)）胜榔。通過此代碼胳喷，網(wǎng)站設(shè)計(jì)人員可設(shè)置"您所請(qǐng)求的資源無(wú)法找到"的個(gè)性頁(yè)面

• 405 Method Not Allowed 客戶端請(qǐng)求中的方法被禁止

• 406 Not Acceptable 服務(wù)器無(wú)法根據(jù)客戶端請(qǐng)求的內(nèi)容特性完成請(qǐng)求

• 407 Proxy Authentication Required 請(qǐng)求要求代理的身份認(rèn)證，與401類似夭织，但請(qǐng)求者應(yīng)當(dāng)使用代理進(jìn)行授權(quán)

• 408 Request Time-out 服務(wù)器等待客戶端發(fā)送的請(qǐng)求時(shí)間過長(zhǎng)吭露，超時(shí)

• 409 Conflict 服務(wù)器完成客戶端的PUT請(qǐng)求是可能返回此代碼，服務(wù)器處理請(qǐng)求時(shí)發(fā)生了沖突

• 410 Gone 客戶端請(qǐng)求的資源已經(jīng)不存在尊惰。410不同于404讲竿，如果資源以前有現(xiàn)在被永久刪除了可使用410代碼，網(wǎng)站設(shè)計(jì)人員可通過301代碼指定資源的新位置

• 411 Length Required 服務(wù)器無(wú)法處理客戶端發(fā)送的不帶Content-Length的請(qǐng)求信息

• 412 Precondition Failed 客戶端請(qǐng)求信息的先決條件錯(cuò)誤

• 413 Request Entity Too Large 由于請(qǐng)求的實(shí)體過大弄屡，服務(wù)器無(wú)法處理题禀，因此拒絕請(qǐng)求。為防止客戶端的連續(xù)請(qǐng)求膀捷，服務(wù)器可能會(huì)關(guān)閉連接迈嘹。如果只是服務(wù)器暫時(shí)無(wú)法處理，則會(huì)包含一個(gè)Retry-After的響應(yīng)信息

• 414 Request-URI Too Large 請(qǐng)求的URI過長(zhǎng)（URI通常為網(wǎng)址）全庸，服務(wù)器無(wú)法處理

• 415 Unsupported Media Type 服務(wù)器無(wú)法處理請(qǐng)求附帶的媒體格式

• 416 Requested range not satisfiable 客戶端請(qǐng)求的范圍無(wú)效

• 417 Expectation Failed 服務(wù)器無(wú)法滿足Expect的請(qǐng)求頭信息

• 500 Internal Server Error 服務(wù)器內(nèi)部錯(cuò)誤秀仲，無(wú)法完成請(qǐng)求

• 501 Not Implemented 服務(wù)器不支持請(qǐng)求的功能，無(wú)法完成請(qǐng)求

• 502 Bad Gateway 充當(dāng)網(wǎng)關(guān)或代理的服務(wù)器神僵，從遠(yuǎn)端服務(wù)器接收到了一個(gè)無(wú)效的請(qǐng)求

• 503 Service Unavailable 由于超載或系統(tǒng)維護(hù)，服務(wù)器暫時(shí)的無(wú)法處理客戶端的請(qǐng)求覆劈。延時(shí)的長(zhǎng)度可包含在服務(wù)器的Retry-After頭信息中

• 504 Gateway Time-out 充當(dāng)網(wǎng)關(guān)或代理的服務(wù)器保礼，未及時(shí)從遠(yuǎn)端服務(wù)器獲取請(qǐng)求

• 505 HTTP Version not supported 服務(wù)器不支持請(qǐng)求的HTTP協(xié)議的版本，無(wú)法完成處理

作者：ONROAD0612
來源：CSDN
原文：https://blog.csdn.net/ONROAD0612/article/details/82216015
版權(quán)聲明：本文為博主原創(chuàng)文章墩崩，轉(zhuǎn)載請(qǐng)附上博文鏈接氓英！