前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载wp-calypso 是 WordPress.com 的前端代码库其购买、续费、优惠券、税务等交易流程都依赖一个统一的前端购物车抽象。本文围绕packages/shopping-cart包包名automattic/shopping-cart当前仓库版本 2.0.2展开系统讲解它的 API 设计、核心数据类型、React 集成方式Provider、Hook、HOC并深入源码说明其缓存状态机、动作排队、错误分类与自动刷新机制帮助你在这个 monorepo 中正确地集成和调试购物车功能。一、包的定位替代已弃用的 lib/cartautomattic/shopping-cart是一个访问 WordPress.com 购物车的库同时提供了一套完整的 TypeScript 类型来描述购物车中流转的数据。正如 README 所述calypso 的lib/cart目录中还存在一个旧版本的购物车接口但那个版本已被弃用deprecated新代码应使用本包。从 package.json 可以看到它的关键元信息包名automattic/shopping-cartsideEffects: false便于打包器做 tree-shaking同时产出 CJSdist/cjs、ESMdist/esm与类型声明dist/types并在exports中通过calypso:src条件暴露src/index.ts源码方便 monorepo 内直接消费未编译的 TypeScript运行时唯一依赖是debugReact 通过 peerDependencies 约束为^18.3.1 || ^19.0.0。入口文件 src/index.ts 导出了包的全部公共 APIuseShoppingCart、useShoppingCartManagerClient、withShoppingCart、ShoppingCartProvider、createRequestCartProduct、createShoppingCartManagerClient经由shopping-cart-manager模块、empty-carts工具、全部类型定义、错误类以及convertResponseCartToRequestCart、convertTaxLocationToLocationUpdate、parseNextDomainCondition等转换函数。二、核心数据模型CartKey、ResponseCart 与 RequestCart理解本包首先要理解两个对象购物车整体是一个ResponseCart其中包含若干ResponseCartProduct。如果要向购物车添加商品则使用要求更少的RequestCart/RequestCartProduct。完整定义见 src/types.ts。2.1 购物车键CartKeyexport type CartKey number | no-user | no-site;每个购物车由一个 cart key 标识通常是 WordPress.com 站点的数字 ID。此外还有两种特殊的无站点购物车no-site无站点购物车no-user无用户购物车。如果 cart key 为undefined购物车将不会被加载isLoading会永远为true——这可以用来临时禁用购物车。这一点在源码中体现得很直接src/shopping-cart-manager.ts 中createShoppingCartManagerClient的forCartKey对 falsy 的 cartKey 直接返回共享的noopManager定义于 src/managers.ts其状态永远是加载中 空购物车动作除reloadFromServer/clearMessages外都会 reject 一条Cart actions cannot be taken without a cart key.的错误。如果手上只有站点 slug 而拿不到站点 ID可以调用ShoppingCartManagerClient上的getCartKeyForSiteSlug把 slug 转换为 cart key。这个函数的实现findCartKeyFromSiteSlug位于 src/cart-functions.ts有一个值得注意的工程细节由于购物车端点在站点刚创建后偶尔会长时间不响应该实现最多串行重试 3 次、每次 1 秒超时全部超时或发生非超时错误时回退为no-site。还有一个从源码结构看的关键约束src/cart-keys.ts 定义了cartKeysThatDoNotAllowFetch: CartKey[] [ no-user ]。也就是说no-user购物车在同步层src/sync.ts会直接返回空购物车而从不真正请求服务端。2.2 ResponseCart只读的服务端快照ResponseCart是购物车端点返回的对象大家平时说的购物车指的就是它。类型注释明确要求它当作不可变对象对待直接修改它要么会出问题要么毫无效果所有变更都必须通过ShoppingCartManagerActions发起请求。其核心字段src/types.ts包括标识blog_id、cart_key、cart_generated_at_timestamp商品列表products: ResponseCartProduct[]金额注意金额有两套表示浮点版本已被标记为deprecated应使用最小货币单位整数版本total_tax字符串浮点弃用 /total_tax_integer最小货币单位total_cost浮点弃用 /total_cost_integersub_total_integer不含税小计、sub_total_with_taxes_integer含折扣不含税、coupon_savings_total_integer、credits_integer账户抵扣额度优惠券coupon、is_coupon_applied、has_auto_renew_coupon_been_automatically_applied展示与提示currency、locale、allowed_payment_methods、messages包含errors/success/persistent_errors三类ResponseCartMessage每个消息有code和message税务tax: { location: ResponseCartTaxLocation, display_taxes }域名相关next_domain_is_free、next_domain_condition逗号分隔的 TLD 白名单空串表示无限制可用parseNextDomainCondition解析为数组、bundled_domain其余is_signup、gift_details/is_gift_purchase为他人站点购买、terms_of_service促销期条款、has_pending_payment等。每个ResponseCartProduct携带uuid购物车项的唯一 ID供removeProductFromCart/replaceProductInCart引用、product_slug、product_id、cart_item_id、各类*_integer价格字段、bill_period天数字符串如 31 / 365 / 730与months_per_bill_period、product_variants可切换的计费周期变体、cost_overrides价格覆盖含human_readable_reason、introductory_offer_terms introductory 优惠条款含interval_unit/interval_count/transition_after_renewal_count/should_prorate_when_offer_ends等大量业务字段。服务端返回的原始购物车在 src/cart-functions.ts 的convertRawResponseCartToResponseCart中被规范化过滤掉wordpress-com-credits这类伪商品、把 PHP 空关联数组序列化成的[]形tax.location纠正为{}、并以cart_item_id兜底补上uuid。2.3 RequestCartProduct向服务端提交的最小请求RequestCartProduct只需product_slug、meta、volume、quantity、extra等字段返回结果可能与请求不同甚至缺失字段。一个特殊规则renewal续费可以不提供product_slug而是提供extra.purchaseId订阅 ID并把extra.purchaseType设为renewal服务端会依据订阅记录反查商品。三、createShoppingCartManagerClient状态管理核心createShoppingCartManagerClient创建本包使用的状态管理系统ShoppingCartManagerClientREADME 建议将其作为单例创建并在整个应用中共享。它接受两个必需的服务端适配函数getCart: ( cartKey: number | no-site | no-user ) PromiseResponseCart从服务端拉取购物车setCart: ( cartKey, requestCart: RequestCart ) PromiseResponseCart把更新后的购物车提交给服务端。创建后ShoppingCartManagerClient暴露两个成员src/shopping-cart-manager.tsforCartKey(cartKey)返回指定 cart key 的ShoppingCartManager。实现上用一个MapCartKey, ShoppingCartManager做缓存同一个 key 只会创建一次 manager传入undefined时返回共享的noopManager购物车永远加载中、动作不产生效果。getCartKeyForSiteSlug(siteSlug)查询服务端把站点 slug 转换为 cart key前文所述的 3 次重试 / 1 秒超时 /no-site兜底逻辑。每个ShoppingCartManager提供getState: () ShoppingCartManagerState返回当前购物车状态字段与useShoppingCart的返回值一致actions: ShoppingCartManagerActions动作对象与useShoppingCart返回的动作完全相同subscribe(callback): UnsubscribeFunction订阅该 key 的变更返回退订函数fetchInitialCart: () PromiseResponseCartmanager 创建后应调用的初始拉取如果其他动作先被调用它会在该动作派发前自动执行。源码层面值得了解三点动作 Promise 的管理。createDispatchAndWaitForValidsrc/shopping-cart-manager.ts把每次 dispatch 包装成一个 Promise登记进createActionPromisesManagersrc/managers.ts。当 reducer 报告购物车不再处于待定状态时全部排队中的 Promise 会一起被 resolve 或 reject——这就是动作 Promise 在购物车下次有效时 resolve可能经过多个排队动作之后的底层机制。错误的分类。getErrorFromState区分两类错误网络/请求级失败loadingError此时购物车可能长期无效与购物车端点返回的业务错误responseCart.messages.errors此时购物车通常仍可用。状态缓存。getCachedManagerState只在底层 state 引用变化时才重新计算ShoppingCartManagerState避免每次getState()都重复构造对象。四、ShoppingCartProvider向组件树注入购物车ShoppingCartProvidersrc/shopping-cart-provider.tsx是一个应放在渲染树顶部附近的 React context provider通过 context 让树内组件以useShoppingCart或withShoppingCart访问购物车。它的 propsmanagerClient: ShoppingCartManagerClient必需购物车管理系统由createShoppingCartManagerClient创建options?: { refetchOnWindowFocus?: boolean; defaultCartKey?: number | no-site | no-user | undefined }可选refetchOnWindowFocus当窗口/标签页从隐藏状态重新聚焦时触发getCartdefaultCartKey当组件未向useShoppingCart/withShoppingCart传入 cart key 时使用的默认值。实现上Provider 用useMemo对 options 做浅层记忆化防止 options 值未变化时因对象引用不同导致子树重渲染它通过两个嵌套 context 分别下发 options 和 managerClient。refetchOnWindowFocus的具体行为在 src/use-refetch-on-focus.ts 中监听visibilitychange、focus、online三个事件只有当窗口已聚焦、且距上次拉取超过 60 秒minimumFetchInterval以cart_generated_at_timestamp为基准、且未离线三者同时满足时才调用manager.actions.reloadFromServer()。此外undefined的 cartKey 和cartKeysThatDoNotAllowFetch中的 key即no-user不会注册监听。五、useShoppingCartHook 形式的购物车访问useShoppingCart( cartKey )可在ShoppingCartProvider下任意子组件中使用返回一个UseShoppingCart对象。参数cartKey: number | no-site | no-user | undefined传undefined时购物车不会被加载但仍会返回空购物车与 noop 动作。其内部逻辑见 src/use-shopping-cart.ts合并 Provider 的defaultCartKey、调用manager.fetchInitialCart()错误被吞掉交由消费端根据messages.errors/loadingError展示、并通过manager.subscribe在每次状态变化后重新生成状态快照触发重渲染。返回对象分为状态字段与动作字段两部分。注意动作只是请求不保证一定被购物车 API 满足。状态字段字段类型说明responseCartResponseCart完整购物车对象只读修改请用动作函数isLoadingboolean初始加载中仅在某个 cartKey 的首次加载或 cartKey 为undefined/null时为 trueisPendingUpdateboolean任何购物车正在以某种方式变化的标志初始加载、cartKey 变化、或修改请求待定loadingErrorstring \| null \| undefined拉取或更新出错时的错误消息loadingErrorTypeShoppingCartError \| undefined错误类型取值为GET_SERVER_CART_ERROR \| SET_SERVER_CART_ERRORcouponStatusfresh \| pending \| applied \| rejected优惠券提交状态未尝试 / 请求中 / 已应用 / 被拒绝拒绝原因在购物车 errors 中isLoading与isPendingUpdate的推导在 src/managers.ts 中一目了然isLoading对应cacheStatus fresh || fresh-pendingisPendingUpdate对应有排队动作或 cacheStatus 不是 valid。这里的CacheStatus共 6 个值src/types.tsfresh刚加载无请求、fresh-pending等待初始请求、invalid本地数据已被编辑、valid本地与服务端一致、pending请求已发出、error。动作字段每个都返回一个PromiseResponseCart在购物车下次有效时 resolve若端点返回错误responseCart.messages.errors或请求本身失败loadingErrorPromise 会 reject拒绝参数是带code与message的错误实例addProductsToCart( products: RequestCartProduct[] )请求添加商品。注意可能变成整体替换从源码 src/cart-functions.ts 的shouldProductReplaceCart看续费与非续费不能共存——购物车里没有续费项而你要加续费项时domain_redemption除外或购物车里已有续费项而你要加非续费项时新商品会替换整个购物车removeProductFromCart( uuidToRemove: string )按uuid移除商品applyCoupon( couponId: string )应用优惠券同时只能有一个removeCoupon()移除优惠券updateLocation( location: LocationUpdate )修改税务地点整体替换当前地点只需改一个字段时可先用convertTaxLocationToLocationUpdate把responseCart.tax.location转成该函数所需结构再局部修改replaceProductInCart( uuidToReplace, productPropertiesToChange: PartialRequestCartProduct )保持uuid不变地替换一个商品适合切换变体如改计费周期replaceProductsInCart( products )用一组新商品整体替换购物车内容传空数组即清空购物车reloadFromServer()丢弃本地缓存、重新从购物车 API 拉取clearMessages()丢弃当前responseCart.messages适合在展示完提示后清空。README 特别提醒无论 Promise 成功与否都应在任何状态变更后检查responseCart.messages.errors和loadingError。对应的错误类在 src/errors.ts 中定义基类CartActionError带code以及两个子类CartActionConnectionError请求级失败与CartActionResponseError端点返回的业务错误。六、withShoppingCart面向类组件的 HOC当无法使用 Hook如类组件时可以用withShoppingCart高阶组件把UseShoppingCart注入目标组件src/with-shopping-cart.tsx。被包裹的组件会额外收到两个 propsshoppingCartManager: UseShoppingCart与useShoppingCart返回值完全相同的对象cart: ResponseCart便捷 prop等价于shoppingCartManager.responseCart。HOC 的入参Component要包裹的组件mapPropsToCartKey?: ( props ) CartKey | undefined必须提供第二个参数来基于组件 props 推导 cart key不提供时回退为读取props.cartKey。七、useShoppingCartManagerClient不订阅任何购物车的管理器入口useShoppingCartManagerClient()直接返回外层ShoppingCartProvider提供的ShoppingCartManagerClient而不订阅任何具体 cart key。它适用于需要向当前组件并未渲染的购物车派发动作的场景——如果为此调用useShoppingCart会在每次渲染时急切地拉取该购物车。README 给出的典型用例在导航离开前清空多个购物车const managerClient useShoppingCartManagerClient(); await Promise.all( [ activeCartKey, no-site, no-user ].map( ( key ) managerClient.forCartKey( key ).actions.replaceProductsInCart( [] ) ) );实现只有一行src/use-shopping-cart-manager-client.ts 中直接调用useManagerClient后者同时负责在缺少 Provider 时报出友好错误。八、辅助函数构造请求商品与空购物车8.1 createRequestCartProductcreateRequestCartProductsrc/create-request-cart-product.ts用于创建可传给addProductsToCart()等函数的RequestCartProduct。入参是一个对象可含RequestCartProduct的部分或全部属性但必须至少包含product_slugrenewal 例外——可以只指定extra.purchaseId订阅 ID并将extra.purchaseType设为renewal。未设置的属性会填入默认值meta: 、volume: 1、quantity: null、extra: {}或由服务端补全。源码还内建了一个防御如果提供了extra.purchaseId却没提供extra.purchaseType会打印console.warn提示这可能是一笔本应标记为续费的购买。同文件还导出批量版本createRequestCartProducts若两者都缺无product_slug且无extra.purchaseId则直接抛错。8.2 getEmptyResponseCart / getEmptyResponseCartProduct这两个函数返回空但合法的ResponseCart/ResponseCartProductsrc/empty-carts.ts主要用于测试中 mock 购物车响应。空购物车的默认值blog_id: 0、cart_key: no-site、currency: USD、locale: en-us、金额全 0、is_coupon_applied: false等也保证了在undefinedcartKey 的 noop 场景下组件仍能拿到结构完整的对象。8.3 convertResponseCartToRequestCart把ResponseCart转换为RequestCartsrc/cart-functions.ts只保留blog_id、每个商品的product_slug/meta/volume/quantity/product_id/extra、coupon以及非空的税务地点8 个字段全空时tax置为null并固定temporary: false。通常购物车管理器会代劳这件事但如果你需要手动操纵购物车对象这个函数会派上用场。8.4 convertTaxLocationToLocationUpdate把responseCart.tax.locationsnake_case 的ResponseCartTaxLocation转换为updateLocation()所需的 camelCaseTaxLocationUpdate结构countryCode/postalCode/subdivisionCode/vatId/organization/address/city/isForBusiness。逆向转换convertLocationUpdateToTaxLocation同样由包导出便于双向映射。九、源码深处的三条重要机制9.1 动作排队与不做乐观更新购物车更新必须经过服务端验证并补全字段后才能成为有效状态因此无法乐观更新。src/shopping-cart-reducer.ts 的reducerWithQueue处理了这一约束当cacheStatus为fresh/pending/fresh-pending购物车尚未加载完成时除RECEIVE_INITIAL_RESPONSE_CART、RECEIVE_UPDATED_RESPONSE_CART、FETCH_INITIAL_RESPONSE_CART、RAISE_ERROR外的动作会被加入queuedActions队列一旦状态回到valid队列中的动作按序回放并清空由于中间状态invalid/pending的responseCart可能含未验证的临时商品对外暴露的始终是lastValidResponseCart上一次有效快照消费端通过isPendingUpdate感知数据正在更新购物车处于待定状态时CART_RELOAD会被直接忽略避免打断进行中的同步。9.2 与服务端的同步链路src/sync.ts 中的createCartSyncManager负责两条链路fetchInitialCartFromServer调用getCart并把响应经convertRawResponseCartToResponseCart规范化后dispatch 为RECEIVE_INITIAL_RESPONSE_CARTsyncPendingCartToServer先convertResponseCartToRequestCart再setCart提交成功后 dispatchRECEIVE_UPDATED_RESPONSE_CART。任何失败都会 dispatchRAISE_ERROR携带GET_SERVER_CART_ERROR或SET_SERVER_CART_ERROR类型——这正是loadingErrorType的取值来源。no-userkey 在此层被拦截直接返回空购物车而不发请求。9.3 测试基线包的测试位于 packages/shopping-cart/test/mock-cart-api.ts提供getCart/setCart的 mock 实现用于驱动 managercart-manager.ts、use-shopping-cart.tsx、with-shopping-cart.tsx、cart-functions.ts分别覆盖了管理器、Hook、HOC 与转换函数的行为。在 monorepo 中修改本包后可以直接运行包内 jest配置见 jest.config.js验证这些行为。十、快速上手小结在 wp-calypso 中集成购物车的典型步骤是以你实现的getCart/setCart对接/shopping-cart端点调用createShoppingCartManagerClient创建单例在应用顶部挂载ShoppingCartProvider managerClient{ client } options{{ defaultCartKey: blogId }} /组件内用const cart useShoppingCart( blogId )读取responseCart并调用cart.addProductsToCart( [ createRequestCartProduct( { product_slug: plan_business_1y } ) ] )等操作每次状态变更后检查cart.responseCart.messages?.errors与cart.loadingError并用couponStatus/isPendingUpdate驱动 UI。这套设计把服务端验证 动作排队 最后有效快照 错误分类 聚焦自动刷新封装在ShoppingCartManager内使上层无论是 Hook、HOC 还是直接持有 manager 的代码路径都能以一致且类型安全的方式驱动 WordPress.com 的购物车。赞分享前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载相关推荐wp-calypso 中 automattic/calypso-babel-config 的配置体系与 importSource 动态化改造解析wp calypso 中 automattic/calypso babel config 的配置体系与 importSource 动态化改造解析 这篇技术指南前端CMSReact-Redux购物车电商应用的状态管理终极指南React Redux购物车电商应用的状态管理终极指南 在当今的电商应用中 购物车功能 是用户体验的核心环节。如何优雅地管理商品添加、数量调整和状态同步这前端wp-calypso Site Sync 状态管理从 State 树到 SITE_SYNC_STATUS 状态机全解析wp calypso Site Sync 状态管理从 State 树到 SITE_SYNC_STATUS 状态机全解析 导读 Site Sync站点同步是前端CMS上一篇TinaCMS 的 tinacms/graphql 数据层演进索引排序、安全加固与自托管数据库实战下一篇esptool 进入 Bootloader串行下载模式实战指南复位原理、自动复位电路与手动操作创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
