前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载本文围绕 client/reader/data/stream/README.md 展开深入剖析 wp-calypso Reader 阅读器模块的流式数据边界Stream data boundary。文章先阐明该模块的职责与设计原则再逐个讲解基于 React Query 的useInfiniteStream游标无限流与usePaginatedStream分页流两个核心 Hook 的用法、返回结构与底层实现最后结合 normalization、缓存助手、查询参数构建等源码细节说明如何正确地在 UI 中消费流数据、预热缓存与维护流内增删帮助读者直接复用这套架构搭建自己的 Reader 风格信息流界面。模块定位Reader 流数据边界在 wp-calypso 的 Reader阅读器体系中client/reader/data/stream是流式数据的唯一边界data boundary。它的设计原则很明确消费方应当从calypso/reader/data/stream导入流相关的 Hook、类型、缓存助手与预取助手而不是直接引用实现文件。也就是说index.ts是这个模块的门面所有对外能力都从这里统一导出见 client/reader/data/stream/index.ts。该模块的职责可以归纳为五件事用 React Query 获取流页面无论是游标式无限流还是页码式分页流网络请求与缓存都由 TanStack Query 接管。把 API 流响应规范化为“流条目身份列表”将 REST 返回的cards/sites/posts载荷统一转换成 UI 可渲染的条目身份item identity结构。把流响应中的帖子正文同步进规范的 Reader 帖子缓存流的响应只负责“排序与身份”正文统一落到calypso/reader/data/post/cache由下游按需读取。集中维护流内本地缓存助手例如本地移除条目、按流查找条目等操作都收敛在本模块内。暴露共享的流条目类型供所有渲染流式列表的 UI 复用避免各自定义局部的Post或占位条目形状。一个容易被忽略、但非常关键的设计约束是帖子正文数据不会长期驻留在流缓存中。流查询只拥有排序ordering、分页pagination与条目身份item identity正文必须通过本模块把流响应同步sync到 client/reader/data/post/cache 之后再经由calypso/reader/data/post/cache读取。在消费端实践中这表现为“流 Hook 返回items身份列表 posts从同一份归一化结果解析出的帖子数组正文则走useCachedPost(s)”。公共 API 速览模块对外暴露的能力分成四类覆盖了“获取数据、预取数据、操作缓存、类型共享”四个维度类别API用途无限流cursoruseInfiniteStream给Stream渲染的游标式 Reader 流使用following、discover、feed、tag、likes 等分页流page/perPageusePaginatedStream页码/每页条数形态的界面目前用于 Recent 与 On This Day预取prefetchInfiniteStream仅在 UI 有意预热与Stream相同的无限流缓存时使用缓存助手getCachedStreamItems/removeStreamItemFromCache/invalidatePaginatedStream读取缓存条目、从匹配的无限流页面移除条目、按流失效分页查询对应的完整导出列表见 client/reader/data/stream/index.ts除了上述 API它还转发了automattic/api-queries中的查询键工具getStreamInfiniteQueryKey、getStreamInfiniteQueryKeyPrefix、parseStreamInfiniteQueryKey与类型PageHandle、StreamIdentity、StreamInfiniteQueryKey等以及buildStreamQueryParams、normalization 系列函数和isPaddingStreamItem。类型体系StreamItem 与占位条目流的类型定义集中在 client/reader/data/stream/types.ts三组类型构成整个数据边界的地基export interface StreamPostKey { blogId?: number | string; feedId?: number | string; postId?: number | string; } export interface StreamItem extends StreamPostKey { feedItemId?: number | string; xPostMetadata?: StreamPostKey; [ key: string ]: unknown; } export interface PaddingStreamItem { isPadding: true; postId: string; } export type StreamListItem StreamItem | PaddingStreamItem;StreamItem无限流使用的“标准流条目身份”。它继承StreamPostKeyblogId/feedId/postId额外携带feedItemId与xPostMetadata跨站转载指向的原始帖子身份并允许扩展字段。StreamListItemStreamItem | PaddingStreamItem的联合供需要为“未拉取页面”渲染占位行的分页 UI 使用。PaddingStreamItem带isPadding: true标记与合成的postId格式如padding-3。isPaddingStreamItem类型守卫type guard用于在 UI 中区分真实条目与占位行export const isPaddingStreamItem ( item: StreamListItem ): item is PaddingStreamItem isPadding in item;README 中提到的PostKey兼容别名在源码中对应的是StreamPostKey——旧版 Reader 代码仍沿用“post-key 术语”时使用。模块的指导意见是优先使用这些共享类型不要在流式 UI 里自行定义局部的Post或占位条目结构这样各渲染面共享同一套身份语义缓存助手getCachedStreamItems、removeStreamItemFromCache才能基于统一的身份做键比较。游标无限流useInfiniteStreamuseInfiniteStream服务于Stream这类“上滑加载更多”的游标式流。README 给出的最小用法const stream useInfiniteStream( { streamKey: following, feedId, localeSlug, startDate, } );入参说明从 client/reader/data/stream/hooks/use-infinite-stream/index.ts 的UseInfiniteStreamOptions看入参如下参数类型默认值说明streamKeystring \| null—流标识如following、discover、recent:123为null或空串时查询被禁用enabled自动置为falsefeedIdnumber \| nullnull订阅源 ID用于feed类流不设置时完全省略feed_id参数localeSlugstring \| nullnull语言标识会作为lang传给 APIstartDatestring \| nullnull起始时间游标perPagenumber—支持该参数的流的每页条数目前是space流使用options.enabledbooleantrue是否启用查询与streamKey非空是“与”关系返回值结构UseInfiniteStreamResult返回的字段直接映射到 UI 渲染需要的能力{ items: StreamItem[]; // 跨页去重后的流条目身份 posts: ReadStreamPost[]; // 从同一份归一化结果解析出的帖子 pages: ReadStreamResponse[]; // 原始响应页供调试/透传 isLoading: boolean; // 首次加载 isFetching: boolean; // 是否正在拉取含后台 refetch isFetchingNextPage: boolean;// 正在拉下一页驱动加载中指示器 isRefetching: boolean; hasNextPage: boolean; // 是否还有下一页 lastPage: boolean; // 已拉完且无更多数据 error: unknown; fetchNextPage: () void; // 触发下一页 refetch: () void; invalidate: () void; // 仅失效、不强制 refetch }底层原理查询键、页面句柄与正文同步从源码看useInfiniteStream的实现链路非常值得借鉴查询键单一来源。getInfiniteStreamQueryOptions调用automattic/api-queries的readStreamInfiniteQuery缓存键由 packages/api-queries/src/read-streams.ts 中的getStreamInfiniteQueryKey统一生成export function getStreamInfiniteQueryKey( { streamKey, feedId, localeSlug, startDate, }: StreamIdentity ): StreamInfiniteQueryKey { return [ read, stream, infinite, streamKey, feedId, localeSlug, startDate ] as const; }与之配套的getStreamInfiniteQueryKeyPrefix返回[ read, stream, infinite, streamKey ]前缀供getQueriesData/invalidateQueries一次匹配某个streamKey的所有变体跨feedId/localeSlug/startDate组合。游标句柄三形态。PageHandle类型{ page_handle: string } | { offset: number } | { before: string } | null反映了不同端点族的翻页约定。getNextPageHandle在上一页归一化出streamItems后通过extractPageHandle从响应中提取下一页句柄若上一页条目为空则返回undefined结束分页。正文同步只做一次。Hook 内用processedPages一个WeakSetReadStreamResponse记录已处理的页面对象避免同页重复同步。syncStreamPage对每个新页面执行两件事syncPostCache( queryClient, streamPosts )把帖子写入规范帖子缓存syncConversationFollowStatus( dispatch, streamPosts )把对话流的“是否关注”状态写入 Redux。前者定义在 client/reader/data/post/cache/index.ts#L530后者在同一文件的L547附近——两者都只在streamPosts.length 0时触发。跨页去重与 X 转载合并。流端点可能在同一帖子出现在多页因此items的 memo 用SetstringkeyToString序列化的身份去重随后combineXPosts会把相邻的、指向同一原始帖子的跨站转载合并把重复转载的 URL 汇总到xPostUrls实现见 client/reader/data/stream/utils.js。fetchNextPage 的 cancelRefetch 细节。源码特意把fetchNextPage包成fetchNextStreamPage( { cancelRefetch: false } )注释解释了原因cancelRefetch默认true会中止进行中的页面请求并重新发起而InfiniteList依赖fetchingNextPage这个 React prop 做门控该值要等一次 commit 后才翻转滚动检查可能在此之前重复触发导致同一页面多个重复请求。设为false后重复调用会合并进进行中的 Promise。预取prefetchInfiniteStream。README 特别强调只在 UI 有意预热与Stream读取的同一个无限流缓存时使用prefetchInfiniteStream绝不要为一个 Stream 预览去预取不同的查询键。源码中该函数先queryClient.prefetchInfiniteQuery( queryOptions )再逐页执行与 Hook 相同的syncStreamPage保证预热后流条目身份与帖子正文缓存都就绪。页码分页流usePaginatedStreamusePaginatedStream面向页码/每页条数形态的界面当前用于Recent与On This Day两个页面。README 的最小用法const stream usePaginatedStream( { streamKey: recent, page: 1, perPage: 15, } );入参与返回值见 client/reader/data/stream/hooks/use-paginated-stream/index.ts入参为streamKey、page、perPage必填与可选的localeSlug返回PaginatedStreamData{ items: StreamListItem[]; // 含占位行的流条目列表 pagination: { totalItems: number; totalPages: number }; isRequesting: boolean; // isLoading || isFetching error: unknown; }占位行机制与跨页拼装分页流与无限流最大的不同在于itemsgetPaginatedStreamItems会通过getQueriesData({ queryKey: getPaginatedStreamQueryKeyPrefix( streamKey ) })收集该流下所有已缓存的页面按perPage与localeSlug过滤、按page排序然后把每个页面归一化出的条目放进以(page - 1) * perPage为起点的数组槽位未拉取页面对应的槽位用{ isPadding: true, postId: padding-${index} }填充。这样 UI 在页码之间切换时已缓存页立即显示真实条目未缓存页显示占位行典型如骨架屏。isRequesting与pagination则由getPaginationFromResponse计算totalItems取响应的total_cards或foundtotalPages取total_pages或按perPage上取整推算。失效与命令式拉取配套的两个工具函数getPaginatedStreamQueryKeyPrefix( streamKey )返回[ read, stream, streamKey ]invalidatePaginatedStream( queryClient, streamKey )用该前缀invalidateQueries一次性失效某个流键的所有分页变体fetchPaginatedStream( queryClient, dispatch, options )以staleTime: 0强制拉取某一页并立即同步正文缓存适合在 Hook 之外命令式触发如首屏服务端预热。真实消费示例在 client/reader/recent/index.tsx#L69-L76 中Recent 页面用侧边栏选中的 feed 构造流键并驱动分页视图const streamKey selectedRecentSidebarFeedId ! null ? recent:${ selectedRecentSidebarFeedId } : recent; const data usePaginatedStream( { streamKey, page: view.page ?? 1, perPage: view.perPage ?? 15, } ); const streamItems data.items; const isLoading data.isRequesting;随后用isPaddingStreamItem过滤占位行、把真实条目映射成feedId/postId后交给useCachedPosts读取正文缓存L89-L101。client/reader/on-this-day/index.tsx#L96-L100 的 On This Day 页面采用完全相同的模式仅streamKey不同——可见这套“分页 Hook 缓存读正文”的组合已经成了分页流界面的标准模板。无限流的经典使用方ReaderStreamV2如果你要基于useInfiniteStream搭建完整的流界面client/reader/stream/stream-v2.tsx 是一个现成的参考实现。它自述为“基于 Hook 的精简 Reader 流”useInfiniteStream负责数据useInfiniteList负责窗口化windowingPostLifecycle负责单篇帖子渲染是旧版“Redux InfiniteList”流的现代化替代首个使用方是 Spaces 的 legacy feed 布局const { items, isLoading, error, refetch, hasNextPage, isFetchingNextPage, fetchNextPage } useInfiniteStream( { streamKey, localeSlug } );注意该组件标注了EXPERIMENTAL / UNSTABLEAPI 可能随时变化但它清楚展示了如何把useInfiniteStream的返回值接到选择器useStreamPostKeySelection、点击打开全文showSelectedPost等既有 Reader 交互上。归一化层不同载荷统一为 { streamItems, streamPosts }流 API 的响应有三种顶层形态——cardsDiscover 推荐流与标签流、sitescustom_recs_sites_with_images站点推荐、posts其余绝大多数。client/reader/data/stream/normalization/index.ts 的normalizeStreamPage按“哪种字段存在”路由到对应的createStreamDataFrom*助手统一输出{ streamItems, streamPosts }对这正是两个 Hook 与缓存助手共同的解析入口。时间键的动态选择值得单独说明。getStreamDateProperty决定用哪个字段作为流的“时间排序键”conversations/conversations-a8c→last_comment_date_gmt对话按最后一条评论排序likes→date_liked赞过的流按点赞时间排序其余 →date。createStreamItemFromPostclient/reader/data/stream/normalization/helpers.ts#L79把每个原始帖子压缩成流条目以keyForPost生成blogId/feedId/postId身份附带时间字段、URL、站点图标/名称/描述、feed_URL、feed_ID对话流还会带上反向排列的评论 ID 列表xPostMetadata通过XPostHelper.getXPostMetadata提取。createStreamDataFromCards则先把cards按type分桶post/recommended_blogs/new_sites帖子桶走createStreamDataFromPosts站点桶生成streamSites与streamNewSites。helpers 里还定义了贯穿所有流的请求规模常量export const PER_FETCH 7; // 游标翻页后每页条数 export const INITIAL_FETCH 4; // 首次请求条数 export const PER_POLL 10; // 轮询条数 export const PER_GAP 40; // gap 填充条数 export const QUERY_META post,discover_original_post;getQueryString为请求附加orderBy: date、meta: QUERY_META与content_width: 675轮询用的getQueryStringForPoll与其保持同形完整帖子载荷这样消费端能用轮询结果直接补全规范帖子缓存无需逐卡再发全文请求。此外还有针对推荐流的埋点助手analyticsForStream发射calypso_traintracks_render按railcar记录与getAlgorithmForStream——buildStreamQueryParams会把记录的算法值回填进后续请求的algorithm参数。查询参数构建buildStreamQueryParams 与各流特化client/reader/data/stream/build-query-params.js 的buildStreamQueryParams是请求形状的汇聚点其参数即两个 Hook 与轮询逻辑的上游buildStreamQueryParams( { streamKey, feedId, pageHandle, isPoll, gap, localeSlug, page, perPage, } )它先根据getStreamType拿到流类型再用getAlgorithmForStream补算法参数条数按规则取值有page时用perPage否则gap ? PER_GAP : (pageHandle ? PER_FETCH : INITIAL_FETCH)语言取localeSlug || i18n.getLocaleSlug()。一个值得注意的兼容性细节是feed_id仅在非空时才会被写入请求——新的wpcom/v2/read/streams/*端点会把feed_id当整数校验空字符串会被拒而旧的rest/v1.2/read/*端点能容忍空值这是 stream-data-layer 迁移后才暴露的问题源码注释引用 commitf3b2cddb32e。各流类型的特化逻辑通过switch ( streamType )分发覆盖了多种端点约定discover按streamKey后缀区分子页签recommended/latest/freshly-pressed/tags推荐排序用orderBy: popular其余用datefreshly-pressed不加getQueryString包装。recentstreamKey带后缀如recent:123时附加feed_id过滤。search从后缀JSON.parse出{ sort, q }。tag_popular附加tags、tag_recs_per_card: 5、site_recs_per_card: 5。list固定number: 40源码注释指出旧>赞分享前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载相关推荐wp-calypso Reader 模块开发实战指南路由、React Query 数据迁移与代码边界wp calypso Reader 模块开发实战指南路由、React Query 数据迁移与代码边界 WordPress.com 的 Calypso 前端仓库前端CMSwp-calypso Reader 模块架构实战从 Redux 数据层到 React Query 的迁移指南wp calypso Reader 模块架构实战从 Redux 数据层到 React Query 的迁移指南 Reader 是 WordPress.com 的前端CMSwp-calypso Reader 数据层迁移指南从 Redux Data-Layer 到 React Query 的完整实战方案wp calypso Reader 数据层迁移指南从 Redux Data Layer 到 React Query 的完整实战方案 导读 本文档对应仓库 .c前端CMS创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考