前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载docs/our-approach-to-data.md即 Calypso 的 Our Approach to Data是 WordPress.com 前端应用 Calypso 官方文档中关于数据层设计的总纲。它系统梳理了项目自 2014 年以来历经的五代数据管理方案并给出了当前自 2023 年 10 月起的选型建议。本文以该文档为骨架结合仓库内client/state、packages/state-utils等目录的真实源码与配置展开讲解每一代方案的架构特征、识别要点、演进原因并给出你在 Calypso 中新增数据管理代码时可直接落地的实践路径。读完本文你将掌握如何识别 Calypso 中遗留的旧式数据代码Redux 全局状态树含模块化状态的目录约定、Action/Reducer/Selector 规范与数据规范化模式以及当前推荐使用 TanStack Query 管理服务器状态、在 Hosting Dashboard 等新场景中搭配路由预加载的具体做法。历史五大「数据管理时代」概览Calypso 在成长过程中为应对应用规模的持续扩张数据层方案经历了五次大的演进。这些方案并非全量替换——新方案推出后旧代码仍然在仓库中大量存在因此你在日常开发中会不断遇到与当前推荐做法不一致的遗留代码。理解每一代方案及其识别特征是安全修改这些代码的前提。时代时间段核心方案第一代2014.06 - 2015.04Emitter Objects事件发射器对象第二代2015.04 - 2015.12Facebook Flux第三代2015.12 - 2020.02Redux 全局状态树第四代2020.02 - 2023.10模块化 Redux 状态树第五代2023.10 - 至今TanStack Query第一代Emitter Objects2014 年 6 月 - 2015 年 4 月Calypso 最初的数据管理采用面向对象思路每个 store 实例继承 Node.js 的EventEmitter接口。通常整个应用共享单个 store 实例实例既负责存储数据也提供「首次请求时自动拉取数据」的便捷能力。配合data-observemixin开发者可以把 store 实例作为 prop 传入 React 组件store 发出change事件时组件自动重新渲染。识别特征lib下以-list结尾的模块目录index 文件导出一个共享的实例对象原型list.js文件包含 store 原型list 提供get方法数据不存在时触发 fetchReact 组件中使用data-observemixin第二代Facebook Flux2015 年 4 月 - 2015 年 12 月Flux 是一套鼓励单向数据流的架构模式store 只能通过全局 dispatcher 分发的 action 被修改。原始数据从不被 store 模块直接暴露只能通过导出的辅助getter方法访问。Flux store 同样继承EventEmitter但只应发出change事件这一点在第一代中虽有约定但未被严格执行。Store 订阅 dispatcher 并监听自己关心的 actionaction creator 负责分发 action。典型场景是action creator 在首次请求时分发FETCH_前缀的「视图 action」收到数据后再分发RECEIVE_前缀的「服务器 action」应用中的任何 store 都可以对其中一种或两种 action 做出反应。识别特征lib下的模块目录模块包含actions.js和至少一个 store命名为store.js或以store结尾action creator 在全局Dispatcher上分发视图 action 或服务器 actionstore 内部持有顶层数据存储对象且不直接导出store 导出若干 getter 辅助函数用于访问已知数据store 订阅 Dispatcher根据关心的 action 类型修改数据优势被分发的 action 会运行在所有订阅的 store 上因此 store 可以针对自身需求做专门化处理数据进入 store 只有一个入口随着应用规模增长更易于管理数据逻辑如 fetch与数据存储解耦采用公认模式可获得社区驱动的参考实现生态第三代Redux 全局状态树2015 年 12 月 - 2020 年 2 月Redux 自称「可预测的状态容器」是对 Flux 思想的演进。它与 Flux 有诸多区别通常只有一个 store 实例维护整个应用的全局状态action creator 不直接调用全局 dispatcher而是返回普通 action 对象交给 store 的dispatch方法Flux store 各自维护自己的状态而 Redux reducer 是可组合的函数只操作全局状态「树」的特定部分状态是唯一事实来源因此 reducer 比 Flux store 更简单、更透明识别特征文件位于state目录目录结构镜像全局状态树结构React 绑定使用react-redux的connect优势相比 Flux是解决同类问题更简单的抽象更适合服务端渲染Flux store 的单例特性存在请求间泄漏会话数据的风险鼓励且常常迫使开发者编写函数式、可测试的代码可扩展支持中间件满足特定需求并有与 React 配合的便捷工具第四代模块化 Redux 状态树2020 年 2 月 - 2023 年 10 月第四代在第三代基础上演进复用同样的 selector、reducer 和 action creator。区别在于不再在启动时构建一个庞大的单一根 reducer而是让各个 reducer 在需要时同步地、自动地通过依赖图解析完成注册。详见仓库中的 docs/modularized-state.md。识别特征模块化 reducer 不再被导入根 reducerclient/state/reducer模块化 reducer 使用withStorageKey将自身状态单独持久化模块化状态包含init模块以副作用方式注册 reducer访问该部分状态的 action creator 和 selector 需要导入init模块优势保留了 Redux 的大部分优点代价是 action creator 和 selector 需要为它们触及的状态部分导入init文件显著减少 Calypso 启动所需加载的代码提升加载性能随着 Redux 状态持续增长这是更具扩展性的方案第五代TanStack Query2023 年 10 月 - 至今第五代是引入 TanStack Query 来负责数据的获取与变更。它为 React 应用中的服务器状态管理提供了轻量而强大的方案开发者可以轻松地获取、缓存、与服务端同步数据并内置分页、乐观更新、后台刷新等能力。当前推荐做法原文档给出了三条当前的硬性推荐适用于不同场景尽可能使用 TanStack Query 进行数据获取与变更。新的 Hosting Dashboard只用 TanStack Query。若数据是路由渲染所必需的则在路由 loader 中预加载若是可选数据则在组件中用 TanStack Query 获取。Calypso 其他部分可以继续使用client/state的 selector。TanStack Query 在仓库中的落地形态从源码看TanStack Query 的接入是全局性的client/state/query-client.ts 是 Calypso 统一管理 QueryClient 的核心模块。createQueryClient会先执行loadPersistedState()创建默认gcTime: MAX_AGE的 QueryClient并通过persistQueryClient将缓存持久化到浏览器存储store key 形如query-state-${persistenceKey ?? logged-out}登录/未登录状态分开存储hydrateServerState负责把 SSR 阶段脱水dehydrate的查询状态重新注水。查询 Hook 的典型写法可参考 packages/help-center/src/data/use-user-sites.ts用useQuery包裹queryKey与queryFn配置staleTime: 5 * 60 * 1000、refetchOnWindowFocus: false并通过enabled参数控制是否启用查询queryKey中带VERSION常量需要作废缓存时只需 bump 版本号。import { useQuery } from tanstack/react-query; import wpcomRequest from wpcom-proxy-request; // Bump this version to invalidate the cache. const VERSION 2; export function useUserSites( userId: number | string, enabled true ) { return useQuery( { queryKey: [ user-sites, userId, VERSION ], queryFn: () wpcomRequest { sites: SiteDetails[] } ( { path: /me/sites/?include_domain_onlytrue, apiVersion: 1.2, } ), refetchOnWindowFocus: false, staleTime: 5 * 60 * 1000, enabled, } ); }需要注意的是TanStack Query 面向的是服务器状态从 API 拉取、可缓存、可与服务端同步的数据而 Redux 状态树仍然承载应用的客户端/全局 UI 状态与规范化数据。两条技术路线在 Calypso 中并存各自有明确的适用边界。附录Redux 状态详解以下内容是 Calypso 中 Redux 数据层的完整约定也是理解遗留代码、维护client/state的必备知识。术语速览Redux 官方文档有详细的术语表下面是从 Calypso 视角的缩写版全局状态state tree一个深层嵌套的普通 JavaScript 对象封装应用当前状态由 Redux store 实例管理Store 实例既持有当前状态值getState也是引入新数据的入口dispatchAction creator返回 action 的函数Action描述一次状态变更意图的对象Reducer给定当前状态与 action返回新状态的函数Selector从状态树中取数的辅助函数这不是 Redux 官方术语而是社区通用模式目录结构约定client/state的根模块导出一个 reducer 函数。由于状态模块化尚未全部完成它启动时会通过 ReduxcombineReducersconst reducers { currentUser, dataRequests, sites, }; export default combineReducers( reducers );该文件顶部还有一条 ESLint 规则no-restricted-imports禁止向根 reducer 新增./*/reducer或state/*/reducer的导入防止遗留 reducer 列表继续膨胀。将状态拆分为子 reducer无论遗留还是模块化可以按主题隔离数据关注点并体现在state目录的文件夹结构上client/state/ ├── index.ts ├── action-types.ts └── { subject }/ ├── actions/ | ├── index.js | ├── action1.js | └── action2.js ├── init.js (for modularized state) ├── package.json (for modularized state) ├── reducer.js ├── schema.js ├── selectors/ | ├── index.js | ├── selector1.js | └── selector2.js └── test/ ├── actions.js (or actions/) ├── reducer.js └── selectors.js (or selectors/)例如维护全局状态中state.sites键的 reducer 位于 client/state/sites/reducer.js。主题 reducer 本身常常又是一个组合 reducer——正如把全局状态按子目录拆分当某个主题变大时把它拆成嵌套子目录通常更易维护。这种可组合性是 Redux 的优势之一。需要牢记状态总是在顶层进行模块化。即使某个顶层 reducer 由多个小 reducer 组合而成顶层 reducer 也始终作为单个原子单元加载。Actionsaction 描述一次改变应用状态的意图。当 action 对象被dispatch到 Redux store 时对应 reducer 会携带该 action 被调用由于应用状态的结构化特定子树可以对它们关心的 action 各自维护状态。action 对象应包含描述动作的type键。所有 action 类型统一定义在 client/state/action-types.ts。例如要描述「把几个新的 post 对象纳入状态」的意图可以创建type: POSTS_RECEIVE的 actionreducer handler 需要的其他属性也可以放在对象里。新 action 应加入action-types.ts。action 类型是全局的——任何状态子树的 reducer 都可以响应系统中分发的任何 action 类型。该文件应保持字母序并推荐把动词后缀化让同一领域内的 action 相对聚拢与其命名为FETCH_POSTS和RECEIVE_POSTS不如命名为POSTS_FETCH和POSTS_RECEIVE。数据规范化编写 reducer 时要审视树中被操作的数据确保主题之间恰当隔离以最小化冗余、避免同步问题。当某个主题需要引用树的另一部分时存一个引用通常是 ID。维护一个「索引化的条目集合indexed set of items」便于在需要查询时快速导航状态树。原文档给出了非常典型的多态「user」案例当前用户、站点订阅者、Reader 信息流中的评论者都是 user 的不同形态——展示方式不同甚至数据来源也不同——但都可以归类为 user且可以通过引用建立 user 与展示上下文之间的关系。下面的状态树展示了 users、sites、posts 如何相互关联同时保持规范化——避免重复、保持同步、便于查询{ users: { items: { 73705554: { ID: 73705554, login: testonesite2014 } } }, sites: { items: { 2916284: { ID: 2916284, name: WordPress.com Example Blog, description: Just another WordPress.com weblog } }, siteUsers: { 2916284: { 73705554: { roles: [ administrator ] } } } }, posts: { items: { 34: { ID: 34, title: Hello World!, site_ID: 2916284, author_ID: 73705554 } } } }注意这里posts.items[34]并不内嵌 site 与 user 对象而是通过site_ID、author_ID引用它们站点与其用户之间的关系单独存放在sites.siteUsers。这正是「以 ID 引用代替对象复制」的规范化核心。Selectorsselector 是从全局状态树中取数据的便捷函数。全局状态树是普通 JavaScript 对象直接访问并非不可但封装 selector 能减少重复、提升代码语义、避免犯错。下面两种方式都能取回某站点的文章数组显然第二种更可读// Using a selector let posts getSitePosts( state, siteId ); // Navigating the state tree posts state.sites.sitePosts[ siteId ].map( ( postId ) state.posts.items[ postId ] );调用约定Calypso 统一约定「任何 selector 的第一个参数总是完整 state 对象」。这种一致性消除了调用不确定性——你总能假定 selector 有相似的参数签名。更重要的是selector 常常需要遍历全局状态的不同部分如上面同时取sites和posts两个顶层键。放置位置遵循模块化状态方案某部分状态的 selector 应放在其state/{ subject }目录下的selectors文件/目录中与所属状态共置跨多个状态部分的 selector 应放在state/selectors下体现其全局性。同时模块化状态要求 selector 模块通过导入该部分的init模块来确保相关状态已初始化——这应放在专门的 selector 模块中而不是散落在各个 connect 组件里。纯函数约束selector 必须是纯函数——传入相同参数序列应始终返回相同结果且调用不得有副作用。例如 selector 中绝不能触发 AJAX 请求或给函数作用域外的变量赋值。典型使用场景解析引用规范化的状态树在减少冗余与同步问题上很理想但对开发者不够友好。selector 可以恢复对有用对象的便捷访问派生数据规范化状态树避免存储重复数据但有时需要基于状态数据计算出的值。例如按站点的 URL 属性计算其 hostname过滤数据用 selector 返回状态树值的子集。例如getJetpackSitesselector 返回所有已知站点中仅 Jetpack 启用的数组备忘memoization补充上述过滤场景也可以用 reducer 聚合 Jetpack 站点 ID 数组实现但那样通常仍需要配套 selector。selector 的缓存问题可以通过 memoization 解决——例如 Calypso 的createSelector仓库中的实现位于 packages/state-utils/src/create-selector/index.ts它基于automattic/js-utils的memoize缓存计算结果通过getDependants描述依赖的状态片段仅当依赖发生浅比较不相等时才清空缓存开发环境下还会对传入复杂对象参数非 number/boolean/string发出警告。createSelector与withStorageKey均通过 packages/state-utils/src/index.ts 统一导出。UI 状态何时用 Redux何时用 React Statestore 也可以跟踪界面状态但重要的是区分「何时」以及「为什么」应该用 Redux store 而不是 React 组件的 state。推荐原则只有当数据需要在页面间持久保存或需要被同页面上应用的不同区域共享时才把 UI 状态放进状态树。典型例子是「当前选中站点」在My Sites区段内翻页时用户期望选中站点不改变且渲染应用的很多部分都会用到它——因此它应存入全局状态。反例是 Sharing 页面展开某个分享服务用户并不期望离开再返回页面后该展开状态仍被保留这种场景用组件本地 React state 跟踪展开状态更合适。原则是「善用判断」但不必刻意回避 React state。全局应用级 UI 状态如 sections、masterbar 可见性相关文件位于 client/state/ui而功能特定的 UI 状态应与该功能的其余状态子树放在一起或作为独立的顶层条目。数据持久化将 Redux 状态持久化到浏览器存储IndexedDB可以避免每次页面加载都从零重建整棵 Redux 树并在 REST API 仍在拉取最新更新时先在 UI 中展示缓存数据而不是占位符。这个主题内容较多原文档指向了独立文档docs/data-persistence.md。此外从源码看模块化状态的持久化与withStorageKey直接相关packages/state-utils/src/with-storage-key/index.ts 的实现只是给 reducer 附加一个storageKey字符串属性真正消费它的是 client/state/add-reducer.ts 的addReducerToStore——注册 reducer 时读取其storageKey若存在且提供了getStoredState则异步加载并dispatchAPPLY_STORED_STATE应用已持久化的状态。这意味着每个模块化状态部分独立持久化、独立恢复不会拖慢全局启动。模块化状态实战为现有状态接入第四代方案模块化状态是理解「当前状态目录为什么长这样」的关键原文档在此仅做了指引其完整操作说明在 docs/modularized-state.md同时被 client/state/README.md 引用。下面按该文档的操作顺序结合仓库源码给出可直接照做的步骤。动机官方推荐的单根 reducer 方案要求根 reducer 在第一个 action 发出前就绪因而进入应用的关键路径。状态越多reducer 及其依赖内部/外部库、随包分发而非 API 运行时获取的大数据集就越多地进入关键路径且 reducer 通常是同步的无法异步加载。模块化方案在不放弃 Redux 架构收益的前提下把启动时加载的代码量压到最低。它必须满足三条约束无需声明「哪些部分用哪些状态」难以确定与维护无需大规模改动现有代码排除把状态异步化等方案状态消费者对模块化无感知——用 selector 的组件不必关心其状态是否模块化方案概览同步的、依赖图驱动的方式——reducer 随使用它们的 chunk 一起自动加载。状态划分为顶层部分每部分是加载意义上的不可再分原子每部分的 reducer 用withStorageKey单独持久化每部分有init模块通过副作用注册 reducer每个访问该状态的 selector/action creator 导入其init模块。这样只需把 selector、action creator 与它们触及的状态部分耦合其余由构建流程自动处理且 reducer 在被需要时必然已注册就绪。落地四步参考 docs/modularized-state.md添加init模块。在状态部分根部新增init.js通过registerReducer注册 reducerimport { registerReducer } from calypso/state/redux-store; import reducer from ./reducer; registerReducer( [ subject ], reducer );client/state/redux-store.ts 中registerReducer的实现显示若 store 已存在则立即注册同时始终把[ key, reducer ]推入reducerRegistrationQueue保证后续新建的 store 也能同步获得该 reducer。添加package.json。init文件有副作用需要让 webpack 知道防止它误以为所有文件都是纯的webpack 默认对package.json中sideEffects声明的文件不做 tree-shaking 剔除{ sideEffects: [ ./init.js ] }用withStorageKey单独持久化。把 reducer 的默认导出改为export default withStorageKey( subject, combinedReducer );真实示例可参考 client/state/reader/reducer.tsconst readerReducer withStorageKey( reader, combinedReducer );其 client/state/reader/init.js 则对应执行registerReducer( [ reader ], readerReducer )。让 selectors / action creators 初始化状态。为所有访问该状态的 selector 与 action creator 引入init模块未遵循推荐目录结构时需排查state/selectors还可能遇到内联 selector 的组件最好一并重构import calypso/state/subject/init; export default function getSubjectMatter( state ) { // ... }import calypso/state/subject/init; export function changeSubjectMatter( matter ) { // ... }最后从遗留根 reducer 列表client/state/reducer.js 及 client/landing/login/store 各自的列表中移除该 reducer——它已完全模块化不再需要常驻。常见排错Reducer with key foo is already registered通常意味着忘了从client/state/reducer或client/landing/login/store移除该 reducer或init文件中注册了错误的 key该 key 已存在于遗留根 reducer或 copy-paste 用了别的状态名。因为模块化方案防止重复初始化这个错误基本只会在上述情况出现。单元测试开始失败常因测试自建了 Redux store 而未正确适配模块化。创建 store 后调用setStore( store, currentUserId )即可解决import { createReduxStore } from calypso/state; import { setStore } from calypso/state/redux-store; import Thing from ../; describe( Thing, () { test( renders correctly, () { const store createReduxStore(); setStore( store, currentUserId ); // Instantiate and test component } ); } );setStore的作用见 client/state/redux-store.ts是替换现有 store 时先clearReducers()再把当前 store 包装为addReducerToStore( store, getStoredState )并同步注册队列中所有待处理的 reducer——这正是测试里「store 一创建模块化 reducer 就绪」的机制。结语三代并存的现实与选型心法从 2014 年的-listEmitter 对象到 2015 年的 Flux、同年年底的 Redux再到 2020 年的模块化 Redux、2023 年的 TanStack QueryCalypso 的数据层演进始终服务于同一个目标在应用规模不断增长时把数据获取、缓存、同步与 UI 状态管理的复杂度控制在可维护的范围内。当前仓库的现实是三代方案并存遗留的 Flux 与早期 Redux 代码需要识别与谨慎修改模块化 Redux 状态树承载着client/state的大部分客户端/全局状态TanStack Query 则成为新代码尤其是 Hosting Dashboard处理服务器状态的首选。选型时可以遵循原文档的三条推荐能上 TanStack Query 就上Hosting Dashboard 只上 TanStack Query必要数据走路由 loader 预加载、可选数据组件内查询其余场景继续使用client/stateselector 并遵守本文附录中的目录、Action、规范化与 Selector 约定。沿着这些规范前进你既不会在遗留代码前迷路也能把新功能写得符合 Calypso 当前的数据管理方向。延伸阅读完整实践请见 docs/modularized-state.md 与 docs/data-persistence.mdRedux 状态部分的代码入口在 client/state/index.ts含createReduxStore的中间件与增强器装配与 client/state/README.mdcreateSelector/withStorageKey等状态工具位于 packages/state-utils。赞分享前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载相关推荐wp-calypso 的 API Queries 包基于 TanStack Query 的 WordPress.com REST API 数据层设计指南wp calypso 的 API Queries 包基于 TanStack Query 的 WordPress.com REST API 数据层设计指南 导读前端CMSWordPress.com Dashboard 数据层实战基于 TanStack Query 的 REST 数据获取与状态管理指南WordPress.com Dashboard 数据层实战基于 TanStack Query 的 REST 数据获取与状态管理指南 本文以 client/da前端CMSwp-calypso数据层10年演进史从EventEmitter到Flux再到data-stores的5大时代wp calypso数据层10年演进史从EventEmitter到Flux再到data stores的5大时代 wp calypso 是 WordPress.前端CMS上一篇Bitfocus Companion安全配置教程保护您的专业控制系统下一篇iTerm2-Color-Schemes 速览605 款终端配色告别长时间编码的视觉疲劳创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考