Apollo Client 3 到 4 迁移指南:使用 codemod 自动化升级 `@apollo/client-codemod-migrate-3-to-4`

原创2026-09-20 21:46:121,729 阅读
文章标签:前端GraphQL缓存抽象

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/Subscription render-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)建议在运行后按以下顺序人工收尾:

  1. 安装新依赖:Apollo Client 4 新增 rxjs 作为 peer dependency,需要执行 npm install @apollo/client@latest graphql rxjs。
  2. 检查 v4-migration 残留引用:removals 变换留下的 @apollo/client/v4-migration import 应逐一查看文档注释并按建议替换或删除,最终清理掉对该入口点的引用。
  3. 人工处理 setContext:按前文所述手动完成 setContext 到 ContextLink 的改写与参数顺序调整。
  4. 确认可选模板:若未使用 @client 指令或 @defer,可删除 codemod 插入的 localState、incrementalHandler 选项及相关类型增强块;若使用了数据屏蔽,则需要将 dataMasking 类型增强块的内容复制到项目自己的 .d.ts 文件中。
  5. 审查 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 迁移更平滑。

登录后查看全文
apollo-client