在這篇文章里我想要通過(guò)一些小例子來(lái)介紹使用jscodeshift來(lái)進(jìn)行自動(dòng)化重構(gòu)的技術(shù)。具體來(lái)說(shuō)，我想要介紹在一個(gè)組件庫(kù)的開(kāi)發(fā)和維護(hù)過(guò)程中，如何使用jscodeshift來(lái)自動(dòng)修改公開(kāi)的API接口，從而盡可能小的產(chǎn)生對(duì)組件用戶(hù)的影響。

如果你們團(tuán)隊(duì)開(kāi)發(fā)的組件被其消費(fèi)者（組織內(nèi)部或者外部）使用了，而這些代碼又不在你的控制之內(nèi)，那么這里討論的技術(shù)和模式可能對(duì)你很有幫助。而如果你的日常工作更多的是使用組件庫(kù)來(lái)開(kāi)發(fā)應(yīng)用程序，我希望這里的知識(shí)和技巧仍然對(duì)你有所啟發(fā)，畢竟在軟件系統(tǒng)中，我們往往都既是某些庫(kù)的消費(fèi)者，又同時(shí)是另外一些庫(kù)的生產(chǎn)者。

從一個(gè)簡(jiǎn)單場(chǎng)景出發(fā)

設(shè)想這樣一個(gè)場(chǎng)景，你發(fā)布了一個(gè)酷炫的組件庫(kù)（fancylib），其中有一個(gè)按鈕（Button）組件。這個(gè)Button的一個(gè)屬性是當(dāng)點(diǎn)擊后處于加載中（loading）狀態(tài)時(shí)現(xiàn)實(shí)一個(gè)表示加載中的小圖標(biāo)。

(圖片來(lái)源：https://xd.adobe.com/ideas/process/ui-design/designing-interactive-buttons-states/)

在代碼實(shí)現(xiàn)中，這個(gè)加載中狀態(tài)被定義為了名為isInLoadingStatus公開(kāi)prop。用戶(hù)可以通過(guò)設(shè)置其值來(lái)控制Button的狀態(tài)：

import Button from '@fancylib/button';

const app = () => (Click me
)

一個(gè)實(shí)習(xí)生在某一天code review的時(shí)候提出了一個(gè)問(wèn)題：在組件庫(kù)中的其他地方，所有的boolean狀態(tài)都是用一個(gè)單詞來(lái)表示的，比如checked, disabled等。如果按照這個(gè)慣例，這里應(yīng)該把isInLoadingStatus簡(jiǎn)化為loading。好主意！

import Button from '@fancylib/button';

const app = () => (Click me
)

假如所有用到Button的地方都在你的控制之內(nèi)，字符串替換大約是一個(gè)快速且80%有效的方案。不過(guò)稍微分析一下，你就會(huì)發(fā)現(xiàn)簡(jiǎn)單的Shift+F6會(huì)遇到很多問(wèn)題。

復(fù)雜情況

比如用戶(hù)對(duì)其做了二次包裝以適配更符合自己用戶(hù)的使用習(xí)慣，這使得簡(jiǎn)單的全局字符串替換變成了不可能:：

import Button as FancyButton from '@fancylib/button';

const MyEvenFancierButton = (props: FancyButtonProps) => (
    const theme = {
        backgroundColor: "orangered",
        color: "white"
    };
    Click me
);

除了這些問(wèn)題之外，由于這是一個(gè)非常受歡迎的組件庫(kù)，Button在很多（包括內(nèi)部和外部的）產(chǎn)品中都有使用，你沒(méi)有辦法訪(fǎng)問(wèn)所有的用戶(hù)代碼，更沒(méi)有辦法讓所有人都用手工的查找替換來(lái)做更新，你需要另尋出路。

你需要一個(gè)工具 -- 一個(gè)可以讀懂代碼意圖的工具 -- 來(lái)幫助你做修改，而且整個(gè)過(guò)程最好可以自動(dòng)化，比如通過(guò)執(zhí)行一個(gè)腳本來(lái)完成。

使用jscodeshift

jscodeshift就是這樣一個(gè)工具（工具集）。簡(jiǎn)單來(lái)說(shuō)，jscodeshift的工作方式就是將源代碼分析成一棵樹(shù)（抽象語(yǔ)法樹(shù)），然后提供API來(lái)修改這棵樹(shù)，最后再把樹(shù)生成為代碼。
?

也就是說(shuō)，她可以讀懂你的代碼，并提供指令（API）來(lái)根據(jù)你的意愿修改相應(yīng)的代碼。

實(shí)現(xiàn)

接下來(lái)，我們可以通過(guò)實(shí)現(xiàn)一個(gè)可以完成上述場(chǎng)景的自動(dòng)重構(gòu)的腳本來(lái)對(duì)jscodeshift的使用做一個(gè)簡(jiǎn)單介紹。簡(jiǎn)單來(lái)說(shuō)，jscodeshift的工作流程是：首先你需要定義一個(gè)轉(zhuǎn)換腳本（transform），這個(gè)腳本需要符合一定的規(guī)范以便jscodeshift調(diào)用；然后jscodeshift的命令行工具會(huì)啟動(dòng)runner，并將轉(zhuǎn)換腳本應(yīng)用到某個(gè)文件或者某個(gè)文件夾中的所有文件中：
jscodeshift -t myTransform src

定義一個(gè)transform

也就是說(shuō)，我們所有的邏輯都會(huì)定義在轉(zhuǎn)換腳本中。transform腳本需要導(dǎo)出一個(gè)固定格式的函數(shù)：

import { Transform } from "jscodeshift";

const transform: Transform = (file, api, options) => {
  //...
};

export default transform;

file為解析后的文件對(duì)象，api是jscodeshift的API對(duì)象，可以通過(guò)它來(lái)查找，修改文件對(duì)象，options是一個(gè)可選的，用來(lái)傳遞其他參數(shù)（比如格式化最終輸出格式等）的對(duì)象。在函數(shù)體中，我們可以使用jscodeshift提供的API來(lái)操縱抽象語(yǔ)法樹(shù)（Abstract Syntax Tree）來(lái)實(shí)現(xiàn)對(duì)代碼的修改。這個(gè)過(guò)程和通過(guò)DOM API來(lái)操作瀏覽器中的頁(yè)面元素非常類(lèi)似：按照屬性查找元素，對(duì)查找結(jié)果進(jìn)行增刪改等操作，只不過(guò)這里的操作對(duì)象是語(yǔ)法樹(shù)（比如變量定義，函數(shù)體，條件語(yǔ)句等等）。

在詳細(xì)討論如何使用jscodeshift的API來(lái)修改代碼之前，我們來(lái)略微看一下抽象語(yǔ)法樹(shù)的概念。這將是我們腳本需要操作的主要對(duì)象。

抽象語(yǔ)法樹(shù)AST

抽象語(yǔ)法樹(shù)，是編譯器將源碼解析（parse）之后形成的一課樹(shù)形結(jié)構(gòu)。簡(jiǎn)單來(lái)說(shuō)，我們的代碼被解析成為T(mén)oken，Token再根據(jù)語(yǔ)法規(guī)則形成子樹(shù)，子樹(shù)最終根據(jù)文法歸并成一顆樹(shù)。我們可以通過(guò)AST Explorer工具來(lái)實(shí)時(shí)查看代碼對(duì)應(yīng)的語(yǔ)法樹(shù)。

舉個(gè)例子，我們的代碼片段：

import Button from '@fancylib/button';

const app = () => (Click me
)

經(jīng)過(guò)解析（jscodeshift默認(rèn)使用babel來(lái)解析，你可以選擇其他的解析器）之后，會(huì)形成右側(cè)的一顆樹(shù)，比如isInLoadingStatus被識(shí)別成JSXIdentifier類(lèi)型，而變量app定義則被識(shí)別為VariableDeclarator等。所有符合語(yǔ)法的元素都會(huì)被抽取成Token，并體現(xiàn)為樹(shù)上的一個(gè)節(jié)點(diǎn)。
?

有了這些基本概念之后，我們就可以開(kāi)始編寫(xiě)一個(gè)簡(jiǎn)單的transform了。這里我們可以通過(guò)AST Explorer提供的在線(xiàn)IDE中的Transform功能來(lái)實(shí)時(shí)調(diào)試（此處選擇jscodeshift作為轉(zhuǎn)換器）。

然后我們定義這樣一個(gè)轉(zhuǎn)換函數(shù)：

// 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，并迭代每一個(gè)找到的節(jié)點(diǎn)，如果它的值是isInLoadingStatus的話(huà)，就將其替換為loading?？梢杂^察到右下側(cè)的調(diào)試器窗口中的轉(zhuǎn)換結(jié)果：
?

測(cè)試驅(qū)動(dòng)開(kāi)發(fā)

當(dāng)然了，作為一個(gè)嚴(yán)肅的程序員，我們不應(yīng)該通過(guò)一個(gè)在線(xiàn)IDE來(lái)進(jìn)行開(kāi)發(fā)。幸運(yùn)的是jscodeshift可以和jest完美配合，同時(shí)我發(fā)現(xiàn)編寫(xiě)自動(dòng)化腳本是一個(gè)非常適合測(cè)試驅(qū)動(dòng)開(kāi)發(fā)的場(chǎng)景：

• 輸入輸出都非常明確
• 各種不同的邊界場(chǎng)景很容易想象/編寫(xiě)成用例
• 每一個(gè)步驟都可以劃分的比較小

jscodeshift提供了一個(gè)小工具defineInlineTest，通過(guò)它你可以很方便的定義測(cè)試用例：

import { defineInlineTest } from 'jscodeshift/dist/testUtils';
import transformer from './transformer';

describe('transformer', () => {
    defineInlineTest(
    { default: transformer, parser: 'tsx' }, 
    {},
    `
    import Button from '@fancylib/button';

    export default () => (Click me
    );
    `,
    `
    import Button from '@fancylib/button';

    export default () => (Click me
    );
    `,
    'change isInLoadingStatus to loading'
  );
});

當(dāng)然，如果你不習(xí)慣字符串模板的話(huà)，它同時(shí)還提供了基于文件形式的測(cè)試定義，這樣你可以將測(cè)試的輸入（轉(zhuǎn)化前）和輸出（轉(zhuǎn)化后）外置到文件中，并在其中構(gòu)建較為復(fù)雜的使用場(chǎng)景。

比如我們希望這個(gè)transform不要誤傷我們代碼中使用的其他Button，比如我們使用了另外一個(gè)組件庫(kù)，而巧合的是那個(gè)庫(kù)中Button也有一個(gè)isInLoadingStatus。

那么對(duì)應(yīng)的測(cè)試用例會(huì)是：

   defineInlineTest(
    { default: transformer, parser: 'tsx' }, 
    {},
    `
    import Button from '@facebook/button';

    export default () => (Click me
    );
    `,
    `
    import Button from '@facebook/button';

    export default () => (Click me
    );
    `,
    'should not change isInLoadingStatus to loading from other package'
  );

對(duì)應(yīng)的我們需要在代碼中加入相應(yīng)的邏輯：

// 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語(yǔ)句，如果沒(méi)有找到從@fancylib/button導(dǎo)入的Button就跳過(guò)后續(xù)的操作。你應(yīng)該已經(jīng)注意到了，我們這里又很多的諸如j.ImportDeclaration和j.ImportDefaultSpecifier之類(lèi)的Token定義，你可以從AST Explorer的樹(shù)結(jié)構(gòu)中找到類(lèi)似的名稱(chēng)，然后用jscodeshift的API來(lái)查找并訪(fǎng)問(wèn)改節(jié)點(diǎn)。

這個(gè)過(guò)程或多或少有點(diǎn)像我們通過(guò)DOM的API來(lái)選擇HTML節(jié)點(diǎn)一樣：

document.querySelectorAll('a')
    .filter(anchor => anchor.classList.includes('button'))
    .forEach(anchor => anchor.style["text-decoration"] = "underline")

如果你覺(jué)得這里要素太多，這是很正常的。嘗試著多寫(xiě)幾個(gè)就會(huì)發(fā)現(xiàn)規(guī)律。

如果把所有的實(shí)現(xiàn)細(xì)節(jié)都列舉在一篇文章中，我覺(jué)得文章會(huì)非常枯燥（可能寫(xiě)成一個(gè)系列教程等），因此這里我不再貼代碼，相關(guān)的源碼可以在這里找到。

可能的陷阱

使用腳本來(lái)自動(dòng)化重構(gòu)的想法當(dāng)然非常有誘惑了，特別是對(duì)于疲于為已經(jīng)公布的API打補(bǔ)丁的人們來(lái)說(shuō)，簡(jiǎn)直太過(guò)于美好。不過(guò)公平起見(jiàn)，我還是得略微說(shuō)一些它的一些drawbacks。

首先，jscodeshift 的API略顯晦澀，有一定的學(xué)習(xí)成本。開(kāi)發(fā)過(guò)程中可能會(huì)有很多調(diào)試的工作。其次，它并不定覆蓋100%的使用場(chǎng)景，比如對(duì)于復(fù)雜的spreading操作，需要調(diào)試和分析的工作量不容小覷，也就是說(shuō)你仍然需要人工校對(duì)一些edge cases。最后，需要一些腳本來(lái)支持組件的消費(fèi)團(tuán)隊(duì)使用，比如自動(dòng)化補(bǔ)丁工具等，如果有多個(gè)transform，如何一次patch等問(wèn)題。

小結(jié)

在這篇文章中，我們從一個(gè)簡(jiǎn)化了的實(shí)際例子出發(fā)，描述了為何jscodeshift在某些場(chǎng)景下可以提供的幫助，比如降低大型修改可能帶來(lái)的影響（而如果影響不可避免，那么如何使其變得不那么痛苦）。隨后我們描述了jscodeshift中的一些基本概念和基本的工作方式，并結(jié)合之前討論的例子實(shí)現(xiàn)了部分的自動(dòng)化重構(gòu)。
?