作者：來自 vivo 網際網路大前端團隊- Wei Xing
在研發專案過程中，我們經常會遇到技術架構迭代更新的需求，透過技術的迭代更新，讓專案從新的技術特性中受益，但由於很多新的技術迭代版本並不能完全向下相容，包含了很多非相容性的改變（Breaking Changes），因此我們需要設計一款工具，幫助我們完成大規模程式碼自動遷移問題。本文簡單闡述了基於 AST 的程式碼遷移概念和大致流程，並透過程式碼案例帶大家瞭解到了其中的處理細節。
一、背景介紹
在研發專案過程中，我們經常會遇到技術架構迭代更新的需求，透過技術的迭代更新，讓專案從新的技術特性中受益。例如將 Vue 2 遷移至 Vue 3、Webpack 4 升級 Webpack 5、構建工具遷移至 Vite 等，這些技術架構的升級能讓專案持續受益，獲得諸如可維護性、效能、擴充套件性、編譯速度、可讀性等等方面的提升，適時的對專案進行技術架構更新是很有必要的。
那既然新特性這麼好，有人會說那當然要與時俱進，隨時更新了。
但問題在於很多新的技術迭代版本並不能完全向下相容，包含了很多非相容性的改變（Breaking Changes），並不是簡單升個版本就行了，通常還需要投入不少的人力和學習成本。例如 Vue 3 只能相容 80%的 Vue 2 程式碼，對於一些新特性、新語法糖，開發者只能參考官方提供的遷移文件，手動完成遷移。
（圖片來源：freecodecamp）
1.1 Vue 3 程式碼遷移案例
來看一個 Vue 3 的程式碼遷移案例，在 Vue 2 和 Vue 3 中宣告一個全域性指令（Directive）的差異：
（1）Vue 2：允許直接在 Vue 原型上註冊全域性指令。而在 Vue 3 中，為了避免多個 Vue 例項產生指令混淆，已經不再支援該寫法。
import Vue from 'vue'
Vue.directive('focus', {
inserted: (el) => el.focus()
})
（2）Vue 3：建議透過 createApp 建立 Vue 例項，並直接在例項上註冊全域性指令。就像這樣：
import { createApp } from 'vue'
const app = createApp({})
app.directive('focus', {
inserted: (el) => el.focus()
})
以上是一個大家熟知的 Vue 3 遷移案例，看似簡單，動幾行程式碼即可。但當我們的專案規模足夠大，或者有大量專案都需要類似程式碼遷移時，工作量會變得巨大，並且很難規避手動遷移的帶來的風險。
因此，一般針對大規模的專案遷移，最好的方式還是寫個腳手架工具，協助我們完成自動化遷移。既能提高效率，又能降低人工遷移的風險。
1.2 本文的程式碼遷移背景
同樣地，我在專案中也遇到了相同的技術架構升級難題。簡單來說，我需要將基於 Vue 2 的專案遷移到一個我司內部自研的技術棧，這個技術棧的語法結構和 Vue 2 相似，但由於底層的技術原因，有一部分語法上的差異，需要手動去遷移改造相容（類似 Vue 2 升級至 Vue 3 的過程）。
除了和遷移 Vue 3 一樣需要針對 JavaScript、Template 模板做遷移處理之外，我還需要額外去單獨處理 CSS、Less、SCSS 等樣式檔案。
所以，我實現了一個自動化遷移腳手架工具，來協助完成程式碼的遷移工作，減少人工遷移帶來的低效和風險問題。
二、程式碼遷移思路
剛剛提到我們需要設計一個腳手架來幫助我們完成自動化的程式碼遷移，那腳手架該如何設計呢？
首先，程式碼遷移思路可以簡單概括為：對原始碼做靜態程式碼分析，並按一定規則替換為新程式碼。那最直觀的辦法就是利用正規表示式來匹配和替換程式碼，所以我也做了這樣的嘗試。
2.1 思路一：利用正規表示式匹配規則和替換程式碼
例如，將下述程式碼：
import { toast } from '@vivo/v-jsbridge'
import { toast } from '@webf/webf-vue-render'
這看起來很簡單，似乎用正則匹配即可完成，像這樣：
const regx = /\@vivo\/v\-jsbridge/gi
const target = '@webf/webf-vue-render'
sourceCode.replace(regx, target)
但在實操過程中，發現正規表示式實在太侷限，有幾個核心問題：
-
正規表示式完全基於字串匹配，對原始碼格式的統一性要求很高。空格、換行、單雙引號等格式差異都可能引起正則匹配錯誤；
-
面對複雜的匹配場景，正規表示式很難寫、很晦澀，容易誤匹配、誤處理；
-
處理樣式檔案時，需要相容 CSS / Less / SCSS / Sass 等語法差異，工作量倍增。
簡單舉個例子，當我需要匹配 import { toast } from '@vivo/v-jsbridge' 字串時。針對單雙引號、空格、分號等細節處理上需要更仔細，稍有不慎就會忽略一些特殊場景，結果就是匹配失敗，造成隱蔽的遷移問題。
import { toast } from '@vivo/v-jsbridge' // 單引號
import { toast } from "@vivo/v-jsbridge" // 雙引號
import { toast } from "@vivo/v-jsbridge"; // 雙引號 + 分號
import {toast} from "@vivo/v-jsbridge"; // 無空格所以，用簡單的正則匹配規則是無法幫助我們完成大規模的程式碼遷移和重構的，我們需要更好的方法：基於 AST 的程式碼遷移。
2.2 思路二：基於 AST（抽象語法樹）的程式碼遷移
在瞭解到正則匹配規則的侷限性後，我把目光鎖定到了基於 AST 的程式碼遷移上。
那麼什麼是基於 AST 的程式碼遷移呢？
2.2.1 Babel 的編譯過程
如果你瞭解過 Babel 的程式碼編譯原理，應該對 AST 程式碼遷移不陌生。我們知道 Babel 的編譯過程大致分為三個步驟：
-
解析：將原始碼解析為 AST（抽象語法樹）；
-
變換：對 AST 進行變換；
-
再建：根據變換後的 AST 重新構建生成新的程式碼。
（圖片來源：Luminosity Blog ）
舉個例子，Babel 將一個 ES6 語法轉換為 ES5 語法的過程如下：
（1）輸入一個簡單的 sayHello 箭頭函式方法原始碼：
const sayHello = () => {
console.log('hello')
}
（2）經過 Babel 解析為 AST（可以看到 AST 是一串由 JSON 描述的語法樹），並對 AST 進行規則變換：
-
將 type 欄位由 ArrowFunctionExpression 轉換為 FunctionExpression
-
將 kind 欄位由 const 轉換為 var
{
"type": "Program",
"start": 0,
"end": 228,
"body": [
{
"type": "VariableDeclaration",
"start": 179,
"end": 227,
"declarations": [
{
"type": "VariableDeclarator",
"start": 185,
"end": 227,
"id": {
"type": "Identifier",
"start": 185,
"end": 193,
"name": "sayHello"
},
"init": {
- "type": "ArrowFunctionExpression",
+ "type": "FunctionExpression",
"start": 196,
"end": 227,
- "id": null,
+ "id": {
+ "type": "Identifier",
+ "start": 203,
+ "end": 211,
+ "name": "sayHello"
+ },
"expression": false,
"generator": false,
"async": false,
"params": [],
"body": {
"type": "BlockStatement",
"start": 202,
"end": 227,
"body": [
{
"type": "ExpressionStatement",
"start": 205,
"end": 225,
"expression": {
"type": "CallExpression",
"start": 205,
"end": 225,
"callee": {
"type": "MemberExpression",
"start": 205,
"end": 216,
"object": {
"type": "Identifier",
"start": 205,
"end": 212,
"name": "console"
},
"property": {
"type": "Identifier",
"start": 213,
"end": 216,
"name": "log"
},
"computed": false,
"optional": false
},
"arguments": [
{
"type": "Literal",
"start": 217,
"end": 224,
"value": "hello",
"raw": "'hello'"
}
],
"optional": false
}
}
]
}
}
}
],
- "kind": "const"
+ "kind": "var"
}
],
"sourceType": "module"
}
（3）從 AST 重新構建為 ES5 語法：
var sayHello = function sayHello() {
console.log('hello');
};這樣就完成了一個簡單的 ES6 到 ES5 的語法轉換。我們的腳手架自動程式碼遷移思路也是如此。
對比正規表示式匹配，基於 AST 程式碼遷移，有幾點好處：
-
比字串匹配更靈活、涵蓋更多複雜場景。
-
通常 AST 程式碼遷移工具都提供了方便的解析、查詢、匹配、替換的 API，能輕易寫出高效的程式碼轉換規則。
-
方便統一轉換後的程式碼風格。
2.2.2 程式碼遷移流程設計
瞭解了 AST 的基本原理和可行性後，我們需要找到合適的工具庫來完成程式碼的 AST 解析、重構、生成。考慮到專案中至少包含了這幾種內容（指令碼、樣式、HTML）：
-
單獨的 JS 檔案；
-
單獨的樣式檔案：CSS / Less / SCSS / Sass；
-
Vue 檔案：包含 Template、Script、Style 三部分。
我們需要分別找到各類檔案內容對應的解析和處理工具。
首先，是 JS 檔案的解析處理工具的選擇。在市面上比較流行的 JS AST 工具有很多種選擇，例如最常見的 Babel、jscodeshift 以及 Esprima、Recast、Acorn、estraverse 等。做了一些簡單調研後，發現這些工具都有一些共通的缺陷：
-
上手難度大，有較大的學習成本，要求開發者充分了解 AST 的語法規範；
-
語法複雜，程式碼量大；
-
程式碼可讀性差，不利於維護。
以 jscodeshift 為例，如果我們需要匹配一個簡單語句：item.update('price')(this, '50')，它的實現程式碼如下：
const callExpressions = root.find(j.CallExpression, {
callee: {
callee: {
object: {
name: 'item'
},
property: {
name: 'update'
}
},
arguments: [{
value: 'price'
}]
},
arguments: [{
type: 'ThisExpression'
}, {
value: '50'
}]
})
其實相比於原始的 Babel 語法，上述的 jscodeshift 語法已經相對簡潔，但可以看出依然有較大的程式碼量，並且要求開發者熟練掌握 AST 的語法結構。
因此我找到了一個更簡潔、更高效的 AST 工具：GoGoCode，它是一款阿里開源的 AST 工具，封裝了類似 jQuery 的語法，簡單易用。一個直觀的對比就是，如果用 GoGoCode 同樣實現上述的語句匹配，只需要一行程式碼：
$(code).find(`item.update('price')(this, '50')`)它直觀的語義以及簡潔的程式碼，讓我選擇了它作為 JS 的 AST 解析工具。
其次，是單獨的 CSS 樣式檔案解析工具選擇。這個選擇很輕易，直接使用通用的 PostCSS 來解析和處理樣式即可。
最後，是 Vue 檔案的解析工具選擇。因為 Vue 檔案是由 Template、Script、Style 三部分組成，因此需要更復雜的工具進行組合處理。很慶幸的是 GoGoCode 除了能夠對單獨的 JS 檔案進行解析處理，它還封裝了對 Vue 檔案中的 Template 和 Script 部分的處理能力，因此 Vue 檔案中除了 Style 樣式部分，我們也可以交由 GoGo Code 來處理。那 Style 樣式的部分該如何處理呢？這裡我大致看了官方的 vue-loader 原始碼，發現原始碼中使用的是 @vue/component-compiler-utils 來解析 Vue 的 SFC 檔案，它可以將檔案中的 Style 樣式內容單獨抽離出來。因此思路很簡單，我們利用 @vue/component-compiler-utils 將 Vue 檔案中的 Style 樣式內容抽離出來，再交由 PostCSS 來處理即可。
那麼，簡單總結下找到的幾款適合的工具庫：
-
GoGoCode：阿里開源的一款抽象語法樹處理工具，可用於解析 JS / HTML / Vue 檔案並生成抽象語法樹（AST），進行程式碼的規則替換、重構等。封裝了類似 jQuery 的語法，簡單易用。
-
PostCSS：大家熟悉的開源 CSS 程式碼遷移工具，可用於解析 Less / CSS / SCSS / Sass 等樣式檔案並生成語法樹（AST），進行程式碼的規則替換、重構等。
-
@vue/component-compiler-utils：Vue 的開源工具庫，可用於解析 Vue 的 SFC 檔案，我用它將 SFC 中的 Style 內容單獨抽出，並配合 PostCSS 來處理樣式程式碼的規則替換、重構。
有了這三個工具，我們就可以梳理出針對不同檔案內容的處理思路：
-
JS 檔案：交給 GoGoCode 處理。
-
CSS / Less / SCSS / Sass 檔案：交給 PostCSS 處理。
-
Vue 檔案:
-
Template / Script 部分：交給 GoGoCode 處理。
-
Style 部分：先用 @vue/component-compiler-utils 解析出 Style 部分，再交給 PostCSS 處理。
有了處理思路後，接下來進入正文，深入程式碼細節，詳細瞭解程式碼遷移流程。
三、程式碼遷移流程詳解
整個程式碼遷移流程分為幾個步驟，分別是：
3.1 遍歷和讀取檔案內容
遍歷專案檔案內容，根據檔案型別交由不同的 transform 函式來處理：
-
transformVue：處理 Vue 檔案
-
transformScript：處理 JS 檔案
-
transformStyle：處理 CSS 等樣式檔案
const path = require('path')
const fs = require('fs')
const transformFiles = path => {
const traverse = path => {
try {
fs.readdir(path, (err, files) => {
files.forEach(file => {
const filePath = `${path}/${file}`
fs.stat(filePath, async function (err, stats) {
if (err) {
console.error(chalk.red(` \n🚀 ~ ${o} Transform File Error:${err}`))
} else {
// 如果是檔案則開始執行替換規則
if (stats.isFile()) {
const language = file.split('.').pop()
if (language === 'vue') {
// 處理vue檔案內容
await transformVue(file, filePath, language)
} else if (jsSuffix.includes(language)) {
// 處理JS檔案內容
await transformScript(file, filePath, language)
} else if (styleSuffix.includes(language)) {
// 處理樣式檔案內容
await transformStyle(file, filePath, language)
}
} else {
// 如果是目錄，則繼續遍歷
traverse(`${path}/${file}`)
}
}
})
})
})
} catch (err) {
console.error(err)
reject(err)
}
}
traverse(path)
}3.2 Vue 檔案的程式碼遷移
由於單獨的 JS、樣式檔案處理流程和 Vue 檔案相似，唯一的差別在於 Vue 檔案多了一層解析。所以這裡以 Vue 檔案為例，闡述下具體的程式碼遷移流程：
const $ = require('gogocode')
const path = require('path')
const fs = require('fs')
// 處理vue檔案
const transformVue = async (file, path, language = 'vue') => {
return new Promise((resolve, reject) => {
fs.readFile(path, function read(err, code) {
const sourceCode = code.toString()
// 1. 利用gogocode提供的 $ 方法，將原始碼轉換為ast語法樹
const ast = $(sourceCode, { parseOptions: { language: 'vue' } })
// 2. 處理script
transformScript(ast)
// 3. 處理template
transformTemplate(ast)
// 4. 處理styles
transformStyles(ast)
// 5. 對處理過的ast重新生成程式碼
const outputCode = ast.root().generate()
// 6. 重新寫入檔案
fs.writeFile(path, outputCode, function (err) {
if (err) {
reject(err)
throw err
}
resolve()
})
})
})
}
可以看到，程式碼中的 Vue 檔案處理流程主要如下：
-
生成 AST 語法樹：利用 GoGoCode 提供的 $ 方法，將原始碼轉換為 Ast 語法樹，然後將 Ast 語法樹交由不同的處理器來完成語法的匹配和轉換。
-
處理 JavaScript：呼叫 transformScript 處理 JavaScript 部分。
-
處理 template：呼叫 transformTemplate 處理 template（HTML）部分。
-
處理 Styles：呼叫 transformStyles 處理樣式部分。
-
對處理過的 Ast 重新生成程式碼：呼叫 GoGoCode 提供的 ast.root().generate() 方法，可以由 Ast 重新生成目的碼。
-
重新寫入檔案：將生成的目的碼重新寫入檔案。
這樣一來，一個 Vue 檔案的程式碼遷移就結束了。接下來看看針對不同的內容 JavaScript、HTML、Style，需要如何處理。
3.3 處理 JavaScript 指令碼
處理 JavaScript 指令碼時，主要是依賴 GoGoCode 提供的一些語法進行程式碼遷移：
-
首先，利用 ast.find('') 解析並找到 Vue 檔案中的 JavaScript 指令碼部分。
-
其次，利用 replace 等方法對原始碼進行一個匹配和替換。
-
最後，返回處理後的 Ast。
下面是一個簡單的程式碼替換案例，主要目的是將一個 import 語句替換引用包的來源。將@vivo/v-jsbridge 替換為@webf/webf-vue-render/modules/jsb。
// 轉換前
import { call } from '@vivo/v-jsbridge'
// 轉換後
import { call } from '@webf/webf-vue-render/modules/jsb'
const transformScript = (ast) => {
const script = ast.find('<script></script>')
// 利用replace方法替換程式碼
script.replace(
`import {$$$} from "@vivo/v-jsbridge"`,
`import {$$$} from "@webf/webf-vue-render/modules/jsb"`
)
return ast
}
除了 replace 之外，還有一些別的語法也經常用到，例如：
-
find（查詢程式碼）
-
has（判斷是否包含程式碼）
-
append（在後面插入程式碼）
-
prepend（在前面插入程式碼）
-
remove（刪除程式碼）等。
只要簡單熟悉下 GoGoCode 的語法，就能很快寫出一些轉換規則（相比於正規表示式，效率高很多）。
3.4 處理 Template 模板
處理 Template 模板時也是類似，主要依賴 GoGoCode 提供的 API：
-
首先，利用 ast.find('') 解析並找到 Vue 檔案中的 Template（HTML）部分。
-
其次，利用 replace 等方法對原始碼進行一個匹配和替換。
-
最後，返回處理後的 Ast 。
下面是簡單的 Template 標籤替換案例，將帶有 @change 屬性的 div 標籤，替換為帶有 :onChange 屬性的 span 標籤。
// 轉換前
<div @change="onChange"></div>
// 轉換後
<span :onChange="onChange"></div>
const transformTemplate = (ast) => {
const template = ast.find('<template></template>')
const tagName = 'div'
const targetTagName = 'span'
// 利用replace方法替換程式碼，將div標籤替換為span標籤
template
.replace(
`<${tagName} @change="$_$" $$$1>$$$0</${tagName}>`,
`<${targetTagName} :onChange="$_$" $$$1>$$$0</${targetTagName}>`
)
return ast
}
值得一提的是，GoGoCode 提供了$ _$、$$$1 這類萬用字元，讓我們能對 DOM 結構進行更好的規則匹配，高效地寫出匹配和轉換規則。
3.5 處理 Style 樣式
最後是處理 Style 樣式部分，這部分和處理 JavaScript、Template 有些不同，由於 GoGoCode 暫時沒有提供針對 Style 樣式的處理方法。所以我們需要額外借用兩個工具，分別是：
-
@vue/component-compiler-utils：解析樣式程式碼，轉成 Ast 。
-
PostCSS：按規則處理樣式，轉換成目的碼。
整個 Style 樣式的處理流程如下（寫過 PostCSS 外掛的同學對這樣式處理這部分應該很熟悉）：
-
獲取 Styles 節點：利用 ast.rootNode.value.styles 獲取 Styles 節點，一個 Vue 檔案中可能包含多個 Style 程式碼塊，對應多個 Styles 節點。
-
遍歷 Styles 節點：
-
利用 @vue/component-compiler-utils 提供的 compileStyle 方法解析 Style 節點內容。
-
利用 postcss.process 方法，根據規則處理樣式內容，生成目的碼。
-
返回轉換後的 Ast 。
下面是一個簡單的案例，將樣式中所有的 color 屬性值統一替換為 red。
// 轉換前
<style>
.button {
color: blue;
}
</style>
// 轉換後
<style>
.button {
color: red;
}
</style>
const compiler = require('@vue/component-compiler-utils')
const { parse, compileStyle } = compiler
const postcss = require('postcss')
// 一個簡單的替換所有color屬性為'red'的postcss外掛
const colorPlugin = (opts = {}) => {
return {
postcssPlugin: 'postcss-color',
Once(root, { result }) {
root.walkDecls(node => {
// 找到所有prop為color的節點，將節點的值設定為red
if (node.prop === 'color') {
node.value = 'red'
}
})
}
}
}
colorPlugin.postcss = true
const transformStyles = (ast) => {
// 獲取styles節點（一個vue檔案中可能包含多個style程式碼塊，對應多個styles節點）
const styles = ast.rootNode.value.styles
// 遍歷所有styles節點
styles.forEach((style, index) => {
let content = style.content
// 獲取檔案的字尾：less / sass / scss / css等
const lang = style.lang || 'css'
// 利用@vue/component-compiler-utils提供的compileStyle方法解析style內容
const result = compileStyle({
source: content,
scoped: false
})
// 交由postcss處理樣式，傳入剛剛宣告的colorPlugin外掛
const res = postcss([colorPlugin]).process(result.code, { from: path, syntax: parsers[lang] })
style.content = res.css
})
return ast
}
到此，整個程式碼遷移流程就完成了。
【原始碼 DEMO 可參考】https://github.com/vivo/BlueSnippets/tree/main/demos/ast-migration
四、總結
本文簡單闡述了基於 AST 的程式碼遷移概念和大致流程，並透過程式碼案例帶大家瞭解到了其中的處理細節。梳理下整個程式碼遷移處理流程：
-
遍歷和讀取檔案內容。
-
將內容分類，針對不同檔案內容，採用不同的處理器。
-
JavaScript 指令碼直接交由 GoGoCode 處理。
-
樣式檔案直接交由 PostCSS 處理。
-
針對 Vue 檔案，透過解析，拆分成 Template、JavaScript、Style 樣式三部分，再進行分別處理。
-
處理完成後，基於轉換後的 Ast 生成目的碼並重新寫入檔案，完成程式碼遷移。
整個處理流程還是相對簡單的，只需要掌握 AST 程式碼轉換的基本概念，對 GoGoCode、PostCSS、@vue/component-compiler-utils 這些工具的基本使用有一定的瞭解，就可以進行一個自動化遷移工具的開發了。
最後，需要額外提醒大家的一點是，在設計程式碼匹配和轉換規則時，需要注意邊界場景，避免產生錯誤的程式碼轉換，從而造成潛在 bug。為了規避程式碼轉換異常，建議大家針對每個轉換規則編寫充分的測試用例，以保障轉換規則的正確性。
如果大家有類似的需求，也可以參照本文進行工具設計和實現。