導讀

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

背景

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

使用 OpenAPI 的痛苦

在過去，我們經常說的 OpenAPI，通常的做法是，開發好服務端的接口，然後在文檔裡簡單寫幾個參數描述，就直接丟給客戶去用。反正我是開發好了，我這裡是好的，客戶能不能用起來我是不用管的。

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

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

總算費心費力調通了接口，以為可以高枕無憂的時候，咋接口老是報錯，網絡連不上，返回的數據不對，諸如此類。再往後，OpenAPI 可能總是要發生一點變化什麼的，總是出現一些數據結構發生變化，不兼容之類的問題。

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

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

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

總而言之，在 OpenAPI 的應用過程中，一件簡單的事情，會變得非常複雜：

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

上面這些要求，如果加上多種編程語言的條件，就會演變為一件細碎而又繁多的體力活。並且這中間不能有任何的變動，因為僅僅是一點點的 OpenAPI 變動，就需要連帶整個下游發生變化。如果一個地方沒有保持一致，那麼客戶問題就會出現。

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

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

然而，作為筆者所在的環境下，會發現，我們身邊的網關有點多。於是不同的網關有不同的風格，不同的簽名算法，不同的序列化格式。於是上述的過程要根據不同網關的數量，進行翻倍：

圖 4 當一個企業變得龐大時，不同風格的 OpenAPI 及網關都會出現

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

TeaDSL 的解決之道

TeaDSL 是由阿里雲開放平臺 SDK 團隊主導設計的一門領域特定語言。主要用於解決如下問題：

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

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

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

圖 5 M 個網關都要支持 N 種編程語言，整個工作量是 M * N 的關係

而具有 TeaDSL 後，我們則形成一箇中間層。可以將原來的工作收斂起來，我們僅需要關注不同的網關到 TeaDSL 的轉換工作，以及 TeaDSL 到各個編程語言的生成工作。

圖 6 經過中間層的隔離，整個工作量變為 M + N 的關係

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

一旦這個中間層建立起來，整個 OpenAPI 的應用形式都可以基於它來構建。比如，編寫一個 OpenAPI 的 Code Sample，Test Case 等。

接下來簡單介紹 TeaDSL 是如何實現支持任意風格的網關和多種編程語言的。

如何支持任意風格的網關

對於不同的 API 網關，或者不同產品的 OpenAPI 而言，它們之間的風格可能都千差萬別，因此在很大的程度上，每種風格的 OpenAPI 都有它自己的元數據定義格式。為了減少網關、風格帶來的差異化，業界主要推動的方式是儘量採用標準的定義格式。比如 Swagger 就是其中的佼佼者，它依託於 OpenAPI Specification ，以 RESTful 風格的 OpenAPI 作為基準，形成了一套業界標準。

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

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

• 設立一套新的標準，來包容不同風格的 OpenAPI
• 以這套新的標準，來建設生態工具鏈

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

新標準的設計

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

{
  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 風格差異，實質則是序列化過程不同而帶來的不同。我們序列化過程和數據模型分離，將用戶更直觀的數據結構提取出來。

比如從用戶角度出發，一個數據模型是更直觀的事物：

model User {
    username: string,
  age: number
}

在不同的網關下，它的傳輸形式可能是 JSON，也可能是 XML，但最終都是 readable，也就是可讀的字節流。

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

最終的結果就是：

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

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

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

儘管上面的代碼不能實際運行，但大致也看出來我們包容不同的網關、風格的辦法如下：

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

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

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

以上就是 TeaDSL 如何實現支持任意網關的方案。整個過程相對抽象，網關間的那些具有差異化的風格，統統交給這些方法去實現，留下來的就只有數據結構。

如何支持不同的編程語言

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

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

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

可能對於別的場合，採用 DSL 的形式並不多見。但對於前端工程師而言，這些年已經見的較多了：CoffeeScript、Babel、JSX、TypeScript 等等。為此我們參考了諸多編程語言的設計，最終形成了自己的一套語法。並借鑑編譯器領域的轉譯方式，因此我們可以在模型一致的情況，生成到各種不同的編程語言下。

整個 TeaDSL 的處理流程如下：

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

• 基本的多種語言的 SDK
• OpenAPI 相關的多種語言的 Code Sample
• OpenAPI 相關的多種語言的 Test Case

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

總結

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

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