RESTful API實踐總結

TandK發表於2021-06-28

REST架構

你是如何理解上網這件事的?

開啟瀏覽器,輸入網址,展現在你面前的就是一個網站了。

你可以在網站裡看視訊、看部落格、寫文章、聽音樂。

但凡寫過點程式碼的人都知道,我們平時訪問的網站,其實是HTML,它不過是一個文字,只是通過渲染,在你面前變成了多姿多彩的網站。

上網這件事,其實就是把在伺服器上的文字、視訊、音訊等資源,轉化一下形式,呈現在你面前而已。

我們訪問的每一個網址,都對應伺服器上的一個具體資源,比如你現在看到的這篇文章,不過就是一個HTML文字而已。

這就是REST架構(Representational State Transfer),阮一峰老師翻譯叫【表現層狀態轉化】。

我們看到的網頁實際上是一個文字,狀態轉化一下,呈現在你面前的就是一個好看的網頁了。

你點選網頁上的一個按鈕,網頁勢必有所變化,或者是開啟一個新連結,或者是請求一些新的資料。

這個互動的過程,其實就是你在對伺服器上的資源進行操作。

本質就好像你對自己電腦上的檔案操作一樣。

不信你開啟檔案資源管理器,輸入網址,一樣的能訪問百度。

瀏覽器,實質上也是個檔案資源管理器,只不過我們通常用來訪問遠端的資源,不然你複製一個資料夾的路徑在瀏覽器開啟試試。

你會發現瀏覽器其實也可以當檔案資源管理器來用。

你在本地寫了一個靜態HTML,預覽的時候,看到瀏覽器的連結也是這個HTML檔案在你硬碟上的路徑。

對RESTful API的應用

檔案資源管理器上,一個檔案路徑代表一個檔案,那麼瀏覽器上,一個連結也代表一個資原始檔。

你會在你的電腦上用動詞去命名一個檔案或者資料夾嗎?

因此,如果遵循RESTful API,我們編寫url的時候,應該都是名詞,而不包含動詞。

比如我們在編寫【新增一個使用者資訊】的介面的時候,寫出來的url很容易是localhost:8080/user/addUser

但其實寫出來的應該是localhost:8008/users

這也是很多人的設計誤區。

這樣一來有人就會問了,那我增刪改查,要怎麼區分這些操作呢?

這些動作,可以用POST、DELETE、PUT、GET來標識。

我們就是通過這四個動作,來實現對伺服器上的資源進行操作的。

同樣是對使用者資訊進行操作,我們編寫出來的介面可以是這樣的:

# 獲取使用者列表
GET localhost:8008/users

# 獲取單個使用者
GET localhost:8008/users/userid

# 新增使用者
POST localhost:8008/users

# 刪除指定使用者
DELETE localhost:8008/users/userid

# 更新使用者資訊
PUT localhost:8008/users/userid

不用怕連結衝突,你換了個動作,就是個新的操作。

看了上面的連結,其實也可以明白,GET代表查詢,POST代表新增,DELETE代表刪除,PUT則代表更新。

在RESTful架構中,每個網址代表一種資源,所有網址中不能有動詞,只能有名詞,而且所用的名詞往往與資料庫的表格名對應。一般來說,資料庫中的表都是同種記錄的"集合",所以API中的名詞也應該使用複數

這樣一來,我們對於編寫連結,就有了個比較好的規範。

說到這裡,可能說了一堆廢話,畢竟有人覺得,localhost:8080/user/addUser這種寫法並不影響使用,並且對很多人來說簡單明瞭,為什麼還要遵循這種看起來沒什麼用的API呢?

《Don't make me think》是一本講網站設計的書,這是一本很好的書。

裡面是這麼看待約束和設計的(當時覺得挺好的就摘抄下來了,不過因為時間久了,我也忘記這段話是原文摘抄還是自己編輯過了):

有一種方式看待設計——任何類別的設計,那就是,它的本質就是處理各種約束(那些你必須遵從和不能去做的事)和妥協(那些為了服從約束而做出的不夠理想的選擇)。

用林肯的話說,你能做到的最好的方式就是在某些時候取悅某些人。

(注:他確實說過這樣的話:“你可以在所有時間欺騙一些人,或者在某些時間欺騙所有人,但你不可能在所有時間欺騙所有人。”我從網際網路上學到的一件事是,如果看到某些名人名言,有92%的概率他們從沒說過這些話。)

有一種成熟的主張認為,約束,與其說他們是一種負面因素,還不如說它們實際上會讓設計變得更加容易,也會催生出新的創意。

的確,約束常常會幫助我們。如果需要適合放在給定的空間裡,同時還需要符合給定的配色方案,實際上往往會讓我們更容易找到一張這樣的沙發,而不是漫無目的地尋找某張沙發。確定了某些約束會有種讓注意力聚焦的效果,而一張有無限可能的空白畫布——雖然它聽起來是種解放——但可能會帶來想法癱瘓。

RESTful API是個很好的設計原則,它約束我們只能用名詞去命名url,動作只能用GET、PUT來實現,這看起來是沒什麼作用的規矩,但最起碼,在我url多到不知道下一個url怎麼寫的時候,遵循這個原則,能讓我更好更快地想到下一個url怎麼寫。

再進一步,寫的url越來越多,就感覺對【上網其實是在操作伺服器上的檔案資源】這個本質認知更深。

一個好的設計,應該是能讓我們在遵循這個設計原則的時候,不僅能提高效率,而且能讓我們對事物有更好的認知。

相關文章