Apollo Client 3 到 4 迁移指南:使用 codemod 自动化升级 `@apollo/client-codemod-migrate-3-to-4`
Apollo Client 3 到 4 迁移指南:使用 codemod 自动化升级 @apollo/client-codemod-migrate-3-to-4
Apollo Client 4 是一次主版本升级,引入了大量破坏性变更:入口点重组、Link 相关 API 的类化、若干导出被移除、ApolloClient 初始化选项全面调整。本文以仓库中官方发布的 @apollo/client-codemod-migrate-3-to-4 为核心,完整讲解该 codemod 的安装运行方式、五大内置变换(legacyEntryPoints、imports、links、removals、clientSetup)各自的作用范围,并结合源码剖析其底层实现原理。读完本文,你将能够一次性或分步自动完成代码库中绝大多数 3.x → 4.x 的机械性迁移工作,并为剩余的少量需人工干预的场景(如 setContext 参数翻转)做好准备。
为什么需要 codemod:Apollo Client 4 的破坏性变更
在动手运行工具之前,先明确它解决的问题。官方迁移文档 docs/source/migrating/apollo-client-4-migration.mdx 将 4.0 的变更归纳为几个层面:
- 框架与打包改进:核心与框架解耦,React 相关导出移至
@apollo/client/react;借助package.json的exports字段提供更好的 ESM 支持;Observable 实现从zen-observable切换到rxjs。 - API 形态变化:
split、from、concat、empty移入ApolloLink命名空间;createHttpLink(...)等函数式 Link 工厂改为new HttpLink(...)类实例。 - 导出清理:HOC、render prop 组件、
parser等一大批内部实现细节被移除。 - 初始化选项重构:
uri/headers/credentials移入link选项、新增clientAwareness、localState、devtools.enabled、incrementalHandler等。
这些变更数量多、模式机械,手动修改既容易遗漏又容易出错,因此官方在仓库的 scripts/codemods/ac3-to-ac4 目录下维护了专用 codemod 包,发布为 npm 包 @apollo/client-codemod-migrate-3-to-4(当前版本 1.0.2,见 package.json),其 bin 字段将 CLI 指向 dist/cli.js。
快速开始:基本用法
在项目根目录执行以下命令即可对指定文件运行全部 codemod:
npx @apollo/client-codemod-migrate-3-to-4 --parser ts file1.ts file2.ts
说明:
npx会自动拉取并执行@apollo/client-codemod-migrate-3-to-4包中的 CLI。--parser ts指定按 TypeScript 语法解析;也可换成tsx、babel、flow等 jscodeshift 支持的 parser。- 文件参数可传多个,也可以使用 glob 通配,例如
./src/**/*.{ts,tsx}(官方 CHANGELOG 中给出的示例命令)。 - 若未通过
--codemod指定,将按默认顺序依次执行全部五个 codemod(见下文),每次变换的结果会作为下一次变换的输入,最终只输出一次。
如果只想运行某一个 codemod,例如只做 import 修正:
npx @apollo/client-codemod-migrate-3-to-4 --parser ts file1.ts file2.ts --codemod imports
--codemod 参数同样支持多个值,可组合出自定义的变换流水线。
五个内置 codemod 详解
以下五个变换按默认执行顺序排列,定义在 src/index.ts 的 codemods 注册表中。若指定的 codemod 名称不存在,CLI 会打印 Codemod "xxx" not found, skipping. 警告并以非零退出码结束(源码见 src/index.ts#L46-L49)。
1. legacyEntryPoints:迁移旧入口点
将来自旧版遗留入口点的 import 迁移到新入口点。旧入口点指的是 3.x 时代为兼容打包工具而暴露的深层路径,例如:
@apollo/client/main.cjs、@apollo/client/apollo-client.cjs、@apollo/client/index.js→@apollo/client@apollo/client/react/react.cjs→@apollo/client/react@apollo/client/core/core.cjs→@apollo/client/core- 以及
@apollo/client/link/http/http.cjs、@apollo/client/testing/testing.cjs等各子模块的.cjs/index.js变体
完整的入口点别名映射表定义在 src/util/entryPointAliases.ts,该文件甚至保留了从各子包 package.json 的 main/module 字段自动生成映射的注释说明。实现上,该变换通过 handleModuleRename 将每一组旧模块路径改写为对应的新模块路径(见 src/legacyEntrypoints.ts)。
2. imports:修正被移动或重命名的导出
处理在 Apollo Client 4 中被移动、重命名,或需要收敛为命名空间导入的符号。它基于 src/renames.ts 中维护的重命名清单,包含两类操作(源码见 src/imports.ts):
- 模块级重命名(
handleModuleRename):如@apollo/client/core→@apollo/client、@apollo/client/link/core→@apollo/client/link、@apollo/client/react/context与@apollo/client/react/hooks→@apollo/client/react、@apollo/client/testing/core→@apollo/client/testing。 - 标识符级重命名(
handleIdentiferRename):将具体符号从一个模块移动到另一个模块,必要时把多个类型折叠进命名空间导入。例如QueryReference类型的迁移就同时考虑了@apollo/client/react、@apollo/client、@apollo/client/react/internal等替代来源。
从源码结构看,renames.ts 中还以注释形式保留了若干"在 AC4 中整体移除"的模块清单(如 react/components、react/hoc、react/parser、testing/experimental、utilities/globals、utilities/subscriptions/urql 等),表明这些模块的符号统一交由 removals 变换处理,而不是在 imports 中做模块重定向。
3. links:Link API 类化与命名空间收敛
处理 Link 相关 API 的形态变化(完整清单见 src/links.ts):
- 将
split、from、concat、empty从@apollo/client/link(或@apollo/client)移动到ApolloLink命名空间下,即split(...)→ApolloLink.split(...)、concat(...)→ApolloLink.concat(...)等。 - 将函数式 Link 工厂调用改写为类实例化:
createHttpLink(...)→new HttpLink(...)createPersistedQueryLink(...)→new PersistedQueryLink(...)onError(...)→new ErrorLink(...)removeTypenameFromVariables(...)→new RemoveTypenameFromVariablesLink(...)
这些"调用表达式转 new 表达式"的改写由 callExpressionToNewExpression 工具完成。
需要人工干预的场景:setContext((operation, prevContext) => {}) 不会自动转换为 new ContextLink((prevContext, operation) => {})。原因是两个回调的参数顺序恰好相反(前者先 operation 后 prevContext,后者先 prevContext 后 operation),机械改写无法可靠判断参数用法,因此 README 明确要求手动处理。源码中对应的转换逻辑同样处于注释状态(见 src/links.ts#L54-L61)。
4. removals:把已移除的导出指向 v4-migration
Apollo Client 4 移除了一大批导出。本变换将这些符号的 import 统一指向新的迁移入口点 @apollo/client/v4-migration,该入口点内为每个移除项附带说明与替代建议。
被移除项分两类(完整清单见 src/removals.ts):
- 类型:如
ClientParseError、FragmentMatcher、Resolver/Resolvers、Masked、MutationUpdaterFn、QueryLazyOptions,以及@apollo/client/utilities下大量RemoveXxxConfig、DirectiveInfo等工具类型。 - 值:如
ApolloError、isApolloError、DataProxy、Concast、Observer/ObservableSubscription、graphql/withApollo等 HOC 函数、Query/Mutation/Subscriptionrender-prop 组件、createMockClient等测试辅助函数。
@apollo/client/v4-migration 入口点由 src/v4-migration.ts 提供。该文件为每个移除项生成了带详细文档注释的占位声明,例如:
Concast注释建议改用rxjs的BehaviorSubject;DataProxy注释指出原命名空间中的类型可在ApolloClient或Cache命名空间中找到;ApolloConsumer、Mutation等 render-prop API 直接标注为已移除。
这样做的价值在于:迁移后你的代码仍能通过编译检查,每处残留引用都会在 IDE 中显示出替代指引,方便逐个排查。
5. clientSetup:重构 ApolloClient 初始化代码
这是信息量最大的一个变换,对应迁移文档中"更新 ApolloClient 初始化"一节。它定位代码中所有 new ApolloClient({...}) 构造调用(通过 import 引用分析精确识别,见 src/apolloClientInitialization.ts 中的 apolloClientConstructions),并按步骤改写,具体包括:
a. 显式构建 link:若不存在 link 选项,则将 uri、credentials、headers 三个选项从顶层移除,导入 HttpLink,并生成 link: new HttpLink({ uri, credentials, headers })(保留其中存在的字段)。
b. 引入 clientAwareness:将顶层 name、version 选项移入 clientAwareness: { name, version }。若无这两个选项则跳过。
c. 引入 localState:新增 localState: new LocalState({ resolvers }) 选项,将顶层 resolvers 移入其中,并删除 typeDefs 与 fragmentMatcher 选项。值得注意的实现细节:如果原代码本来没有 resolvers,codemod 仍会插入一个空的 LocalState 实例,并附带注释说明——"如果你的应用没有使用 @client 指令,可以安全移除该选项"。
d. devtools 选项重构:将 connectToDevTools: true/false 改写为 devtools: { enabled: true/false }(实现中处理了简写属性等边缘情况)。
e. 重命名 disableNetworkFetches:将 disableNetworkFetches 重命名为 prioritizeCacheValues。
f. dataMasking 类型模板:若启用 dataMasking(且值为非 false),则会在文件尾部插入一段全局类型增强模板(declare module "@apollo/client" { interface TypeOverrides extends GraphQLCodegenDataMasking.TypeOverrides {} }),用于恢复数据屏蔽(data masking)的类型支持。模板前会添加标记注释 @apollo/client-codemod-migrate-3-to-4 applied——该标记使 codemod 具备幂等性:重复运行时若检测到标记则跳过,避免重复插入。
g. incrementalHandler:新增 incrementalHandler: new Defer20220824Handler() 选项(从 @apollo/client/incremental 导入),用于启用 @defer 增量交付;同时同样插入一段类型增强模板,为自定义 Link 中的网络响应提供正确的增量类型。若未使用 @defer,插入的注释也明确提示可安全移除。
h. 移除 TCacheShape 泛型参数:从所有 ApolloClient 的类型标注和构造调用中删除 TCacheShape 类型参数(该步骤对所有引用生效,不仅限于构造调用,见 src/apolloClientInitialization.ts#L67-L90)。
此外,clientSetup 还支持 --apolloClientInitialization 参数来单独启用某个子步骤(源码通过 options.apolloClientInitialization 读取,默认启用全部步骤)。ApolloClient 的识别不仅限于 @apollo/client,还包括 @apollo/client/core、@apollo/client-integration-nextjs、@apollo/client-integration-react-router、@apollo/client-integration-tanstack-start、@apollo/experimental-nextjs-app-support、@apollo/client-react-streaming 等替代来源。
进阶用法
针对 TypeScript / TSX 分别运行
TypeScript 与 TSX(TypeScript + JSX)文件存在语法重叠,直接混用单一 parser 可能报错。README 建议分别对两类文件运行,并借助 --ignore-pattern 互相排除:
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
注意第一个命令还通过 --ignore-pattern="*.{tsx,d.ts}" 排除了声明文件 .d.ts。
从特定 PR 使用 codemod
如果你想使用某个尚未正式发版的 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
其中 @12733 是 apollo-client 仓库的 PR 编号。例如 CHANGELOG 中记录的 1.0.1 修复(networkStatus 未能正确迁移到目标包的问题)即属于此类场景。
在仓库内本地运行
如果要在 apollo-client 仓库内直接对源码运行,仓库提供了 runLocally.sh 脚本,它会以 babylon parser 配合完整的 Babel 插件配置(覆盖 TypeScript、JSX、decorators、pipeline operator 等各类语法)执行 CLI,默认作用于 src 目录。本地开发也可通过 npm run local:cli(即 node --import ./src/devLoader.js src/cli.ts)直接调试 CLI。
迁移后的收尾工作
codemod 只覆盖机械性改写,官方迁移文档(docs/source/migrating/apollo-client-4-migration.mdx)建议在运行后按以下顺序人工收尾:
- 安装新依赖:Apollo Client 4 新增
rxjs作为 peer dependency,需要执行npm install @apollo/client@latest graphql rxjs。 - 检查 v4-migration 残留引用:
removals变换留下的@apollo/client/v4-migrationimport 应逐一查看文档注释并按建议替换或删除,最终清理掉对该入口点的引用。 - 人工处理 setContext:按前文所述手动完成
setContext到ContextLink的改写与参数顺序调整。 - 确认可选模板:若未使用
@client指令或@defer,可删除 codemod 插入的localState、incrementalHandler选项及相关类型增强块;若使用了数据屏蔽,则需要将dataMasking类型增强块的内容复制到项目自己的.d.ts文件中。 - 审查 diff 并重跑:codemod 插入的标记注释(
@apollo/client-codemod-migrate-3-to-4 applied)在迁移完成后即可删除;由于标记使变换幂等,分批迁移时重跑是安全的。
原理与边界:它如何保证安全性
从 src/index.ts 的实现可以看出几个设计要点:
- 流水线式应用:未指定 codemod 时依次运行全部变换,前一个变换的输出作为后一个的输入;只有发生实际修改时才返回新源码,否则返回
undefined表示文件未变(避免无谓改动与格式抖动)。 - 基于 jscodeshift 的 AST 变换:包依赖仅有
jscodeshift(17.3.0),所有改写均在 AST 层面完成,而非文本替换,因此对注释、字符串内容、代码格式等不相关部分零干扰;CLI 入口(src/cli.ts)本质上就是把 jscodeshift 的--transform指向打包后的index.js。 - 导入引用追踪:
clientSetup不会盲目改写所有ApolloClient使用点,而是先找到 import 说明符,再通过findReferences做作用域感知的引用分析,仅改写真正的构造调用,避免误伤同名变量。 - 幂等标记:
dataMasking等步骤通过标记注释防止重复应用,这是长期维护代码库时可以放心重跑的前提。
需要提醒的边界:该工具只处理文档明确列出的机械模式,对 setContext 参数翻转、涉及业务逻辑的 HOC 迁移、以及 @apollo/client/react/parser 等被整体移除模块的替代方案选择,仍需结合 src/v4-migration.ts 中的指引与官方迁移文档(docs/source/migrating/apollo-client-4-migration.mdx)人工完成。官方建议:若从更早的 3.x 版本迁移,应先升级到 3.14——该版本引入了大量弃用警告,能帮助你在运行 codemod 前提前暴露需要处理的问题,让整个 3 → 4 迁移更平滑。