商業(yè)前端TS開發(fā)自動化工具
一、背景
商業(yè)側的業(yè)務比較復雜,B端項目中含有大量常量類的類型判斷,且因歷史原因,很多常量值前端無法直接知其含義,這既不利于新人的上手,也不利于項目的維護。
在開發(fā)協(xié)作上,前后端的API溝通,大都通過配置swagger api來進行,要不就是口口相傳或者通過寫info文檔來定義結構、入參及出參,這種協(xié)作方式不僅溝通成本高,且前端缺少能主動感知后端API變更的手段。
同時,為了提高項目的可維護性,組內推動前端項目TS工程化,在改造過程中,也會因為業(yè)務迭代,需要創(chuàng)建新的項目,而新項目TS工程化的過程,不僅需要自定義大量的類型,也需要定義后端API類型參數(shù),如果全部通過手動敲,代價太大,不僅很容易出錯,也會影響業(yè)務的開發(fā)效率。
因此,為了提升開發(fā)協(xié)作效率,增加前端主動感知API的能力,提升項目的可維護性和開發(fā)效率,開發(fā)實現(xiàn)了TS自動化生成工具。
二、核心功能
- 自動生成api函數(shù)體結構
- 自動化生成api interface
- 自動生成本地mock file
- 支持自定義模版輸出改造
- 支持駝峰與下劃線轉換輸出
- 支持自定義header改造
- 同時支持swagger api v2和v3版本
三、轉換原理
swagger api doc的文檔結構
圖片
關鍵屬性拆分:
圖片
注:Template Function可根據實際情況進行覆蓋,默認是商業(yè)側的模版輸出格式。
四、項目接入
工具地址:(Package - @bilibili-business/ad-swagger-fe)
接入步驟:
1.安裝
npm install @bilibili-business/ad-swagger-fe --registry=http://registry.npm.bilibili.co
2.配置模版文件,在項目根目錄下新建swagger.config.js文件(目錄按需)
3.可將示例代碼(下方文檔中)可以直接copy到swagger.config.js文件中
4.替換修改代碼中的source地址,將其替換成目標swagger doc地址
5.命令行中執(zhí)行:node ./swagger.config.js
6.項目中的src目錄下,會多出一個swagger文件夾,即為生成的目標文件
7.可以根據生成的內容,調整工具參數(shù),包括header
模版示例代碼
圖片
五、項目實踐
目前該工具已在商業(yè)前端項目中推廣并廣泛使用,商業(yè)側整體接入率85%, 帶貨項目接入率100%。
生成的API函數(shù)和TS interface 可直接使用,無需手動編碼,業(yè)務開發(fā)效率提升1pd。
舉例:后端API接口數(shù)1556個
圖片
通過工具生成的代碼
- 生成的API實例
圖片
- 生成的Interface
圖片
- 在項目中直接使用
本期作者
楊雨浩嗶哩嗶哩資深開發(fā)工程師