前端GraphQL【免费下载链接】apollo-clientThe industry-leading GraphQL client for TypeScript, JavaScript, React, Vue, Angular, and more. Apollo Client delivers powerful caching, intuitive APIs, and comprehensive developer tools to accelerate your app development.项目地址https://gitcode.com/gh_mirrors/ap/apollo-client点击查看免费下载本篇文章以仓库中的 .api-reports/api-report-core.api.md由 Microsoft API Extractor 自动生成的apollo/client主入口类型报告为骨架逐一拆解ApolloClient、ObservableQuery、QueryManager三大核心类及其配套的类型系统并结合 src/core 目录下的真实实现源码ApolloClient.ts、QueryManager.ts、ObservableQuery.ts、networkStatus.ts、watchQueryOptions.ts做纵深印证。读完本文你将能熟练阅读.api-reports下的全部 API 报告理解 Apollo Client 查询、变更、缓存读写的完整调用链以及fetchPolicy、errorPolicy、NetworkStatus、数据掩蔽等核心类型在类型层面与运行时层面的双重语义。一、这份文档是什么读懂 API Report 的定位与价值.api-reports/api-report-core.api.md是仓库通过 config/apiExtractor.ts 调用 API Extractor 生成的公共 API 快照。它面向apollo/client包的入口文件即import ... from apollo/client时能拿到的全部导出具有以下特点不可手工编辑文件头部明确标注 Do not edit this file. It is a report generated by API Extractor任何公共 API 的增删改都会在 CI 中反映到该文件的 diff是团队维护接口稳定性的契约文件。标注可见性每条导出都带有public、internal、deprecated标签。例如ApolloClientOptions被标记为public deprecatedInternalTypes命名空间为internal deprecated说明它们是旧版本遗留、仅为了向后兼容而保留的别名。以export { ... }形式回显转发导出报告会把从apollo/client/cache、apollo/client/link、apollo/client/errors、apollo/client/masking等子路径转发出来的符号如ApolloCache、ApolloLink、InMemoryCache、gql、HttpLink、makeVar一并列出并保留原始来源路径见报告第 5113 行的 import 清单。在 .api-reports 目录下与 core 报告并列的还有 cache、link、react、testing、utilities 等 30 余份分模块报告共同构成整个包的API 地图。本文聚焦 core 报告覆盖的正是包根入口所暴露的最核心 API。二、ApolloClient 类客户端实例的完整面貌报告第 476550 行给出了ApolloClient类的全部公共成员。它同时以类 命名空间的合并声明形式暴露大量类型ApolloClient.Options、ApolloClient.QueryOptions、ApolloClient.WatchQueryOptions等这是 Apollo Client 现代版本的标志性设计类型与运行时实现同名共存便于 IDE 自动补全与文档联动。2.1 构造函数与 Options 配置项constructor(options: ApolloClient.Options)中Options接口报告第 322344 行在源码 ApolloClient.ts 中有完整注释各字段及语义如下配置项类型默认值/说明linkApolloLink必填网络层负责把操作发往 GraphQL 服务端cacheApolloCache必填本地缓存官方推荐InMemoryCachessrForceFetchDelaynumber服务端渲染后强制重新拉取查询的延迟毫秒数默认0ssrModeboolean置为true时配合getDataFromTree做服务端渲染默认falsequeryDeduplicationboolean完全相同的查询查询串、变量、operationName 均一致在途时是否复用同一请求默认trueassumeImmutableResultsboolean假定应用从不修改缓存读出的结果以开启性能优化默认falsedefaultContextPartialDefaultContext注入每个操作的默认 contextclientAwareness/enhancedClientAwarenessClientAwarenessOptions向服务端上报客户端标识对应ClientAwarenessLink见 src/link/client-awarenessdocumentTransformDocumentTransform对文档进行全局变换见 src/utilities/graphql/DocumentTransform.tsdevtoolsDevtoolsOptions开发工具配置enabled决定 Devtools 扩展能否连接生产默认false、开发且有window时默认truename用于多客户端实例时在面板中区分dataMaskingboolean是否启用数据掩蔽默认falseincrementalHandlerIncremental.Handler解析defer增量响应分块的策略见 src/incrementalexperimentsExperiment[]实验性功能入口v: 1版本号的函数数组仅供 Apollo 官方提供refetchEventManagerRefetchEventManager管理自动重新拉取的事件管理器2.2 查询方法族query 与 watchQueryApolloClient提供两套查询入口对应源码 ApolloClient.tsquery(options)一次性的 Promise 语义返回PromiseQueryResultMaybeMaskedTData。源码中明确校验开发环境下抛出 invariant 错误不允许cache-and-network因为它需要返回多个结果见watchQuery的注释不允许standby该策略不发起请求必须传query且以gql包装query.kind DocumentreturnPartialData、pollInterval、notifyOnNetworkStatusChange仅适用于watchQuery。watchQuery(options)返回ObservableQueryTData, TVariables可订阅持续接收缓存更新同时支持pollInterval轮询、returnPartialData、refetchOn等选项。源码还会把defaultOptions.watchQuery与调用参数合并mergeOptions并对refetchOn对象形式与默认值做深度合并。补充query的现代签名ApolloClient.query.Signature报告第 346389 行由SignatureStyleclassic | modern驱动modern风格通过OptionsFor/ResultForOptions泛型推导出错误策略相关的返回类型这是 integration-tests/type-tests/signatures 中专门做类型级测试的对象。2.3 变更方法mutatemutate(options)返回PromiseMutateResultMaybeMaskedTData。源码 ApolloClient.ts 展示了默认值合并逻辑fetchPolicy默认为network-only变更结果写入缓存可改为no-cache跳过缓存写入errorPolicy默认为none校验 mutation 必须是OperationTypeNode.MUTATION文档。MutateOptions的完整字段见报告第 279293 行optimisticResponse支持函数式(vars, { IGNORE }) ...、updateQueries、refetchQueries、awaitRefetchQueries、update缓存更新函数MutationUpdaterFunction、onQueryUpdated、errorPolicy、context、fetchPolicy、keepRootFields、mutation。2.4 缓存交互方法族read/write/watchreadQuery/readFragment从缓存同步读取数据不发网络请求返回UnmaskedTData | null。源码显示实现为this.cache.readQuery({ ...options, query: this.transform(options.query) }, optimistic)即先经transform应用文档变换再委托给缓存。readFragment从cache.identify得到的特定 id 开始读取。两者都提供已废弃的第二个参数optimistic: boolean重载应改为放入 options 对象中。writeQuery/writeFragment写入缓存返回写入的Reference | undefined。选项含broadcast是否广播变更通知观察者、overwrite、extensions等。watchFragmentsince 3.10.0返回ObservableFragment带getCurrentResult()方法支持from为单个对象/数组/null 的多种重载返回类型随之精确到TData、ArrayTData、null等。restore(serializedState)把序列化状态写回缓存SSR 水合常用返回ApolloCache。2.5 存储与生命周期管理resetStore()清空缓存并重新拉取所有活跃查询返回PromiseQueryResult[] | nullclearStore()清空缓存但不重取查询onResetStore(cb)/onClearStore(cb)注册钩子返回取消函数extract(optimistic?)导出当前缓存内容配合restore做 SSRrefetchQueries({ include, onQueryUpdated, optimistic, updateCache })按描述符集合重新拉取查询返回RefetchQueriesResult同时是 Promise 并附带queries与results属性getObservableQueries(include?)返回当前活跃的ObservableQuery集合stop()彻底停止客户端——取消所有订阅、以 QueryManager stopped while query was in flight 拒绝在途查询、清空 suspense 缓存并断开RefetchEventManager源码 ApolloClient.ts 注释详述了这一激进清理策略。其他值得注意的成员version: string运行时版本、link、cache、defaultOptions、queryDeduplication: boolean、setLink(newLink)运行时替换网络层、__actionHookForDevTools与__requestRaw供 Devtools 使用的内部钩子。2.6 错误策略与查询结果类型的联动报告第 295316 行、399416 行的MutateResultMap/QueryResultMap是理解 Apollo Client 类型精妙之处的最佳入口——返回类型取决于errorPolicy泛型参数errorPolicy: none默认{ data: TData; error?: never }类型上保证无错误errorPolicy: all{ data: TData | undefined; error?: ErrorLike }错误与数据并存errorPolicy: ignore{ data: TData | undefined; error?: never }错误被吞掉未指定{ data: TData | undefined; error?: ErrorLike }最保守的联合。运行时语义见 watchQueryOptions.ts 注释none把任何错误当作运行时错误终止 Observableignore不终止但不触发nextall把错误当数据通知观察者。ErrorPolicy的取值即none | ignore | all报告第 648 行。三、核心选项类型详解3.1 FetchPolicy 与 WatchQueryFetchPolicywatchQueryOptions.ts 定义了完整的读取策略集合FetchPolicy cache-first | network-only | cache-only | no-cachequery/mutate可用范围WatchQueryFetchPolicy FetchPolicy | cache-and-network | standby仅watchQuery可用多出两种需多次回流的策略MutationFetchPolicy network-only | no-cache变更仅允许这两种见 2.3 节源码校验。语义速查源码注释cache-first默认缓存命中即返回cache-and-network先返回缓存再取网络cache-only缓存缺失即失败no-cache强制网络且不写缓存network-only强制网络但写缓存standby不主动取数仅供refetch/updateQueries使用。WatchQueryOptions报告第 455469 行还包含nextFetchPolicy字符串或(currentFetchPolicy, context) next函数context.reason为after-fetch | variables-changed见NextFetchPolicyContext第 810819 行、initialFetchPolicy、refetchWritePolicy: merge | overwrite网络结果覆盖缓存时的写入策略、pollInterval、notifyOnNetworkStatusChange、returnPartialData、skipPollAttempt、refetchOn以及隐藏符号variablesUnknownSymbol。3.2 ErrorLike 与错误体系报告第 637645 行定义ErrorLike { message; name; stack? }——Apollo Client 以形状兼容而非同构类的方式对待错误因此任何符合该形状的对象包括 GraphQL 服务端错误都能融入结果类型。包内还从 src/errors 导出了一系列具体错误类CombinedGraphQLErrors、CombinedProtocolErrors、LinkError、LocalStateError、ServerError、ServerParseError、UnconventionalError见报告中的export { ... }回显。四、ObservableQuery可观察的查询对象watchQuery的返回值ObservableQueryTData, TVariables报告第 909957 行同时实现Subscribable与InteropObservable支持Symbol.observable拥有 rxjs 风格的pipe与subscribe。核心成员源码见 src/core/ObservableQuery.ts成员说明refetch(variables?)重新拉取返回ResultPromisePromise 且带retain()防止结果被 GCfetchMore(options)分页取下一批结果updateQuery合并新旧数据setVariables(vars)更新变量并触发网络请求对应NetworkStatus.setVariablessubscribeToMore(options)为查询补充订阅数据返回终止函数updateQuery(mapFn)以映射函数原地更新查询缓存结果startPolling(ms)/stopPolling()开启/停止轮询轮询中网络状态为pollgetCurrentResult()同步读取当前含缓存结果reobserve(newOptions?)以新选项重新开始观察stop()停止该查询的所有订阅hasObservers()是否仍有订阅者ObservableQuery.ResultTData, TStates第 885890 行的结构为{ error?, loading, networkStatus, partial }叠加DataState联合——即通过dataState: complete | streaming | partial | empty四态描述数据完整性其中streaming对应defer增量到达的中间状态DataState见报告第 581594 行DataValue命名空间通过 HKTApplyHKTImplementationWithDefault允许用TypeOverrides覆盖类型实现。SubscribeToMoreOptions第 895906 行包含document、variables、context、onError、updateQueryFetchMoreOptions第 858867 行包含query、variables、errorPolicy、context、updateQuery。五、QueryManager幕后调度中枢与查询去重原理报告第 10251115 行暴露了公共 API 中几乎隐藏的QueryManager类——ApolloClient的所有网络行为最终都委托给它query、mutate、watchQuery、startGraphQLSubscription、refetchObservableQueries、refetchQueries、broadcastQueries、clearStore、transform等。其中最有价值的是查询去重query deduplication的源码实现位于 QueryManager.ts每个QueryManager持有inFlightLinkObservables new Trie{ observable?; restart? }(false)基于wry/trie在getObservableFromLink中若deduplication为真context.queryDeduplication ?? this.queryDeduplication即单次操作可覆盖客户端默认值则以print(serverQuery)打印后的查询串与canonicalStringify(variables)规范化变量 JSON为键查询 Trie若键已存在且 observable 在途直接复用否则创建新 observable 并存入。这正印证了Options.queryDeduplication注释中完全相同的查询才会去重的定义通过withRestart包装支持对订阅方暴露restart()去重场景下重新订阅会复用同一在途流。QueryManager还维护obsQueries活跃查询集合、mutationStore在途变更记录含error/loading/mutation/variables、fetchCancelFns取消在途请求的映射以及maskOperation/maskFragment方法——它们是数据掩蔽dataMasking在运行时把类型层面的MaybeMasked/Unmasked变成实际的掩蔽/还原行为的关键对应 src/masking 模块。六、NetworkStatus查询网络状态枚举报告第 797807 行与源码 networkStatus.ts 完全一致地定义了 8 个状态值注意缺省了历史值 5值名称触发场景1loading查询首次发起即便缓存已有部分数据2setVariablessetVariables触发的新请求在途3fetchMorefetchMore请求在途4refetchrefetch请求在途6poll轮询请求在途7ready无在途请求且无错误8error无在途请求但存在错误9streamingdefer已收到首个增量分块但尚未流完当notifyOnNetworkStatusChange: true时观察者会收到每次网络状态跳变loading字段也随之变为true——这是区分缓存命中静默更新与真实网络往返的关键。七、RefetchEventManager 与 refetchOn事件驱动的自动重取core 报告新引入了自动重取体系对应源码 src/core/RefetchEventManager.ts 与 src/core/refetchSourcesRefetchEvents第 12281233 行预定义了两个事件源online浏览器网络恢复与windowFocus窗口重新聚焦RefetchEventManager第 12131225 行负责connect(client)/disconnect(client)、emit(source, payload)、setEventSource注册/替换事件源、setEventHandler为特定事件注册处理器、setDefaultEventHandler仓库预置onlineSource、windowFocusSource两个事件源src/core/refetchSources/onlineSource.ts、src/core/refetchSources/windowFocusSource.ts用navigator.onLine与window.focus等浏览器事件驱动refetchOnWatchQueryOptions字段类型见第 12361248 行可为boolean、回调(context) boolean或{ online?, windowFocus? }对象watchQuery源码中会对defaultOptions与调用参数做对象合并并在未配置RefetchEventManager或事件源缺失时于开发环境打印警告ApolloClient.ts。使用方式构造客户端时传入new RefetchEventManager({ sources: { online: onlineSource, windowFocus: windowFocusSource } })查询通过refetchOn: { windowFocus: true }声明式订阅事件。八、类型层面的现代化设计掩蔽、去重与别名8.1 数据掩蔽类型MaybeMasked / Unmasked从 src/masking 转发的MaybeMasked、Unmasked、FragmentType贯穿所有方法签名query返回MaybeMaskedTData类型层面可能仍被掩蔽而readQuery/writeQuery/updateQuery回调等要求UnmaskedTData彻底解除掩蔽后的精确类型。运行时对应QueryManager.maskOperation/maskFragment。这是 Apollo Client 数据掩蔽dataMasking: true在类型系统上的投影。8.2 已废弃别名与内部类型报告清晰地标注了一整组deprecated顶层别名全部指向命名空间内的新形态ApolloClientOptions、ApolloQueryResult、DefaultOptions、DevtoolsOptions、MutateResult、MutationOptions、QueryOptions、RefetchQueriesOptions、RefetchQueriesResult、SubscribeToMoreOptions、SubscriptionOptions、WatchQueryOptions等InternalTypes、ObservableQuery.CacheWatchOptions、applyOptions、reFetchObservableQueries旧命名新名为refetchObservableQueries、disableNetworkFetches: never占位赋值为never以在编译期拒绝使用则属于内部/移除项。迁移路径可参考 src/v4-migration.ts 与 docs/source/migrating/apollo-client-4-migration.mdx。8.3 其他值得关注的核心导出NetworkStatus、version: string运行时版本、build: source | esm | cjs当前构建产物形态ErrorPolicy、FetchPolicy、RefetchWritePolicy、OperationVariables Recordstring, any回调函数类型MutationUpdaterFunction、MutationQueryReducer、MutationQueryReducersMap、OnQueryUpdated、SubscribeToMoreFunction、UpdateQueryMapFn缓存相关转发InMemoryCache、InMemoryCacheConfig、makeVar、ReactiveVar、defaultDataIdFromObject、TypePolicies、FieldPolicy、MissingFieldError等完整清单见 .api-reports/api-report-cache.api.md报告末尾附带的ae-forgotten-export警告第 13981402 行指向src/core/ApolloClient.ts、ObservableQuery.ts、QueryManager.ts中未被入口导出但被引用的内部符号NextFetchPolicyContext、QueryManager、MutationStoreValue——它们以声明但不出现在 import 白名单的方式维持着类型推导这解释了为什么报告中会存在大量interface ...未 export形态的定义。九、如何在你的项目中利用这份报告作为 API 变更审计基线升级依赖或提交改动前diff.api-reports/api-report-core.api.md即可一眼看出公共 API 的新增、删除与deprecated标注作为类型速查手册当你对某个选项如refetchOn的取值、WatchQueryFetchPolicy的合法值、QueryResult随errorPolicy的形态变化不确定时直接检索本文件比翻阅在线文档更贴近当前仓库版本结合源码闭环验证类型声明看报告运行时行为看 src/core。例如cache-and-network为什么不能用于query这种问题类型报告只给出签名而 ApolloClient.ts 的 invariant 注释给出完整答案多模块对照core 报告只是包根入口的投影各子路径的完整 API 请对照 .api-reports/api-report-cache.api.md、.api-reports/api-report-link.api.md、.api-reports/api-report-react.api.md 等并行阅读。结语api-report-core.api.md以机器可读、可 diff 的形式浓缩了apollo/client核心入口的全部公共契约。从ApolloClient的构造选项、query/mutate/watchQuery三驾马车到ObservableQuery的观察者 API、QueryManager的 Trie 去重实现再到NetworkStatus的状态机与errorPolicy驱动的返回类型分发类型报告与 src/core 源码互为镜像。掌握报告定位类型、源码定位行为的双轨阅读法你就能以最高效率理解并驾驭 Apollo Client 的核心 API 体系。赞分享前端GraphQL【免费下载链接】apollo-clientThe industry-leading GraphQL client for TypeScript, JavaScript, React, Vue, Angular, and more. Apollo Client delivers powerful caching, intuitive APIs, and comprehensive developer tools to accelerate your app development.项目地址https://gitcode.com/gh_mirrors/ap/apollo-client点击查看免费下载相关推荐Microsoft 365 Copilot 声明式 Agent 开发指南基于 v1.5 Schema 与 TypeSpec 的生产级实践Microsoft 365 Copilot 声明式 Agent 开发指南基于 v1.5 Schema 与 TypeSpec 的生产级实践 声明式 Agent前端GraphQLApollo Client 4 完整 API 参考读懂 apollo/client 官方 API 报告api-report.api.mdApollo Client 4 完整 API 参考读懂 apollo/client 官方 API 报告api report.api.md 导读 apo前端GraphQLGitHub_Trending/skills4/skills最佳实践总结来自社区的经验分享GitHub_Trending/skills4/skills最佳实践总结来自社区的经验分享 GitHub_Trending/skills4/skills是一个人工智能AI 技能AI 插件上一篇如何快速保护网站隐私免费安全检测完整指南下一篇mirrors/ggml-org/models批量转换工具将其他格式模型转为GGUF教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
