作者 | 邱俊濤
在這篇文章里我想要通過一些小例子來介紹使用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 = () => (
<Button isInLoadingStatus>Click me</Button>
)
一個實習生在某一天code review的時候提出了一個問題：在組件庫中的其他地方，所有的boolean狀態都是用一個單詞來表示的，比如checked, disabled等。如果按照這個慣例，這里應該把isInLoadingStatus簡化為loading。好主意!
import Button from '@fancylib/button';
const app = () => (
<Button loading>Click me</Button>
)
假如所有用到Button的地方都在你的控制之內，字符串替換大約是一個快速且80%有效的方案。不過稍微分析一下，你就會發現簡單的Shift+F6會遇到很多問題。
復雜情況
比如用戶對其做了二次包裝以適配更符合自己用戶的使用習慣，這使得簡單的全局字符串替換變成了不可能:：
import Button as FancyButton from '@fancylib/button';
const MyEvenFancierButton = (props: FancyButtonProps) => (
const theme = {
backgroundColor: "orangered",
color: "white"
};
<FancyButton {props} theme={theme}>Click me</FancyButton>
);
除了這些問題之外，由于這是一個非常受歡迎的組件庫，Button在很多(包括內部和外部的)產品中都有使用，你沒有辦法訪問所有的用戶代碼，更沒有辦法讓所有人都用手工的查找替換來做更新，你需要另尋出路。
你需要一個工具 -- 一個可以讀懂代碼意圖的工具 -- 來幫助你做修改，而且整個過程最好可以自動化，比如通過執行一個腳本來完成。
使用jscodeshift
jscodeshift就是這樣一個工具(工具集)。簡單來說，jscodeshift的工作方式就是將源代碼分析成一棵樹(抽象語法樹)，然后提供API來修改這棵樹，最后再把樹生成為代碼。
也就是說，她可以讀懂你的代碼，并提供指令(API)來根據你的意愿修改相應的代碼。
實現
接下來，我們可以通過實現一個可以完成上述場景的自動重構的腳本來對jscodeshift的使用做一個簡單介紹。簡單來說，jscodeshift的工作流程是：首先你需要定義一個轉換腳本(transform)，這個腳本需要符合一定的規范以便jscodeshift調用;然后jscodeshift的命令行工具會啟動runner，并將轉換腳本應用到某個文件或者某個文件夾中的所有文件中：
jscodeshift -t myTransform src
定義一個transform
也就是說，我們所有的邏輯都會定義在轉換腳本中。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來修改代碼之前，我們來略微看一下抽象語法樹的概念。這將是我們腳本需要操作的主要對象。
抽象語法樹AST
抽象語法樹，是編譯器將源碼解析(parse)之后形成的一課樹形結構。簡單來說，我們的代碼被解析成為Token，Token再根據語法規則形成子樹，子樹最終根據文法歸并成一顆樹。我們可以通過AST Explorer工具來實時查看代碼對應的語法樹。
舉個例子，我們的代碼片段：
import Button from '@fancylib/button';
const app = () => (
<Button isInLoadingStatus>Click me</Button>
)
經過解析(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 () => (
<Button isInLoadingStatus>Click me</Button>
);
`,
`
import Button from '@fancylib/button';
export default () => (
<Button loading>Click me</Button>
);
`,
'change isInLoadingStatus to loading'
);
});
當然，如果你不習慣字符串模板的話，它同時還提供了基于文件形式的測試定義，這樣你可以將測試的輸入(轉化前)和輸出(轉化后)外置到文件中，并在其中構建較為復雜的使用場景。
比如我們希望這個transform不要誤傷我們代碼中使用的其他Button，比如我們使用了另外一個組件庫，而巧合的是那個庫中Button也有一個isInLoadingStatus。
那么對應的測試用例會是：
defineInlineTest(
{ default: transformer, parser: 'tsx' },
{},
`
import Button from '@facebook/button';
export default () => (
<Button isInLoadingStatus>Click me</Button>
);
`,
`
import Button from '@facebook/button';
export default () => (
<Button isInLoadingStatus>Click me</Button>
);
`,
'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中的一些基本概念和基本的工作方式，并結合之前討論的例子實現了部分的自動化重構。
