如何設計出優美的Web API？-有解無憂

熱文索引，堅持原創不易，請小伙伴們不吝「推薦」支持：

1. 程式員必須掌握的性能調優 X Y Z

2. 程式員必須懂的架構入門課 1 2 3

3. 如何把單體式應用拆解成微服務？【上】

4. 如何把單體式應用拆解成微服務？【下】

5. 如何寫好產品幫助檔案？

概述

WEB API的應用場景非常豐富，例如：將已有系統的功能或資料開放給合作伙伴或生態圈；對外發布可嵌入到其他網頁的微件；構建前后端分離的WEB應用；開發跨不同終端的移動應用；集成公司內部不同系統等等，在上述場景里，你可能是WEB API的使用者，也可能是設計者，但你知道如何評判WEB API的優劣嗎？

評判標準

我們可以從三個維度來評判一個WEB API的優劣：

易于使用：WEB API的用戶是程式還是人？我覺得首先是人，然后是程式，為什么這么說呢？是否采用某個WEB API的決定是人做出的，一個好的WEB API必須符合人的審美，例如：簡短易記、通俗易懂、便于輸入等，從程式角度看，WEB API應該遵循行業規范，在呼叫時不需要做特殊化處理，有利于復用已有的代碼或工具，
便于更改：一個WEB API發布上線之后，免不了要根據真實用戶的反饋或者業務發展的需要做更新修改，這些更新修改必須盡量不影響用戶，要么提供多版本支持，要么給用戶提供切實可行的更新策略等等，
健壯穩定：對外公開的WEB API存在被攻擊的風險，以及無法準確預估的訪問量等，一個好的WEB API必須要有防注入、防篡改、防重放等安全機制，還要在訪問量急劇上漲時避免服務被擊穿，

做到了上述三個方面，我們才有底氣將一個WEB API對外開放，接受公眾的檢驗，好的WEB API不僅方便使用，還助于提升個人或企業的技術影響力，從而形成正向回圈，帶來越來越多的業務價值，為了設計出優美的WEB API，我們需要了解與之相關的設計規范和事實標準，并且在設計開發程序中盡量遵循它們，

設計規范

URI

便于輸入的URI，簡短不冗余，每個WEB API都是一個服務，那下面反例當中的“service”就是冗余的，而且“api”也重復出現了兩次，這種冗余都不利于記憶和輸入：

反例：http://api.example.com/service/api/users
正例：http://api.example.com/users

容易讀懂的URI，不要隨意采用縮寫，縮寫必須要符合國際標準規范，不要憑空發明創造，例如：國家代碼定義（ISO3166），反例中出現了兩處縮寫“sv”、“u”，在沒有附加說明的情況下，用戶壓根不知道含義：

反例：http://api.example.com/sv/u

沒有大小寫混用的URI，HTTP協議（RFC7230）規定：除了模式（schema）和主機名以外，URI的其他資訊都要區分字母的大小寫，下述兩個反例大小寫混用，不方便記憶，

反例：http://api.example.com/Users/12345
反例：http://example.com/API/getUserName

易于修改的URI，命名存在可預見的規律，下述正例我們可以很容易猜測改變最后的ID就可以訪問其他商品的資訊，

正例：http://api.example.com/v1/items/123456

不會暴露服務端架構的URI，URI只需要體現功能、資料結構和含義，無需暴露服務端如何運作的資訊，這些資訊對用戶來說沒有意義，還存在潛在的風險，惡意用戶或者黑客會利用這些資訊來尋找漏洞，發起對服務的攻擊，

反例：http://api.example.com/cgi-bin/get_user.php?user=100

規則統一的URI，確保采用統一的規則和風格，方便用戶記憶和使用，下述反例中第一個URI采用了查詢引數，第二個URI采用了路徑引數，這兩者沒有保持一致，容易造成混亂，

反例：獲取好友資訊，http://api.example.com/friends?id=100
反例：發送訊息，http://api.example.com/friend/100/messages
正例：獲取好友資訊，http://api.example.com/friends/100
正例：發送訊息，http://api.example.com/friends/100/messages

URI最好由名詞組成，URI的全稱是統一資源定位符（Uniform Resource Identifier），用于標識資源在互聯網上的位置，類似于郵寄地址，而地址都是由名詞組成的，在名詞使用上也有一些需要注意的事項：其一，使用名詞復數形式；其二，盡量采用多數API中使用的表示相同含義的單詞；其三，通過盡可能少的單詞來表示；其四，盡可能不用奇怪的縮略語等，
不使用空格及需要編碼的字符，例如在URI中使用中文等，
使用連接符（-）來連接多個單詞，推薦脊柱法：首先，URI里的主機名（域名）允許使用連字符而禁止使用下劃線，且不區分大小寫，其次，點字符具有特殊含義，為了與主機名的規則保持一致，

脊柱法：http://api.example.com/v1/users/12345/profile-image
蛇形法：http://api.example.com/v1/users/12345/profile_image
駝峰法：http://api.example.com/v1/users/12345/profileImage

查詢引數

許多場景下需要通過API分批次獲取資料，我們會經常糾結采用什么樣的查詢引數，業界有兩種常用的引數設計（per-page與page、limit與offset），用于標識每次獲取的資料量和起始位置，在分批次獲取資料的程序中，資料集合中的記錄可能發生增刪改變，我們需要注意采用相對位置或絕對位置所帶來的不同效果，

風格1：http://api.example.com/friends?per-page=50&page=3
風格2：http://api.example.com/friends?limit=50&offset=100

在設計過濾的引數時，業界也有一些事實標準可供參考，如果我們期望查詢結果的特定屬性取值跟過濾引數的取值完全相同，那過濾引數的名稱通常為屬性名；如果我們期望查詢結果任意屬性部分包含過濾引數的取值，那過濾引數的名稱通常為“q”，

完全符合：http://api.example.com/v1/users?name=ken
全文搜索：http://api.example.com/v1/users?q=ken

URI是否可以包含動詞“search”？通常以搜索為主的在線服務API可以包含，除此之外建議采用名詞復數形式，常用英文單詞“search”和“find”都有查找的含義，但兩者還是有一些細微的差別，其中“search”用于模糊搜索，而“find”用于精準查詢，

模糊搜索：http://yboss.yahooapis.com/ysearch/web?q=ipod

某個屬性究竟是作為URI路徑的構成元素還是作為查詢引數呢？我們可以按照以下規則來判斷：如果該屬性資訊可以唯一定位資源，那么它就適合作為路徑構成元素，否則就作為查詢引數；如果該屬性可以省略，那么它就是適合作為查詢引數，

路徑元素：http://api.example.com/v1/users/{id}
查詢引數：http://api.example.com/v1/users?name=ken

HTTP方法

按照HTTP協議設計的本意，URI用于標識被操作的目標物件（資源），而HTTP方法則是表示操作方法，基于HTTP協議的簡單物件訪問協議SOAP逐漸被RESTful的原生HTTP協議取代，我們也沒有必要畫蛇添足，最好就是吃透HTTP協議，充分利用它的特性，

GET /v1/users/123 HTTP/1.1
Host: api.example.com

GET，獲取資源
POST，新增資源
PUT，更新已有資源
DELETE，洗掉資源
PATCH，更新部分資源
HEAD，獲取資源的元資訊

如果遇到上述HTTP方法無法覆寫的場景，那通常是資源的設計粒度太大了，我們可以把粗粒度的資源分解成多個細粒度的資源，在使用HTTP協議設計WEB API的專業能力上，業界將其劃分為四個層級，LEVEL3相對較理想化，缺乏實施的基礎，LEVEL2是切實可行的：

LEVEL 0：使用HTTP
LEVEL 1：引入資源的概念
LEVEL 2：引入HTTP動詞（GET/POST/PUT/DELETE等）
LEVEL 3：引入HATEOAS概念

回應資料

常用的資料格式有：HTML、XML、JSON、YAML等，如果我們的服務在回應時支持不同型別的資料格式，那應用在呼叫服務時如何獲得期望格式的回應資料呢？通常我們可以考慮采用下述幾種指定資料格式的方法：

使用查詢引數的方法：

示例：https://api.example.com/v1/users?format=xml

使用擴展名的方法：

示例：https://api.example.com/v1/users.json

使用在請求首部指定媒體型別的方法，優先推薦此種方法：

GET /v1/users
Host: api.example.com
Accept: application/json

回應資料應該包含哪些資訊呢？是否越多越好？亦或越少越好，僅僅包含ID？建議是按需回傳，根據業務功能所需回傳相應的資料，如果一個WEB API需要提供給不同業務場景使用，不同業務場景對資料屬性資訊的要求不同，或多或少，這種情況我們可以讓用戶來選擇回應的內容，選擇方法就是通過查詢引數指定：

示例：http://api.example.com/v1/users/123?fields=name,age

回應資料的結構應該盡量扁平化，不要嵌套太深，減少沒有具體含義的資訊載荷，這樣既可以壓縮報文尺寸，又可以節省帶寬的，當然，如果層級結構更具優勢，也可以采用，

出錯資訊

建議通過HTTP協議首部的狀態碼來表示出錯資訊，而不是再封裝一層，遵守協議規范的好處是可以減少溝通的成本，也可以利用許多成熟的軟硬體產品來處理例外出錯資訊，HTTP協議定了了五種型別的狀態碼：

1XX：訊息
2XX：成功
3XX：重定向
4XX：客戶端原因引起的錯誤
5XX：服務器端原因引起的錯誤

我們需要每種狀態碼的使用場景，確保正確使用狀態碼，除此之外，服務還需要向客戶端回傳詳細的出錯資訊，我們通常可以采用下述兩種方法來傳遞詳細的出錯資訊：

方法1：定義私有的首部，將其填入回應訊息的首部，
方法2：將詳細的出錯資訊放入訊息體，

版本管理

隨著業務的發展，每個發布上線的WEB API都存在更新修改的可能，那就需要引入版本管理的機制，業界有三種常見的標注WEB API版本的方法：

在URI中嵌入版本編號：

示例：http://api.linkedin.com/v1/people

在查詢字串里加入版本資訊：

示例：http://api.example.com/users/123?v=2

通過媒體型別來指定版本資訊

Accept: application/vnd.github.v3+json
Content-Type: application/vnd.github.v3+json

同樣，版本編號也存在業界規范：語意化版本控制（Semantic Versioning）規范，網站地址：semver.org，版本編號由點號連接的3個數字組成，例如：1.2.3，分別表示主版本編號、次版本編號、補丁版本編號，版本編號的增加遵循下述規則：

在對軟體進行不向下兼容的變更時，增加主版本編號；
在對軟體進行向下兼容的變更或廢除某些特定的功能時，增加次版本編號；
如果軟體的API沒有發生變更，只是修正了部分bug，則增加補丁版本編號，

按照版本編號增長的規則，WEB API的版本編號只需要標注主版本編號就可以了，因為次版本編號、補丁版本編號的增加都可以做到向下兼容，不會影響用戶使用，唯有主版本編號增加才需要用戶更新升級，除了標注版本資訊之外，我們在對外發布WEB API時還需要設計好版本變更的策略，例如：老版本提供多久的過渡期、同時兼容多少個版本、特定版本的終止日期等等，

總結

何為優美？就是符合大眾審美的，對于WEB API來說，就是符合標準規范的，這有利于降低用戶學習和使用的成本，便于交流，不存在隱沒成本，通常，業界存在的標準規范和事實標準都是經過實踐篩選出來的，從遵循模仿開始，然后再找機會創新，而不是一上來就重復發明輪子，

WEB API設計領域的標準規范就是URI、HTTP等，我們要最大程度地利用這些協議規范，讓每個WEB API都是用戶友好（易于使用）、技術友好（支持快取、易于更改）的，除此之外，我們還需要考慮WEB API的健壯性，下一次我們再來談一談如何設計健壯的WEB API，歡迎大家找我討論交流相關話題，今天先分享到這里，如果你覺得有價值，麻煩動動手指點下文「推薦」按鈕，讓更多小伙伴可以看到，我也會更加有動力堅持分享，另外，老兵哥我后續還會分享職業規劃、應聘面試、技能提升、影響力打造等經驗，歡迎關注本專欄或歪信公主號「 IT老兵哥」，

關注「 IT老兵哥 」，賦能程式人生！

軟技能-熱門文章：（首發于公眾號）

“花式”裁員套路深，你知道嗎？
遭遇裁員，如何渡過心理危機？
如何在寒冬中找到好作業？
2C 還是 2B，跟找作業有什么關系？
大公司 vs 小公司，你會選哪個？
記住這一點，不怕找不到好作業！
跳槽，跳還是不跳，該怎么跳？
程式員“求包養”攻略揭秘
很努力了，為什么我還在原地踏步？
從程式員到架構師，有捷徑嗎？

硬技能-熱門文章：

圖解 Spring：HTTP 請求的處理流程與機制【1】
圖解 Spring：HTTP 請求的處理流程與機制【2】
圖解 Spring：HTTP 請求的處理流程與機制【3】
圖解 Spring：HTTP 請求的處理流程與機制【4】
圖解 Spring：HTTP 請求的處理流程與機制【5】
如何正確使用 Spring Cloud？【上】
如何正確使用 Spring Cloud？【中】
如何正確使用 Spring Cloud？【下】
Spring 核心技術與產品理念剖析【上】
Spring 核心技術與產品理念剖析【下】

轉載請註明出處，本文鏈接：https://www.uj5u.com/ruanti/29235.html

標籤：架構設計

上一篇：Jenkins多環境持續集成架構實踐

下一篇：NServiceBus 入門到精通（一）