博主剛剛接觸web開發的時候，寫了一個介面 /get_article_info/1 獲取id為1的這篇文章的內容，被前輩們看見了，前輩給我說我這個介面設計的不太好啊，不符合RESTFUL規範，當前輩們說出這些話的時候，我很迷惑，我寫的介面不能夠好好工作嗎？能夠正常返回內容啊，對於不存在的文章也能夠在 ...
博主剛剛接觸web開發的時候，寫了一個介面 /get_article_info/1 獲取id為1的這篇文章的內容，被前輩們看見了，前輩給我說我這個介面設計的不太好啊，不符合RESTFUL規範，當前輩們說出這些話的時候，我很迷惑，我寫的介面不能夠好好工作嗎？能夠正常返回內容啊，對於不存在的文章也能夠在返回的內容體中提示不存在，而且介面的意思很明確，一看就能明白，這還有什麼不好的地方嗎？
一、RESTFUL是什麼？
RESTFUL是英文單詞Representational State Transfer的縮寫，翻譯成中文就是表現層狀態轉化，什麼是表現層？什麼是狀態？什麼是轉化？
表現層可以理解為一種資源，可以是一篇文章，一張圖片，一個訂單...... 所有網路上的一個實體，都可以說是一個資源，而URL就是這個唯一資源的定位符，狀態和轉化應該連在一起理解，這是一個動作，即狀態變化，可以是新建，刪除，更新，獲取，比如新建一篇文章，刪除一篇文章，更新文章內容，獲取文章內容。HTTP協議應當如何表示這種變化？HTTP協議中有四個操作方法，可以用來表示，GET表示獲取，POST表示新建，DELETE表示刪除，PUT表示更新。
綜上，RESTFUL可以通俗的理解通過HTTP協議的動詞和URL對一個資源進行各種操作，實現表現層狀態轉化。
二、 RESTFUL如何指導我們設計API？
核心思想就是HTTP動詞 + URL資源，比如獲取文章信息 GET /articles, GET是動詞，/articles 是名詞
1. 動詞通常是HTTP的方法
GET： 獲取信息
POST： 新建信息
DELETE： 刪除信息
PUT： 更新信息
2. 資源必須是名詞
已經有了HTTP的方法的動詞，URL中，我們就沒有必要使用動詞了
POST /create_articles POST /delete_articles POST /update_articles
上面都是不好的用法，我們應當使用下麵這種用法
POST /articles DELETE /articles/2 PUT /articles/2
3. 資源最好使用名詞的複數，任何情況下都能夠適用
/airticles/1 獲取id為1的文章內容 /airticles 獲取所有文章內容
# 使用單數 /article 獲取一篇文章內容？還是所有的文章內容？
4. 避免多級URL
/authors/5/airticles 獲取作者id為5的所有文章
上面換成這種形式更好，也利於擴展 /airticles?author_id=5
5. 利用querystring來過濾和篩選
一般情況下一個url很難滿足複雜多變的情況，比如分頁，過濾，這時候我們應當如何設計？
/airticles/published 這種形式？
不不不，published不是一個資源，而且這種url不宜於擴展
最佳實踐應當是下麵這種形式
/articles?page=1 獲取第一頁的文章 /articles?published=true 獲取已經發佈的文章
6. 返回有意義的狀態碼
HTTP有很多狀態碼，表示不同的意義，我們應當充分利用這些狀態碼
尤其是出現錯誤時，不要返回200，意義很不明確
一般成功請求後返回的狀態碼
GET：200 OK POST：201 Created PUT：200 OK DELETE：204 No Content
其他狀態碼信息
1xx：相關信息
2xx：請求成功
3xx：重定向
4xx：客戶端錯誤
5xx：伺服器端錯誤
2xx狀態碼表示成功
200 OK 請求成功
201 Created 請求成功，並創建了資源
202 Accepted 請求接受，但未處理完成，一般用於非同步處理
204 No Content 請求處理成功，但未返回內容，一般用於DELETE請求成功
3xx狀態碼表示重定向
301 Moved Permanently 永久重定向
302 Found 暫時重定向
4xx狀態碼表示客戶端錯誤
400 Bad Request 錯誤請求，伺服器不理解請求，沒做任何處理
401 Unauthorized 未認證
403 Forbidden 用戶通過了認證，但是沒有許可權
404 Not Found 沒有發現請求的內容
405 Method Not Allowed 不允許的請求方法
5xx狀態碼表示服務端錯誤
500 Internal Server Error 伺服器內部錯誤，無法完成請求
503 Service Unavailable 服務不可用
三、總結
RESTFUL就是一種規範，我們不遵循這種規範也能夠寫出可用的代碼，但是遵循這種規範卻能給我們帶來更多的好處，API設計更加可讀，與其他人交流也能夠很方便。現在讓我看看我剛剛接觸web介面開發時的設計，真的是不太好啊，URL信息太重覆，錯誤的返回狀態不明確，全是200。
參考文章：https://blog.florimond.dev/restful-api-design-13-best-practices-to-make-your-users-happy
rear
