工程思維落地

《你不知道的 JAVA 》系列博客的工程理念與設計模式，已落地成一款 全新設計的 Java 腳手架 ，可與博客配套使用。

Web Api 的重要性

設計 api 端點是後端開發經常接觸的工作，但你是否從來沒有想過好的 web api 應該是什麼樣子？

Api 端點的設計就像名片一樣——專業的名片可以在客户面前建立信任感；糟糕的名片會讓你的產品在被使用前就給客户留下負面印象。一旦客户產生負面情緒，這種情緒可能就會蔓延到產品及其相關公司上。

今天就和大家分享一些 api 設計的套路與規範，讓你也能設計出優雅、健壯、擴展性強的應用程序接口。

設計原則，如果有的話

先讓我們回顧曾經提到過的關於設計模式的內容：設計模式的精髓在於設計原則，而非模式的生搬硬套。與此類似，優雅的 Web Api 有兩個重要原則如下所示：

• 設計規範明確的內容必須遵守相關規範
• 沒有設計規範的內容必須遵守相關事實標準

也許你依然對如何設計 web api 毫無頭緒，但是彆着急，好的創作總是從模仿開始的。

下面是一些國際大廠的 api 示例，給自己一些時間消化消化。

如何設計出國際範兒的 Api

背口訣

觀察和分析上一小節中的國際大廠的設計往往都具備以下幾個特點：

• 短小便於輸入的 URI。

  沒人喜歡複雜的單詞。

• 人可以讀懂的 URI。

  名片是拿給人讀的。不要把機器碼和 16 進制寫到 URI 裏。

• 沒有大小寫混用的 URI。

  實際上一般的事實規範是建議全部小寫。

• 修改方便的 URI。

  api.sample.com/user/:id

• 不會暴露服務端架構的 URI。

  api.sample.com/servlet/login.do

• 規則統一的 URI。

  api.com.cn/Api/user-InfoById/info.json

• 當端點裏出現兩個以上的單詞時，使用脊柱法（連詞符號）。

  api.linkedin.com/v1/people-search

合理利用 REST API

REST API 的概念首先出現在 Roy Fielding 的論文中。

• 狹義上的 REST API 實際上就是指符合 Fielding 的 REST 架構風格的 Web 服務系統。REST API 的設計風格嚴謹，考慮周全，結構優美。但過於苛刻的標準一直是狹義 REST API 推廣壯大的絆腳石。
• 廣義上的 REST API 指符合 RPC 風格的 JSON + Http 的接口的系統。這樣的 REST API 定義卻又過於粗獷和隨意了。

於是，針對 WEB API 的發展以及廣義 REST 與 狹義 REST 的特點， Martin Fowler 提出在達到完美的 REST API 之前有以下幾種 API 的設計級別。

• REST LEVEL0: 使用 HTTP
• REST LEVEL1: 引入資源的概念
• REST LEVEL2: 引入 HTTP 動詞
• REST LEVEL3: 引入 HATEOAS 概念

按照 HTTP 協議中，URI 代表資源，而 HTTP method 代表對資源的操作。
我以此理論作為基礎，再參照上述 REST LEVEL，設計了一個符合 REST LEVEL2 標準的示例 URI ，如下所示

從今以後，你的 WEB API 只要參照以上示例，那就是符合基本標準看起來還不錯的設計。

寫在最後

• 我是 Chuck1sn，一個長期致力於現代 Jvm 生態推廣的開發者。
• 您的回帖、點贊、收藏、就是我持續更新的動力。
• 舉手之勞的一鍵三連，對我來説是莫大的支持，非常感謝！
• 關注我的賬號，第一時間收到文章推送。

blog