一次基于AST的大规模代码迁移实践

在研发项目过程中，我们经常会遇到技术架构迭代更新的需求，通过技术的迭代更新，让项目从新的技术特性中受益。例如将 Vue 2 迁移至 Vue 3、Webpack 4 升级 Webpack 5、构建工具迁移至 Vite 等，这些技术架构的升级能让项目持续受益，获得诸如可维护性、性能、扩展性、编译速度、可读性等等方面的提升，适时的对项目进行技术架构更新是很有必要的。

那既然新特性这么好，有人会说那当然要与时俱进，随时更新了。

但问题在于很多新的技术迭代版本并不能完全向下兼容，包含了很多非兼容性的改变（Breaking Changes），并不是简单升个版本就行了，通常还需要投入不少的人力和学习成本。例如 Vue 3 只能兼容80%的 Vue 2 代码，对于一些新特性、新语法糖，开发者只能参考官方提供的迁移文档，手动完成迁移。

（图片来源：freecodecamp）

import Vue from 'vue'
 
Vue.directive('focus', {
  inserted: (el) => el.focus()
})

import { createApp } from 'vue'
 
const app = createApp({})
 
app.directive('focus', {
  inserted: (el) => el.focus() 
})

以上是一个大家熟知的 Vue 3 迁移案例，看似简单，动几行代码即可。但当我们的项目规模足够大，或者有大量项目都需要类似代码迁移时，工作量会变得巨大，并且很难规避手动迁移的带来的风险。

因此，一般针对大规模的项目迁移，最好的方式还是写个脚手架工具，协助我们完成自动化迁移。既能提高效率，又能降低人工迁移的风险。

同样地，我在项目中也遇到了相同的技术架构升级难题。简单来说，我需要将基于 Vue 2 的项目迁移到一个我司内部自研的技术栈，这个技术栈的语法结构和 Vue 2 相似，但由于底层的技术原因，有一部分语法上的差异，需要手动去迁移改造兼容（类似 Vue 2 升级至 Vue 3 的过程）。

除了和迁移 Vue 3 一样需要针对 JavaScript、Template 模板做迁移处理之外，我还需要额外去单独处理 CSS、Less、SCSS 等样式文件。

所以，我实现了一个自动化迁移脚手架工具，来协助完成代码的迁移工作，减少人工迁移带来的低效和风险问题。

刚刚提到我们需要设计一个脚手架来帮助我们完成自动化的代码迁移，那脚手架该如何设计呢？

首先，代码迁移思路可以简单概括为：对原代码做静态代码分析，并按一定规则替换为新代码。那最直观的办法就是利用正则表达式来匹配和替换代码，所以我也做了这样的尝试。

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)

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 的代码迁移上。

那么什么是基于 AST 的代码迁移呢？

2.2.1 Babel 的编译过程

（图片来源：Luminosity Blog ）

（1）输入一个简单的 sayHello 箭头函数方法源码：

const sayHello = () => {
    console.log('hello')
}

（2）经过 Babel 解析为 AST（可以看到 AST 是一串由 JSON 描述的语法树），并对 AST 进行规则变换：

{
  "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 代码迁移，有几点好处：

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 来处理即可。

那么，简单总结下找到的几款适合的工具库：

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)
}

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()
           })
        })
    })
}

// 转换前
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
}

// 转换前
<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
}

3.5 处理 Style 样式

// 转换前
<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 的代码迁移概念和大致流程，并通过代码案例带大家了解到了其中的处理细节。梳理下整个代码迁移处理流程：

整个处理流程还是相对简单的，只需要掌握 AST 代码转换的基本概念，对 GoGoCode、PostCSS、

@vue/component-compiler-utils 这些工具的基本使用有一定的了解，就可以进行一个自动化迁移工具的开发了。

最后，需要额外提醒大家的一点是，在设计代码匹配和转换规则时，需要注意边界场景，避免产生错误的代码转换，从而造成潜在 bug。为了规避代码转换异常，建议大家针对每个转换规则编写充分的测试用例，以保障转换规则的正确性。

如果大家有类似的需求，也可以参照本文进行工具设计和实现。