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