1
雷鋒網按：本文作者朱赟，Airbnb 資深程序媛。由授權雷鋒網發布。
經歷過一個小公司成長為大公司，可能你也遇到過這樣的情形：當你看到一行代碼，覺得不是那么值得推敲。于是你用 git blame 尋找它的主人，赫然發現，居然原作者是那位如今早已不寫 code 的 CTO 或者 VP 或者 Director 了。
然后一個偶然的機會，你跟他聊天提到這件事，他會很自豪地給你講個故事：“哦，那時候，我們必須一天做出這個產品特性。當時也就我一個程序員吧，可能 Tom 也在。一天的時間，這是當時能做出最好的方案了。” 說完，他便陷入了對美好時光的遐思……
你可能也聽說過類似這樣的故事：有一天，你的 CTO 突發奇想，覺得自己其實還可以寫一些代碼。于是華麗麗提交了一段代碼。大家一看，很激動啊，于是很多人咔咔咔開始在 PR 上給 comments。你的 CTO 一看：靠，幾十條comments……現在這個代碼要這么寫啊？這么麻煩啊？于是跟一個工程師說，“你把 comments address 下，然后 merge 吧。” 然后就開開心心地自己該干啥干啥去了。
哦，有點離題了。
其實這兩個故事，想說的是：一個公司早期的代碼因為各種歷史原因，可能不是那么完美，但是在特定的時候，那就是最好的方案。隨著時間的消逝，功能不斷疊加，代碼架構不斷優化。系統可能會經歷一些變復雜、再簡化的迭代過程。然后某一天，代碼會面目全非，最初的主人也已經不認識自己當初的作品了。
API 的設計和實現尤為如此。一套成熟的 API，很多時候都是不斷演化迭代出來的，很少有 API 的設計和實現從最開始就是完美無瑕疵的，說說自己做 API 的一些體會吧。
先從 API 的 signiture 說起吧。也就是 API request 和 response 支持哪些格式、哪些參數。
首先，做過 API 的人都知道，一個上線使用的 API 再想改它的 signiture，通常由于 compatibility 的原因，后期再想改，都是格外痛苦不堪的。因此，API signiture 設計初期，一定要反復推敲再推敲，盡量避免上線后的改動。
而除了一些基本的 RESTful 原則外，Signiture 的定義很多時候是對業務邏輯的抽象過程。一個系統的業務邏輯可能錯綜復雜，因此 API 設計的時候就應該做到用最簡潔直觀的格式去支持所有的需求。這其實往往是 API 設計中相對立的兩面。有時候我們為了支持某一個功能，似乎不得不增加一個很違反設計的接口；而有時候我們為了保證 API 絕對規范，似乎又不得不放棄對某一些功能的直接支持，因此功能只能通過迭代調用或 client 端預處理來實現。
而這種設計上的取舍，通常只有列出所有可行的方案，從簡單的設計到繁雜的設計，然后通過分析各種使用實例的頻率和使用某種設計時的復雜度，從實際的系統需求入手，盡可能讓常用的功能得到最簡單直接的支持，而一定程度上 “犧牲” 一些極少用到的功能。反復推敲系統場景，盡可能取得一個合理的折衷。
在這個取折衷的過程中，始終保證下面的一些基本原則被滿足，例如：
保證 API 100% RESTful。RESTful 的核心是 everything is a “resource”，所有的 action 和接口，都應該是相應 resource 上的 CRUD 操作。如果脫離這種設計模式，一定要再三考慮是不是必要？有沒有其他方案可以避免。
在 request 和 response 中，都應該盡可能的保持參數的結構化。如果是一個 hash，就傳一個 hash（不要傳 hash.to_string）。API 的 serialization / deserialization 會將其自動序列化成字符串。多語言之間的 API，比如 Ruby，Java，C# 之間的調用，通常都是在 serialization / deserialization 中完成不同語言間類型的轉換。
Authentication 和 Security 的考慮，應該始終放在首位。保證對特定的用戶永遠只 expose 相關的接口和權限。Authentication 可能是使用證書和白名單，也可能是通過用戶登陸的 credentials 生成的驗證 token，或者 session / cookie 等方式來處理。此外，所有的 API 層的 logging，應該保證不要 log 任何 sensitive 的信息。
API 本身應該是 client 無關的。也就是說，一個 API 對 request 的處理盡可能避免對 client 是 mobile 還是 web 等的考慮。Client 相關的 response 格式，不應該在 API 中實現。而所有的 client 無關的計算和處理，又應該盡可能的在 server 端統一處理。以提高性能和一致性。
盡可能讓 API 是 Idempotent（冪等）的。這有好幾個不同層次的含義。舉幾個例子：同一個 request 發一遍和發兩遍是不是能夠保證相同結果？Request 失敗后重發和第一次發是不是能保證相同結果？當然具體的做法還是要看應用場景。
另外，每個語言都已經提供了很好的 API 框架。設計前先多了解這些框架。
為什么說多了解呢？如果你是一個小團隊，可能多方比較后，選一個合適的框架入手，適當調整，比從零開始造輪子要好。但實際中，很多公司由于各自業務邏輯的特殊需求，最終都會有一套自己的定制方案。
而評估一個框架，可以從以下幾個方面考慮：
對訪問權限的統一控制
自動測試的支持
對 request 和 response 的 formatting，以及 serialization 和 deseialization 的支持
對 logging 和 logging filtering 的支持
對自動文檔生成的支持
實際實現的架構以及性能的考慮
最后，如何處理設計中的一些對立面。
除了上文中提到的，接口簡潔和功能繁復之間偶爾存在的對立，API 設計和實現中還有很多別的對立和取舍。
1、自由總是相對的。
就好像在一個群體里，如果沒有規則，完全行為自由，就會出現各種問題。小群體還好，而對于一個大群體，就會有人被別人自由的誤傷。
寫軟件也是一樣。一個小 startup 里，API 怎么設計，代碼怎么寫，幾個人一協商，達成共識，并不需要那么多的條條框框，也照樣行的通。公司一大，代碼協作的人越多，每個人的自由就會導致最終的沖突甚至問題。所以，很多大公司會制定一些 API 的 best practice，強制要求設計和實現中必須按照某種模式來做。有些規則雖有道理，但也不是說不這樣不行。很多時候，就因為這樣的原因，我們的 API 設計中會有很多限制，表面上似乎給設計帶來無謂的難度，但是仔細考量，從規范代碼一致性的角度而言，還是有很大好處的。
API 設計里很常見的一個情況是，有一個系統功能，目前并沒有人使用，只是有人提出：“這種情況我們以后應該要支持。” 之前說過，由于 API 上線后再改很困難，所以在設計初期就要盡可能的考慮未來的發展。但是這些 “可能” 的應用場景因為需求的細節和使用頻度都不明確，最容易造成系統的 over-design。
我記得好像聽過一個說法，重新概括一下，就是：think about future, design with flexibility, but only implement for production。中文大概就是說：要考慮未來的場景，設計時留有余地，但永遠只實現 production 確實要用的功能。
設計和實現里常常會有一些封裝和抽象的概念。某些特殊情況下，封裝再分拆的過程可能一定程度上影響 API 的速度，或者是代碼質量的優化和性能的優化上有沖突。這個很難一概而論，還是要看具體代碼是不是在 critical path 或者是不是一段需要很多人協作的代碼。最終的選擇還是要看情況。
AOP 編程本身就是一個極具爭議的話題。概括說來，AOP 的理念是從主關注點中分離出橫切關注點，是面向側面的程序設計的核心概念。分離關注點使得解決特定領域問題的代碼從業務邏輯中獨立出來，業務邏輯的代碼中不再含有針對特定領域問題代碼的調用，業務邏輯同特定領域問題的關系通過側面來封裝、維護，這樣原本分散在在整個應用程序中的變動就可以很好的管理起來。
因為 API 的設計和實現中有很多通用的關注點，如 Logging、Authentication、Parsing、Monitoring 等等，所以 API 成了 AOP 一個很自然的應用領域。使用 AOP 的 API design 繼承了 AOP 的優勢，如：代碼的重用性，規整性，以及程序員可以集中關注于系統的核心業務邏輯等。但也自然而然繼承了 AOP 固有的問題，如 代碼的 profiling 和 debugging 等；程序員 experience 的要求以及相互協作的要求（例如改變某一個功能可能會影響到其它的功能）等。
這篇考慮到不同系統和語言情況都不太一樣，因此沒有涉及到太多細節。只把一些做 API 中得到的感悟泛泛寫了寫，大家有什么體會，留言里說說吧。
題圖：from Pinterest
雷鋒網注：轉載請聯系作者授權，并務必保留出處和作者，不得刪減內容。
雷峰網原創文章，未經授權禁止轉載。詳情見轉載須知。
