91精品国产综合久久香蕉,精品一区二区三区五区六区七区,国产91精品免费

圖 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): stringtoXML(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 更適配的生態體系。

文章轉自微信公眾號@阿里云開發者