Apollo Client 3→4 迁移指南:@apollo/client-codemod-migrate-3-to-4 全面解析
Apollo Client 3→4 迁移指南:@apollo/client-codemod-migrate-3-to-4 全面解析
@apollo/client-codemod-migrate-3-to-4 是 Apollo Client 官方提供的自动化迁移工具,用于将项目从 Apollo Client 3.x 一键迁移到 4.x。本文以该工具的变更日志(CHANGELOG.md)为骨架,结合仓库内工具源码(位于 scripts/codemods/ac3-to-ac4/src)与配套文档(README.md),完整梳理其五个转换步骤、clientSetup 七大自动改写动作、版本演进过程与手动介入要点。读完本文,你将能独立运行该 codemod 完成项目迁移,并理解每一行改写背后的实现原理。
一、工具定位:从 3.x 入口点到 4.x 的自动桥接
Apollo Client 4.0 对包的导入入口(entry point)、API 命名与构造函数选项进行了大规模重构。手写迁移既枯燥又易错,因此官方随迁移指南一同发布了名为 @apollo/client-codemod-migrate-3-to-4 的 codemod 工具,通过 jscodeshift)解析并改写 TypeScript/JavaScript 源码。
从当前仓库的 src/index.ts 可以看到,工具内置五个可独立或串联执行的 codemod,按默认顺序依次为:
export const codemods = {
legacyEntrypoints,
imports,
links,
removals,
clientSetup,
} satisfies Record<string, Transform>;
入口 transform 会对每个文件逐个执行启用的 codemod,并把上一次的结果作为下一次的输入,形成流水线(src/index.ts)。cli.ts 则将自身注册为 jscodeshift 的 transform 后直接转交 jscodeshift 的 CLI 执行(src/cli.ts)。
二、快速上手:安装、运行与常用参数
工具通过 npx 直接运行,无需预先安装(命令来自 README.md):
# 对指定文件运行全部 codemod(按默认顺序)
npx @apollo/client-codemod-migrate-3-to-4 --parser ts file1.ts file2.ts
# 仅运行某一个 codemod
npx @apollo/client-codemod-migrate-3-to-4 --parser ts file1.ts file2.ts --codemod imports
工具支持 .js、.jsx、.ts、.tsx 四种文件类型(CHANGELOG.md 中 1.0.0 版本明确声明)。由于 TypeScript 与 TSX 存在语法重叠,官方建议对两种扩展名分别运行以避免解析错误(README.md):
npx @apollo/client-codemod-migrate-3-to-4 --parser ts --ignore-pattern="*.{tsx,d.ts}" file1.ts file2.ts
npx @apollo/client-codemod-migrate-3-to-4 --parser tsx --ignore-pattern="*.ts" file1.ts file2.ts
若需试用某个特定 PR 的版本,还可以借助 pkg.pr.new 直接按 PR 号运行:
npx https://pkg.pr.new/apollographql/apollo-client/@apollo/client-codemod-migrate-3-to-4@12733 --parser ts file1.ts file2.ts
三、五个 codemod 步骤详解
3.1 legacyEntryPoints:清理旧入口点导入
Apollo Client 3.x 时代,除语义化入口点外,还暴露了大量形如 @apollo/client/main.cjs、@apollo/client/index.js、@apollo/client/core/core.cjs 的物理文件入口。该步骤将这些旧入口点的导入统一改写为 4.x 的语义化入口点,例如(legacyEntryPoints.test.ts):
@apollo/client/main.cjs、@apollo/client/index.js、@apollo/client/apollo-client.cjs→@apollo/client@apollo/client/core/index.js、@apollo/client/core/core.cjs→@apollo/client@apollo/client/link/core/index.js、@apollo/client/link/core/core.cjs→@apollo/client/link@apollo/client/react/react.cjs→@apollo/client/react
映射表定义在 src/util/entryPointAliases.ts,覆盖全部历史入口点(含 main.cjs.native.js 等变体)。实现上,该步骤会遍历 entryPointAliases,对每个"旧入口 → 新入口"对执行模块重命名(src/legacyEntrypoints.ts),并且当目标入口已存在同名导入时,会将标识符合并进已有 import 语句,避免重复声明。
3.2 imports:模块与标识符重命名
4.x 收紧了各入口点的导出范围,大量 API 更换了模块归属或名称。该步骤基于 renames 表(src/renames.ts)执行两类改写:
- 模块级重命名:如
@apollo/client/core→@apollo/client、@apollo/client/link/core→@apollo/client/link、@apollo/client/react/hooks与@apollo/client/react/context→@apollo/client/react、@apollo/client/testing/core→@apollo/client/testing; - 标识符级重命名:如类型
QueryReference→QueryRef;ApolloProvider、createQueryPreloader、skipToken、useQuery、useSuspenseQuery等 hook 与组件被迁移到@apollo/client/react入口点重新导出,同时大量 hook 相关类型(LazyQueryHookOptions、MutationHookOptions、PreloadQueryFunction等)也一并移动。
具体实现位于 src/imports.ts:先执行模块重命名,再执行标识符重命名,并把"类型"迁移到命名空间导入(namespace import)中,保证类型与值互不混淆。CHANGELOG 1.0.0 的 Minor Changes 中也记载了这一扩展(CHANGELOG.md)。
3.3 links:Link 函数式 API 到类式 API
4.x 将链接(link)相关的函数式 API 收敛为类(class)形式,该步骤完成以下改写(src/links.ts):
| 3.x 写法 | 4.x 写法 |
|---|---|
concat(...) |
ApolloLink.concat(...) |
empty(...) |
ApolloLink.empty(...) |
from(...) |
ApolloLink.from(...) |
split(...) |
ApolloLink.split(...) |
createHttpLink({...}) |
new HttpLink({...}) |
onError(...) |
new ErrorLink(...) |
createPersistedQueryLink(...) |
new PersistedQueryLink(...) |
removeTypenameFromVariables(...) |
new RemoveTypenameFromVariablesLink(...) |
前四项把 concat/empty/from/split 挂到 ApolloLink 命名空间下,后四项通过 callExpressionToNewExpression 工具把函数调用改写为 new 表达式。
需要特别注意的是 setContext:代码中该转换被显式注释禁用(src/links.ts),因为 setContext((operation, prevContext) => {}) 与 4.x 的 ContextLink 回调参数顺序是翻转的((prevContext, operation)),这种语义反转无法被可靠地自动化改写,必须由开发者手动处理——这是本次迁移中少有的"机器代劳不了"的环节。
3.4 removals:已删除导出的兜底指引
4.x 移除了大量 API,包括 graphql HOC(withApollo/withMutation 等)、Query/Mutation/Subscription 渲染属性组件、ApolloConsumer、parser/operationName、Concast、ObservableSubscription 等(完整清单见 src/removals.ts)。该步骤不会凭空修复这些代码,而是把相关导入全部指向专用的 @apollo/client/v4-migration 入口点(src/removals.ts)。
该入口点的实现位于 src/v4-migration.ts,每个被移除的导出都以 never 类型占位并附带说明注释,例如 Concast 的注释建议改用 rxjs 的 BehaviorSubject,DataProxy 的注释提示相关类型可到 ApolloClient 或 Cache 命名空间查找。迁移后,你的 IDE 会在这些位置给出清晰的迁移指引,逐个击破即可。
3.5 clientSetup:ApolloClient 初始化选项整体改写
这是信息量最大的一个步骤,见下文专节。
四、clientSetup 七大自动改写动作
clientSetup(实现文件为 src/apolloClientInitialization.ts)会找到所有 new ApolloClient({...}) 构造调用(包括从 @apollo/client、@apollo/client/core 及各类集成包导入的 ApolloClient,见 L516-L527),依次应用下列步骤(steps 注册表见 L14-L22):
- 显式构造 Link:若未传
link选项,则移除uri/credentials/headers,并自动生成link: new HttpLink({ uri, credentials, headers }),HttpLink的导入自动补到@apollo/client/link/http(explicitLinkConstruction); - clientAwareness:将
name与version收敛为clientAwareness: { name, version }子对象(clientAwareness); - localState:移除顶层
typeDefs与fragmentMatcher,将resolvers移入新增的localState: new LocalState({ resolvers }),LocalState从@apollo/client/local-state导入;若原本没有resolvers,会自动追加一段注释提醒"未使用@client指令时可安全删除此选项"(localState); - devtools 选项:
connectToDevTools: true/false→devtools: { enabled: true/false }(devtoolsOption); - disableNetworkFetches 更名:
disableNetworkFetches→prioritizeCacheValues,语义从"禁用网络请求"调整为"优先返回缓存值"(prioritizeCacheValues); - dataMasking 类型增强模板:若启用
dataMasking,向文件末尾追加一段"模块增强(module augmentation)"模板,继承GraphQLCodegenDataMasking.TypeOverrides以恢复 data masking 的类型能力;仅在.ts/.tsx文件中插入,且通过 codemod 标记注释保证重复运行不会重复插入(dataMasking); - incrementalHandler:新增
incrementalHandler: new Defer20220824Handler()(从@apollo/client/incremental导入),并为自定义 link 的网络响应类型追加Defer20220824Handler.TypeOverrides类型增强模板,同时附注释说明不使用@defer指令时可安全移除(incrementalHandler)。
此外还有第 8 个动作 removeTypeArguments:移除所有 ApolloClient 使用处的 TCacheShape 泛型参数——4.x 不再接受该类型参数,无论类型声明还是构造调用都会一并清理(L67-L90,见 CHANGELOG 1.0.0 Patch Changes)。
五、版本演进:从 CHANGELOG 看工具迭代
关联文档 CHANGELOG.md 完整记录了工具从 1.0.0-rc.0 到 1.0.2 的演进,主线如下:
- 1.0.0-rc.0 / 1.0.0:引入首个
imports重命名 codemod(最初即支持.js/.jsx/.ts/.tsx);随后的 rc.1/rc.2 相继加入legacyEntryPoints转换步骤与links、removalscodemod,并扩展imports;同时修正gql不应从@apollo/client/react入口点导出(改为从@apollo/client导入);clientSetup增加移除TCacheShape泛型的能力。 - 1.0.1:从
@apollo/client/utilities导出isNetworkStatusInFlight,新增isNetworkStatusSettled并在@apollo/client顶层带弃用标记重新导出——对应仓库中的 src/utilities/isNetworkRequestInFlight.ts 与 src/utilities/isNetworkRequestSettled.ts。 - 1.0.2:修复
networkStatus未被移动到正确包的问题(与 src/core/networkStatus.ts 中的NetworkStatus类型组织相关),这也是当前仓库所持版本(见 package.json)。
值得注意的是 clientSetup 的引入(PR #12851)同时被记录在 1.0.0-rc.3 与 1.0.0 中,属于发布前合并进正式版的功能,两个版本的变更说明完全一致。
六、正确性与可验证性
工具自带 Vitest 测试套件(npm test,见 package.json),覆盖各步骤的转换行为:
- legacyEntryPoints.test.ts:验证各类旧入口点的重命名、同名导入合并、以及"类型导入与值导入不合并"等边界情况;
imports.test.ts、links.test.ts、removals.test.ts及apolloClientInitialization.test.ts分别验证对应步骤;__tests__/__snapshots__/目录下的快照文件记录了exports与removals转换的精确输出;__testfixtures__/imports.input.ts与imports.output.ts提供"输入 → 期望输出"的成对夹具(fixture)示例。
removals 步骤的准确性还依赖 exports.removed.json、exports.removed.local.json 等导出清单文件(见 src/tests),这些清单与实际 4.x 包的导出保持同步。
七、迁移注意事项与手动收尾
综合 CHANGELOG 与源码,迁移后仍需人工检查的点包括:
setContext→ContextLink必须手动改写:回调参数顺序翻转,无法自动化(src/links.ts);removals指向的v4-migration占位需要逐条对照注释寻找替代方案(src/v4-migration.ts);dataMasking与incrementalHandler生成的类型增强模板需要复制到项目的.d.ts文件中才能生效,若未使用@client指令或@defer指令,相关选项与模板均可安全删除;- codemod 生成的注释块带有
@apollo/client-codemod-migrate-3-to-4标记(apolloClientInitialization.ts),用于防止重复运行时的重复改写——迁移完成后记得清理这些标记注释; - 迁移完成后建议在仓库内运行
tsc类型检查并执行测试套件,以v4-migration入口点的类型错误作为待办清单,逐项完成剩余修复。