記一次在老掉牙的Vue2項目中引入TypeScript和組合式Api和vueuse來改善大家伙的開發(fā)體驗的艱辛歷程

封面

原由

現(xiàn)有的一個項目2年前創(chuàng)建的，隨著時間流逝，代碼量已經(jīng)暴增到了將近上萬個文件，但是工程化已經(jīng)慢慢到了不可維護的狀態(tài)，想給他來一次大換血，但是侵入式代碼配置太多了……，最終以一種妥協(xié)的方式引入了TypeScript、組合式Api、vueuse，提升了項目的工程化規(guī)范程度，整個過程讓我頗有感概，記錄一下。

先配置TypeScript相關(guān)的

一些庫的安裝和配置

  1. 由于webpack的版本還是3.6，嘗試數(shù)次升級到4、5都因為大量的配置侵入性代碼的大量修改工作放棄了，所以就直接找了下面這些庫
npm i -D ts-loader@3.5.0 tslint@6.1.3 tslint-loader@3.6.0 fork-ts-checker-webpack-plugin@3.1.1
  1. 接下來就是改webpack的配置了，修改main.js文件為main.ts,并在文件的第一行添加// @ts-nocheck讓TS忽略檢查此文件，在webpack.base.config.js的入口中相應(yīng)的改為main.ts
  2. 在webpack.base.config.js的resolve中的extensions中增加.ts和.tsx,alias規(guī)則中增加一條'vue$': 'vue/dist/vue.esm.js'
  3. 在webpack.base.config.js中增加plugins選項添加fork-ts-checker-webpack-plugin，將ts check的任務(wù)放到單獨的進程中進行，減少開發(fā)服務(wù)器啟動時間
  4. 在 webpack.base.config.js文件的rules中增加兩條配置和fork-ts-checker-webpack-plugin的插件配置
{
  test: /\.ts$/,
  exclude: /node_modules/,
  enforce: 'pre',
  loader: 'tslint-loader'
},
{
  test: /\.tsx?$/,
  loader: 'ts-loader',
  exclude: /node_modules/,
  options: {
    appendTsSuffixTo: [/\.vue$/],
    transpileOnly: true // disable type checker - we will use it in fork plugin
  }
},,
// ...
plugins: [new ForkTsCheckerWebpackPlugin()], // 在獨立進程中處理ts-checker，縮短webpack服務(wù)冷啟動、熱更新時間 https://github.com/TypeStrong/ts-loader#faster-builds
  1. 根目錄中增加tsconfig.json文件補充相應(yīng)配置，src目錄下新增vue-shim.d.ts聲明文件

tsconfig.json

{
  "exclude": ["node_modules", "static", "dist"],
  "compilerOptions": {
    "strict": true,
    "module": "esnext",
    "outDir": "dist",
    "target": "es5",
    "allowJs": true,
    "jsx": "preserve",
    "resolveJsonModule": true,
    "downlevelIteration": true,
    "importHelpers": true,
    "noImplicitAny": true,
    "allowSyntheticDefaultImports": true,
    "moduleResolution": "node",
    "isolatedModules": false,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "lib": ["dom", "es5", "es6", "es7", "dom.iterable", "es2015.promise"],
    "sourceMap": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
    },
    "pretty": true
  },
  "include": ["./src/**/*", "typings/**/*.d.ts"]
}

vue-shim.d.ts

declare module '*.vue' {
  import Vue from 'vue'
  export default Vue
}

路由配置的改善

原有路由配置是通過配置path、name和component，這樣在開發(fā)和維護的過程中有一些缺點：

  1. 使用的時候可能出現(xiàn)使用path或者使用name不規(guī)范不統(tǒng)一的情況
  2. 開發(fā)人員在維護老代碼的時候查找路由對應(yīng)的單文件不方便
  3. 要手動避免路由的name和path不與其他路由有沖突

將所有的路由的路徑按照業(yè)務(wù)抽離到不同的枚舉中。在枚舉中定義可以防止路由 path 沖突，也可以將枚舉的 key 定義的更加語義化，又可以借助Typescript的類型推導(dǎo)能力快速補全，在查找路由對應(yīng)單文件的時候可以一步到位

為什么不用name，因為name只是一個標(biāo)識這個路由的語義，當(dāng)我們使用枚舉類型的path之后，枚舉的Key就足以充當(dāng)語義化的路徑path這個name屬性就沒有存在的必要了，我們在聲明路由的時候就不需要聲明name屬性，只需要path和component字段就可以了

demo

export enum ROUTER {
  Home = '/xxx/home',
  About = '/xxx/about',
}

export default [
  {
    path: ROUTER.Home,
    component: () => import( /* webpackChunkName:'Home' */ 'views/Home')
  },
  {
    path: ROUTER.About,
    component: () => import( /* webpackChunkName:'About' */ 'views/About')
  }
]

常量和枚舉

之前在我們項目中也是通過把所有的常量抽離到services/const中進行管理，現(xiàn)在集成了Typescript之后，我們就可以在之后項目在services/constant中進行管理常量，在services/enums中管理枚舉。

比如常見的接口返回的code就可以聲明為枚舉，就不用在使用的時候還需要手寫if (res.code === 200)類似的判斷了，可以直接通過聲明好的RES_CODE枚舉直接獲取到所有的接口返回code類型

// services/enums/index.ts
/** RES_CODE Enum */
export enum RES_CODE {
  SUCCESS = 200
  // xxx
}

比如storage的key我們就可以聲明在services/constant/storage.ts中

/** userInfo-storageKey */
export const USERINFO_STORE_KEY = 'userInfo'

/** 與用戶相關(guān)的key可以通過構(gòu)造一個帶業(yè)務(wù)屬性參數(shù)的純函數(shù)來聲明 */
export const UserSpecialInfo = (userId: string) => {
  return `specialInfo-${userId}`
}

類型聲明文件規(guī)范

全局類型聲明文件統(tǒng)一在根目錄的typings文件夾中維護（可復(fù)用的數(shù)據(jù)類型）

比較偏業(yè)務(wù)中組裝數(shù)據(jù)過程中的類型直接在所在組件中維護即可（不易復(fù)用的數(shù)據(jù)結(jié)構(gòu)）

接口中的類型封裝

請求基類封裝邏輯

在 utils 文件夾下新增requestWrapper.ts文件，之后所有的請求基類方法封裝可以在此文件中進行維護

// src/utils/requestWrapper.ts
import { AxiosResponse } from 'axios'
import request from '@/utils/request'

// 請求參數(shù)在之后具體封裝的時候才具體到某種類型，在此使用unknown聲明，返回值為泛型S，在使用的時候填充具體類型
export function PostWrapper<S>(
  url: string,
  data: unknown,
  timeout?: number
) {
  return (request({
    url,
    method: 'post',
    data,
    timeout
  }) as AxiosResponse['data']) as BASE.BaseResWrapper<S> // BASE是在typings中定義的一個命名空間 后面會有代碼說明
}

在具體的業(yè)務(wù)層進行封裝后的使用

在api/user中新建一個index.ts文件，對比之前的可以做到足夠簡潔，也可以提供類型提示，知曉這個請求是什么請求以及參數(shù)的參數(shù)以及返回值

import { PostWrapper } from '@/utils/requestWrapper'

// 此處只需要在注釋中標(biāo)注這個接口是什么接口，不需要我們通過注釋來標(biāo)識需要什么類型的參數(shù)，TS會幫我們完成, 只需要我們填充請求參數(shù)的類型和返回參數(shù)的類型即可約束請求方法的使用
/** 獲取用戶信息 */
export function getUserInfo(query: User.UserInfoReqType) {
  return PostWrapper<User.UserInfoResType>(
    '/api/userinfo',
    query
  )
}
  • 需要提供類型支持的接口，需要聲明在api/**/*.ts文件中，并通過給對應(yīng)的function標(biāo)注參數(shù)請求類型和響應(yīng)類型
  • 如果結(jié)構(gòu)極為簡潔，可以不需要在typings/request/*.d.ts中維護，直接在封裝接口處聲明類型即可，如果參數(shù)稍多，都應(yīng)在typings/request/*.d.ts中維護，避免混亂

現(xiàn)在業(yè)務(wù)中的服務(wù)端的接口返回的基本都是通過一層描述性對象包裹起來的，業(yè)務(wù)數(shù)據(jù)都在對象的request字段中，基于此我們封裝接口就在typings/request/index.d.ts中聲明請求返回的基類結(jié)構(gòu)，在具體的xxx.d.ts中完善具體的請求類型聲明，例如user.d.ts中的一個報錯的接口，在此文件中聲明全局的命名空間User來管理所有此類作業(yè)接口的請求和響應(yīng)的數(shù)據(jù)類型

typings/request/index.d.ts

import { RES_CODE } from '@/services/enums'

declare global {
  // * 所有的基類在此聲明類型
  namespace BASE {
    // 請求返回的包裹層類型聲明提供給具體數(shù)據(jù)層進行包裝
    type BaseRes<T> = {
      code: RES_CODE
      result?: T
      info?: string
      time: number
      traceId: string
    }
    type BaseResWrapper<T> = Promise<BASE.BaseRes<T>>
    // 分頁接口
    type BasePagination<T> = {
      content: T
      now: string
      page: number
      size: number
      totalElements: number
      totalPages: number
    }
  }

typings/request/user.d.ts

declare namespace User {

/** 響應(yīng)參數(shù) */
type UserInfoResType = {
  id: number | string
  name: string
  // ...
}

/** 請求參數(shù) */
type UserInfoReqType = {
  id: number | string
  // ...
}

到此TypeScript相關(guān)的就結(jié)束了，接下來是組合式Api的

Vue2中使用組合式Api

  1. 安裝@vue/componsition-api 
npm i @vue/componsition-api
  1. 在 main.ts 中use即可在.vue文件中使用組合式 API
import VueCompositionAPI from '@vue/composition-api'
// ...
Vue.use(VueCompositionAPI)

Vue2 中使用組合式 Api 中的一些注意事項

  1. 組合式 Api文檔，不了解的小伙伴可以先參照文檔學(xué)習(xí)一下，在比較復(fù)雜的頁面，組件多的情況下組合式 API 相比傳統(tǒng)的Options API更靈活，可以把邏輯抽離出去封裝為單獨的use函數(shù)，使組件代碼結(jié)構(gòu)更為清晰，也更方便復(fù)用業(yè)務(wù)邏輯。
  2. 所有的組合式 Api 中的api都需要從@vue/composition-api中引入，然后使用export default defineComponent({ })替換原有的export default { }的寫法，即可啟用組合式 Api 語法和Typescript的類型推導(dǎo)(script需要添加對應(yīng)的lang="ts"的attribute)
  3. template中的寫法和Vue2中一致，無需注意Vue3中的v-model和類似.native的事件修飾符在Vue3中取消等其他的break change
  4. 子組件中調(diào)用父組件中的方法使用setup(props, ctx)中的ctx.emit(eventName, params)即可，給Vue實例對象上掛載的屬性和方法都可以通過ctx.root.xxx來獲取，包括$route、$router等，為了使用方便推薦在setup中第一行就通過結(jié)構(gòu)來聲明ctx.root上的屬性,，如果之前在Vue實例對象上添加的有業(yè)務(wù)屬性相關(guān)的屬性或方法可以通過擴展模塊vue/types/vue上的Vue接口來添加業(yè)務(wù)屬性相關(guān)的類型：

typings/common/index.d.ts

// 1. Make sure to import 'vue' before declaring augmented types
import Vue from 'vue'
// 2. Specify a file with the types you want to augment
//    Vue has the constructor type in types/vue.d.ts
declare module 'vue/types/vue' {
  // 3. Declare augmentation for Vue
  interface Vue {
    /** 當(dāng)前環(huán)境是否是IE */
    isIE: boolean
    // ... 各位根據(jù)自己的業(yè)務(wù)情況自行添加
  }
}
  1. 所有template中使用到的變量、方法、對象都需要在setup中return，其他的在頁面邏輯內(nèi)部使用的不需要return
  2. 推薦根據(jù)頁面展示元素和用戶與頁面的交互行為定義setup中的方法，比較復(fù)雜的邏輯細節(jié)和對數(shù)據(jù)的處理盡量抽離到外部，保持.vue文件中的代碼邏輯清晰
  3. 在需求開發(fā)前，根據(jù)服務(wù)端接口數(shù)據(jù)的定義，來制定頁面組件中的數(shù)據(jù)和方法的接口，可以提前聲明類型，之后在開發(fā)過程中實現(xiàn)具體的方法
  4. 在當(dāng)下的Vue2.6版本中通過@vue/composition-api使用組合式 Api 不能使用setup語法糖，待之后的Vue2.7版本release之后再觀察，其他的一些 注意事項和限制

基于 reactive 的 store 的風(fēng)格規(guī)范

鑒于在Vuex中接入TS的不便和Vuex使用場景的必要性，在組合式 Api 中提供了一個最佳實踐：將需要響應(yīng)的數(shù)據(jù)聲明在一個ts文件中通過reactive包裹初始化對象，暴漏出一個更新的方法，即可達到原有在Vuex中更新store中state的效果，使用computed可以達到getter的效果，哪些組件需要對數(shù)據(jù)進行獲取和修改只需要引入即可，更改直接就可以達到響應(yīng)效果！

提供一份Demo，各位對于這部分內(nèi)容的封裝可以見仁見智

// xxxHelper.ts
import { del, reactive, readonly, computed, set } from '@vue/composition-api'

// 定義store中數(shù)據(jù)的類型，對數(shù)據(jù)結(jié)構(gòu)進行約束
interface CompositionApiTestStore {
  c: number
  [propName: string]: any
}

// 初始值
const initState: CompositionApiTestStore = { c: 0 }

const state = reactive(initState)

/** 暴露出的store為只讀，只能通過下面的updateStore進行更改 */
export const store = readonly(state)

/** 可以達到原有Vuex中的getter方法的效果 */
export const upperC = computed(() => {
  return store.c.toUpperCase()
})

/** 暴漏出更改state的方法，參數(shù)是state對象的子集或者無參數(shù)，如果是無參數(shù)就便利當(dāng)前對象，將子對象全部刪除, 否則俺需更新或者刪除 */
export function updateStore(
  params: Partial<CompositionApiTestStore> | undefined
) {
  console.log('updateStore', params)
  if (params === undefined) {
    for (const [k, v] of Object.entries(state)) {
      del(state, `${k}`)
    }
  } else {
    for (const [k, v] of Object.entries(params)) {
      if (v === undefined) {
        del(state, `${k}`)
      } else {
        set(state, `${k}`, v)
      }
    }
  }
}

vueuse

vueuse是一個很好用的庫，具體的安裝和使用非常簡單，但是功能很多很強大，這部分我就不展開細說了，大家去看官方文檔吧！

總結(jié)

這次的項目升級實在是迫不得已，沒辦法的辦法，項目已經(jīng)龐大無比還要兼容IE，用的腳手架及相關(guān)庫也都很久沒有更新版本，在項目創(chuàng)建開始就已經(jīng)欠下了很多的技術(shù)債了，導(dǎo)致后面開發(fā)維護人員叫苦不迭（其實就是我，項目是別個搞的，逃…），各位老大哥在新起項目的時候一定要斟酌腳手架和技術(shù)棧啊，不要前人挖坑后人填了……

如果你也在維護這樣的項目，并且也受夠了這種糟糕的開發(fā)體驗，可以參照我的經(jīng)驗來改造下你的項目，如果看過感覺對你有幫助，也請給個一鍵三連~

最后編輯于 ：
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時請結(jié)合常識與多方信息審慎甄別。
平臺聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點，簡書系信息發(fā)布平臺，僅提供信息存儲服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

友情鏈接更多精彩內(nèi)容