基于.NetCore開發(fā)博客項(xiàng)目 StarBlog - (21) 開始開發(fā)RESTFul接口
最近電腦壞了,開源項(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)詞,一目了然RESTFul風(fē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ù)格式不一致,很惡心。(微信有些接口也是這樣)
分別是增刪改查的接口
操作 | 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)代碼。 |
這樣就很清晰了,看接口返回的狀態(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è)分類。
4需要關(guān)注的其他東西PS:之前在開發(fā)博客前臺(tái)的時(shí)候,把大部分功能都寫在了 services里面,現(xiàn)在開發(fā)接口的時(shí)候就派上用場了,很多邏輯都是通用的,在接口的controller里面只需要調(diào)用這些 services就可以了。
本文不涉及具體實(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)
相關(guān)閱讀
-
基于.NetCore開發(fā)博客項(xiàng)目 StarBlog -...
1前言最近電腦壞了,開源項(xiàng)目的進(jìn)度也受到一些影響這篇醞釀很久了,... -
天天熱推薦:波卡周報(bào)|31 項(xiàng)公投在 O...
加入PolkaWorld社區(qū),共建Web3 0!PolkadotOmniBTC贏得Polkadot第34次插槽Auction。https: -
熱文:原創(chuàng) | Attention is all yo...
作者:楊金珊審校:陳之炎本文約4300字,建議閱讀8分鐘“Attentioni... -
速訊:天才交易員SBF的謝幕:或?qū)⒚媾R終...
原力區(qū)原作眼看著你起高樓,眼看著你酬賓客,眼看著樓塌了——賈平... -
干貨 | 數(shù)字經(jīng)濟(jì)創(chuàng)新創(chuàng)業(yè)——軟件研究...
下文整理自清華大學(xué)大數(shù)據(jù)能力提升項(xiàng)目能力提升模塊課程“Innovatio... -
世界熱文:含對(duì)乙酰氨基酚的中成藥
【本文只提供官方信息,不是購買建議】【本文也不表達(dá)對(duì)中藥和中成...