Apollo Client 3→4 迁移指南:@apollo/client-codemod-migrate-3-to-4 全面解析

原创2026-09-20 12:07:231,685 阅读
文章标签:前端GraphQL缓存抽象

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):

  1. 显式构造 Link:若未传 link 选项,则移除 uri/credentials/headers,并自动生成 link: new HttpLink({ uri, credentials, headers }),HttpLink 的导入自动补到 @apollo/client/link/http(explicitLinkConstruction);
  2. clientAwareness:将 name 与 version 收敛为 clientAwareness: { name, version } 子对象(clientAwareness);
  3. localState:移除顶层 typeDefs 与 fragmentMatcher,将 resolvers 移入新增的 localState: new LocalState({ resolvers }),LocalState 从 @apollo/client/local-state 导入;若原本没有 resolvers,会自动追加一段注释提醒"未使用 @client 指令时可安全删除此选项"(localState);
  4. devtools 选项:connectToDevTools: true/false → devtools: { enabled: true/false }(devtoolsOption);
  5. disableNetworkFetches 更名:disableNetworkFetches → prioritizeCacheValues,语义从"禁用网络请求"调整为"优先返回缓存值"(prioritizeCacheValues);
  6. dataMasking 类型增强模板:若启用 dataMasking,向文件末尾追加一段"模块增强(module augmentation)"模板,继承 GraphQLCodegenDataMasking.TypeOverrides 以恢复 data masking 的类型能力;仅在 .ts/.tsx 文件中插入,且通过 codemod 标记注释保证重复运行不会重复插入(dataMasking);
  7. 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、removals codemod,并扩展 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 与源码,迁移后仍需人工检查的点包括:

  1. setContext → ContextLink 必须手动改写:回调参数顺序翻转,无法自动化(src/links.ts);
  2. removals 指向的 v4-migration 占位需要逐条对照注释寻找替代方案(src/v4-migration.ts);
  3. dataMasking 与 incrementalHandler 生成的类型增强模板需要复制到项目的 .d.ts 文件中才能生效,若未使用 @client 指令或 @defer 指令,相关选项与模板均可安全删除;
  4. codemod 生成的注释块带有 @apollo/client-codemod-migrate-3-to-4 标记(apolloClientInitialization.ts),用于防止重复运行时的重复改写——迁移完成后记得清理这些标记注释;
  5. 迁移完成后建议在仓库内运行 tsc 类型检查并执行测试套件,以 v4-migration 入口点的类型错误作为待办清单,逐项完成剩余修复。
登录后查看全文
apollo-client