1前言

最近電腦壞了，開源項(xiàng)目的進(jìn)度也受到一些影響

(相關(guān)資料圖)

這篇醞釀很久了，作為本系列第二部分（API接口開發(fā)）的第一篇，得想一個(gè)好的開頭，想著想著就鴿了好久，索性不扯那么多了，直接開寫吧~

2關(guān)于RESTFul

網(wǎng)上很多相關(guān)的文章都要把RESTFul歷史來龍去脈給復(fù)制一遍，所以我這就不重復(fù)了，現(xiàn)在主要的HTTP接口風(fēng)格就倆：RPC和RESTFul。

舉個(gè)例子就可以看出這倆的區(qū)別

RPC風(fēng)格

分別是增刪改查的接口

操作	HTTP方法	URL
增	post	/blog/add
刪	post	/blog/deleteById
改	post	/blog/updateById
查	get	/blog/getAll

可以看出RPC風(fēng)格的特點(diǎn)：

基本就是用post和get這倆方法來操作接口URL的命名跟函數(shù)命名一樣，都是動(dòng)詞，一目了然

PS：RPC這種幾乎一個(gè)團(tuán)隊(duì)一個(gè)風(fēng)格，我見過有人把所有接口都做成post方法，然后請(qǐng)求參數(shù)全部用json格式放在body里的。

關(guān)鍵是這個(gè)請(qǐng)求參數(shù)還不統(tǒng)一，同個(gè)項(xiàng)目不同開發(fā)人員寫的請(qǐng)求參數(shù)格式不一致，很惡心。（微信有些接口也是這樣）

RESTFul風(fēng)格

分別是增刪改查的接口

操作	HTTP方法	URL
增	post	/blog/
刪	delete	/blog/{id}/
改	put	/blog/{id}/
查	get	/blog/
查	get	/blog/{id}/

可以看出RESTFul風(fēng)格的特點(diǎn)：

利用各種HTTP方法來實(shí)現(xiàn)增刪改查（其實(shí)還有patch、head這些方法，不展開了）URL的命名是名詞，以資源名稱作為URL，更統(tǒng)一使用get獲取資源，方便后端、客戶端、網(wǎng)關(guān)這些地方做緩存，提高性能接口返回值

除了請(qǐng)求接口，RESTFul還建議接口返回的時(shí)候根據(jù)不同狀態(tài)使用不同的HTTP狀態(tài)碼。

以下是HTTP定義的五類狀態(tài)碼。

類別	描述
1xx：信息	通信傳輸協(xié)議級(jí)信息。
2xx：成功	表示客戶端的請(qǐng)求已成功接受。
3xx：重定向	表示客戶端必須執(zhí)行一些其他操作才能完成其請(qǐng)求。
4xx：客戶端錯(cuò)誤	此類錯(cuò)誤狀態(tài)代碼指向客戶端。
5xx：服務(wù)器錯(cuò)誤	服務(wù)器負(fù)責(zé)這些錯(cuò)誤狀態(tài)代碼。

比如添加了數(shù)據(jù)，返回 201 (created)添加、更新、刪除這些不需要返回?cái)?shù)據(jù)的接口，返回 204 (no content)沒登錄，返回 401 (unauthorized)找不到，返回 404 (not found)沒權(quán)限，返回 403 (forbidden)

這樣就很清晰了，看接口返回的狀態(tài)碼就能知道結(jié)果如何。

在一些前端ajax庫（比如axios）中，返回碼如果是4xx或5xx，就會(huì)拋出異常，這樣訪問邏輯就可以根據(jù)錯(cuò)誤做出一些提示。

例子

假設(shè)接口返回結(jié)構(gòu)是這樣

{"successful":true,"message":"請(qǐng)求成功","data":[{...},{...},{...}]}

請(qǐng)求接口的 JavaScript 代碼如下

axios.get("/blog/").then(res=>msg.success(`請(qǐng)求成功，返回信息：${res.data.message}`)).catch(res=>msg.error(`請(qǐng)求失敗，返回信息：${res.data.message}`))

但是！實(shí)際場景很復(fù)雜，HTTP標(biāo)準(zhǔn)狀態(tài)碼就40個(gè)，根本不夠用啊。

所以這些HTTP狀態(tài)碼只能對(duì)返回值做個(gè)大概的分類，復(fù)雜系統(tǒng)還是得自己定義一套錯(cuò)誤碼。

小結(jié)

這倆各有優(yōu)劣，RESTFul看起來比較統(tǒng)一優(yōu)雅，但表達(dá)能力有限；RPC的URL命名看起來比較隨意，不過自由發(fā)揮的空間也很大。

我個(gè)人是比較傾向RESTFul風(fēng)格的，所以StarBlog使用了RESTFul風(fēng)格的接口，不過這并不能滿足全部功能需求，所以參考Django的RestFramework，將RESTFul和RPC稍微結(jié)合一下。

舉個(gè)例子：要在博客增刪改查的基礎(chǔ)上增加設(shè)置置頂、點(diǎn)贊等功能。

操作	HTTP方法	URL
設(shè)置置頂	post	/blog/{id}/setTop/
點(diǎn)贊	post	/blog/{id}/thumbUp/
獲取置頂文章	get	/blog/getTop/

可以看到這種縫合怪是以RESTFul為基礎(chǔ)，增刪改查以外的功能，在對(duì)應(yīng)的資源上使用RPC風(fēng)格。

setTop/ thumbUp/ getTop這些動(dòng)詞在RestFramework里面也叫 action ，意為對(duì)一系列資源執(zhí)行的動(dòng)作。

關(guān)于HTTP方法，對(duì)資源有修改的，使用post方法，沒有修改單純讀取的，使用get方法。

3接口開發(fā)規(guī)劃

本系列文章更新順序跟StarBlog博客開發(fā)的順序基本一致，即在已有MVC架構(gòu)網(wǎng)站的基礎(chǔ)上，增加RESTFul接口，用于管理后臺(tái)（前后端分離）對(duì)博客進(jìn)行配置管理。

目前我把接口分成這幾類

auth - 認(rèn)證授權(quán)，顧名思義，后面會(huì)細(xì)說admin - 管理員相關(guān)，主要功能有配置管理、訪問記錄、系統(tǒng)監(jiān)控等blog - 博客相關(guān)，功能就是文章、分類、圖片等信息的crudcommon - 公用接口，StarBlog除了博客功能外，還以接口形式提供了一些小功能，如一句詩、一言、隨機(jī)圖片、主題切換等test - 測試接口，用于一些功能測試，在正式環(huán)境會(huì)關(guān)閉訪問links - 友情鏈接管理，這個(gè)功能比較復(fù)雜，單獨(dú)做成一個(gè)分類

后續(xù)會(huì)有更多類似友情鏈接這樣比較復(fù)雜的功能加入（比如評(píng)論），這種會(huì)單獨(dú)做成一個(gè)分類。

PS：之前在開發(fā)博客前臺(tái)的時(shí)候，把大部分功能都寫在了 services里面，現(xiàn)在開發(fā)接口的時(shí)候就派上用場了，很多邏輯都是通用的，在接口的controller里面只需要調(diào)用這些 services就可以了。

4需要關(guān)注的其他東西

本文不涉及具體實(shí)現(xiàn)，只是作為RESTFul接口開發(fā)部分的前言或者大綱，接口開發(fā)看似就crud四個(gè)操作很簡單，實(shí)際上比想象的復(fù)雜。

例如，獲取文章列表接口，博客的文章數(shù)量會(huì)很多，不可能一個(gè)接口返回所有文章信息，因此要做分頁處理，同時(shí)我們還希望能在文章列表實(shí)現(xiàn)關(guān)鍵詞過濾、分類、狀態(tài)篩選、排序等功能；

已登錄用戶才能發(fā)表評(píng)論，管理員才能管理文章，因此需要實(shí)現(xiàn)認(rèn)證授權(quán)、角色管理等功能；

同一時(shí)間可能有很多人訪問博客（或者是爬蟲），需要對(duì)接口做限流處理，以免程序崩潰；

接口數(shù)量多起來了，swagger顯示太雜亂，需要對(duì)接口分組，或者更換swagger前端；

正式環(huán)境不想讓用戶看到swagger接口文檔，可以隱藏或者給swagger加鎖；

頻繁訪問的資源，可以使用服務(wù)端緩存提升性能，減輕IO壓力，使用客戶端緩存降低服務(wù)器流量；

耗時(shí)操作（如批量導(dǎo)出文章、發(fā)送短信通知）放到異步任務(wù)隊(duì)列（或者后臺(tái)任務(wù)）里執(zhí)行；

以上列舉的種種只是我在撰寫本文的當(dāng)下考慮博客需要用到的，實(shí)際上應(yīng)該還有很多。只能說后端的水很深，開發(fā)本項(xiàng)目的過程也是一個(gè)不斷探索、實(shí)踐的過程，“No silver bullet”，沒有任何技術(shù)能適用全部場景，只能在不斷的積累中得出某個(gè)場景下的最佳實(shí)踐。

OK，本文就到這吧。

5系列文章基于.NetCore開發(fā)博客項(xiàng)目 StarBlog - (1) 為什么需要自己寫一個(gè)博客？基于.NetCore開發(fā)博客項(xiàng)目 StarBlog - (2) 環(huán)境準(zhǔn)備和創(chuàng)建項(xiàng)目基于.NetCore開發(fā)博客項(xiàng)目 StarBlog - (3) 模型設(shè)計(jì)基于.NetCore開發(fā)博客項(xiàng)目 StarBlog - (4) markdown博客批量導(dǎo)入基于.NetCore開發(fā)博客項(xiàng)目 StarBlog - (5) 開始搭建Web項(xiàng)目基于.NetCore開發(fā)博客項(xiàng)目 StarBlog - (6) 頁面開發(fā)之博客文章列表基于.NetCore開發(fā)博客項(xiàng)目 StarBlog - (7) 頁面開發(fā)之文章詳情頁面基于.NetCore開發(fā)博客項(xiàng)目 StarBlog - (8) 分類層級(jí)結(jié)構(gòu)展示基于.NetCore開發(fā)博客項(xiàng)目 StarBlog - (9) 圖片批量導(dǎo)入基于.NetCore開發(fā)博客項(xiàng)目 StarBlog - (10) 圖片瀑布流基于.NetCore開發(fā)博客項(xiàng)目 StarBlog - (11) 實(shí)現(xiàn)訪問統(tǒng)計(jì)基于.NetCore開發(fā)博客項(xiàng)目 StarBlog - (12) Razor頁面動(dòng)態(tài)編譯基于.NetCore開發(fā)博客項(xiàng)目 StarBlog - (13) 加入友情鏈接功能基于.NetCore開發(fā)博客項(xiàng)目 StarBlog - (14) 實(shí)現(xiàn)主題切換功能基于.NetCore開發(fā)博客項(xiàng)目 StarBlog - (15) 生成隨機(jī)尺寸圖片基于.NetCore開發(fā)博客項(xiàng)目 StarBlog - (16) 一些新功能 (監(jiān)控/統(tǒng)計(jì)/配置/初始化)基于.NetCore開發(fā)博客項(xiàng)目 StarBlog - (17) 自動(dòng)下載文章里的外部圖片基于.NetCore開發(fā)博客項(xiàng)目 StarBlog - (18) 實(shí)現(xiàn)本地Typora文章打包上傳基于.NetCore開發(fā)博客項(xiàng)目 StarBlog - (19) Markdown渲染方案探索基于.NetCore開發(fā)博客項(xiàng)目 StarBlog - (20) 圖片顯示優(yōu)化基于.NetCore開發(fā)博客項(xiàng)目 StarBlog - (21) 開始開發(fā)RESTFul接口

關(guān)鍵詞： 請(qǐng)求參數(shù) 配置管理 錯(cuò)誤狀態(tài)