這樣設計 RESTful API，也許能讓你效率倍增

在目前移動端、前端趨於統一的大背景下，基於 RESTFul 的 API 也大放異彩，咱們須要愈來愈多的與 API 打交到，設計可擴展，易於維護的 API 在咱們的工做中也變得更加劇要。那麼，有沒有可能，經過必定測策略與指導方法，讓 API 的設計更規範，更有章可循，高效率的設計出好用的 API 呢？本文嘗試總結筆者在這方面的思考，但願對讀者有所啓發。

在開始以前，咱們先作一個定義，那就是什麼樣的 API 可以算得上優秀的 API，以下是筆者認爲優秀 API 須要知足的四個要素：

1. 遵循業界最佳實踐

2. 高度的統一性和一致性，優秀的 API 必定是高度一致和統一的，遵循必定的共性和約定

3. 基於深入理解業務的合理抽象

4. 探索業務共性，總結規範

這四個要素層層遞進，亦能夠做爲咱們進行 API 設計的指導方法，下面詳細介紹筆者對這四個要素的理解，必要的時候提供案例進行說明。

遵循業界最佳實踐

遵循業界最佳實踐我以爲是優秀 API 應具有最基本的一個要素，它能讓相關人員最快的理解，創建統一的基礎認知，若是咱們的 API 對外的，這就顯得更加劇要。

就本文而言，筆者所說的業內最佳實踐指的是基於 HTTP 的 RESTful API。它用 URI 表示資源，用 HTTP Verb 表示操做，要設計好 RESTFul API，很大程度上須要處理好對資源的抽象。

至於 RESTFul API 更具體是個什麼東西，有哪些原則，本文不作更多探討，互聯網上相關的資料不少。

高度的統一性和一致性

若是說遵循業界最佳實踐是基礎，那麼保持 API 的統一性和一致性就是設計合格 API 的保障。若是咱們的 API 不統1、不一致，缺乏必要約定，使用者必然會感到困惑，學習成本與維護成本必然大大增長。

下面是保證 API 高度統一和一致性須要考慮的一個列表，也許並不完整：

1. 受權與鑑權方式的統一

2. 每一個 API 分頁方式與對應參數的統一

3. 排序參數與對應行爲的統一一致

4. 查詢條件的寫法經事先約定且保持一致

5. 考慮存在於全局的參數，造成基礎認知

6. 等等等

深度理解業務的高度抽象

若是咱們的 API 知足了前面兩個要素，那它應該基本算是合格了，可以知足平常業務的須要，但對於優秀的 API，這纔剛剛開始。

許多人在設計 API 的時候，沒有大局觀，僅僅爲界面而設計，只有前臺界面一變化，API 可能又須要從新設計，從而致使 API 擴展性差，頻繁修改。

因此，咱們在設計 API 的時候，就須要站在更高的維度，在深刻理解業務的前提下，抽象出更高層次的 API。這樣的 API 通常是界面無關的，即使界面變化，只要不是業務的調整，影響也不會很大。

優秀的 API 就像優秀的產品，不在於提供了多少 API （功能），而在於解決了多少問題。一個優秀的 API 能直接解決多個通常 API 才能解決的問題。

下面舉一個例子：

假如，咱們有這樣一個需求，在一個博客系統中，咱們須要獲取全站訪問最多和訪問最少的文章，各n篇文章，應該怎樣設計 API 呢？

有下面兩個版本：

版本一:

提供兩個API，以下：

GET /posts/most-viewed?limit=10 - 獲取訪問最多的文章
GET /posts/least-viewed?limit=10 - 獲取訪問最少的文章

版本二：

提供一個API，使用sort參數排序，間接實現需求

GET /posts?sort=total_views desc&limit=10 - 獲取訪問最多的文章
GET /posts?sort=total_views asc&limit=10 - 獲取訪問最少的文章

筆者認爲，版本二會更好一些，直接使用已有 API 加排序完成需求，擴展性和抽象層次都更高。

探索業務共性，總結規範

每一個業務均可能有它的共性，若是把這些共性提煉出來，造成規範，就會極大的提升 API 的設計及開發效率，API 的使用也會所以受益，由於總體 API 的理解會容易許多。

就好比筆者目前所在的公司，面臨許多 toB 業務，有許許多多的聚合統計需求，若是把每一個統計需求都寫成單獨的API，那 API 的數量恐怕浩如煙海，也很難維護。

因此，咱們就在思考，如何把這些共性的統計需求就行抽象，總結成規範，變成 API 設計規範的一部分，從而指導 API 設計。

好比說，咱們有以下的業務需求：

用戶的狀態（status）有 active, disabled 和 achieved 三種，須要統計知足條件用戶三個狀態各自的數量。

在咱們目前API設計規範下，咱們會用以下的方式解決這個需求，而非提供新的 API：

GET /users?kw=foo&$aggregate=status 按 status 就行聚合統計，kw是查詢參數

這裏咱們引入了 $aggregate 的聚合方法，在不添加新 API 的狀況下解決該需求，該方式也變成解決該類問題規範。

設計優秀 API 的四個要素介紹完了，但願對你有所幫助，之後筆者會再分享 API 規範的設計思路~

---

本文首發於「代碼寫詩」微信公衆號及同名知乎專欄

微信公衆號: http://mp.weixin.qq.com/s?__b...
知乎專欄: https://zhuanlan.zhihu.com/p/...

掃描二維碼關注「代碼寫詩」公衆號