wp-calypso 通知客户端数据模型解析：API 耦合、轮询竞态与 Redux 状态增强设计
【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址: https://gitcode.com/gh_mirrors/wp/wp-calypso
本文以 wp-calypso 仓库中apps/notifications/src/doc/data-model.md为骨架，深入剖析通知面板（Notifications Panel）的数据模型：它如何直接耦合 WordPress.com 通知 API 的返回结构，如何通过"数据增强"（Augmentation）机制化解本地操作与后台轮询之间的竞态条件，以及hiddenNoteIds、noteLikes、noteApprovals等本地状态在 Redux 中的落地实现。读完本文，你将掌握通知客户端"服务端数据 + 本地覆盖"这一双流状态模型的完整设计思路，并能直接定位到对应的 reducer、action、selector 与 thunk 源码。
一、数据模型总览：直接耦合 API 响应
通知客户端目前没有在应用层建立一套与 API 解耦的独立领域模型，而是直接将 WordPress.com 通知 API 返回的数据与内部数据结构耦合在一起（data-model.md 开篇即明确这一点："the app is currently built by directly coupling the data from the WordPress.com API for notifications with the internal data structures"）。
在此基础上，应用额外维护了一套数据增强系统（data augmentation system），专门用来处理"本地状态同步"与"远程轮询"之间天然存在的竞态问题。换句话说：
- 数据本体：来自 API 的原始 note 对象，直接被塞进 Redux store；
- 数据增强：由应用自己维护的、叠加在原始数据之上的局部状态（隐藏、点赞、审核等），用于在异步网络请求往返期间稳定 UI。
来自 API 的 note 结构
API 返回的单条通知（note）对象包含以下字段：
const note = { id: [number] // note id as a number , type: [string] // type of notification, such as "comment" or "like_milestone_achievement" , read: [1 or 0] // boolean value representing whether or not the note has already been read , noticion: [unicode character] // mapping to icon in the noticon font corresponding to note category type , timestamp: [ISO8601 string] // time note was created , title: [string] // brief title to display above note , icon: [string URL] // URL for image to show as main notification icon , url: [string URL] // naturally related link to note: a post, a comment, a sign-up page, etc… , subject // list of blocks for header , body // list of blocks for body , meta // related note references: posts, sites, comments, etc… }各字段要点说明：
| 字段 | 类型 | 语义 |
|---|---|---|
id | number | 通知的唯一数字 ID，也是 Redux 状态中所有以 ID 为键的映射（如hiddenNoteIds、noteLikes）的核心索引 |
type | string | 通知类别，例如"comment"、"like_milestone_achievement"，决定通知如何渲染、对应哪些操作按钮 |
read | 1 或 0 | 该通知是否已被阅读 |
noticion | unicode 字符 | 映射到 noticon 字体中对应通知类别图标的字符 |
timestamp | ISO8601 字符串 | 通知创建时间 |
title | string | 显示在通知上方的简短标题 |
icon | 字符串 URL | 作为主通知图标展示的图片 URL |
url | 字符串 URL | 与通知自然相关的链接：一篇文章、一条评论、一个注册页等 |
subject | block 数组 | 渲染在头部的 block 列表 |
body | block 数组 | 渲染在正文的 block 列表 |
meta | 对象 | 关联的通知引用：posts、sites、comments 等 |
其中body/subject的 block 数组以及meta的具体渲染细节，可参见同目录下的 note-rendering.md（block 的ranges索引如何驱动富文本格式化）与 getting-notes.md（数据如何从/me/notifications接口与 Pinghub 通道进入应用）。
二、数据增强（Augmentation）：为什么需要它
轮询与本地修改的竞态
只要通知面板处于可见状态，后台轮询就始终在运行（"Polling is always active in the background while the app is visible"）。这带来一个必然结果：当用户在应用内做出修改（比如删除一条通知、点赞一条评论）时，这个本地修改与"在我们修改之前就已经开始在网络上传送的旧更新"之间，会形成竞态条件。
data-model.md 用一张时序图展示了这一过程：例如删除一条通知时，较早发出的轮询请求可能携带"该通知仍然存在"的数据返回，导致 UI 上出现"闪烁"——通知消失、重新出现、然后又突然消失。
当前策略：由于尚未实现理想的"网络锁"（network-lock，即"在既有请求成功或失败之前，阻止某些更新写入本地数据"），应用退而求其次，采用一套有状态的、彼此独立的本地数据存储来分别管辖各自类型的数据：点赞、删除（隐藏）等。每个 store 只管自己那一类状态，从而在轮询数据"迟到"时，本地覆盖仍然生效，避免 UI 抖动。
未来演进方向
data-model.md 明确写道，随着持续重构，期望能建立"网络锁"机制来从根本上防止竞态——在此之前，当前的"状态化、独立 store"方案是过渡性的务实设计。这也是阅读本模块代码时理解许多 reducer 为何"自成一体、互不耦合"的关键背景。
三、隐藏通知（Hidden Notes）：标记与撤销
当通知被标记为spam（垃圾）或trash（回收站）时，它应当从应用中消失；但同时，如果用户想要撤销这个破坏性操作，它又应该立即重新出现。因此应用维护了一个"hidden notes"列表，保存那些不应被渲染的 note id；当撤销 trash 或 spam 操作时，只需把对应 id 从该列表中移除即可。
state.notes.hiddenNoteIds = [ id1, id2, id3 /*...*/ ]; getIsNoteHidden( store.getState(), noteId );reducer 实现
data-model.md 中提到该列表由state/notes/reducers.js#hiddenNoteIdsreducer 维护。在当前仓库中，对应实现位于 apps/notifications/src/panel/state/notes/reducer.js：
export const hiddenNoteIds = ( state = {}, { type, noteId } ) => { if ( types.TRASH_NOTE === type || types.SPAM_NOTE === type ) { return { ...state, [ noteId ]: true }; } if ( types.UNDO_ACTION === type ) { const nextState = { ...state }; delete nextState[ noteId ]; return nextState; } return state; };可以看出它是一个以 noteId 为键、布尔值为值的普通对象：收到TRASH_NOTE或SPAM_NOTE时把 id 置为true，收到UNDO_ACTION时删除对应键。对应的 action 创建函数trashNote、spamNote定义在 apps/notifications/src/panel/state/notes/actions.js，而真正触发隐藏的 thunk 是 trash-note.js 与 spam-note.js。
值得注意的细节：trashNote/spamNotethunk 支持"立即执行"与"延迟执行"两种模式（immediately参数）。延迟模式下会调用restClient.global.updateUndoBar( 'trash', note )弹出撤销条——这正是"隐藏 → 可撤销 → 立即重现"交互的支撑；立即模式下则直接调用wpcom()REST 接口删除评论。无论哪种模式，最终都会 dispatch 对应的本地 action，把 noteId 写入hiddenNoteIds。
selector 与消费方
- selector：get-is-note-hidden.js 直接判断
notesState.hiddenNoteIds[ noteId ] === true；get-hidden-note-ids.js 返回整个隐藏 id 集合。 - 消费方：任何使用"可见通知列表"的地方都必须过滤掉该列表中的 id。data-model.md 列举了三处关键场景：
- 实际渲染在列表中的通知；
- 决定"高亮"落在哪里（键盘在通知列表中的导航）；
- 查找"下一条通知"。
源码中的落实例如 apps/notifications/src/app/note-list/index.tsx 通过tab.notes.filter( ( note ) => hiddenNoteIds[ note.id ] !== true )过滤可见列表，apps/notifications/src/app/note-list/hooks.ts 在键盘导航、查找下一条通知时同样逐一校验hiddenNoteIds[ id ] !== true。
四、点赞通知（Liked Notes）：本地点赞覆盖
当通知内部的评论或文章被点赞（like）或取消点赞（unlike）时，这个本地变更应当在"点赞网络请求返回"之前，持续覆盖外部轮询带来的更新，避免点赞状态被迟到的轮询数据闪回。这些本地点赞被维护在 Redux 状态中：
store.dispatch( actions.notes.likeNote( noteId, isLiked ) ); getIsNoteLiked( store.getState(), note );与隐藏通知的差异
data-model.md 特别强调了两点差异：
- 没有对应的"撤销"机制（"no corresponding 'undo' as with the hidden notes"）——点赞不存在 spam/trash 那样的可撤销交互；
- 如果一条评论/文章在点赞之后又要取消点赞，只需再次调用同一函数并传入新状态即可；但该函数并不能消除快速连续点赞/取消点赞时产生的竞态（"This function does not eliminate the race conditions when quickly liking and unliking in sequence"）。
reducer 与 thunk 实现
点赞状态由 reducer.js 中的noteLikesreducer 维护：
export const noteLikes = ( state = {}, { type, noteId, isLiked } ) => { if ( types.LIKE_NOTE === type ) { return { ...state, [ noteId ]: isLiked }; } if ( types.RESET_LOCAL_LIKE === type ) { const nextState = { ...state }; delete nextState[ noteId ]; return nextState; } return state; };LIKE_NOTE写入本地覆盖，RESET_LOCAL_LIKE在轮询数据可以安全接管时清除本地覆盖（对应 actions.js 中的likeNote与resetLocalLike，后者注释明确说明：本地点赞覆盖的目的是防止"轮询操作带来的过期数据把点赞状态错误地闪回"）。
实际的点赞请求走 set-like-status.js：
const setLikeStatus = ( noteId, siteId, postId, commentId, isLiked, restClient ) => async ( dispatch ) => { const type = commentId ? 'comment' : 'post'; dispatch( likeNote( noteId, isLiked ) ); // ...bumpStat / recordTracksEvent... const entityPath = type === 'comment' ? `comments/${ commentId }` : `posts/${ postId }`; if ( isLiked ) { await wpcom().req.post( `/sites/${ siteId }/${ entityPath }/likes/new` ); } else { await wpcom().req.del( `/sites/${ siteId }/${ entityPath }/likes/mine/delete` ); } // getNote() updates the redux store with a fresh object from the API restClient.getNote( noteId ); };关键顺序：dispatch( likeNote(...) )在发起网络请求之前执行——这正是"本地立即生效、覆盖轮询"的时序保证；请求完成后通过restClient.getNote( noteId )拉取最新对象并（配合resetLocalLike）让本地覆盖让位于权威数据。
selector 实现
get-is-note-liked.js 展示了"本地覆盖优先、API 数据兜底"的完整读取逻辑：
export const getIsNoteLiked = ( notesState, note ) => { const noteLikes = notesState.noteLikes; if ( noteLikes.hasOwnProperty( note.id ) ) { return noteLikes[ note.id ]; } const actionMeta = getActions( note ); const likeProperty = note.meta.ids.comment ? 'like-comment' : 'like-post'; return actionMeta[ likeProperty ] ?? false; };即：本地有覆盖就读本地，否则回落到从 note 的meta/action 信息中推导出的服务端状态。
五、审核通知（Approved Notes）：与点赞同构的机制
审核（批准/不批准评论）的机制与点赞完全同构，只是函数不同：
store.dispatch( actions.notes.approveNote( noteId, isApproved ) ); getIsNoteApproved( store.getState(), note );对应实现：
- reducer：reducer.js 中的
noteApprovals，处理APPROVE_NOTE（写入[ noteId ]: isApproved）与RESET_LOCAL_APPROVAL（删除键）； - action：actions.js 中的
approveNote与带注释的resetLocalApproval； - thunk：set-approve-status.js 通过
wpcom().site( siteId ).comment( commentId ).update( { status: isApproved ? 'approved' : 'unapproved' } )调用 REST API，请求前 dispatchapproveNote( noteId, isApproved )，请求回调中调用restClient.getNote( noteId )刷新权威数据； - selector：get-is-note-approved.js。
需要注意的是，data-model.md 中写的是state/notes/reducers.js，而仓库实际文件名为单数形式的 apps/notifications/src/panel/state/notes/reducer.js，阅读源码时请以实际路径为准。
六、从文档到源码：状态机的全景映射
将>export default combineReducers( { allNotes, // API 返回的全部 note，以 id 为键 filteredNoteIds, // 各过滤标签页下的有序 id 列表 hiddenNoteIds, // 隐藏通知 id 集合 noteApprovals, // 本地审核覆盖 noteLikes, // 本地点赞覆盖 noteReads, // 已读标记 filteredNoteReads, // 当前过滤视图下的已读 id } );
allNotes与hiddenNoteIds、noteLikes、noteApprovals的分离，正是"服务端数据直接耦合 + 本地增强覆盖"这一文档主旨的代码落地：API 数据进allNotes，本地竞态处理全在三个独立的覆盖型 reducer 里。
七、延伸阅读
- getting-notes.md：通知数据如何通过
/me/notificationsAPI、id+note_hash双流网络优化以及 Pinghub WebSocket 通道进入应用，是理解"轮询为什么始终活跃"的上游文档； - public-api.md：通知面板对外暴露的 props 与消息协议，其中
isVisible/isShowing的轮询节流策略直接决定了竞态窗口的大小； - note-rendering.md：note 的
body/subjectblock 数组如何渲染，meta中的 posts/sites/comments 引用如何被消费； - 模块总览见 apps/notifications/README.md，构建、iframe 通信（
togglePanel、iFrameReady、renderAllSeen、widescreen、render）等完整说明均在其中。
综上，wp-calypso 通知客户端的数据模型本质上是一套"权威数据来自 API、本地增强兜底竞态"的双层结构：allNotes直接耦合接口返回，hiddenNoteIds、noteLikes、noteApprovals三个独立 reducer 在请求往返期间维持 UI 稳定。理解这个模型，是后续为通知面板新增任何"乐观更新"类交互（回复、关注、编辑等）时避免 UI 闪烁问题的前提。
【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址: https://gitcode.com/gh_mirrors/wp/wp-calypso
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
