譯自：API Governance: Using Patterns From PayPal, Netflix and More[1]作者：Charles Humble

許多組織將API治理交給機(jī)會(huì)，但這是一種冒險(xiǎn)的做法。相反，看看全球企業(yè)如何指導(dǎo)他們的API開發(fā)。

我承認(rèn)，API 治理并不是一個(gè)令人心跳加速的話題。它或許最好被描述為枯燥但重要。

做好 API 治理，有助于保持一致性并促進(jìn) API 的重用。它還應(yīng)該提供一種機(jī)制，讓內(nèi)部和外部客戶都能提供反饋并請(qǐng)求更改。然后，可以根據(jù)其他競(jìng)爭(zhēng)性優(yōu)先事項(xiàng)評(píng)估這些請(qǐng)求，以便就是否、如何以及何時(shí)實(shí)施它們做出決策。

根據(jù)我的經(jīng)驗(yàn)，許多組織將 API 治理[2] 交給機(jī)會(huì)。但是，與組織文化一樣，無論你是否定義治理流程，它都會(huì)出現(xiàn)。因此，在我看來，最好是有意為之。

治理不必繁瑣。許多開發(fā)人員都?xì)g迎有關(guān)如何設(shè)計(jì) API 的指南，因?yàn)檫@意味著不必過多地?fù)?dān)心做出選擇——例如如何處理一組 API 結(jié)果中的分頁，或者事務(wù) ID 應(yīng)該叫什么。

INNOQ 的首席顧問、O'Reilly 作者和 API 建議 YouTuber Erik Wilde[3] 告訴 The New Stack：“在最近德國(guó)的一次會(huì)議上，我問了 150 名開發(fā)人員，‘你們有多少人在組織中擁有 API 指南？’，只有很少的人舉手。”“然后我問，‘你們有多少人希望擁有指南？’，看起來大多數(shù)人都舉手了。我沒有預(yù)料到差異會(huì)如此之大?！?/p>

如果你想為組織中的 API 建立治理流程，你可以應(yīng)用三種主要模式：集中式設(shè)計(jì)權(quán)限、聯(lián)邦式治理和受影響的自治理。每種模式都有不同的權(quán)衡，并且更適合某些情況。

在本文中，借助現(xiàn)實(shí)世界的例子，我們將研究每一種模式，并檢查它最適合應(yīng)用于何處。

模式 1：集中式設(shè)計(jì)權(quán)限

集中式設(shè)計(jì)權(quán)限 (CDA) 帶有架構(gòu)審查委員會(huì)和過于官僚的流程的包袱，或許是我們考慮的三種模式中最不受歡迎的一種。但這不應(yīng)該讓你忽視這樣一個(gè)事實(shí)：在某些情況下，它可能是有效的。

例如，它是發(fā)展編程語言的一種廣泛采用的方法——想想 C++ 的 ISO 標(biāo)準(zhǔn)[4]、Java 的 Java 社區(qū)流程[5] 或 Python 增強(qiáng)提案 (PEP)[6] 流程以及相應(yīng)的 Python 指導(dǎo)委員會(huì)。

CDA 的主要作用是看門人，這意味著為了有效，它需要防止做出低質(zhì)量或有風(fēng)險(xiǎn)的決策。除了其看門人的作用外，該機(jī)構(gòu)還應(yīng)驗(yàn)證良好的決策，并通過 文檔[7] 和其他指導(dǎo)來告知團(tuán)隊(duì)如何滿足質(zhì)量要求。

投資高質(zhì)量文檔尤其重要；如果沒有它，實(shí)施團(tuán)隊(duì)需要與 CDA 舉行的會(huì)議數(shù)量會(huì)迅速膨脹到無法管理的程度。

由于 CDA 的主要作用是看門人，因此其成功在很大程度上受到組織內(nèi)技術(shù)團(tuán)隊(duì)文化的的影響。如果各個(gè)團(tuán)隊(duì)覺得可以忽略 CDA 告訴他們做的事情，那么它就無法有效。相反，CDA 需要認(rèn)識(shí)到，過于繁重或官僚的流程會(huì)促使開發(fā)人員尋求繞過它的方法。

使用 CDA 模式的主要優(yōu)點(diǎn)是它推動(dòng)了統(tǒng)一性。使用此模式可以避免或至少限制開發(fā)人員擁有更多自主權(quán)時(shí)可能發(fā)生的重復(fù)工作量。它還可以確保正確遵循安全策略和其他組織協(xié)議。

一個(gè)重要的缺點(diǎn)是，隨著公司的發(fā)展，該機(jī)構(gòu)幾乎不可避免地會(huì)成為瓶頸，導(dǎo)致 API 項(xiàng)目停滯不前，因?yàn)槠涑蓡T等待與核心團(tuán)隊(duì)討論問題。

Wilde 建議：“使用此模型，你通常會(huì)遇到可擴(kuò)展性問題，開發(fā)人員認(rèn)為設(shè)計(jì)權(quán)限阻礙了他們的工作。”“這與其說他們不喜歡該機(jī)構(gòu)正在做什么，不如說他們認(rèn)為這會(huì)減慢他們的速度，因此他們?cè)噲D繞過它來完成工作?！迸c其他形式的軟件架構(gòu)權(quán)威一樣，API 設(shè)計(jì)權(quán)威成員也存在與實(shí)際工作脫節(jié)而無法做出良好決策的風(fēng)險(xiǎn)。這種現(xiàn)象等同于Stack Overflow的共同創(chuàng)建者Joel Spolsky[8]所說的“架構(gòu)宇航員[9]”。

鑒于此，CDA模式最好應(yīng)用于啟動(dòng)流程時(shí)，或變更量相對(duì)較小時(shí)。不出所料，它在監(jiān)管更嚴(yán)格的行業(yè)中通常更受歡迎。

PayPal如何使用集中式設(shè)計(jì)權(quán)威

在線支付提供商PayPal使用集中式設(shè)計(jì)權(quán)威進(jìn)行治理。在2018年北歐API平臺(tái)峰會(huì)上發(fā)言[10]時(shí)，當(dāng)時(shí)擔(dān)任該支付提供商API平臺(tái)負(fù)責(zé)人的Jayadeba Jena[11]描述了一個(gè)四步流程：

1. 定義（API組合對(duì)齊）：將包含用例和目標(biāo)客戶的API提案提交給API組合團(tuán)隊(duì)。組合團(tuán)隊(duì)審查重疊部分，并就API分類法、命名空間和資源名稱提供建議。如果批準(zhǔn)，則建立一個(gè)GitHub代碼庫(kù)來定義API契約，然后可以開始設(shè)計(jì)階段。

2. 設(shè)計(jì)（API設(shè)計(jì)審查）：對(duì)于REST API，使用OpenAPI[12]方法，將API契約和示例通過拉取請(qǐng)求提交給中心團(tuán)隊(duì)進(jìn)行審查。一群API設(shè)計(jì)師會(huì)審查規(guī)范是否符合設(shè)計(jì)標(biāo)準(zhǔn)。解決問題和意見，然后，一旦API規(guī)范獲得批準(zhǔn)，它就進(jìn)入開發(fā)階段。

3. 開發(fā)（API實(shí)現(xiàn)）：實(shí)現(xiàn)符合標(biāo)準(zhǔn)的API，例如服務(wù)等級(jí)協(xié)議和日志記錄。這是一個(gè)迭代過程，會(huì)來回提交PR。在這個(gè)過程結(jié)束時(shí)，團(tuán)隊(duì)使用工具根據(jù)OpenAPI規(guī)范自動(dòng)創(chuàng)建驗(yàn)證測(cè)試，來驗(yàn)證實(shí)現(xiàn)是否與契約定義匹配。

4. 外部化（商家和合作伙伴訪問）：提供速率限制、API外觀和OAuth范圍。創(chuàng)建外部文檔。更新SDK。確保API通過集成就緒檢查清單。

為了保持一致性，確保遵守公司的安全策略、向后兼容性和生命周期管理。PayPal的CDA維護(hù)著一套定義模式、版本控制策略和樣式指南的標(biāo)準(zhǔn)。這確保了“客戶/合作伙伴獲得統(tǒng)一的視圖和相同的API體驗(yàn)，”Jena說。

Jena指出，CDA最終成為瓶頸。PayPal的解決方案是培訓(xùn)產(chǎn)品負(fù)責(zé)人根據(jù)組織范圍的治理標(biāo)準(zhǔn)來審查其開發(fā)團(tuán)隊(duì)的工作。中央API設(shè)計(jì)團(tuán)隊(duì)仍然負(fù)責(zé)制定治理標(biāo)準(zhǔn)，但它不再負(fù)責(zé)審查每個(gè)API。

模式2：聯(lián)邦治理

我們的第二個(gè)模式，聯(lián)邦治理，是一種內(nèi)部咨詢模型。來自集中專家池的個(gè)人會(huì)加入負(fù)責(zé)構(gòu)建API的團(tuán)隊(duì)。這些專家可以就關(guān)鍵決策提供建議，也可以被授權(quán)代表實(shí)施團(tuán)隊(duì)做出決策。

如果人員配備適當(dāng)，聯(lián)邦治理團(tuán)隊(duì)?wèi)?yīng)該有足夠的帶寬來進(jìn)行研究，嘗試各種方案，并就實(shí)踐、工具和框架提出有根據(jù)的建議。

聯(lián)邦治理比CDA模式具有三個(gè)優(yōu)勢(shì)。首先，由于中心團(tuán)隊(duì)專家的參與，可以在流程早期做出重要決策。

其次，專家們自己可以獲得經(jīng)驗(yàn)，并將這些經(jīng)驗(yàn)帶回中心團(tuán)隊(duì)，確保理解和指導(dǎo)不斷改進(jìn)。第三，那些監(jiān)督工作的人不太可能成為與現(xiàn)實(shí)脫節(jié)的“宇航員”，因?yàn)樗麄冎苯訁⑴c了這個(gè)過程。

然而，聯(lián)邦治理是資源密集型的，因?yàn)樾枰罅康膶＜襾泶_保每個(gè)團(tuán)隊(duì)都能得到所需的幫助。與咨詢公司一樣，您必須要么增加員工數(shù)量以滿足高峰需求，并接受團(tuán)隊(duì)成員在空閑時(shí)期可能沒有太多工作要做，要么您需要準(zhǔn)備好裁員以應(yīng)對(duì)工作量下降——或者接受一些瓶頸。

實(shí)際上，我還發(fā)現(xiàn)，需要付出相當(dāng)大的努力才能保持專家之間對(duì)共享理解的一致性，以避免失去一致性。

HSBC如何使用聯(lián)邦治理

匯豐銀行從集中式團(tuán)隊(duì)轉(zhuǎn)向了聯(lián)邦治理?！拔覀円呀?jīng)建立了一個(gè)由匯豐銀行各部門的‘API 冠軍’組成的社區(qū)，以了解標(biāo)準(zhǔn)，將其應(yīng)用于各自的團(tuán)隊(duì)，并升級(jí)問題或差距，”匯豐銀行批發(fā)銀行首席API架構(gòu)師John Phenix在其公司博客文章中寫道。

然而，匯豐銀行也遇到了一些問題。Phenix 寫道：“并非所有 API 冠軍都擁有同等的經(jīng)驗(yàn)，因此我們?nèi)匀恍枰粋€(gè)相當(dāng)大的中央團(tuán)隊(duì)來確保一致性?！痹摴镜慕鉀Q方案是提高自動(dòng)化程度。

他補(bǔ)充道：“自動(dòng)化測(cè)試可以構(gòu)成DevOps流水線的一部分，確保測(cè)試內(nèi)置于常規(guī)的構(gòu)建、測(cè)試和發(fā)布周期中。”“這阻止了人們?cè)噲D操縱治理流程，并確保了更高的API審查覆蓋率?！?/p>

但Phenix 承認(rèn)，并非所有檢查都能以這種方式自動(dòng)化：“只需相對(duì)較小的投資，就可以在一致性、完整性和可觀測(cè)性方面獲得巨大的收益?！?/p>

模式 3：定向自我治理

也許最流行的API治理方法是定向自我治理，這是一種依賴影響而非控制的模式。這種模式最適合DevOps和云原生軟件構(gòu)建方法。因此，它已被Netflix等硅谷公司推廣，并被Spotify等歐洲同行效仿。

總體目標(biāo)是允許高度的自主性，但在這種自主性內(nèi)，要保持一些護(hù)欄——一條“黃金路徑”——這使得開發(fā)人員更容易做正確的事情。

Wilde告訴我們：“我們?cè)絹碓蕉嗟乜吹狡脚_(tái)的建立以及API治理的融入?！薄澳梢允褂米詣?dòng)化進(jìn)行CI/CD流水線中的一些設(shè)計(jì)檢查，以使流程盡可能輕量級(jí)?！?/p>

借鑒“團(tuán)隊(duì)拓?fù)洹币粫梢詫⒆晕抑卫砼c支持團(tuán)隊(duì)相結(jié)合，這些團(tuán)隊(duì)可以幫助處理流對(duì)齊團(tuán)隊(duì)不擅長(zhǎng)的方面，例如API設(shè)計(jì)。

Wilde 告訴TNS：“你需要提高組織內(nèi)部發(fā)生的事情的有效性和標(biāo)準(zhǔn)化，而不要過于強(qiáng)硬。”“目的是避免團(tuán)隊(duì)多次做同樣的事情，或者不同的團(tuán)隊(duì)選擇不同的解決方案?！?/p>

這種方法相對(duì)于我們已經(jīng)討論過的其他兩種方法的一個(gè)顯著優(yōu)勢(shì)是執(zhí)行速度；當(dāng)團(tuán)隊(duì)被賦予對(duì)其做出的決策的完全自主權(quán)時(shí)，他們可以非?？焖俚匦袆?dòng)。它還可以很好地?cái)U(kuò)展，而無需大量額外招聘。

主要缺點(diǎn)是團(tuán)隊(duì)可能會(huì)無意中做出不一致的決策，或者為了局部環(huán)境而優(yōu)化決策，從而損害整體利益?！皩?duì)于內(nèi)部API，如果它們遵循相同的外觀和感覺，這確實(shí)有助于提高開發(fā)人員的生產(chǎn)力，因?yàn)槟拈_發(fā)人員將使用許多不同的API，”Wilde 告訴The New Stack?！斑@使得制定指南成為一項(xiàng)不錯(cuò)的投資，因?yàn)槟鷮⒃陂_發(fā)人員生產(chǎn)力方面獲得回報(bào)。”

英國(guó)金融時(shí)報(bào)如何使用定向自我治理

在英國(guó)金融時(shí)報(bào)任職期間，Sarah Wells擔(dān)任過許多高級(jí)職務(wù)，其中包括媒體內(nèi)容平臺(tái)的團(tuán)隊(duì)負(fù)責(zé)人，該平臺(tái)為內(nèi)部和外部合作伙伴提供對(duì)英國(guó)金融時(shí)報(bào)內(nèi)容的豐富版本的API訪問。

從Wells的回憶來看，英國(guó)金融時(shí)報(bào)在自我治理方面的方法似乎相當(dāng)有機(jī)?！拔覀儧]有API專家團(tuán)隊(duì)，”她告訴The New Stack?！暗覀兇_實(shí)有API網(wǎng)關(guān)和一些文檔標(biāo)準(zhǔn)?！?/p>

Wells說：“我們還有一些關(guān)于健康檢查外觀的標(biāo)準(zhǔn)，有了這些，我們發(fā)現(xiàn)我們的開發(fā)人員更有可能使他們的API看起來像一個(gè)通用的API?！薄拔覀冇懻摿藰?gòu)建API時(shí)需要考慮什么，以確保它與所有其他API完全不同；這非常有價(jià)值。例如，我們?cè)噲D確保它可以通過API網(wǎng)關(guān)發(fā)現(xiàn)，并且我們?cè)诿绞缴媳３忠恢??！?/p>

Netflix 如何結(jié)合 API 治理策略

正如我們所看到的，即使在同一家公司內(nèi)，也可以結(jié)合不同的方法。并且在不同的地方和不同的時(shí)間使用多種方法通常是最佳的。

例如，Netflix以提倡高信任、高自主性的文化而聞名，它使用黃金路徑和定向自我治理方法。然而，這家流媒體公司正在更廣泛地采用GraphQL的過程中，也使用了集中式治理。2021年，Netflix的高級(jí)軟件工程師在InfoQ播客與我交談[13]時(shí)，解釋了該公司如何擁有一個(gè)模式工作組來監(jiān)督圖的演變。

“這是一個(gè)非常依賴人員的過程，”她說?！叭魏蜗胍蔀檫@個(gè)聯(lián)邦圖一部分的團(tuán)隊(duì)都需要參與模式工作組。我們有一位數(shù)據(jù)架構(gòu)師負(fù)責(zé)監(jiān)督這個(gè)單一統(tǒng)一圖的演變。因此，任何時(shí)候有人想要向現(xiàn)有類型添加新的實(shí)體或字段，他們都必須來到模式工作組參與討論。

“我們確保這一切都說得通，而且大家不會(huì)隨意地向圖中添加模式片段?！?/p>

最后，無論您選擇哪種方法，請(qǐng)記住，治理，就像您的API一樣，應(yīng)該隨著時(shí)間的推移而發(fā)展。持續(xù)考慮您的治理模型是否正在做您想做的事情非常重要。

引用鏈接

[1]API Governance: Using Patterns From PayPal, Netflix and More:https://thenewstack.io/api-governance-using-patterns-from-paypal-netflix-and-more/

[2]API 治理:https://thenewstack.io/api-management/

[3]Erik Wilde:https://www.youtube.com/ErikWilde

[4]C++ 的 ISO 標(biāo)準(zhǔn):https://thenewstack.io/coming-to-iso-c-26-standard-an-ai-acceleration-edge/

[5]Java 的 Java 社區(qū)流程:https://thenewstack.io/microsoft-goes-deep-on-java-with-jcp-membership/

[6]Python 增強(qiáng)提案 (PEP):https://thenewstack.io/guido-van-rossums-ambitious-plans-for-improving-python-performance/

[7]文檔:https://thenewstack.io/poor-documentation-is-costly-heres-how-to-fix-it/

[8]Joel Spolsky:https://www.linkedin.com/in/joelspolsky/

[9]架構(gòu)宇航員:https://www.joelonsoftware.com/2001/04/21/dont-let-architecture-astronauts-scare-you/

[10]在2018年北歐API平臺(tái)峰會(huì)上發(fā)言:https://www.youtube.com/watch?v=LuZiWas_nNw

[11]Jayadeba Jena:https://www.linkedin.com/in/jayadeba-jena-1a6a0020/

[12]OpenAPI:https://www.openapis.org

[13]與我交談:https://www.infoq.cn/podcasts/netflix-graphql-adoption-performance/