丨每個工程師都應(yīng)該了解的api設(shè)計和實現(xiàn)

有一天你的CTO奇想，行云流水地提交了一段代碼；大家一看很激動啊，很多人跑去觀摩大神的代碼，結(jié)果覺得問題多多，于是在PR（PullRequest）上提了一堆評論。CTO一看有點傻眼了：“幾十條評論……現(xiàn)在代碼要這么寫啊，好麻煩?！庇谑撬秃鸵晃还こ處熣f：“你把評論里的問題解決下，合并（Merge）到主分支吧”，然后就開開心心隨著公司的發(fā)展，成品功能不斷疊加，代碼架構(gòu)不斷優(yōu)化，系統(tǒng)會經(jīng)歷一些從簡到繁，然后再由繁到簡的迭代過程，代碼的改動也會相當(dāng)巨大，也許有一天，你會幾乎不認(rèn)識自己當(dāng)初的作品了。API的設(shè)計更是如此。在我們的工作中，很少能見到API的設(shè)計從最開始就完美無瑕疵。一套成API，很多時候都是需要通過不斷演化迭代出來的。今天我就和你聊聊API的設(shè)計。首先第一點，我們先從API的簽名（Signature）說起API的簽名API的簽名，或者叫協(xié)議，就是指API請求（Request）和響應(yīng)（Response）支持哪些首先，做過API的人都知道，一個上線使用的API再想改它的簽名，會因為兼容性的問題痛苦。因此，API簽名的設(shè)計初期，一定要經(jīng)過反復(fù)推敲，盡量避免上線后的改動。除了一些基本的RESTful原則外，簽名的定義很多時候是對業(yè)務(wù)邏輯的抽象過程。一個系統(tǒng)的業(yè)務(wù)邏輯可能錯綜復(fù)雜，因此API設(shè)計的時候，就應(yīng)該做到用最簡潔直觀的格式去支這往往是API設(shè)計中相對立的兩面，我們需要找到平衡。有時候為了支持某一個功能，似乎不得不增加一個很設(shè)計的接口；而有時候我們?yōu)榱吮ＷCAPI絕對規(guī)范，又不得不放這種設(shè)計上的取舍，通常會列出所有可行的方案，從簡單的設(shè)計到繁雜的設(shè)計；然后通過分析各種使用實例的頻率和使用某種設(shè)計時的復(fù)雜度，從實際的系統(tǒng)需求入手，盡可能讓常用的功能得到最簡單直接的支持；還要一定程度上“犧牲”一些極少用到的功能，反復(fù)考慮系統(tǒng)使用場景，盡可能獲得一個合理的折衷方案。API在這個折衷的過程中，我們需要始終保證滿足這些基本原保證API100%RESTful。RESTful的是：everythingisa“resource”，所有的行為（Action）和接口，都應(yīng)該是相應(yīng)Resource上的增刪改查（CRUD）操作。如果RESTful格在請求和響應(yīng)中，應(yīng)該盡可能地保持參數(shù)的結(jié)構(gòu)化。如果是一個哈希（hash），就傳一個哈希（不要傳hash.to_sring）。API的序列化和反序列化機(jī)制（erializaion/Deserializaion）會將其自動序列化成字符串。多語言之間的API，比如Ruy、Java、C#之間的調(diào)用，通常都是在序列化和反序列化機(jī)制中完成不同語言間類型的轉(zhuǎn)換。認(rèn)證（Autheiaion）和安全（ecity）的考慮。安全的考慮始終應(yīng)該放在首位，保證對特定的用戶只相關(guān)的接口和權(quán)限。可以使用和白，也可以通過用戶登陸的（Creenials）生成的驗證票據(jù)（Toen），或者ession/等方式來處理。此外，所有的API層的日志（Loging），要保證不記錄任何敏感的信息。API本身應(yīng)該是客戶端無關(guān)的。也就是說，一個API對請求的處理盡可能避免對客戶端動端還是網(wǎng)頁端的考慮?？蛻舳讼嚓P(guān)的響應(yīng)格式，不應(yīng)該在API現(xiàn)。所有的客戶端無關(guān)的計算和處理，要盡可能在服務(wù)器（Server）端統(tǒng)一處理，以提高性能和一盡可能讓API是冪等（Idempotent）的。關(guān)于冪等，可以參考我之前寫的“聊聊冪使用好API每個語言都已經(jīng)提供了很好的API架，你需要在設(shè)計前先多了解這些框架。如果你是個小團(tuán)隊，資源沒那么充分，選一個合適的框架入手，適當(dāng)調(diào)整，比從零開始造要好多。等公司長大了，由于各自業(yè)務(wù)邏輯的特殊需求，最終都會定制一套自己的API評估一個API框架，可以從以下幾個方面對權(quán)限的統(tǒng)一控自動測試的支對請求和響應(yīng)的格式，以及序列化和反序列化（SerializationDeserialization）的對日志和日志過濾（Logging和LoggingFiltering）的支對自動文檔生成的支對架構(gòu)以及性能的影API計中存在很多對立的因素，比如簡潔還是繁復(fù)，兼容性和效率，為現(xiàn)在設(shè)計還是為未自由總是相對對于一個大群體，有人就會被別人的”自由“誤傷。寫軟件也是一樣。一個小的里，API怎么設(shè)計，代碼怎么寫，幾個人一協(xié)商，達(dá)成突。所以，很多大公司會制定一些API的最佳實踐，強(qiáng)制要求設(shè)計中必須按照某種API計中會有很多限制，這在表面上似乎給設(shè)計帶來無謂的難度，但是仔細(xì)考量，從規(guī)范為當(dāng)前設(shè)計，還是為未來設(shè)API設(shè)計里很常見的一個情況是：一個目前并沒有人使用的系統(tǒng)功能，它的存在只是因為有人提出：“這種情況我們以后應(yīng)該要支持。”前文中我曾講過，由于API上線后再改很困難，所以在設(shè)計初期就要盡可能地考慮未來的發(fā)展；但是這些“可能”的應(yīng)用場景因為需求的細(xì)節(jié)和使用頻度都不明確，最容易造成系統(tǒng)的過度設(shè)計（Over-design）。我記得有一個API計的經(jīng)典原則，概括一下就是：要考慮未來的場景，在設(shè)計時留有余可性和效率（Maintainabilityv.s.在一定程度上影響API的響應(yīng)速度，或者代碼質(zhì)量的優(yōu)化和性能的優(yōu)化上有。這個很是否采用AOP身就是一個極具爭議的話題。概括說來，AOP理念是從主關(guān)注點中分離出橫切關(guān)分離關(guān)注點使得解決特定領(lǐng)域問題的代碼從業(yè)務(wù)邏輯中獨立出來，業(yè)務(wù)邏輯的代碼中不再含有針對特定領(lǐng)域問題代碼的調(diào)用，業(yè)務(wù)邏輯同特定領(lǐng)域問題的關(guān)系通過側(cè)面來封裝、，這樣原本分散在在整個應(yīng)用程序中的變動就可以很好地管理起來。因為API的設(shè)計中有很多通用的關(guān)注點，如日志（Logging）、解（Parsing）、（Monitoring）等等，所以API成了AOP一個很自然的應(yīng)用領(lǐng)域使用AOP的API設(shè)計繼承了AOP的優(yōu)勢，如：代碼的重用性，規(guī)整性，以及程序員可以集中關(guān)注于系統(tǒng)的業(yè)務(wù)邏輯等；但也會自然而然地繼承了AOP固有問題，例如代碼的剖析（Profiling）和調(diào)試（Deuging）增加，對程序員的相關(guān)經(jīng)驗有要求，相互協(xié)作的要求也增強(qiáng)了，比如改變某一個功能可能會影響到其它的功能，等等。是否選擇使用AOP，和你的需求場景，人員技能和設(shè)計復(fù)雜度關(guān)，需要技術(shù)決策者今天我從兩個小故事入手，和你討論了API設(shè)計和原則，內(nèi)容分為四個部分：API名、API的設(shè)計原則、使用現(xiàn)有編程語言的API框架、如何在API設(shè)計中取得平衡。API設(shè)計是現(xiàn)代軟件系統(tǒng)中不可或缺的一個環(huán)節(jié)，不同的系統(tǒng)需求和不同編程語言下，API最后，給你留一道思考題，API的簽名（Signature）設(shè)計是語言無關(guān)的，那你在設(shè)計中會引入的語言還是更少的語言去實現(xiàn)不同的API呢，優(yōu)點和缺點各是什么？期待你的回戳此獲取你的專屬海 歸科技所有 不得售賣。頁面已增加防盜追蹤，將依 上一篇17|下一篇19|寫言精選留言寫言水有罔象置 有幫助謝謝安姐展藍(lán)翔Sean置 1API的RESTfulAPI都能實現(xiàn)成RESTfulloginlogoutAPI的設(shè)計有展loginlogoutAPIt