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

背景

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

使用 OpenAPI 的痛苦

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

?

??

圖 1 第一代的 OpenAPI 通常僅由簡單的文檔及實際的接口構(gòu)成

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

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

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

?

??

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

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

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

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

上面這些要求，如果加上多種編程語言的條件，就會演變?yōu)橐患毸槎址倍嗟捏w力活。并且這中間不能有任何的變動，因為僅僅是一點點的 OpenAPI 變動，就需要連帶整個下游發(fā)生變化。如果一個地方?jīng)]有保持一致，那么客戶問題就會出現(xiàn)。

?

??

圖 3 當用戶量變多，OpenAPI 的提供者需要提供完善的工具及更多的編程語言支持

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

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

?

??

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

當我們在抱怨使用不同產(chǎn)品的 OpenAPI/SDK 體驗不一致，文檔不對，Demo 出錯等等問題時，真不是因為做這些事情太難，而是太多，太瑣碎。一件簡單的事情，需要做一百次，也就不是簡單的事情了。

TeaDSL 的解決之道

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

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

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

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

?

??

圖 5 M 個網(wǎng)關(guān)都要支持 N 種編程語言，整個工作量是 M * N 的關(guān)系

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

?

??

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

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

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

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

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

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

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

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

• 設(shè)立一套新的標準，來包容不同風格的 OpenAPI
• 以這套新的標準，來建設(shè)生態(tài)工具鏈

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

新標準的設(shè)計

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

{ 
   protocol: string, // http or https 
   port: number,         // tcp port 
   host: string,         // domain 
   request: { 
     method: string, // http method 
     pathname: string, // path name 
     query: map[string]string, // query string 
     headers: map[string]string,  // request headers 
     body: readable      // request body 
   }, 
     response: { 
     statusCode: number, // http method 
     statusMessage: string, // path name 
     headers: map[string]string,  // response headers 
     body: readable      // response body 
   }, 
 }

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

比如從用戶角度出發(fā)，一個數(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);

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

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

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

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

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

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

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

如何支持不同的編程語言

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

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

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

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

整個 TeaDSL 的處理流程如下：

?

??

最終我們支持多種編程語言的場景主要有3個：

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

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

總結(jié)

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

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

【本文為51CTO專欄作者“阿里巴巴官方技術(shù)”原創(chuàng)稿件，轉(zhuǎn)載請聯(lián)系原作者】

??戳這里，看該作者更多好文??