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