使用Jscodeshift做自动化重构

发布时间：2025-11-05 15:22:28 来源：码上建站 作者：数据库

作者 | 邱俊涛

在这篇文章里我想要通过一些小例子来介绍使用jscodeshift来进行自动化重构的使用技术。具体来说，做自动我想要介绍在一个组件库的化重开发和维护过程中，如何使用jscodeshift来自动修改公开的使用API接口，从而尽可能小的做自动产生对组件用户的影响。

如果你们团队开发的化重组件被其消费者(组织内部或者外部)使用了，而这些代码又不在你的使用控制之内，那么这里讨论的做自动技术和模式可能对你很有帮助。而如果你的化重日常工作更多的是使用组件库来开发应用程序，我希望这里的使用知识和技巧仍然对你有所启发，毕竟在软件系统中，做自动我们往往都既是化重某些库的消费者，又同时是使用另外一些库的生产者。

从一个简单场景出发

设想这样一个场景，做自动你发布了一个酷炫的化重组件库(fancylib)，其中有一个按钮(Button)组件。这个Button的亿华云一个属性是当点击后处于加载中(loading)状态时现实一个表示加载中的小图标。

(图片来源：https://xd.adobe.com/ideas/process/ui-design/designing-interactive-buttons-states/)

在代码实现中，这个加载中状态被定义为了名为isInLoadingStatus公开prop。用户可以通过设置其值来控制Button的状态：

import Button from @fancylib/button;

const app = () => (

)

一个实习生在某一天code review的时候提出了一个问题：在组件库中的其他地方，所有的boolean状态都是用一个单词来表示的，比如checked, disabled等。如果按照这个惯例，这里应该把isInLoadingStatus简化为loading。好主意!

import Button from @fancylib/button;

const app = () => (

)

假如所有用到Button的地方都在你的控制之内，字符串替换大约是一个快速且80%有效的方案。不过稍微分析一下，你就会发现简单的Shift+F6会遇到很多问题。

比如用户对其做了二次包装以适配更符合自己用户的使用习惯，这使得简单的全局字符串替换变成了不可能:：

import Button as FancyButton from @fancylib/button;

const MyEvenFancierButton = (props: FancyButtonProps) => (

const theme = {

backgroundColor: "orangered",

color: "white"

};

Click me

);

除了这些问题之外，由于这是一个非常受欢迎的组件库，Button在很多(包括内部和外部的香港云服务器)产品中都有使用，你没有办法访问所有的用户代码，更没有办法让所有人都用手工的查找替换来做更新，你需要另寻出路。

你需要一个工具 -- 一个可以读懂代码意图的工具 -- 来帮助你做修改，而且整个过程最好可以自动化，比如通过执行一个脚本来完成。

jscodeshift就是这样一个工具(工具集)。简单来说，jscodeshift的工作方式就是将源代码分析成一棵树(抽象语法树)，然后提供API来修改这棵树，最后再把树生成为代码。

也就是说，她可以读懂你的代码，并提供指令(API)来根据你的意愿修改相应的代码。

实现

接下来，我们可以通过实现一个可以完成上述场景的自动重构的脚本来对jscodeshift的使用做一个简单介绍。简单来说，jscodeshift的工作流程是云服务器提供商：首先你需要定义一个转换脚本(transform)，这个脚本需要符合一定的规范以便jscodeshift调用;然后jscodeshift的命令行工具会启动runner，并将转换脚本应用到某个文件或者某个文件夹中的所有文件中：

jscodeshift -t myTransform src

也就是说，我们所有的逻辑都会定义在转换脚本中。transform脚本需要导出一个固定格式的函数：

import { Transform } from "jscodeshift";

const transform: Transform = (file, api, options) => {

//...

};

export default transform;

file为解析后的文件对象，api是jscodeshift的API对象，可以通过它来查找，修改文件对象，options是一个可选的，用来传递其他参数(比如格式化最终输出格式等)的对象。在函数体中，我们可以使用jscodeshift提供的API来操纵抽象语法树(Abstract Syntax Tree)来实现对代码的修改。这个过程和通过DOM API来操作浏览器中的页面元素非常类似：按照属性查找元素，对查找结果进行增删改等操作，只不过这里的操作对象是语法树(比如变量定义，函数体，条件语句等等)。

在详细讨论如何使用jscodeshift的API来修改代码之前，我们来略微看一下抽象语法树的概念。这将是我们脚本需要操作的主要对象。

抽象语法树，是编译器将源码解析(parse)之后形成的一课树形结构。简单来说，我们的代码被解析成为Token，Token再根据语法规则形成子树，子树最终根据文法归并成一颗树。我们可以通过AST Explorer工具来实时查看代码对应的语法树。

举个例子，我们的代码片段：

import Button from @fancylib/button;

const app = () => (

)

经过解析(jscodeshift默认使用babel来解析，你可以选择其他的解析器)之后，会形成右侧的一颗树，比如isInLoadingStatus被识别成JSXIdentifier类型，而变量app定义则被识别为VariableDeclarator等。所有符合语法的元素都会被抽取成Token，并体现为树上的一个节点。

有了这些基本概念之后，我们就可以开始编写一个简单的transform了。这里我们可以通过AST Explorer提供的在线IDE中的Transform功能来实时调试(此处选择jscodeshift作为转换器)。

然后我们定义这样一个转换函数：

// Press ctrl+space for code completion

export default function transformer(file, api) {

const j = api.jscodeshift;

return j(file.source)

.find(j.JSXIdentifier)

.forEach(path => {

if(path.node.name === "isInLoadingStatus") {

j(path).replaceWith(

j.identifier(loading)

)

}

})

.toSource();

}

比如上述代码中，我们查找所有的j.JSXIdentifier，并迭代每一个找到的节点，如果它的值是isInLoadingStatus的话，就将其替换为loading。可以观察到右下侧的调试器窗口中的转换结果：

当然了，作为一个严肃的程序员，我们不应该通过一个在线IDE来进行开发。幸运的是jscodeshift可以和jest完美配合，同时我发现编写自动化脚本是一个非常适合测试驱动开发的场景：

jscodeshift提供了一个小工具defineInlineTest，通过它你可以很方便的定义测试用例：

import { defineInlineTest } from jscodeshift/dist/testUtils;

import transformer from ./transformer;

describe(transformer, () => {

defineInlineTest(

{ default: transformer, parser: tsx },

{},

`

import Button from @fancylib/button;

export default () => (

);

`,

`

import Button from @fancylib/button;

export default () => (

);

`,

change isInLoadingStatus to loading

);

});

当然，如果你不习惯字符串模板的话，它同时还提供了基于文件形式的测试定义，这样你可以将测试的输入(转化前)和输出(转化后)外置到文件中，并在其中构建较为复杂的使用场景。

比如我们希望这个transform不要误伤我们代码中使用的其他Button，比如我们使用了另外一个组件库，而巧合的是那个库中Button也有一个isInLoadingStatus。

那么对应的测试用例会是：

defineInlineTest(

{ default: transformer, parser: tsx },

{},

`

import Button from @facebook/button;

export default () => (

);

`,

`

import Button from @facebook/button;

export default () => (

);

`,

should not change isInLoadingStatus to loading from other package

);

对应的我们需要在代码中加入相应的逻辑：

// Press ctrl+space for code completion

export default function transformer(file, api) {

const j = api.jscodeshift;

const root = j(file.source);

const specifiers = root

.find(j.ImportDeclaration)

.filter((path) => path.node.source.value === "@fancylib/button")

.find(j.ImportDefaultSpecifier);

if (specifiers.length === 0) {

return;

}

//...

}

即，我们先查找所有的import语句，如果没有找到从@fancylib/button导入的Button就跳过后续的操作。你应该已经注意到了，我们这里又很多的诸如j.ImportDeclaration和j.ImportDefaultSpecifier之类的Token定义，你可以从AST Explorer的树结构中找到类似的名称，然后用jscodeshift的API来查找并访问改节点。

这个过程或多或少有点像我们通过DOM的API来选择HTML节点一样：

document.querySelectorAll(a)

.filter(anchor => anchor.classList.includes(button))

.forEach(anchor => anchor.style["text-decoration"] = "underline")

如果你觉得这里要素太多，这是很正常的。尝试着多写几个就会发现规律。

如果把所有的实现细节都列举在一篇文章中，我觉得文章会非常枯燥(可能写成一个系列教程等)，因此这里我不再贴代码，相关的源码可以在https://github.com/abruzzi/codemod-demo找到。

使用脚本来自动化重构的想法当然非常有诱惑了，特别是对于疲于为已经公布的API打补丁的人们来说，简直太过于美好。不过公平起见，我还是得略微说一些它的一些drawbacks。

首先，jscodeshift 的API略显晦涩，有一定的学习成本。开发过程中可能会有很多调试的工作。其次，它并不定覆盖100%的使用场景，比如对于复杂的spreading操作，需要调试和分析的工作量不容小觑，也就是说你仍然需要人工校对一些edge cases。最后，需要一些脚本来支持组件的消费团队使用，比如自动化补丁工具等，如果有多个transform，如何一次patch等问题。

小结

在这篇文章中，我们从一个简化了的实际例子出发，描述了为何jscodeshift在某些场景下可以提供的帮助，比如降低大型修改可能带来的影响(而如果影响不可避免，那么如何使其变得不那么痛苦)。随后我们描述了jscodeshift中的一些基本概念和基本的工作方式，并结合之前讨论的例子实现了部分的自动化重构。

相关文章