鍵.png)
使用NestJS和Prisma構(gòu)建REST API：身份驗(yàn)證
圖 1 第一代的 OpenAPI 通常僅由簡單的文檔及實(shí)際的接口構(gòu)成
然而接下來的問題就來了。首先，文檔上寫得不清不楚的參數(shù)，沒有試過，完全不知道它到底能不能 Work。其次，OpenAPI 總得有一定的權(quán)限認(rèn)證吧，那么總得有一個(gè)簽名啥的，每個(gè)客戶都要寫一遍，關(guān)鍵是總是沒法寫對。再次，不同的客戶所使用的編程語言不一樣，得把接口重新包裝才能用。
總算費(fèi)心費(fèi)力調(diào)通了接口，以為可以高枕無憂的時(shí)候，咋接口老是報(bào)錯(cuò)，網(wǎng)絡(luò)連不上，返回的數(shù)據(jù)不對，諸如此類。再往后，OpenAPI 可能總是要發(fā)生一點(diǎn)變化什么的，總是出現(xiàn)一些數(shù)據(jù)結(jié)構(gòu)發(fā)生變化，不兼容之類的問題。
一個(gè) OpenAPI 到最后，不光是用戶使用起來覺得很氣，作為維護(hù)者也是很艱難的。當(dāng)公布一個(gè) OpenAPI 后，第一步給出簡單的文檔后，會發(fā)現(xiàn)除了要把參數(shù)詳情寫得越來越完善準(zhǔn)確外，還得給出簽名算法，讓不同語言的開發(fā)者來接入。然而給出簽名算法后，會發(fā)現(xiàn)只有一些開發(fā)者能順利完成，大部分的開發(fā)者只能眼巴巴地請你幫忙提供一個(gè) SDK 。好吧，那就提供一下我最拿手的 Java 語言的簽名，提供一個(gè)核心 SDK 唄。
圖 2 第二代的 OpenAPI 會有 SDK 的實(shí)現(xiàn)，但僅有少許的語言支持
隨著這個(gè) OpenAPI 接口的用戶越來越多，一個(gè)客戶說我要用 C++ 來對接你，另一個(gè)客戶說我要用 Python 來對接你，于是，我一個(gè) Java 程序員，怎么就要寫那么多語言的 SDK 呢。沒有辦法，如果不提供良好的 SDK，客戶說，沒有 IDE 提示呢，我怎么寫代碼呢。
總而言之，在 OpenAPI 的應(yīng)用過程中，一件簡單的事情，會變得非常復(fù)雜：
上面這些要求，如果加上多種編程語言的條件，就會演變?yōu)橐患?xì)碎而又繁多的體力活。并且這中間不能有任何的變動，因?yàn)閮H僅是一點(diǎn)點(diǎn)的 OpenAPI 變動，就需要連帶整個(gè)下游發(fā)生變化。如果一個(gè)地方?jīng)]有保持一致，那么客戶問題就會出現(xiàn)。
圖 3 當(dāng)用戶量變多，OpenAPI 的提供者需要提供完善的工具及更多的編程語言支持
通常為了解決此類的問題，以及 OpenAPI 的諸如簽名校驗(yàn)，限流，生成 SDK 、文檔等等，業(yè)界通常會使用 API 網(wǎng)關(guān)來承擔(dān)這些橫向的責(zé)任。
然而，作為筆者所在的環(huán)境下，會發(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)都會出現(xiàn)
當(dāng)我們在抱怨使用不同產(chǎn)品的 OpenAPI/SDK 體驗(yàn)不一致，文檔不對，Demo 出錯(cuò)等等問題時(shí)，真不是因?yàn)樽鲞@些事情太難，而是太多，太瑣碎。一件簡單的事情，需要做一百次，也就不是簡單的事情了。
TeaDSL 是由阿里云開放平臺 SDK 團(tuán)隊(duì)主導(dǎo)設(shè)計(jì)的一門領(lǐng)域特定語言。主要用于解決如下問題：
因此 TeaDSL 的核心能力就是通過一種中間語法來描述 OpenAPI，提供類似編程語言的能力，來將 OpenAPI、SDK、Code Sample 等場景及語言有機(jī)地結(jié)合在一起。
在沒有 TeaDSL 之前，對于不同的網(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 等。
接下來簡單介紹 TeaDSL 是如何實(shí)現(xiàn)支持任意風(fēng)格的網(wǎng)關(guān)和多種編程語言的。
對于不同的 API 網(wǎng)關(guān)，或者不同產(chǎn)品的 OpenAPI 而言，它們之間的風(fēng)格可能都千差萬別，因此在很大的程度上，每種風(fēng)格的 OpenAPI 都有它自己的元數(shù)據(jù)定義格式。為了減少網(wǎng)關(guān)、風(fēng)格帶來的差異化，業(yè)界主要推動的方式是盡量采用標(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等場景下，無法使用上 Swagger 這樣強(qiáng)大的生態(tài)工具鏈。
為了解決這些問題，我們需要進(jìn)行兩步操作：
如果完成這兩個(gè)步驟，那么現(xiàn)實(shí)世界上的每一個(gè) OpenAPI，RESTful 或者非 RESTful 的，不需要做任何遷移，也能具有強(qiáng)大的工具鏈支持。
通過我們的研究發(fā)現(xiàn)，無論 OpenAPI 的參數(shù)是如何組成的，傳輸是 JSON，還是 XML，乃至自定義協(xié)議，OpenAPI 都是基于 HTTP 協(xié)議棧進(jìn)行提供的。也就是說，萬變不離其宗的是 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
},
}
對于不同風(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): stringtoXML(user: User): string
最終的結(jié)果就是：
__request.body = toJSON(user);__request.body = toXML(user);
更進(jìn)一步的過程是，我們會將一個(gè) OpenAPI 的請求/響應(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)格的辦法如下：
這些方法在不同的編程語言下具有不同的實(shí)現(xiàn)，但我們只要定義好統(tǒng)一的簽名，就能確保一致性：
function toXML(data: $Model): string;function toJSON(data: $Model): string;
以上就是 TeaDSL 如何實(shí)現(xiàn)支持任意網(wǎng)關(guān)的方案。整個(gè)過程相對抽象，網(wǎng)關(guān)間的那些具有差異化的風(fēng)格，統(tǒng)統(tǒng)交給這些方法去實(shí)現(xiàn)，留下來的就只有數(shù)據(jù)結(jié)構(gòu)。
如果只是能通過一種描述方式來描述不同的 OpenAPI 調(diào)用過程，只是完成了一半的工作。另一半的工作是如何將這種描述語言落地到不同的編程語言下。在過去，我們支持不同的編程語言，主要是基于模版的形式來生成不同語言的實(shí)際代碼。但這對我們來說仍然還有一些不足之處：
從上面的形式也看到，這個(gè)方案，被我們設(shè)計(jì)成了一種 DSL 代碼。因此它是具有自己的詞法、語法、語義規(guī)則的，在生成目標(biāo)編程語言代碼之前，會有一套自身的校驗(yàn)。DSL 的這些能力是模版所不具備的。
可能對于別的場合，采用 DSL 的形式并不多見。但對于前端工程師而言，這些年已經(jīng)見的較多了：CoffeeScript、Babel、JSX、TypeScript 等等。為此我們參考了諸多編程語言的設(shè)計(jì)，最終形成了自己的一套語法。并借鑒編譯器領(lǐng)域的轉(zhuǎn)譯方式，因此我們可以在模型一致的情況，生成到各種不同的編程語言下。
整個(gè) TeaDSL 的處理流程如下：
最終我們支持多種編程語言的場景主要有3個(gè)：
通過中間語言的強(qiáng)校驗(yàn)，生成到多種目標(biāo)場景，可以解決編程語言支持不全面的問題。同時(shí)也大幅節(jié)約 OpenAPI 維護(hù)者的精力成本，不需要反復(fù)手工地編寫不同編程語言下的 Code Sample。隨著對不同編程語言的支持逐步完善，這些中間 TeaDSL 代碼不需要任何操作，即可自動支持到新的編程語言下。
TeaDSL 的主要能力是支持到不同風(fēng)格的 OpenAPI，同時(shí)支持多語言的 SDK、Code Sample 目標(biāo)生成。最終的目的仍然是打通從 OpenAPI 定義到文檔、到 SDK、CLI 等 OpenAPI 使用場景下的一致性。提供給用戶更統(tǒng)一、專業(yè)、一致的使用體驗(yàn)。同時(shí)也大幅降低 OpenAPI 提供者用來支持用戶的成本，通過自動化的方式，節(jié)省精力的同時(shí)，還減少人為參與時(shí)導(dǎo)致的錯(cuò)誤。
目前 TeaDSL 在阿里云的一些 SDK 上已經(jīng)有所應(yīng)用，如：https://github.com/aliyun/aliyun-ccp。阿里云開放平臺在持續(xù)努力提升它的整個(gè)工具支持生態(tài)，以期望能建成比 Swagger 更適配的生態(tài)體系。
文章轉(zhuǎn)自微信公眾號@阿里云開發(fā)者
