TypeScript + React最佳實踐 - 第三節：Service類型化（1） - sm2tsservice技術方案介紹

前言

TypeScript + React 類型安全三件套：Component、Redux、和Service類型化。

Service 類型化

通用基礎方案

規範和基礎類型

首先須要明確先後端交互的基本接口規範，例如，全部接口返回數據格式都應該遵循：

interface AjaxResult<R extends any> {
    /** 錯誤碼 */
    code?: number | null;
    /** 描述信息 */
    message?: string | null;
    /** 數據主體 */
    result: R
}
複製代碼

而對應的，全部接口調用函數應該遵循這樣接口定義：

interface AjaxFunction {
    (...args: any[]): Promise<AjaxResult<any>>
}
複製代碼

業務邏輯裏須要明確的就是，接口定義裏入參和響應數據主體的類型。

示例

舉個獲取用戶信息接口例子，經過後端提供的任意格式的文檔，好比 swagger、yapi 甚至 wiki 得知：

• url 是 /api/user/info
• 需傳遞一個數字類型 get 參數 id
• 返回數據主體是包含數字 id、字符串 name 的一個對象

手寫成 TypeScript 調用代碼：

/** 後端數據主體 */
interface UserResult {
    /** id */
    id: number;
    /** 英文名 */
    name: string;
}

/** 接口調用代碼 */
const getUserInfo = (id: number): AjaxResult<UserResult> => axios.get('/api/user/info', { id })
複製代碼

sm2tsservice 方案 【will be @tefe/service】

從前邊的例子，可知 Service 類型化真正的痛點在於基於接口文檔手寫 TypeScript 代碼，在已有 swagger 或者 yapi 文檔格式化數據的狀況下，這無異於重複的人力浪費，找到一套自動化生成技術方案，將極大的提高研發效率。

swagger-codegen

基於 Java 代碼註解提取文檔的 Swagger 體系裏，有提供了全套的 Java 註解、註解解析、文檔UI界面以及生成各類語言調用代碼的技術工具方案 Swagger-Codegen。

該方案支持生成 TypeScript 類型、接口調用代碼，其核心數據轉換、生成規則以下：

基於以上規則，咱們很容易發現，該方案存在如下隱患：

• Tags註解不爲空，變動註解或者註解爲空，變動Controller Name，都會形成Tags值變更，進而形成生成的文件名變更；
• API註解不爲空，註解重複或者註解爲空，Method Name重複，當重複的Method Name順序變動的時候，會形成operationId值變更；
• 當Method參數順序發生變動的時候，會形成對應接口調用代碼的參數變動。

這些隱患會致使當知足特定條件時，生成的代碼會發生不可控的變更，進而致使邏輯錯亂，形成十分嚴重的後果。

sm2tsservice

sm2tsservice 改造了 swagger-codegen，並在此基礎上進行了封裝，旨在解決業務使用上的痛點：

• 實現 yapi 轉 swagger 文檔模塊，支持 yapi 自動生成接口調用代碼
• 制定 swagger 文檔編寫規範，提高先後端協做效率
• 實現 swagger 文檔規範校驗、規則校訂模塊，確保生成代碼穩定性
• 實現 swagger 文檔增量更新模塊，更靈活的控制代碼生成
• 實現接口入參、數據返回校驗模塊，利用 swagger 文檔對數據進行校驗

yapi 轉 swagger 規則

將 yapi 文檔轉換成 swagger 文檔，曲線支持 yapi 自動生成 service 代碼，轉換規則以下：

swagger 文檔規範

接口規範，旨在消除人爲形成的不肯定性，其中核心條目包括：

swagger 校驗、校訂模塊

校驗 swagger 文檔是否符合規範，校訂 operationId 的生成方式，核心規則以下：

定製 swagger-codegen 代碼，修改調用函數格式：

增量更新

將接口文檔分爲本地和遠端版本，本地版本跟隨 vcs 進行維護；每次生成代碼，會下載遠端版本，而後與本地版本進行 diff，將差別已 web 界面的形式顯示出來，供選擇任意差別、增量更新：

雙向校驗

提供 proxy 插件，可在聯調階段對接口入參、後端返回，依照對應的 swagger 文檔約定進行校驗，默承認以打印出不符合約定的接口錯誤。

More

• sm2tsservive文檔站
• 增量更新技術方案 json-diff
• 代碼生成方案 定製 swagger-codegen