wp-calypso 客户端数据层的核心引擎：Query Manager 查询管理器原理与扩展实战

前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载Query Manager 是 wp-calypsoJavaScript 与 API 驱动的 WordPress.com 前端客户端数据层的基础设施之一它把资源的存储与查询完全搬到浏览器端让应用可以在不等待服务端响应的情况下乐观地预测某一操作对资源集合产生的影响。本篇指南以 client/lib/query-manager/README.md 为主线结合仓库源码系统讲解receive的核心写入机制、getItem/getItems/getFound等读取接口、三种内置实现Paginated / Post / Theme QueryManager以及如何通过matches、compare、sort与 QueryKey 扩展出自定义的查询管理器。读完你可以掌握这一组件从写入、归并、排序到分页的全部工作原理并能基于它实现属于自己的客户端查询缓存。一、Query Manager 是什么Query Manager 是一个可扩展的实用工具类extendable utility class专门用于管理这样的复杂数据集其中的条目item可以同时关联一个或多个查询query并且会随时间变化。用一句话概括其设计目标Query Manager 在客户端内完整复刻了资源的存储与查询能力从而让我们能够乐观地预测对资源执行特定操作后的效果——例如把一篇文章移入回收站客户端可以先于服务端同步更新草稿列表、回收站列表、分页结果与总数。在架构上Query Manager 位于客户端状态层与 Redux reducer 协同工作。例如 client/state/posts/reducer.js 中就使用PostQueryManager来维护按站点拆分的文章数据client/state/posts/selectors/get-posts-for-query.js 通过查询管理器暴露的接口向 UI 提供查询结果。可以看到Query Manager 是以组件为中心的数据管理在 wp-calypso 中的落地实现。二、核心写入接口receive整个 Query Manager 的核心是receive方法。它负责把新收到的数据或其修订合并进内部存储并通过不同的选项控制合并行为。receive不会修改实例自身状态而是返回一个新的 QueryManager 实例如果数据发生了变化否则返回当前实例——这一点与 Redux 的不可变更新理念完全一致见 client/lib/query-manager/index.js 的实现与 JSDoc 注释。receive的完整签名如下receive( items [], options {} )items一个或多个要接收的条目。若传入单个对象会自动被包装为数组。options控制接收行为的选项对象。2.1 通过query选项关联查询将接收到的条目与某个查询对象关联。底层实现中Query Manager 会用QueryKey.stringify( query )把查询对象序列化为字符串键再写入this.data.queries[ queryKey ]记录该查询对应的itemKeys条目键数组与found匹配总数。2.2 通过found选项记录总数found表示与某个查询匹配的条目总数对应 REST API 响应中的总数信息。当options.found 0且与当前记录不一致时会更新查询的 found 值。分页管理器依赖该值计算总页数。2.3 替换条目不带任何选项调用receive时收到的条目会整体替换同名条目按 itemKey 定位且这种替换对所有跟踪该条目的查询全局生效。2.4 通过patch选项做局部更新patch: true表示对条目做部分变更即把收到的修订与已有条目浅合并Object.assign( {}, item, revisedItem )而不是整体替换。这一能力使得把某篇草稿的状态改为 trashed这样的局部更新可以在所有关联查询中同步生效。2.5 通过mergeQuery选项合并查询集合mergeQuery: true表示把新收到的条目追加到查询已有的集合中而不是整体替换该查询的条目集。追加前会把传入的键从现有集合中剔除再在随后的匹配测试中根据matches的结果重新放回避免重复。2.6receive的完整工作流从 index.js 的源码可以看出receive内部大致分四步合并条目对每个收到的条目用mergeItem( item, receivedItem, options.patch )计算出合并后的新条目若返回undefined则从集合中删除该条目。mergeItem是静态方法其中定义了特殊标记DELETE_PATCH_KEY __DELETE当 patch 修订对象带有__DELETE: true时表示该条目应被移除见 index.js。更新目标查询根据query/found/mergeQuery选项更新指定查询的itemKeys与found。协调所有查询遍历全部已跟踪查询对每个收到的条目做匹配测试条目已在查询集合中但已被删除或不再matches→ 从集合中剔除并递减 found条目不在查询集合中但matches返回 true → 插入集合递增 found并标记需要重排序。排序对发生插入的查询调用this.constructor.sort重新排序最后返回新的实例。因此改变一个条目会影响所有跟踪它的查询这一行为正是由第 3 步的全局协调保证的README 中称之为 reconciles any change to an item across all queries。2.7 删除条目删除也走receiveremoveItem/removeItems会把待删除的键包装成{ [itemKey]: key, __DELETE: true }并带patch: true调用receive从而触发mergeItem的删除分支。如果集合未发生实际变化二者会返回当前实例否则返回新实例。三、核心读取接口条目写入后可通过以下方法读取见 index.js方法说明返回getItem( itemKey: string )按键返回单个条目条目对象getItems( query: ?object )返回所有跟踪的条目若传入 query则只返回与该查询关联的条目Object[]查询未知时返回nullgetFound( query: object )返回匹配该查询的条目总数?number查询未知时返回nullremoveItem( itemKey: string )移除单个条目变更时返回新实例否则返回当前实例removeItems( itemKeys: string[] )批量移除条目同上值得注意的实现细节getItems在无 query 时返回全部条目在给定 query 时先用QueryKey.stringify序列化查询、再查找对应的itemKeys最终通过getItemsForKeys完成键到对象的映射。getItemsForKeys带有两级 WeakMap 记忆化缓存index.js对同一items实例与同一itemKeys数组的重复映射不会重复计算——这是 wp-calypso 在数据量大时保持读取性能的手段之一。四、一个完整场景草稿移入回收站README 给出了一个极具代表性的例子在一个同时跟踪草稿文章drafts与回收站文章trashed的PostQueryManager实例中调用receive传入一条单篇草稿已移入回收站的局部变更会发生以下连锁反应该文章在所有跟踪它的查询中被更新从草稿查询集合中移除加入回收站查询集合按对应查询的排序参数重新排序重新分配草稿与回收站两个查询受影响的分页结果草稿查询的 found 计数递减回收站查询的 found 计数递增。这正是 Query Manager 乐观预测操作效果能力的集中体现一次receive调用即可在客户端内完整模拟一次服务端操作对多个视图的最终影响UI 无需等待接口响应即可渲染出新状态。五、内置实现Query Manager 本身是抽象的单独使用价值有限必须由具体实现定制过滤matches、排序compare/sort与合并行为。仓库当前内置了三个实现5.1 PaginatedQueryManager — 分页数据管理位于 client/lib/query-manager/paginated。它把分页视为客户端模拟层而非真正存储的分页状态PAGINATION_QUERY_KEYS [ number, offset, page ]constants.js——在存储与序列化查询时这些分页参数会被剥离真正的数据以忽略分页的完整集合保存getItems( query )先把分页键从查询中剔除、取出完整集合再按page与number计算起始偏移( page - 1 ) * number切片返回当前页带有pageCache记忆化getNumberOfPages( query )用Math.ceil( found / perPage )计算总页数receive重写为默认以mergeQuery: true合并因为分页请求本质上是对同一完整集合的分片拉取并剥离分页键后再交给父类处理针对服务端返回的一页不足 perPage 条的情况例如密码保护文章对无权限用户不可见源码采用取历史 found 与新的 found 的最大值的策略避免因总数递减而漏掉末尾页——这是一个很典型的边界处理注释写在 paginated/index.js。DEFAULT_PAGINATED_QUERY { number: 20, page: 1 }。5.2 PostQueryManager — 文章查询管理位于 client/lib/query-manager/post管理文章对象的分页查询。它实现了完整的matches匹配逻辑post/index.js支持以下查询参数的客户端匹配search对post.title与post.content做不区分大小写的子串匹配after/before/modified_after/modified_before基于 moment 的时间比较after系用isAftermodified_前缀对应modified字段term按分类法的 slugs 匹配tag/category按名称或 slug 匹配typeany或等于文章类型parent_id匹配post.parent或其IDexclude排除指定 ID支持数组stickyrequire要求置顶、exclude排除置顶author优先使用嵌套的author.IDstatus支持逗号分隔的多状态any匹配任意状态。comparepost/index.js支持按order_by的ID、comment_count、title、modified、date排序默认按date降序order为DESC或缺失时取反。DEFAULT_POST_QUERYpost/constants.js定义如下同时服务于匹配测试与查询键规整export const DEFAULT_POST_QUERY { context: display, http_envelope: false, pretty: false, number: 20, offset: 0, page: 1, order: DESC, order_by: date, type: post, status: publish, sticky: include, search: , };5.3 ThemeQueryManager — 主题查询管理位于 client/lib/query-manager/theme管理主题对象的分页查询思路与 PostQueryManager 一致只是匹配与排序针对主题对象的字段定制。说明README 中给出的查询选项完整文档指向 WordPress.com REST API 的sites/$site/posts端点当前仓库以客户端matches逻辑post/index.js为实际匹配依据二者共同决定了查询语义。六、如何扩展 Query Manager按 README 的建议多数场景只需实现两个方法matches与compare必要时再加sort。6.1 matches( query, item )静态方法返回true表示该条目应被纳入该查询的集合。基类默认实现为!!item只要条目存在即匹配PostQueryManager 则实现了上文列出的复杂匹配。在你自己的实现中这里是对条目字段与查询参数逐一比较的地方。6.2 compare( itemA, itemB )排序比较函数遵循Array.prototype.sort的约定返回 -1 表示 A 在前1 表示 B 在前0 表示相等。README 特别提醒返回 0 表示相等的做法并非在所有浏览器与环境中都可靠——因为Array.prototype.sort不保证是稳定排序。6.3 sort( keys, items, query )排序函数对键数组按对应条目排序通常内部就是用compare做比较。它的存在意义是允许某个实现保持键的顺序不变依赖 REST API 返回的顺序只要重写sort为直接返回原keys即可。这种需求无法通过重载compare达成——因为即便比较函数恒返回 0Array.prototype.sort在某些环境如 Chrome 与 Node 的 V8 引擎仍会改变数组顺序README 引用了 V8 的 issue #90。基类sort的实现还会对条目尚未从集合中移除的情况做快速跳过优化index.js。6.4 通过 QueryKey 做更细的定制如果还需要进一步定制可以扩展查询键序列化。PostQueryManager与ThemeQueryManager都扩展了 key.js 的实现基类QueryKey负责把查询对象序列化为稳定字符串键内部按键名排序后JSON.stringify保证{ a: 1, b: 2 }与{ b: 2, a: 1 }得到相同的键并支持两个静态配置DEFAULT_QUERY若定义序列化时省略所有与默认值相同的参数OMIT_NULL_VALUES若为 true省略所有null值。PostQueryKeypost/key.js通过isDefaultOrNullQueryValue判断值为 null/undefined 或等于默认查询值并一并省略其目的正如 README 所说确保包含默认值的查询与不包含默认值的查询被视为同一个查询。例如查询中带page: 1与完全省略page应当被视为同一查询否则会产生重复的缓存条目。七、配套工具与工程实践7.1 withQueryManager与 Redux 状态对接client/lib/query-manager/with-query-manager.js 提供了一个实用的状态更新辅助函数withQueryManager( state, siteId, callback, create )它对state[ siteId ]中的 QueryManager 实例执行callback变换返回更新后的 state 对象若siteId不存在或实例缺失则原样返回 state若回调结果与旧实例相同未变化也不会产生新 state。create可选回调用于在 siteId 首次出现时创建实例。这层封装让 QueryManager 的不变性语义同实例即未变化与 Redux reducer 的浅比较优化无缝配合。7.2 测试完备性README 强调Query Manager 及其所有实现均使用 JSDoc 详尽注释含参数类型并且每一处实现都附带完整的测试用例集。仓库中可见的测试包括client/lib/query-manager/test/index.js 与 test/key.js基类与 QueryKey 的行为测试client/lib/query-manager/paginated/test分页管理的分页、found 计数、页数计算等测试client/lib/query-manager/post/testPostQueryManager 的 matches/compare/排序测试client/lib/query-manager/theme/test主题实现的测试client/state/posts/test/reducer.js与状态层集成的测试。这些测试同时扮演了行为规范文档的角色是理解每个方法边界条件例如getItems返回null、removeItems返回同实例等的最佳参考资料。八、小结Query Manager 用一套简洁的抽象解决了 wp-calypso 中多查询视图共享同一批会变化的数据这一核心难题receive负责写入与全局协调getItem/getItems/getFound负责读取matches/compare/sort与 QueryKey 负责定制匹配、排序与查询归一化PaginatedQueryManager则在客户端模拟分页切片。配合withQueryManager与不可变实例语义它可以干净地嵌入 Redux 状态层为 UI 提供乐观更新的即时数据。若你需要在 wp-calypso 中维护一类新的可查询资源例如评论、媒体、订阅者等照抄 PostQueryManager 的实现骨架补上你自己的matches与compare即可获得完整的分页、查询缓存与乐观更新能力。赞分享前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载相关推荐wp-calypso Query Posts 数据查询组件指南React 声明式文章数据获取实战wp calypso Query Posts 数据查询组件指南React 声明式文章数据获取实战 Query Posts 是 WordPress.com 前端前端CMSwp-calypso 用户设置数据获取指南QueryUserSettings 组件原理与实战wp calypso 用户设置数据获取指南QueryUserSettings 组件原理与实战 QueryUserSettings / 是 WordPress前端CMSwp-calypso 数据查询组件深度解析QueryKeyringConnections / 的用法、原理与 Keyring 连接数据流wp calypso 数据查询组件深度解析 QueryKeyringConnections / 的用法、原理与 Keyring 连接数据流 QueryKe前端CMS上一篇shadPS4性能基准测试不同硬件配置下的游戏帧率对比下一篇HTTP Prompt安全最佳实践保护API密钥与敏感数据创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考