前端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点击查看免费下载导读本文以 Apollo Client 仓库中由 API Extractor为骨架结合 src/cache 下的真实源码系统讲解 Apollo Client 缓存层的完整公开 API从抽象基类ApolloCache的方法契约、Cache命名空间下全部选项类型到默认实现InMemoryCache的归一化存储与乐观层机制再到TypePolicy/FieldPolicy类型策略、makeVar响应式变量、Fragment Registry 与缓存修改器Modifier。读完本文你将掌握缓存模块每个公开符号的类型签名、参数语义、默认值与底层实现原理并能够直接据此编写类型安全的缓存读写、批量事务、乐观更新与自定义字段策略代码。一、缓存模块的导出全貌缓存模块的公开入口是 src/cache/index.tsAPI 报告中的所有符号均由此处导出主要包括类别导出符号缓存基类ApolloCache抽象类与Cache类型命名空间、Transaction默认实现InMemoryCache、InMemoryCacheConfig、ApolloReducerConfig类型策略TypePolicies、TypePolicy、FieldPolicy、FieldReadFunction、FieldMergeFunction、KeyArgsFunction、KeyFieldsFunction、PossibleTypesMap、Policies存储结构EntityStore、NormalizedCache、NormalizedCacheObject、OptimisticStoreItem、MergeTree、MergeInfo响应式变量makeVar、ReactiveVar、cacheSlotFragment 注册表createFragmentRegistry、FragmentRegistryAPI修改器与缺失字段Modifier、Modifiers、ModifierDetails、IgnoreModifier、MissingFieldError、MissingTree工具函数defaultDataIdFromObject、fieldNameFromStoreName、canonicalStringify、isReference、Reference、StoreObject、StoreValue只读选项类型ReadQueryOptions、DiffQueryAgainstStoreOptions、IdGetter、IdGetterObj、ReadMergeModifyContext、ReadFieldOptions一个值得注意的细节API 报告中出现的CacheGroup、Layer、Root、Stump、WriteContext、StorageType等符号带有(undocumented)标记且未从入口文件导出——它们属于InMemoryCache的内部实现结构见 src/cache/inmemory/entityStore.ts普通使用者无需直接接触但在理解缓存原理时非常关键。二、ApolloCache所有缓存的抽象契约ApolloCache是一个抽象基类定义于 src/cache/core/cache.ts定义了任何缓存实现都必须遵守的接口。从源码看它被明确划分成几组能力2.1 核心抽象方法必须实现方法签名要点语义readread(options: Cache.ReadOptions): UnmaskedTData \| null从缓存读取查询结果读不到返回nullwritewrite(options: Cache.WriteOptions): Reference \| undefined写入缓存并返回写入对象对应的Referencediffdiff(options: Cache.DiffOptions): Cache.DiffResult返回读取结果及完整性信息complete、missing、fromOptimisticTransaction见下文DiffResultwatchwatch(options: Cache.WatchOptions): () void订阅缓存变化返回取消订阅函数resetreset(options?: Cache.ResetOptions): Promisevoid清空缓存并重启所有 watch除非discardWatches: trueevictevict(options: Cache.EvictOptions): boolean按id/fieldName/args移除整个对象或字段有数据被移除时返回truerestorerestore(serializedState: unknown): this用序列化状态替换缓存SSR 水合、离线存储恢复、热重载时调用extractextract(optimistic?: boolean): unknown导出缓存完整状态格式可序列化供restore还原removeOptimisticremoveOptimistic(id: string): void移除指定 ID 的乐观层fragmentMatchesfragmentMatches(fragment, typename): boolean判断内联片段/片段定义的类型条件是否匹配某typename数据掩蔽data masking依赖它2.2 事务与批量 APIbatch方法用于把多个缓存操作打包成一次事务确保 watcher 只在全部操作完成后被通知一次避免中间态的重复渲染。其选项Cache.BatchOptions见 src/cache/core/types/Cache.ts包含update(cache)执行缓存操作的函数返回值即batch的返回值optimistic?: string | booleanstring表示以该 ID 创建新的乐观层之后用removeOptimistic移除true更新当前最顶层含乐观数据false只更新根非乐观数据默认值为falseremoveOptimistic?: string批次完成后移除该 ID 的乐观层可用于服务器数据到达 清除 pending 乐观更新的原子应用全程只广播一次onWatchUpdated对受影响的每个 watcher 回调传入 watch 选项、新旧 diff返回false可阻止对该 watcher 广播。典型用法源码 JSDoc 示例cache.batch({ update(cache) { cache.writeQuery({ query: GET_TODOS, data: { todos: updatedTodos }, }); cache.evict({ id: Todo:123 }); }, }); // 乐观更新 自定义层 ID cache.batch({ optimistic: add-todo-optimistic, update(cache) { cache.modify({ fields: { todos(existing []) { return [...existing, newTodoRef]; }, }, }); }, });batch的默认实现src/cache/core/cache.ts内部委托给抽象方法performTransaction(transaction, optimisticId?)recordOptimisticTransaction(transaction, optimisticId)则直接调用performTransaction传入字符串 ID。此外updateQuery/updateFragment也是基于batch实现的读-改-写便捷方法// updateQuery 内部等价实现源码可证 cache.batch({ update(cache) { const value cache.readQuery(options); const data update(value); if (data void 0 || data null) return value; cache.writeQuery({ ...options, data }); return data; }, });2.3 高层便捷方法ApolloCache还为常见场景提供了带默认行为的便捷方法它们的类型与默认值如下readQuery/readFragment读取数据optimistic与returnPartialData默认均为falsereadQuery未传id时以ROOT_QUERY为根。方法签名同时保留了一个已弃用的第二参数形式readQuery(options, optimistic: boolean)API 报告明确标注 deprecated应改为把optimistic放进 options 对象。writeQuery/writeFragment写入数据broadcast默认true通知 watcheroverwrite默认false与既有字段合并而非覆盖。writeQuery未传id时同样写入ROOT_QUERY。watchFragment响应式监听片段变化返回ApolloCache.ObservableFragmentTData一个继承 rxjsObservable并额外带getCurrentResult()的对象。它有 6 个按from取值重载的签名单个对象/Reference/字符串、null、数组及混合数组保证返回类型精确。lookupFragment(fragmentName)按名称查找已注册片段基类默认返回nullInMemoryCache会结合 Fragment Registry 真正实现。2.4WatchFragmentOptions与WatchFragmentResultwatchFragment的选项ApolloCache.WatchFragmentOptionsfragment必填gql解析出的片段文档from必填标识目标实体可为包含__typename与主键字段的对象、{ __ref: ... }引用、字符串 ID或它们的数组/nullvariables?片段可能依赖的变量fragmentName?片段文档含多个片段时必填否则可省略optimistic?是否返回乐观结果默认true。结果类型WatchFragmentResultTData是判别联合complete: true时数据完整无missingcomplete: false时附带MissingTree形式的missing与dataState: partial的部分数据。实现细节在 src/cache/core/cache.ts 中from值会先经toCacheIdtypeof from string ? from : this.identify(from)转换为缓存 ID开发模式下若id undefined会打印警告提示对象无法被归一化可能缺少主键字段。数组形式的from由combineLatestBatched合并多个子 observable并聚合complete、missing按索引归组与data。2.5 其它可选能力transformDocument(document)对每个输入文档调用一次做静态改写如自动补__typenametransformForLink(document)每次 ApolloLink 请求前调用做动态改写如补全缺失的片段定义identify(object)返回对象对应的缓存 IDgc(): string[]垃圾回收返回被回收的 ID 列表modify(options)按字段修改器就地更新缓存resolvesClientField?(typename, fieldName)判断client字段能否由缓存解析供LocalState使用不实现等价于返回false此时字段值将被置为null并给出警告assumeImmutableResults只读属性声明该缓存假定结果不可变。ApolloCache默认false而InMemoryCache覆盖为true开发模式下结果对象被冻结生产环境期望逻辑不可变。getMemoryInternals?internal deprecated的实验性 API仅用于开发构建向 DevTools 暴露内存信息源码中仅在__DEV__下挂载。三、Cache 命名空间选项与结果类型详解Cache报告中为Cache_2最终以export { Cache_2 as Cache }导出是一个类型命名空间集中定义了上述方法的参数与返回值类型。以下要点直接对应 API 报告中的类型签名3.1 读写与监听ReadOptionsquery、variables?、id?/rootId?默认ROOT_QUERY、previousResult?、必填的optimistic: boolean、returnPartialData?。WriteOptionsquery、variables?、dataId?、result、broadcast?默认true、overwrite?默认false、extensions?ExtensionsWithStreamInfo可在merge函数中读取。DiffOptionsOmitReadOptions, rootId即ReadOptions去掉rootId后的别名。WatchOptions在DiffOptions基础上增加watcher?、immediate?、callback: WatchCallback(diff, lastDiff?) void与lastDiff?。DiffResultTData判别联合——complete: true时result为完整数据complete: false时result为部分数据或null并附missing?: MissingFieldError两种分支都可能有fromOptimisticTransaction?: boolean。3.2 实体标识选项CacheIdentifierOptionreadFragment/writeFragment/updateFragment的标识采用互斥联合type CacheIdentifierOptionTData | { id?: string; from?: never } // 直接传缓存 ID | { id?: never; from?: ApolloCache.FromOptionValueTData }; // 传对象/引用/字符串注意from的优先级高于id源码注释明确说明 from is given precedence over id。from的类型FromOptionValueTData为StoreObject | Reference | FragmentTypeTData | string。3.3 其余选项EvictOptionsid?、fieldName?、args?不传args时移除该字段所有参数变体、broadcast?。ResetOptionsdiscardWatches?。ModifyOptionsid?、fieldsModifiersEntity或AllFieldsModifierEntity、optimistic?、broadcast?。ReadQueryOptions/ReadFragmentOptions/WriteQueryOptions/WriteFragmentOptions组合了query/fragmentvariablesoptimistic/returnPartialData 标识 data/broadcast/overwrite/extensions其字段默认值统一为optimisticfalse、returnPartialDatafalse、broadcasttrue、overwritefalse。UpdateQueryOptionsOmitReadQueryOptions WriteQueryOptions, dataUpdateFragmentOptionsOmitReadFragmentOptions WriteFragmentOptions, data | id | from再与CacheIdentifierOption交叉。四、InMemoryCache默认缓存实现InMemoryCache extends ApolloCachesrc/cache/inmemory/inMemoryCache.ts是开箱即用的归一化缓存。其构造函数接收InMemoryCacheConfiginterface InMemoryCacheConfig extends ApolloReducerConfig { resultCaching?: boolean; // 结果缓存/依赖跟踪默认开启关闭可省内存但重复读取更慢 possibleTypes?: PossibleTypesMap; // 接口/联合类型到实现类型的映射 typePolicies?: TypePolicies; // 类型策略见下一节 fragments?: FragmentRegistryAPI; // 片段注册表 } // ApolloReducerConfig { dataIdFromObject?: KeyFieldsFunction } // 全局主键提取函数4.1 双存储与乐观层源码显示InMemoryCache内部维护两个EntityStorethis.dataEntityStore.Root根存储含归一化数据与resultCaching开关this.optimisticData初始为rootStore.stump一个树桩层。当有乐观写入时optimisticData会变成以Layer为节点的链表链尾仍是this.data。由此可解释 API 报告中的OptimisticStoreItem { id, data, transaction }与removeOptimistic的语义每次乐观事务都新增一层removeOptimistic(id)移除对应层并触发广播。extract(optimistic false)读取乐观或根存储read根据options.optimistic选择optimisticData或data。4.2 结果缓存与广播resetResultCache()会重建StoreReader/StoreWriter并用 optimism 的wrap包装maybeBroadcastWatch。其makeCacheKey仅当存储支持结果缓存supportsResultCaching时启用缓存键包含 query、callback 本身源码注释引用了 issue #5733不同 watch 可共享相同 query/optimistic/variables但必须为不同 callback 分别投递结果以及canonicalStringify({ optimistic, id, variables })。这也解释了为什么报告同时导出canonicalStringify——它是整个缓存键系统的规范化序列化器。4.3 其它实现特性restore(data)先init()重建全部内部结构再data.replace(data)无需手工清旧数据gc(options?: { resetResultCache?: boolean })返回被回收 ID 数组retain/release(rootId, optimistic?)增减引用计数以保护/暴露对象免于被 GC标记-清除算法见 docs/source/caching/garbage-collection.mdxmakeVar以实例属性暴露makeVar函数见第六节identify、modify、batch、watch、diff等全部按契约实现read以returnPartialData默认false提供重载——因为read只返回数据或null若默认返回部分数据会破坏返回类型的T完整性源码 JSDoc 明确解释了与diff的差异diff带完整性元数据可以默认returnPartialData: trueread不行。InMemoryCache也实现了resolvesClientField与fragmentMatches前者与本地状态解析有关后者依赖Policies.fragmentMatches供数据掩蔽与本地 resolver 判断联合/接口类型条件是否匹配。五、类型策略TypePolicies 与 FieldPolicy类型策略是定制缓存行为的核心入口src/cache/inmemory/policies.ts。5.1TypePolicy结构export type TypePolicy { keyFields?: KeySpecifier | KeyFieldsFunction | false; merge?: FieldMergeFunction | boolean; queryType?: true; // 自定义根 Query 类型的 __typename mutationType?: true; // 自定义根 Mutation 类型的 __typename subscriptionType?: true; // 自定义根 Subscription 类型的 __typename fields?: { [fieldName: string]: FieldPolicyany | FieldReadFunctionany; }; };keyFields用字段名数组KeySpecifier ReadonlyArraystring | KeySpecifier支持嵌套、自定义函数或false禁用归一化定义主键。若dataIdFromObject与keyFields同时存在后者优先级更高。merge定义该类型对象被合并时的策略merge: true是用传入值整体替换的简写merge: false等价于默认合并父字段的 merge 优先于类型级 merge。fields逐字段配置FieldPolicy或直接给FieldReadFunction。5.2FieldPolicy与字段函数export type FieldPolicy TExisting any, // 缓存内部存储形态须可 JSON 序列化 TIncoming TExisting, // merge 函数 incoming 参数的类型GraphQL 响应形态子对象被替换为 Reference TReadResult TIncoming, // read 函数实际返回类型 { keyArgs?: KeySpecifier | KeyArgsFunction | false; // 参与字段缓存键的实参 read?: FieldReadFunctionTExisting, TReadResult, TReadOptions; // 读时转换 merge?: FieldMergeFunctionTExisting, TIncoming, TMergeOptions | boolean; // 写时合并 };FieldReadFunction(existing, options)与FieldMergeFunction(existing, incoming, options)共享基础上下文FieldFunctionOptionsargs、cacheInMemoryCache实例、canRead、field、fieldName、isReference、mergeObjects、readField、storage、storeFieldName、toReference、variables?。FieldMergeFunctionOptions额外提供existingData、extensions与streamFieldInfo?增量流式信息关联 src/incremental 的defer支持。KeyArgsFunction(args, context)返回KeySpecifier | false | string用于按实参动态决定缓存键。PossibleTypesMap { [supertype: string]: string[] }用于让缓存识别接口/联合类型下的具体类型可运行时用cache.policies.addPossibleTypes()增量补充。Policies类报告中公开导出聚合了上述全部配置并提供getReadFunction、getMergeFunction、getStoreFieldName、hasKeyArgs、identify、readField、runMergeFunction、addTypePolicies、addPossibleTypes、fragmentMatches等方法是InMemoryCache解析策略的执行引擎。六、响应式变量与 cacheSlotsrc/cache/inmemory/reactiveVars.ts 实现了轻量级响应式状态原语export interface ReactiveVarT { (newValue?: T): T; // 传参即写不传参即读 onNextChange(listener: (value: T) any): () void; // 订阅下一次变化返回退订函数 attachCache(cache: ApolloCache): this; forgetCache(cache: ApolloCache): boolean; } export function makeVarT(value: T): ReactiveVarT;调用makeVar(initialValue)得到函数式变量myVar()读取myVar(newValue)写入写入会令消费过该变量的自定义read字段失效并广播缓存变化。cacheSlot是一个 optimism 的Slot上下文槽当Policies#readField调用自定义 read 函数时cacheSlot持有当前缓存实例使makeVar在读取路径中也能自动记录依赖attachgetCacheInfo(cache).dep(rv)从而让字段级缓存依赖跟踪与响应式变量打通。forgetCache静默广播并允许缓存被 GCrecallCache可重新挂接。实际使用中makeVar常与useReactiveVarReact 侧配合实现局部 UI 状态见 docs/source/local-state/reactive-variables.mdx。七、Fragment Registry命名片段管理export interface FragmentRegistryAPI { lookup(fragmentName: string): FragmentDefinitionNode | null; register(...fragments: DocumentNode[]): this; resetCaches(): void; transformD extends DocumentNode(document: D): D; // 把具名片段补全进文档 } export function createFragmentRegistry(...fragments: DocumentNode[]): FragmentRegistryAPI;用途当查询引用了不在当前文档中的具名片段时注册表按名称解析定义。将注册表传入InMemoryCache的fragments选项后ApolloCache.transformForLink/transformDocument与lookupFragment即可在请求前/写入前补全片段。可配合代码生成工具见 docs/source/development-testing/graphql-codegen.mdx与apollo/client的 masking 能力FragmentType/Unmasked使用。八、Modifier就地修改缓存字段cache.modify的字段修改器类型定义于 src/cache/core/types/common.tsexport type ModifierT ( value: T, details: ModifierDetails ) DeepPartialT | DeleteModifier | InvalidateModifier | undefined; export type ModifierDetails { DELETE: DeleteModifier; // 返回 details.DELETE 删除字段 INVALIDATE: InvalidateModifier; // 返回 details.INVALIDATE 使字段失效触发相关查询重读 fieldName: string; storeFieldName: string; // 含 keyArgs 部分的存储字段名 readField: ReadFieldFunction; canRead: CanReadFunction; isReference: typeof isReference; toReference: ToReferenceFunction; storage: StorageType; };ModifiersT是逐字段可选映射AllFieldsModifier则对所有字段生效IgnoreModifier用于内部标记跳过该字段。报告中用unique symbol声明的_deleteModifier/_invalidateModifier/_ignoreModifier使这些标记类型互不兼容、不可伪造。九、缺失字段与错误模型MissingTree string | { readonly [key: string]: MissingTree }树状描述缺失字段路径。MissingFieldError extends Error携带message、pathMissingTree | Arraystring | number、query、variables?与只读的missing: MissingTree。源码显示构造函数会把数组形式的path逐层折叠为嵌套MissingTree并手动修正原型链兼容 Android见 issue #3236。数据读取时字段缺失即产生MissingFieldErrordiff的complete: false分支与watchFragment的missing字段均由此而来。相关错误类型在 src/errors 下还有ServerError、CombinedGraphQLErrors等可参阅 .api-reports/api-report-errors.api.md。十、归一化存储架构EntityStore 与 GC虽然EntityStore、Layer、Root、Stump未从入口导出但报告揭示了其类层次src/cache/inmemory/entityStore.tsNormalizedCache归一化存储的接口has/get/merge/modify/delete/clear/retain/release/getFieldValue/toReference/canRead/getStorage。NormalizedCacheObject{ [dataId: string]: StoreObject | undefined }可选__META.extraRootIds记录额外根 ID写入的ROOT_MUTATION等单例或经cache.retain/writeFragment成为根的对象使这些根 ID 能在extract/restore往返后存活。CacheGroup依赖跟踪组depend/dirty维护字段级依赖keyMaker: Trieobject与makeCacheKey支撑结果缓存resetCaching()在重建缓存时清空依赖。Root/Layer/StumpRoot是底层存储Layer是乐观/中间层parent链表Stump是Root之上的树桩层optimisticData的初始值merge直接落到根。GC 采用 mark-and-sweepgc()从根 ID 出发标记可达实体回收不可达者并返回其 ID 列表详见 docs/source/caching/garbage-collection.mdx。十一、辅助函数与再导出defaultDataIdFromObject({ __typename, id, _id }, context?)默认主键提取——优先id、其次_id否则返回undefined对象不做归一化。context?: KeyFieldsContext提供typename、storeObject、readField、selectionSet、fragmentMap、keyObject内部用。fieldNameFromStoreName(storeFieldName)从存储字段名含keyArgs部分还原 GraphQL 字段名。canonicalStringify、isReference、Reference、StoreObject、StoreValue从apollo/client/utilities再导出供缓存相关代码统一使用。已弃用类型WatchFragmentOptions/WatchFragmentResult顶层是ApolloCache.WatchFragmentOptions/WatchFragmentResult的别名标注deprecated新代码应使用命名空间形式。十二、深入阅读路径缓存模块全部公开 API 的权威签名.api-reports/api-report-cache.api.mdAPI Extractor 生成勿手工编辑。实现源码抽象契约 src/cache/core/cache.ts、选项类型 src/cache/core/types/Cache.ts、默认实现 src/cache/inmemory/inMemoryCache.ts、策略引擎 src/cache/inmemory/policies.ts、存储与 GC src/cache/inmemory/entityStore.ts、响应式变量 src/cache/inmemory/reactiveVars.ts、片段注册表 src/cache/inmemory/fragmentRegistry.ts。测试佐证缓存行为测试 src/cache/core/tests/cache.ts、watchFragment类型测试 src/cache/core/tests/cache.watchFragment/types.test.ts、乐观更新测试 src/cache/inmemory/tests/optimistic.ts、策略测试 src/cache/inmemory/tests/policies.ts。官方使用文档缓存配置 docs/source/caching/cache-configuration.mdx、缓存交互 docs/source/caching/cache-interaction.mdx、字段行为 docs/source/caching/cache-field-behavior.mdx、垃圾回收 docs/source/caching/garbage-collection.mdx。综上所述api-report-cache.api.md所刻画的缓存模块 API 面覆盖了抽象契约 → 选项类型 → 默认实现 → 策略定制 → 响应式扩展的完整层次。无论是二次开发自定义缓存实现ApolloCache抽象方法、深度定制InMemoryCachetypePolicies/possibleTypes/fragments还是仅用readQuery/watchFragment/batch等日常 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点击查看免费下载相关推荐Apollo Client Utilities 公共 API 完全指南文档变换、分页策略、缓存调优与类型工具Apollo Client Utilities 公共 API 完全指南文档变换、分页策略、缓存调优与类型工具 apollo/client/utilities前端GraphQLFluent UI与GraphQL缓存Apollo Client缓存策略Fluent UI与GraphQL缓存Apollo Client缓存策略 在现代前端开发中UI框架与数据管理的协同是构建高性能应用的关键。Fluent UI前端UI组件设计系统抖音批量下载指南一个主页链接把全部作品无水印存到本地抖音批量下载指南一个主页链接把全部作品无水印存到本地 想把抖音作品存下来App 里只能一条条存存出来还带水印想归档一整个创作者的主页手动根本没法做。网页爬虫CLI上一篇构建私有工具箱28MB轻量级OmniTools本地部署全攻略下一篇pi-subagents 性能优化提升执行效率的 15 个技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
