一、背景

商業(yè)側(cè)的業(yè)務(wù)比較復(fù)雜，B端項(xiàng)目中含有大量常量類的類型判斷，且因歷史原因，很多常量值前端無(wú)法直接知其含義，這既不利于新人的上手，也不利于項(xiàng)目的維護(hù)。

在開(kāi)發(fā)協(xié)作上，前后端的API溝通，大都通過(guò)配置swagger api來(lái)進(jìn)行，要不就是口口相傳或者通過(guò)寫(xiě)info文檔來(lái)定義結(jié)構(gòu)、入?yún)⒓俺鰠?，這種協(xié)作方式不僅溝通成本高，且前端缺少能主動(dòng)感知后端API變更的手段。

同時(shí)，為了提高項(xiàng)目的可維護(hù)性，組內(nèi)推動(dòng)前端項(xiàng)目TS工程化，在改造過(guò)程中，也會(huì)因?yàn)闃I(yè)務(wù)迭代，需要?jiǎng)?chuàng)建新的項(xiàng)目，而新項(xiàng)目TS工程化的過(guò)程，不僅需要自定義大量的類型，也需要定義后端API類型參數(shù)，如果全部通過(guò)手動(dòng)敲，代價(jià)太大，不僅很容易出錯(cuò)，也會(huì)影響業(yè)務(wù)的開(kāi)發(fā)效率。

因此，為了提升開(kāi)發(fā)協(xié)作效率，增加前端主動(dòng)感知API的能力，提升項(xiàng)目的可維護(hù)性和開(kāi)發(fā)效率，開(kāi)發(fā)實(shí)現(xiàn)了TS自動(dòng)化生成工具。

二、核心功能

1. 自動(dòng)生成api函數(shù)體結(jié)構(gòu)
2. 自動(dòng)化生成api interface
3. 自動(dòng)生成本地mock file
4. 支持自定義模版輸出改造
5. 支持駝峰與下劃線轉(zhuǎn)換輸出
6. 支持自定義header改造
7. 同時(shí)支持swagger api v2和v3版本

三、轉(zhuǎn)換原理

swagger api doc的文檔結(jié)構(gòu)

圖片

關(guān)鍵屬性拆分：

圖片

注：Template Function可根據(jù)實(shí)際情況進(jìn)行覆蓋，默認(rèn)是商業(yè)側(cè)的模版輸出格式。

四、項(xiàng)目接入

工具地址：（Package - @bilibili-business/ad-swagger-fe）

接入步驟：

1.安裝

npm install @bilibili-business/ad-swagger-fe --registry=http://registry.npm.bilibili.co

2.配置模版文件，在項(xiàng)目根目錄下新建swagger.config.js文件（目錄按需）

3.可將示例代碼（下方文檔中）可以直接copy到swagger.config.js文件中

4.替換修改代碼中的source地址，將其替換成目標(biāo)swagger doc地址

5.命令行中執(zhí)行：node ./swagger.config.js

6.項(xiàng)目中的src目錄下，會(huì)多出一個(gè)swagger文件夾，即為生成的目標(biāo)文件

7.可以根據(jù)生成的內(nèi)容，調(diào)整工具參數(shù)，包括header

模版示例代碼

圖片

五、項(xiàng)目實(shí)踐

目前該工具已在商業(yè)前端項(xiàng)目中推廣并廣泛使用，商業(yè)側(cè)整體接入率85%， 帶貨項(xiàng)目接入率100%。

生成的API函數(shù)和TS interface 可直接使用，無(wú)需手動(dòng)編碼，業(yè)務(wù)開(kāi)發(fā)效率提升1pd。

舉例：后端API接口數(shù)1556個(gè)

圖片

通過(guò)工具生成的代碼

• 生成的API實(shí)例

圖片

• 生成的Interface

圖片

• 在項(xiàng)目中直接使用

圖片

本期作者

楊雨浩嗶哩嗶哩資深開(kāi)發(fā)工程師