您的位置:首頁 >聚焦 >

基于.NetCore開發博客項目 StarBlog - (21) 開始開發RESTFul接口

2022-12-18 05:41:29    來源:程序員客棧
1前言

最近電腦壞了,開源項目的進度也受到一些影響


(相關資料圖)

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

2關于RESTFul

網上很多相關的文章都要把RESTFul歷史來龍去脈給復制一遍,所以我這就不重復了,現在主要的HTTP接口風格就倆:RPC和RESTFul。

舉個例子就可以看出這倆的區別

RPC風格

分別是增刪改查的接口

操作HTTP方法URL
post/blog/add
post/blog/deleteById
post/blog/updateById
get/blog/getAll

可以看出RPC風格的特點:

基本就是用post和get這倆方法來操作接口URL的命名跟函數命名一樣,都是動詞,一目了然

PS:RPC這種幾乎一個團隊一個風格,我見過有人把所有接口都做成post方法,然后請求參數全部用json格式放在body里的。

關鍵是這個請求參數還不統一,同個項目不同開發人員寫的請求參數格式不一致,很惡心。(微信有些接口也是這樣)

RESTFul風格

分別是增刪改查的接口

操作HTTP方法URL
post/blog/
delete/blog/{id}/
put/blog/{id}/
get/blog/
get/blog/{id}/

可以看出RESTFul風格的特點:

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

除了請求接口,RESTFul還建議接口返回的時候根據不同狀態使用不同的HTTP狀態碼。

以下是HTTP定義的五類狀態碼。

類別描述
1xx:信息通信傳輸協議級信息。
2xx:成功表示客戶端的請求已成功接受。
3xx:重定向表示客戶端必須執行一些其他操作才能完成其請求。
4xx:客戶端錯誤此類錯誤狀態代碼指向客戶端。
5xx:服務器錯誤服務器負責這些錯誤狀態代碼。
比如添加了數據,返回 201 (created)添加、更新、刪除這些不需要返回數據的接口,返回 204 (no content)沒登錄,返回 401 (unauthorized)找不到,返回 404 (not found)沒權限,返回 403 (forbidden)

這樣就很清晰了,看接口返回的狀態碼就能知道結果如何。

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

例子

假設接口返回結構是這樣

{"successful":true,"message":"請求成功","data":[{...},{...},{...}]}

請求接口的 JavaScript 代碼如下

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

但是!實際場景很復雜,HTTP標準狀態碼就40個,根本不夠用啊。

所以這些HTTP狀態碼只能對返回值做個大概的分類,復雜系統還是得自己定義一套錯誤碼。

小結

這倆各有優劣,RESTFul看起來比較統一優雅,但表達能力有限;RPC的URL命名看起來比較隨意,不過自由發揮的空間也很大。

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

舉個例子:要在博客增刪改查的基礎上增加設置置頂、點贊等功能。

操作HTTP方法URL
設置置頂post/blog/{id}/setTop/
點贊post/blog/{id}/thumbUp/
獲取置頂文章get/blog/getTop/

可以看到這種縫合怪是以RESTFul為基礎,增刪改查以外的功能,在對應的資源上使用RPC風格。

setTop/ thumbUp/ getTop這些動詞在RestFramework里面也叫 action ,意為對一系列資源執行的動作。

關于HTTP方法,對資源有修改的,使用post方法,沒有修改單純讀取的,使用get方法。

3接口開發規劃

本系列文章更新順序跟StarBlog博客開發的順序基本一致,即在已有MVC架構網站的基礎上,增加RESTFul接口,用于管理后臺(前后端分離)對博客進行配置管理。

目前我把接口分成這幾類

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

后續會有更多類似友情鏈接這樣比較復雜的功能加入(比如評論),這種會單獨做成一個分類。

PS:之前在開發博客前臺的時候,把大部分功能都寫在了 services里面,現在開發接口的時候就派上用場了,很多邏輯都是通用的,在接口的controller里面只需要調用這些 services就可以了。

4需要關注的其他東西

本文不涉及具體實現,只是作為RESTFul接口開發部分的前言或者大綱,接口開發看似就crud四個操作很簡單,實際上比想象的復雜。

例如,獲取文章列表接口,博客的文章數量會很多,不可能一個接口返回所有文章信息,因此要做分頁處理,同時我們還希望能在文章列表實現關鍵詞過濾、分類、狀態篩選、排序等功能;

已登錄用戶才能發表評論,管理員才能管理文章,因此需要實現認證授權、角色管理等功能;

同一時間可能有很多人訪問博客(或者是爬蟲),需要對接口做限流處理,以免程序崩潰;

接口數量多起來了,swagger顯示太雜亂,需要對接口分組,或者更換swagger前端;

正式環境不想讓用戶看到swagger接口文檔,可以隱藏或者給swagger加鎖;

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

耗時操作(如批量導出文章、發送短信通知)放到異步任務隊列(或者后臺任務)里執行;

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

OK,本文就到這吧。

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

關鍵詞: 請求參數 配置管理 錯誤狀態

相關閱讀

欧美视频线路在线_欧美中文字幕在线中出观看_中年美女露比自慰交配a一级片免费播放_九九精品国中文字幕在线视频