正在上傳…重新上傳取消

導(dǎo)讀

在以云計(jì)算為主角的開發(fā)者視界中，OpenAPI 是絕對(duì)的主角。要發(fā)短信，用 OpenAPI；要管理資源，用 OpenAPI；要管理權(quán)限，用 OpenAPI。如果一個(gè) OpenAPI 解決不了你的問題，那就再來一個(gè)。在今天，開放平臺(tái)及 OpenAPI 隨處可見，它是系統(tǒng)與系統(tǒng)之間集成的重要橋梁。但 OpenAPI 用起來是否真的舒服，這要打一個(gè)大大的問號(hào)。本文將介紹 OpenAPI 領(lǐng)域下的難題和一些解決方案。

背景

阿里云有位工程師叫樸靈，熱愛開源，是活躍在 Github 上的國(guó)內(nèi)技術(shù)大牛之一。在阿里工作 6 年之際，樸靈產(chǎn)生了離職的想法，打算去一家創(chuàng)業(yè)公司再戰(zhàn)高峰。走之前，樸靈做了一些研究工作，他發(fā)現(xiàn)阿里云在功能和產(chǎn)品上可以說是一流的云計(jì)算廠商，是創(chuàng)業(yè)公司的首選，但由于過去的業(yè)務(wù)中寫過大量的 Node.js SDK，對(duì)開發(fā)者體驗(yàn)有著自己的體感，他覺得在開發(fā)者體驗(yàn)關(guān)懷上，阿里云做得還不夠好。來自一個(gè)熱血工程師最樸素的想法，自己何不先留下來，去把這件事情做好，于是，樸靈加入了阿里云開放平臺(tái)負(fù)責(zé) SDK 業(yè)務(wù)，期間，他和團(tuán)隊(duì)研發(fā)了專利 TeaDSL，下面樸靈將分享 TeaDSL 如何解決多語言 SDK 的問題。

使用 OpenAPI 的痛苦

在過去，我們經(jīng)常說的 OpenAPI，通常的做法是，開發(fā)好服務(wù)端的接口，然后在文檔里簡(jiǎn)單寫幾個(gè)參數(shù)描述，就直接丟給客戶去用。反正我是開發(fā)好了，我這里是好的，客戶能不能用起來我是不用管的。

?

正在上傳…重新上傳取消
圖 1 第一代的 OpenAPI 通常僅由簡(jiǎn)單的文檔及實(shí)際的接口構(gòu)成

然而接下來的問題就來了。首先，文檔上寫得不清不楚的參數(shù)，沒有試過，完全不知道它到底能不能 Work。其次，OpenAPI 總得有一定的權(quán)限認(rèn)證吧，那么總得有一個(gè)簽名啥的，每個(gè)客戶都要寫一遍，關(guān)鍵是總是沒法寫對(duì)。再次，不同的客戶所使用的編程語言不一樣，得把接口重新包裝才能用。

總算費(fèi)心費(fèi)力調(diào)通了接口，以為可以高枕無憂的時(shí)候，咋接口老是報(bào)錯(cuò)，網(wǎng)絡(luò)連不上，返回的數(shù)據(jù)不對(duì)，諸如此類。再往后，OpenAPI 可能總是要發(fā)生一點(diǎn)變化什么的，總是出現(xiàn)一些數(shù)據(jù)結(jié)構(gòu)發(fā)生變化，不兼容之類的問題。

一個(gè) OpenAPI 到最后，不光是用戶使用起來覺得很氣，作為維護(hù)者也是很艱難的。當(dāng)公布一個(gè) OpenAPI 后，第一步給出簡(jiǎn)單的文檔后，會(huì)發(fā)現(xiàn)除了要把參數(shù)詳情寫得越來越完善準(zhǔn)確外，還得給出簽名算法，讓不同語言的開發(fā)者來接入。然而給出簽名算法后，會(huì)發(fā)現(xiàn)只有一些開發(fā)者能順利完成，大部分的開發(fā)者只能眼巴巴地請(qǐng)你幫忙提供一個(gè) SDK。好吧，那就提供一下我最拿手的 Java 語言的簽名，提供一個(gè)核心 SDK 唄。

?

圖 2 第二代的 OpenAPI 會(huì)有 SDK 的實(shí)現(xiàn)，但僅有少許的語言支持

隨著這個(gè) OpenAPI 接口的用戶越來越多，一個(gè)客戶說我要用 C++ 來對(duì)接你，另一個(gè)客戶說我要用 Python 來對(duì)接你，于是，我一個(gè) Java 程序員，怎么就要寫那么多語言的 SDK 呢。沒有辦法，如果不提供良好的 SDK，客戶說，沒有 IDE 提示呢，我怎么寫代碼呢。

總而言之，在 OpenAPI 的應(yīng)用過程中，一件簡(jiǎn)單的事情，會(huì)變得非常復(fù)雜：

• 需要提供良好的 API 文檔，作為最基本的要求
• 需要提供 SDK，保障開發(fā)者的編碼體驗(yàn)，封裝細(xì)節(jié)，代碼提示等
• 需要提供 Code Sample，更理解接口的使用效果
• 如果有 CLI 就更好了，這樣連 bash 腳本寫起來也更方便
• 如果沒有 Test Cases 作為日常的持續(xù)集成，接口質(zhì)量可能存在問題

上面這些要求，如果加上多種編程語言的條件，就會(huì)演變?yōu)橐患?xì)碎而又繁多的體力活。并且這中間不能有任何的變動(dòng)，因?yàn)閮H僅是一點(diǎn)點(diǎn)的 OpenAPI 變動(dòng)，就需要連帶整個(gè)下游發(fā)生變化。如果一個(gè)地方?jīng)]有保持一致，那么客戶問題就會(huì)出現(xiàn)。

?

轉(zhuǎn)存失敗重新上傳取消
圖 3 當(dāng)用戶量變多，OpenAPI 的提供者需要提供完善的工具及更多的編程語言支持

通常為了解決此類的問題，以及 OpenAPI 的諸如簽名校驗(yàn)，限流，生成 SDK、文檔等等，業(yè)界通常會(huì)使用 API 網(wǎng)關(guān)來承擔(dān)這些橫向的責(zé)任。

然而，作為筆者所在的環(huán)境下，會(huì)發(fā)現(xiàn)，我們身邊的網(wǎng)關(guān)有點(diǎn)多。于是不同的網(wǎng)關(guān)有不同的風(fēng)格，不同的簽名算法，不同的序列化格式。于是上述的過程要根據(jù)不同網(wǎng)關(guān)的數(shù)量，進(jìn)行翻倍：

?

圖 4 當(dāng)一個(gè)企業(yè)變得龐大時(shí)，不同風(fēng)格的 OpenAPI 及網(wǎng)關(guān)都會(huì)出現(xiàn)

當(dāng)我們?cè)诒г故褂貌煌a(chǎn)品的 OpenAPI/SDK 體驗(yàn)不一致，文檔不對(duì)，Demo 出錯(cuò)等等問題時(shí)，真不是因?yàn)樽鲞@些事情太難，而是太多，太瑣碎。一件簡(jiǎn)單的事情，需要做一百次，也就不是簡(jiǎn)單的事情了。

TeaDSL 的解決之道

TeaDSL 是由阿里云開放平臺(tái) SDK 團(tuán)隊(duì)主導(dǎo)設(shè)計(jì)的一門領(lǐng)域特定語言。主要用于解決如下問題：

• 通過一門中間語言，可以支持不同風(fēng)格的網(wǎng)關(guān)。即使網(wǎng)關(guān)下的 OpenAPI 風(fēng)格各異，也能一致地表達(dá)到。
• 可以通過翻譯的能力，實(shí)現(xiàn)對(duì)不同編程語言的代碼生成。也就是可以基于統(tǒng)一的中間表達(dá)，生成多語言的 SDK。
• 基于中間表達(dá)，我們可以將一組 OpenAPI 視為一個(gè) library，因此可以在這個(gè)基礎(chǔ)上實(shí)現(xiàn) OpenAPI 接口的 Code Sample 編寫。進(jìn)而實(shí)現(xiàn)多語言的 Code Sample 統(tǒng)一生成。

因此 TeaDSL 的核心能力就是通過一種中間語法來描述 OpenAPI，提供類似編程語言的能力，來將 OpenAPI、SDK、Code Sample 等場(chǎng)景及語言有機(jī)地結(jié)合在一起。

在沒有 TeaDSL 之前，對(duì)于不同的網(wǎng)關(guān)，我們要為它制定獨(dú)立的工作流程，即從 OpenAPI 定義到不同語言的 SDK 生成，是獨(dú)特的。換一個(gè)新的網(wǎng)關(guān)風(fēng)格，就要重新實(shí)現(xiàn)這套流程。

?

正在上傳…重新上傳取消
圖 5 M 個(gè)網(wǎng)關(guān)都要支持 N 種編程語言，整個(gè)工作量是 M * N 的關(guān)系

而具有 TeaDSL 后，我們則形成一個(gè)中間層。可以將原來的工作收斂起來，我們僅需要關(guān)注不同的網(wǎng)關(guān)到 TeaDSL 的轉(zhuǎn)換工作，以及 TeaDSL 到各個(gè)編程語言的生成工作。

?

圖 6 經(jīng)過中間層的隔離，整個(gè)工作量變?yōu)?M + N 的關(guān)系

也就是說，TeaDSL 是在做一件 M * N 到 M + N 的工作。當(dāng)網(wǎng)關(guān)越多，支持的編程語言越多，收益則越大。

一旦這個(gè)中間層建立起來，整個(gè) OpenAPI 的應(yīng)用形式都可以基于它來構(gòu)建。比如，編寫一個(gè) OpenAPI 的 Code Sample，Test Case 等。

接下來簡(jiǎn)單介紹 TeaDSL 是如何實(shí)現(xiàn)支持任意風(fēng)格的網(wǎng)關(guān)和多種編程語言的。

如何支持任意風(fēng)格的網(wǎng)關(guān)

對(duì)于不同的 API 網(wǎng)關(guān)，或者不同產(chǎn)品的 OpenAPI 而言，它們之間的風(fēng)格可能都千差萬別，因此在很大的程度上，每種風(fēng)格的 OpenAPI 都有它自己的元數(shù)據(jù)定義格式。為了減少網(wǎng)關(guān)、風(fēng)格帶來的差異化，業(yè)界主要推動(dòng)的方式是盡量采用標(biāo)準(zhǔn)的定義格式。比如 Swagger 就是其中的佼佼者，它依托于 OpenAPI Specification ，以 RESTful 風(fēng)格的 OpenAPI 作為基準(zhǔn)，形成了一套業(yè)界標(biāo)準(zhǔn)。

但這個(gè)世界就是這樣不完美，我們現(xiàn)有的大量 OpenAPI 并不是 RESTful 風(fēng)格的。這導(dǎo)致很多的產(chǎn)品現(xiàn)存的 OpenAPI 在文檔、SDK等場(chǎng)景下，無法使用上 Swagger 這樣強(qiáng)大的生態(tài)工具鏈。

為了解決這些問題，我們需要進(jìn)行兩步操作：

• 設(shè)立一套新的標(biāo)準(zhǔn)，來包容不同風(fēng)格的 OpenAPI
• 以這套新的標(biāo)準(zhǔn)，來建設(shè)生態(tài)工具鏈

如果完成這兩個(gè)步驟，那么現(xiàn)實(shí)世界上的每一個(gè) OpenAPI，RESTful 或者非 RESTful 的，不需要做任何遷移，也能具有強(qiáng)大的工具鏈支持。

新標(biāo)準(zhǔn)的設(shè)計(jì)

通過我們的研究發(fā)現(xiàn)，無論 OpenAPI 的參數(shù)是如何組成的，傳輸是 JSON，還是 XML，乃至自定義協(xié)議，OpenAPI 都是基于 HTTP 協(xié)議棧進(jìn)行提供的。也就是說，萬變不離其宗的是 HTTP 協(xié)議本身。因此我們確立的基本模型是這樣的：

{protocol: string, // http or httpsport: number, // tcp porthost: string, // domainrequest: {method: string, // http methodpathname: string, // path namequery: map[string]string, // query stringheaders: map[string]string, // request headersbody: readable // request body},response: {statusCode: number, // http methodstatusMessage: string, // path nameheaders: map[string]string, // response headersbody: readable // response body}, }

對(duì)于不同風(fēng)格的 OpenAPI 而言，就像不同風(fēng)格的建筑，它們的建筑材料都幾乎相同，只是施工手法，組合形式不一樣而已。我們看到的 OpenAPI 風(fēng)格差異，實(shí)質(zhì)則是序列化過程不同而帶來的不同。我們序列化過程和數(shù)據(jù)模型分離，將用戶更直觀的數(shù)據(jù)結(jié)構(gòu)提取出來。

比如從用戶角度出發(fā)，一個(gè)數(shù)據(jù)模型是更直觀的事物：

model User {username: string,age: number }

在不同的網(wǎng)關(guān)下，它的傳輸形式可能是 JSON，也可能是 XML，但最終都是 readable，也就是可讀的字節(jié)流。

toJSON(user: User): string toXML(user: User): string

最終的結(jié)果就是：

__request.body = toJSON(user); __request.body = toXML(user);

更進(jìn)一步的過程是，我們會(huì)將一個(gè) OpenAPI 的請(qǐng)求/響應(yīng)包裝為一個(gè)類似于編程代碼的方法：

api getUser(username: string): User {__request.method = 'GET';__request.pathname = `/users/${username}`;__request.headers = {host = 'hostname',}; } returns {var body = readAsJSON(__response.body);return body; }

盡管上面的代碼不能實(shí)際運(yùn)行，但大致也看出來我們包容不同的網(wǎng)關(guān)、風(fēng)格的辦法如下：

• 以 request / response 也就是 HTTP 協(xié)議作為核心模型
• 通過引入一些方法，如 toJSON / toXML / readAsJSON 等方法來分離數(shù)據(jù)結(jié)構(gòu)和序列化過程
• 將整個(gè)過程包裝成方法

這些方法在不同的編程語言下具有不同的實(shí)現(xiàn)，但我們只要定義好統(tǒng)一的簽名，就能確保一致性：

function toXML(data: $Model): string; function toJSON(data: $Model): string;

以上就是 TeaDSL 如何實(shí)現(xiàn)支持任意網(wǎng)關(guān)的方案。整個(gè)過程相對(duì)抽象，網(wǎng)關(guān)間的那些具有差異化的風(fēng)格，統(tǒng)統(tǒng)交給這些方法去實(shí)現(xiàn)，留下來的就只有數(shù)據(jù)結(jié)構(gòu)。

如何支持不同的編程語言

如果只是能通過一種描述方式來描述不同的 OpenAPI 調(diào)用過程，只是完成了一半的工作。另一半的工作是如何將這種描述語言落地到不同的編程語言下。在過去，我們支持不同的編程語言，主要是基于模版的形式來生成不同語言的實(shí)際代碼。但這對(duì)我們來說仍然還有一些不足之處：

• 模版的生成方式相對(duì)生硬，實(shí)現(xiàn)起來容易，但維護(hù)起來不那么靈活
• 生成出來的代碼容易帶來命名沖突，語法錯(cuò)誤等

從上面的形式也看到，這個(gè)方案，被我們?cè)O(shè)計(jì)成了一種 DSL 代碼。因此它是具有自己的詞法、語法、語義規(guī)則的，在生成目標(biāo)編程語言代碼之前，會(huì)有一套自身的校驗(yàn)。DSL 的這些能力是模版所不具備的。

可能對(duì)于別的場(chǎng)合，采用 DSL 的形式并不多見。但對(duì)于前端工程師而言，這些年已經(jīng)見的較多了：CoffeeScript、Babel、JSX、TypeScript 等等。為此我們參考了諸多編程語言的設(shè)計(jì)，最終形成了自己的一套語法。并借鑒編譯器領(lǐng)域的轉(zhuǎn)譯方式，因此我們可以在模型一致的情況，生成到各種不同的編程語言下。

整個(gè) TeaDSL 的處理流程如下：

?

最終我們支持多種編程語言的場(chǎng)景主要有3個(gè)：

• 基本的多種語言的 SDK
• OpenAPI 相關(guān)的多種語言的 Code Sample
• OpenAPI 相關(guān)的多種語言的 Test Case

通過中間語言的強(qiáng)校驗(yàn)，生成到多種目標(biāo)場(chǎng)景，可以解決編程語言支持不全面的問題。同時(shí)也大幅節(jié)約 OpenAPI 維護(hù)者的精力成本，不需要反復(fù)手工地編寫不同編程語言下的 Code Sample。隨著對(duì)不同編程語言的支持逐步完善，這些中間 TeaDSL 代碼不需要任何操作，即可自動(dòng)支持到新的編程語言下。

總結(jié)

TeaDSL 的主要能力是支持到不同風(fēng)格的 OpenAPI，同時(shí)支持多語言的 SDK、Code Sample 目標(biāo)生成。最終的目的仍然是打通從 OpenAPI 定義到文檔、到 SDK、CLI 等 OpenAPI 使用場(chǎng)景下的一致性。提供給用戶更統(tǒng)一、專業(yè)、一致的使用體驗(yàn)。同時(shí)也大幅降低 OpenAPI 提供者用來支持用戶的成本，通過自動(dòng)化的方式，節(jié)省精力的同時(shí)，還減少人為參與時(shí)導(dǎo)致的錯(cuò)誤。

目前 TeaDSL 在阿里云的一些 SDK 上已經(jīng)有所應(yīng)用，如：https://github.com/aliyun/aliyun-ccp。阿里云開放平臺(tái)在持續(xù)努力提升它的整個(gè)工具支持生態(tài)，以期望能建成比 Swagger 更適配的生態(tài)體系。

原文鏈接

本文為云棲社區(qū)原創(chuàng)內(nèi)容，未經(jīng)允許不得轉(zhuǎn)載。

總結(jié)

以上是生活随笔為你收集整理的TeaDSL：支持任意 OpenAPI 网关的多语言 SDK 方案的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。