ts-migrate：大規模遷移到 TypeScript 的工具
文章信息
原文地址：https://medium.com/airbnb-engineering/ts-migrate-a-tool-for-migrating-to-typescript-at-scale-cd23bfeb5cc
原文作者：Sergii Rudenko
本文譯者：一川
寫在前面
TypeScript 是 Airbnb 前端 Web 開發的官方語言。然而，采用 TypeScript 和遷移包含數千個 JavaScript 文件的成熟代碼庫的過程并非一日之功。TypeScript 的采用經歷了初始提議、多個團隊采用、測試階段以及最終成為 Airbnb 前端開發的官方語言的過程。您可以在 Brie Bunge 的這次演講中了解更多關于我們如何大規模采用 TypeScript 的信息。
遷移策略
大規模遷移是一項復雜的任務，我們探索了從 JavaScript 遷移到 TypeScript 的幾個選項：
混合遷移策略
逐個文件部分遷移，修復類型錯誤，然后重復，直到遷移完整項目。allowJS 配置選項允許我們讓 TypeScript 和 JavaScript 文件并排共存于項目中，這使得這種方法成為可能！
在混合遷移策略中，我們不必暫停開發，可以逐個文件逐步遷移。雖然，在大規模上，這個過程可能需要很長時間。此外，還需要對來自組織不同部門的工程師進行培訓和入職培訓。
全面遷移
獲取 JavaScript 或部分 TypeScript 項目并將其完全轉換。我們需要添加一些 any 類型和 @ts-ignore 注釋，以便項目編譯時不會出錯，但隨著時間的推移，我們可以用更具描述性的類型替換它們。
選擇 all-in 遷移策略有幾個顯著優勢：
- 跨項目的一致性：整體遷移將保證每個文件的狀態相同，工程師無需記住他們可以在哪里使用 TypeScript 功能以及編譯器將在何處防止基本錯誤。
- 只修復一種類型比修復文件容易得多：修復整個文件可能非常復雜，因為文件可能有多個依賴項。使用混合遷移，很難跟蹤遷移的實際進度和文件的狀態。
看起來整體遷移是這里的明顯贏家！
但是，對大型成熟代碼庫執行全面遷移的過程是一個沉重而復雜的問題。為了解決這個問題，我們決定使用代碼修改腳本——codemods！通過我們最初手動遷移到 TypeScript 的過程，我們認識到可以自動化的重復操作。我們為這些步驟中的每一個都制作了代碼模塊，并將它們組合到總體遷移管道中
根據我們的經驗，并不能 100% 保證自動遷移會產生完全沒有錯誤的項目，但我們發現下面概述的步驟組合為我們提供了最終遷移到無錯誤 TypeScript 的最佳結果項目。使用 codemods，我們能夠在一天內將包含 50,000 多行代碼和 1,000 多個文件的項目從 JavaScript 轉換為 TypeScript！
基于這個管道，我們創建了一個名為“ts-migrate”的工具：
在 Airbnb，我們將 React 用于我們前端代碼庫的重要部分。這就是為什么 codemods 的某些部分與基于 React 的概念相關。ts-migrate 可以通過額外的配置和測試與其他框架或庫一起使用。
遷移過程的步驟
讓我們來看看將項目從 JavaScript 遷移到 TypeScript 所需的主要步驟以及這些步驟是如何實現的：
1、每個 TypeScript 項目的第一部分是創建一個 tsconfig.json 文件，如果需要可以通過ts-migrate執行此操作。有一個默認的配置文件模板和一個驗證檢查，可以幫助我們確保所有項目的配置一致。
這是基本級別配置的示例：
{
"extends": "../typescript/tsconfig.base.json",
"include": [".", "../typescript/types"]
}2、tsconfig.json 文件就位后，下一步是將源代碼文件的文件擴展名從 .js/.jsx 更改為 .ts/.tsx 。此步驟的自動化非常簡單，而且還消除了大量手動工作。
3、下一步是運行 codemods！我們稱它們為“插件”。ts-migrate 的插件是代碼模塊，可以通過 TypeScript 語言服務器訪問其他信息。插件將字符串作為輸入并生成更新的字符串作為輸出。jscodeshift、TypeScript API、字符串替換或其他 AST 修改工具可用于為代碼轉換提供動力。
在每個步驟之后，我們檢查 Git 歷史記錄中是否有任何待處理的更改并提交它們。這有助于將遷移拉取請求拆分為更易于理解的提交，還可以跟蹤文件重命名。
我們將 ts-migrate 分成 3 個包：
- ts-migrate[https://github.com/airbnb/ts-migrate]
- ts-migrate-server[ter/packages/ts-migrate-server]
- ts-migrate-plugins[https://github.com/airbnb/ts-migrate/tree/master/packages/ts-migrate-plugins]
通過這樣做，我們能夠將轉換邏輯與核心運行器分開，并為不同的目的創建多個配置。目前，我們有兩個主要配置：migration 和 reignore 。
雖然遷移配置的目標是從 JavaScript 遷移到 TypeScript，但 reignore 的目的是通過簡單地忽略所有錯誤使項目可編譯。當代碼庫很大并且正在執行以下任務時，Reignore 很有用：
- 升級 TypeScript 版本
- 對代碼庫進行重大更改或重構
- 改進一些常用庫的類型
這樣，即使有一些我們不想立即處理的錯誤，我們也可以遷移項目。它使 TypeScript 或庫的更新變得更加容易。
這兩個配置都在 ts-migrate-server 上運行，它由兩部分組成：
- TSServer ：這部分與 VSCode 編輯器為編輯器和語言服務器之間的通信所做的非常相似。TypeScript 語言服務器的新實例作為單獨的進程運行，開發工具使用語言協議與服務器通信。
- 遷移運行器：這部分運行并協調遷移過程。
它需要以下參數：
interface MigrateParams {
rootDir: string; // path to the root directory
config: MigrateConfig; // migration config, including list of
// plugins it contains
server: TSServer; // an instance of the TSServer fork
}它執行以下操作：
- 解析 tsconfig.json 。
- 創建 .ts 源文件。
- 將每個文件發送到 TypeScript 語言服務器進行診斷。編譯器為我們提供了三種類型的診斷：semanticDiagnostics 、 syntacticDiagnostics 和 suggestionDiagnostics 。我們使用這些診斷來查找源代碼中有問題的地方。基于唯一的診斷代碼和行號，我們可以識別問題的潛在類型并應用必要的代碼修改。
- 在每個文件上運行所有插件。如果文本因插件執行而發生變化，我們會更新原始文件的內容并通知 TypeScript 語言服務器文件已更改。
您可以在示例包或主包中找到 ts-migrate-server 用法示例。ts-migrate-example 還包含插件的基本示例。它們分為 3 個主要類別：
- 基于js代碼轉化
- 基于 TypeScript 抽象語法樹 (AST)
- 基于文本
存儲庫中有一組示例來演示如何構建各種簡單的插件并將它們與 ts-migrate-server 結合使用。以下是轉換以下代碼的示例遷移管道：
function mult(first, second) {
return first * second;
}into:
function tlum(tsrif: number, dnoces: number): number {
console.log(`args: ${arguments}`);
return tsrif * dnoces;
}ts-migrate 在上面的例子中做了 3 次轉換：
- 反轉所有標識符 first -> tsrif
- 添加類型到函數聲明 function tlum(tsrif, dnoces) -> function tlum(tsrif: number, dnoces: number): number
- 插入 console.log(‘args:${arguments}’);
生成插件
實際的插件位于一個單獨的包中 — ts-migrate-plugins。讓我們來看看其中的一些。我們有兩個基于 jscodeshift 的插件：explicitAnyPlugin 和 declareMissingClassPropertiesPlugin。jscodeshift 是一個可以使用 recast 包將 AST 轉換回字符串的工具通過使用函數 toSource() ，我們可以直接更新文件的源代碼。
explicitAnyPlugin 背后的主要思想在于從 TypeScript 語言服務器中提取所有語義診斷錯誤以及行號。然后，我們需要在診斷中指定的行上添加 any 類型。這種方法允許我們解決錯誤，因為添加 any 類型可以修復編譯錯誤。
使用前：
const fn2 = function(p3, p4) {}
const var1 = [];使用后：
const fn2 = function(p3: any, p4: any) {}
const var1: any = [];declareMissingClassPropertiesPlugin 使用代碼 2339 進行所有診斷（你能猜出這段代碼的含義嗎？），如果它可以找到缺少標識符的類聲明，插件將使用 any 類型注釋將它們添加到類主體中。顧名思義，這個 codemod 只適用于 ES6 類。
下一類插件是基于 TypeScript AST 的插件。通過解析 AST，我們可以在源文件中生成一個包含以下類型的更新數組：
type Insert = { kind: 'insert'; index: number; text: string };
type Replace = { kind: 'replace'; index: number; length: number; text: string };
type Delete = { kind: 'delete'; index: number; length: number };生成更新后，唯一剩下的就是以相反的順序應用更改。如果通過這些操作的結果，我們收到新文本，我們將更新源文件。讓我們來看看其中幾個基于 AST 的插件：stripTSIgnorePlugin 和 hoistClassStaticsPlugin。
stripTSIgnorePlugin 是遷移管道中的第一個插件。它從文件中刪除所有 @ts-ignore 1 實例。如果我們將一個 JavaScript 項目轉換為 TypeScript，這個插件將不會做任何事情。但是，如果它是部分 TypeScript 項目（在 Airbnb，我們有幾個項目處于這種狀態），這是必不可少的第一步。只有在刪除 @ts-ignore 注釋后，TypeScript 編譯器才會發出所有需要解決的診斷錯誤。
const str3 = foo
? // @ts-ignore
// @ts-ignore comment
bar
: baz;轉換：
const str3 = foo
? bar
: baz;刪除 @ts-ignore 評論后，我們運行 hoistClassStaticsPlugin 。該插件遍歷文件中的所有類聲明。它決定了我們是否可以提升標識符或表達式，并決定一個賦值是否已經被提升到一個類。
為了能夠快速迭代并防止回歸，我們為每個插件和 ts-migrate 添加了一系列單元測試。
React相關插件
reactPropsPlugin 將類型信息從 PropTypes 轉換為 TypeScript 道具類型定義。它基于 Mohsen Azimi 編寫的出色工具。我們只需要在包含至少一個 React 組件的 .tsx 文件上運行這個插件。reactPropsPlugin 查找所有 PropTypes 聲明并嘗試使用 AST 和簡單的正則表達式（如 /number/ 或更復雜的情況如 /objectOf$/ ）來解析它們。當檢測到 React 組件（功能組件或類組件）時，它會轉換為具有新屬性類型的組件：type Props = {…}; 。
reactDefaultPropsPlugin 涵蓋了 React 組件的 defaultProps 模式。我們使用一種特殊類型來表示具有默認值的props：
type Defined<T> = T extends undefined ? never : T;
type WithDefaultProps<P, DP extends Partial<P>> = Omit<P, keyof DP> & {
[K in Extract<keyof DP, keyof P>]:
DP[K] extends Defined<P[K]>
? Defined<P[K]>
: Defined<P[K]> | DP[K];
};我們試圖找到默認的 props 聲明并將它們與上一步生成的組件 props 類型合并。
狀態和生命周期的概念在 React 生態系統中非常普遍。我們在兩個插件中解決了這些問題。如果組件是有狀態的，則 reactClassStatePlugin 會生成一個新的 type State = any; 并且 reactClassLifecycleMethodsPlugin 會使用適當的類型注釋組件生命周期方法。這些插件的功能可以擴展，包括用更具描述性的類型替換 any 的能力。
對于狀態和道具，還有更多改進和更好類型支持的空間。然而，作為一個起點，這個功能被證明是足夠的。我們也不涉及 hooks，因為在遷移開始時我們的代碼庫使用的是舊版本的 React。
確保項目編譯成功
我們的目標是獲得一個具有基本類型覆蓋率的編譯 TypeScript 項目，不會導致應用程序運行時行為發生變化。
在所有轉換和代碼修改之后，我們的代碼可能具有不一致的格式并且一些 lint 檢查可能會失敗。我們的前端代碼庫依賴于 prettier-eslint 設置——Prettier 用于自動格式化代碼，ESLint 確保代碼遵循最佳實踐。因此，我們可以通過從我們的插件運行 eslint-prettier 來快速修復前面步驟可能引入的任何格式問題。
遷移管道的最后一部分確保解決所有 TypeScript 編譯違規問題。為了檢測和修復潛在的錯誤，tsIgnorePlugin 使用行號進行語義診斷，并插入帶有有用解釋的 @ts-ignore 注釋，例如：
// @ts-ignore ts-migrate(7053) FIXME: No index signature with a parameter of type 'string...
const { field1, field2, field3 } = DATA[prop];
// @ts-ignore ts-migrate(2532) FIXME: Object is possibly 'undefined'.
const field2 = object.some_property;我們還添加了對 JSX 語法的支持：
{*
// @ts-ignore ts-migrate(2339) FIXME: Property 'NORMAL' does not exist on type 'typeof W... */}
<Text weight={WEIGHT.NORMAL}>
some text
</Text>
<input
id="input"
// @ts-ignore ts-migrate(2322) FIXME: Type 'Element' is not assignable to type 'string'.
name={getName()}
/>在注釋中包含有意義的錯誤消息可以更輕松地解決問題并重新訪問需要注意的代碼。這些注釋與 $TSFixMe 2 相結合，使我們能夠收集有關代碼質量的有用數據并識別代碼中可能存在問題的區域。
最后但同樣重要的是，我們需要運行 eslint-fix 插件兩次。在 tsIgnorePlugin 之前給定的格式可能會影響我們將在何處獲得編譯器錯誤。在 tsIgnorePlugin 之后再次出現，因為插入 @ts-ignore 注釋可能會引入新的格式錯誤。
總結
我們的遷移故事正在進行中：我們有一些遺留項目仍在使用 JavaScript，我們的代碼庫中仍然有大量的 $TSFixMe 和 @ts-ignore 評論。
然而，使用 ts-migrate 極大地加快了我們的遷移過程和生產力。工程師們能夠專注于編碼優化，而不是手動逐個文件遷移。目前，我們的 600 萬行前端 monorepo 中約有 86% 已轉換為 TypeScript，我們有望在年底前實現 95% 的轉換。
您可以查看 ts-migrate 并在 Github 存儲庫的主包中找到有關如何安裝和運行 ts-migrate 的說明。如果您發現任何問題或有改進的想法，我們歡迎您的貢獻！
非常感謝 Brie Bunge，他是 Airbnb TypeScript 的推動者，也是 ts-migrate 的創建者。感謝 Joe Lencioni 幫助我們在 Airbnb 采用 TypeScript 并改進我們的 TypeScript 基礎設施和工具。特別感謝 Elliot Sachs 和 John Haytko 為 ts-migrate 做出的貢獻。感謝所有提供反饋和幫助的人！
Footnote
我們想記下我們在此過程中發現的一些關于遷移的事情，它們可能會有用：
- TypeScript 3.7 版本引入了 @ts-nocheck 注釋，可以將其添加到 TypeScript 文件的頂部以禁用語義檢查。我們沒有使用這個注釋，因為它之前不支持 .ts/.tsx 文件，但它在遷移過程中也可以成為一個很好的中間階段幫手。
- TypeScript 3.9 版本引入了 @ts-expect-error 注釋。當一行以 @ts-expect-error 注釋為前綴時，TypeScript 將禁止報告該錯誤。如果沒有錯誤，TypeScript 將報告不需要 @ts-expect-error 。在 Airbnb 代碼庫中，我們改用 @ts-expect-error 注釋而不是 @ts-ignore 。
- @ts-ignore 注釋允許我們告訴編譯器忽略下一行的錯誤。
- 我們為 any 類型引入了自定義別名 — 和函數類型TSFixMeFunction = (…args: any[]) => any; 。盡管最佳實踐是避免使用 any 類型，但使用它可以幫助我們簡化遷移過程并明確應該重新訪問哪些類型。
寫在最后
在ts大量應用在新項目，而對于js老項目維護卻日益艱難，在前端行業有很多人做過很多嘗試將js項目遷移到ts代碼。ts-migrate的出現在一定程度上，能夠幫助我們漸進式遷移到ts，減少使用和開發成本。
學而知不足，水平有限，還望諸君多多指教。覺得文章不錯的讀者，不妨點個關注，收藏起來上班摸魚的時候品嘗。
