源寶導讀：Web應用程序一般都是前后端分離的基本架構，而前后端很可能分別是兩撥人分別開發(fā)，前后端的接口連調成為高頻溝通的對象，開發(fā)內耗最大的也在這個環(huán)節(jié)。本文將分享如何基于OpenAPI將前后端接口協(xié)議標準化和自動化，從而大幅降低開發(fā)內耗。

一、背景

? 通常的前端開發(fā)中, 接口service層依靠人工閱讀接口文檔來手動書寫, 然而大部分工作是重復的, 骨架是相同的，只是接口數(shù)據(jù)和接口路徑等改變, 對于一個龐大的項目(比如接口數(shù)量幾百個), 并且客戶端存在多個情況下(比如h5和小程序還有android, IOS), 重復的勞動成倍增加, 而且維護起來也會非常麻煩和不可靠。

? 重復的工作是，后端開發(fā)人員開發(fā)了一套接口, ?前端開發(fā)又書寫了同樣一遍接口, 而且還要生成文檔, 而這些接口可以統(tǒng)一成一份與語言無關的結構化的描述, 前端可以利用code-gen自動生成可調用的service層。

? 而且對于現(xiàn)在基于Typescript前端的開發(fā), ?接口協(xié)議生成的數(shù)據(jù)interface應該直接拿來使用, 用來約束各個業(yè)務模塊的數(shù)據(jù)結構, 如果要組合生成新的數(shù)據(jù)結構, 應該使用Typescript的高級類型來組合生成(比如Pick<>,Required<>, Partial<>, Omit<>), ?這樣前端的業(yè)務組件數(shù)據(jù)結構將和接口協(xié)議描述保持一致。

1.1 傳統(tǒng)前端后端聯(lián)調模式問題: 不可靠, 重復工作量, 低效

• 整個過程寫了兩份協(xié)議, 服務端一份, 客戶端一份, 工作重復。

• 聯(lián)調周期很長,并且需要不斷的重復溝通, B發(fā)布了一項接口參數(shù)更新, 需要通知C去查看文檔, 那么C有這么一個待辦事項, 什么時候執(zhí)行大多數(shù)時候不得而知, 過了一段時間C查看了文檔之后發(fā)現(xiàn)有幾個地方不合理, 那么又通知B, 這樣聯(lián)調的周期又延時又低效。

• 令人忽視的一點是注釋, 同一個接口描述, 同一個參數(shù)的描述可能存在3種描述, 這可能讓團隊每個人對業(yè)務的理解都不一樣。

1.2 Typescript前端項目的特點

1.2.1 可使用豐富的高級派生類型

• 業(yè)務模塊中的子組件的數(shù)據(jù)結構一般是派生的子類型

• 當SampleInterface結構發(fā)生變化,派生的類型會自動繼承其中的屬性, 如果有沖突, ts會給出錯誤提示

1.2.2 開發(fā)過程數(shù)據(jù)結構優(yōu)先

• 前端的業(yè)務模塊中:顯示, 交互等與用戶相關的功能操作都是圍繞數(shù)據(jù)來進行。

• 前端開發(fā), 擴展, 維護和重構等工作也是圍繞數(shù)據(jù)來進行。

• 并且業(yè)務模塊的數(shù)據(jù)結構與接口的數(shù)據(jù)結構有很強的關聯(lián)性。

基于以上特點將數(shù)據(jù)結構定義來源單一化, 使業(yè)務數(shù)據(jù)定義更合理：

• 單一源化數(shù)據(jù)結構定義, 有利于統(tǒng)一維護, 利于重構。

• 當service接口數(shù)據(jù)結構發(fā)生變化, 那么派生的數(shù)據(jù)結構會自動適應, 如果有錯誤, 能夠根據(jù)Typescript語法提示完成重構, 最后再根據(jù)語法提示修改相關的業(yè)務相關的組件。

• 前端業(yè)務組件大部分數(shù)據(jù)結構與API接口的數(shù)據(jù)結構是關聯(lián)的。

能不能通過某種接口協(xié)議自動生成Typescript的接口定義呢?
Swagger Open API協(xié)議, ?protobuf協(xié)議等都是可以描述RESTFul API接口。

二、前后端聯(lián)調的優(yōu)化解決方案: 以API協(xié)議為中心

• 按照之前的思路的理解: 特定的業(yè)務邏輯的數(shù)據(jù)結構在不同的業(yè)務組件中是高度一致的, 一個數(shù)據(jù)結構的定義應該只存在一份, 不應該手寫多份。

• 前后端維護唯一一個的規(guī)范來描述接口定義。

• 不同的客戶端語言可以根據(jù)這個協(xié)議生成可執(zhí)行的接口。

2.1 步驟

2.1.1 基于Open API Specification (Swagger)協(xié)議的轉換研究

? OAS用來定義一個標準的, 與編程語言無關的RESTFul API的接口, ?可提供給計算機解析, 也可進行人工閱讀和分析, 是一種能結構化描述API接口的約定, 而目前主流的文檔生成工具都支持這種標準, 可實現(xiàn)個性化需求。

? OAP協(xié)議可以用JSON Schema來定義, 詳細可看:? https://swagger.io /specification /v2/

基本結構:

對應的Typescript示例:

2.1.2 生成Typescript目標代碼實際項目中的分析

? 命名空間根據(jù)項目的業(yè)務模塊來區(qū)分, 在Swagger協(xié)議中一般在tags里做為標記：

2.1.3 利用模板引擎mustache生成代碼

• 使用編程語言將原始的Swagger JSON轉換成更加直接并且有豐富變量的模板數(shù)據(jù)。

• mustache模板是根據(jù)項目實際來設定, 靈活使用不同模板生成不同的目標代碼。

• 遇到少量 的特殊的接口, 可以過濾不生成, 然后手動實現(xiàn)接口即可。

• 具體項目在 https://github.com/mmmy/swagger-typescript-gen。

2.2 實踐結果

? 參考了一個nodejs的開源轉換工具, 修改增加了模板數(shù)據(jù)變量和模板：

• Pulsar前端接口220+, code-gen生成了7000+行代碼。

• dmp前端接口250+, code-gen生成了9000+行代碼。

? 后端生成的Swagger response中字段缺少必填屬性和枚舉屬性, 生成的接口相應Typescript數(shù)據(jù)結構都是可選參數(shù)。

? ?遇到的問題：類似遞歸的結構暫時無法生成：

? 遇到少量接口不能實現(xiàn), 可以手動實現(xiàn)該接口。

? 不需要看api文檔, 卻能發(fā)現(xiàn)文檔的很多問題：接口定義了一個query參數(shù) 還有一個類型為json的body參數(shù)。

? 還有少量的接口未定義返回參數(shù), 實際上有返回參數(shù)。

2.2.1 帶來的優(yōu)勢

• ?一致性

? ? ? 前端的接口調用參數(shù), 描述等任何信息將與協(xié)議一鍵同步。

• ?重構優(yōu)勢

? ? ? 如果業(yè)務邏輯上接口發(fā)生變化, 將會自動影響相關的業(yè)務組件, 按照Typescirpt的提示能完成絕大部分工作。

• ?減少工作量

? 前端不需要再去查看API文檔, 手動同步書寫接口代碼, 后期維護也是維護源頭的協(xié)議。

三、結合Typescript開發(fā)模式進一步優(yōu)化

? 假設所有的模塊都是具有完備的typescript設計和定義,為什么運行時還是會報語法錯誤, 類型錯誤?

? Javasctript本身是動態(tài)弱類型語言, 運行時并不能保證紅色箭頭輸入是合法的, 比如預期某個接口返回一個值為對象Object, 但是實際返回了一個null, 為了兼容, 不得不在每個組件中對很多值進行空值判斷, 來防止運行錯誤, 實際上不應該在B中做無意義的判斷, 因為在組件A中已經給了B正確的類型輸入, 正確的做法是處理和兼容紅色的輸入, 來確保輸入到A的值是合法的, 所以你對輸入數(shù)據(jù)不確定的代碼處才是問題的根本, 這和Tyepscript本身沒有關系。

3.1 在數(shù)據(jù)進入組件之前進行糾錯, 前端0錯誤成為可能

? 假設服務端的數(shù)據(jù)完整性是不可靠的, 比如對象和數(shù)組可能是null, 但是協(xié)議定義的卻是必要的, 不能是null, 這樣給前端運行時帶來風險, 所有對這些空字段可以做空默認值處理, 這個操作可以在前端獲取到數(shù)據(jù)的時進行校驗并賦予默認值, 這樣業(yè)務組件拿到的數(shù)據(jù)不會存在空類型操作錯誤。

四、總結與展望

• 基于協(xié)議為中心的前后端聯(lián)調模式可以為軟件開發(fā)帶來益處, 特別是對于Typescript項目, 摒棄掉了低效的重復的工作, 讓工作更集中在具體的業(yè)務實現(xiàn)方案上。

• 本次研究只是實現(xiàn)了基本的RESTFul的常規(guī)接口,模板也相對復雜度不高, 并不能完全處理通用Swagger協(xié)議,比如參數(shù)在路徑中, 不同http狀態(tài)碼的處理。

• 對于其他平臺還需研究, 比如小程序, Android(Java), IOS(Object-C)。

------ END ------

作者簡介

楊同學：?前端工程師，目前在云技術創(chuàng)新中心負責DMP產品的研發(fā)工作。

也許您還想看

云客后臺優(yōu)化的“前世今生”(一)

云客后臺優(yōu)化的“前世今生”(二)

在明源云客，一個全新的服務會經歷什么？

“弱中心”化的分布式配置管理技術可行性探索

基于 Go 的微服務運行情況監(jiān)控實踐

總結

以上是生活随笔為你收集整理的Typescript前端接口联调自动化的探究与实践的全部內容，希望文章能夠幫你解決所遇到的問題。

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