wp-calypso 多站点 Dashboard 的包导入限制策略：calypso 与 @automattic 依赖边界实战指南

前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载本文解读 wp-calypso 仓库中新版多站点 Dashboard服务于 WordPress.com 托管控制台与 Commerce-in-a-Box位于 client/dashboard所采用的包导入限制政策。该政策通过 ESLint 规则强制约束模块对calypso/与automattic/包的依赖边界防止旧的 Calypso 概念、Redux 状态和过重 UI 渗入新架构。读完本文你将掌握这套白名单机制的完整规则、例外流程以及在实际开发中如何判断某个包是否可以安全引入。政策概览为什么要限制 Dashboard 的导入新版 Dashboard 采用了与旧 Calypso 不同的技术栈使用 TanStack Query 与 TanStack Router明确不使用 Redux 与calypso/state见 client/dashboard/AGENTS.md 中的 Conventions 一节。在这一前提下client/dashboard/docs/package-imports.md 定义了核心约束Dashboard 限制从calypso/与automattic/包导入并由 client/dashboard/.eslintrc.js 中的 ESLint 规则强制执行。政策给出了三个层面的理由概念耦合许多包会把 Calypso 的代码与概念providers、全局状态、旧版架构假设一并带进来这是新架构最想避免的设计系统不一致非核心 UI 元素与 Dashboard 自身的组件体系、设计规范不匹配会破坏视觉与交互一致性隐性运行时依赖这些包可能依赖 Calypso 的 Context providers 或 Redux store导入后会产生难以察觉的运行时副作用。从源码结构看这一约束与 Dashboard 的定位高度一致它是多入口的独立应用WordPress.com、A4A、CIAB 共用同一代码库见 client/dashboard/docs/entry-points.md需要保持架构独立性与依赖可控性。理想依赖的标准在能不用就不用的基调下政策明确了哪些依赖是理想的自身依赖极少minimal dependencies of their own引入成本可预测使用automattic/api-core提供 API 类型保证类型与数据获取逻辑的统一来源不依赖 Calypso 的 providers 或 Redux 状态不把旧状态管理架构带进新代码不提供整块页面或完整 UI只提供工具函数或 UI 原语utilities or UI primitives。第 2 点与仓库实际分层完全吻合packages/api-core/README.md 定义了 Automattic 生态统一的数据获取函数与类型每个资源目录包含fetchers.ts/mutators.ts/types.ts/index.tspackages/api-queries/README.md 在其上构建了 TanStack Query 层的queryClient与 query/mutation 构造器。Dashboard 的数据层即建立在automattic/api-queries之上详见 client/dashboard/docs/data-library.md因此这两个包处于依赖白名单的核心位置。ESLint 强制机制白名单规则逐条解读政策不是倡议而是通过 client/dashboard/.eslintrc.js 中no-restricted-imports规则L5-L199落地的硬约束。规则包含两组patterns按 glob 匹配的包前缀白名单与一组paths针对具体导入的精细限制。第一组calypso/*及其例外规则先整体禁止calypso/*随后用!前缀逐项放行白名单模块L10-L45类别放行的白名单说明数据calypso/data/data-center、calypso/data/php-versions仅放行这两个与 Dashboard 直接相关的数据模块其余calypso/data/*全部禁止库calypso/lib/ai-launchpad、calypso/lib/color-scheme、calypso/lib/explat、calypso/lib/interval、calypso/lib/load-dev-helpers、calypso/lib/logstash、calypso/lib/version-compare、calypso/lib/wp工具类库其中calypso/lib/use-site-launch-gating-variant与calypso/lib/interval被标注为 temporary临时例外资源calypso/assets/icons、calypso/assets/images仅限图标与图片资源不包含任何代码配置中的注释明确提示Allowed项即白名单并反复强调不要添加会把 Calypso 代码/概念带进来的例外L43-L44。值得注意calypso/lib/interval的例外处理规则放行的是!calypso/lib/interval整个目录但在calypso/lib/*通配之后。而calypso/lib/use-interval并未放行——从配置看允许的是interval目录本身使用时需按calypso/lib/interval/use-interval引用这与注释中的临时标注一致。第二组automattic/*及其例外同理先禁止automattic/*再放行白名单L49-L104。核心白名单包括基础设施automattic/api-core、automattic/api-queries、automattic/calypso-config、automattic/calypso-sentry、automattic/calypso-support-session、automattic/calypso-stripe、automattic/calypso-url、automattic/urls、automattic/js-utils、automattic/i18n-utils、automattic/languages、automattic/load-script、automattic/viewport、automattic/browser-data-collector、automattic/posthog、automattic/survicate、automattic/omnibar、automattic/generate-password、automattic/number-formatters、automattic/calypso-analytics、automattic/charts领域功能包automattic/date-range-picker、automattic/domain-search、automattic/domains-table含src/utils/*、automattic/help-center、automattic/agents-manager、automattic/mini-cart、automattic/search、automattic/composite-checkout、automattic/shopping-cart、automattic/ui、automattic/site-launch-modals部分放行automattic/components仅放行src下的circular-progress-bar、summary-button、breadcrumbs含types、logos、resurrected-welcome-modal等具体模块automattic/onboarding仅放行src/utils/email-validation对比第一组可见automattic/包的粒度更细像automattic/components、automattic/onboarding这类组件库并非整体放行而是只放行被 Dashboard 实际使用、且不携带 Calypso 概念的子路径。第三层paths级别的精细规则除了包前缀L108-L198 对具体导入路径与具名导入importNames做了更严格的约束automattic/calypso-analytics整体禁止改为使用本地useAnalytics()来自client/dashboard/app/analytics。本地实现见 client/dashboard/app/analytics/index.tsx它通过 React Context 暴露recordTracksEvent/recordPageView并附带bumpStat统计能力未命中 Provider 时在非生产环境告警、生产环境通过captureException上报一次calypso/lib/color-scheme的ClassicColorSchemeProvider禁止导入要求使用 query-backed 的配色方案 provider而非基于 Classic Redux 的 provider——这是不依赖 Redux 状态原则的直接体现automattic/componentsbarrel 文件禁止从桶文件导入必须使用automattic/components/src/summary-button这类具体路径防止整个包被打进 Dashboard 的 bundleautomattic/onboardingbarrel 文件同上只允许automattic/onboarding/src/utils/email-validationi18n-calypso整体禁止改用wordpress/i18nmoment整体禁止改用date-fnswordpress/components的 Card 系列Card/CardBody/CardDivider/CardHeader/CardFooter/CardMedia禁止改用本地client/dashboard/components/card该组件是对wordpress/componentsCard 的临时包装提供响应式 padding 控制见 client/dashboard/components/card/readme.mdtanstack/react-router的redirect禁止直接使用改用client/dashboard/app/router/redirect.ts导出的dashboardRedirect——它封装了 TanStack 的redirect()并强制关闭 view transitions重定向属于自动跳转而非用户主动导航不应触发过渡动画同时保留与原始函数相同的泛型推断见 client/dashboard/app/router/redirect.tsautomattic/api-queries的sitesQuery、dashboardSiteListQuery、dashboardSiteFiltersQuery禁止直接导入改用context或useAppContext提供的本地 querieswordpress/element的 React 原语useState、useEffect、useCallback、useMemo、memo、Fragment等二十余项全部禁止要求直接从react导入。规则注释解释了原因Dashboard 对 React 是硬依赖不同于 Gutenberg 依赖wordpress/element少数仍需从wordpress/element导入的如createInterpolateElement不受此限制。这些paths规则的意义远超禁止本身——它们强制指向了本地的替代实现保证新代码落盘时就走正确的架构路径。例外机制如何申请新的白名单政策明确例外在正常的 PR review 过程中讨论。当需要新增例外时必须说明两件事为什么需要why its needed这个依赖解决了什么问题是否有本地替代方案如何被审查验证how it has been vetted依赖是否满足理想依赖的四条标准——依赖少、基于automattic/api-core、不依赖 Calypso providers/Redux、只提供工具或 UI 原语。配置中的注释是这一流程的实体化calypso/lib/use-site-launch-gating-variant与calypso/lib/interval明确标注为 temporary说明例外带有时效性未来应持续推动移除而!calypso/data/data-center、!calypso/data/php-versions等则属于长期稳定的领域例外。修改白名单即修改 client/dashboard/.eslintrc.js任何新增都必须遵守注释中的告诫不要添加会引入 Calypso 代码/概念的例外。开发实践写出合规导入的检查清单结合上述规则在 Dashboard 内编写新代码时建议按以下顺序决策优先使用本地实现分析统计用client/dashboard/app/analytics的useAnalytics()路由重定向用dashboardRedirect卡片布局用client/dashboard/components/cardReact 原语直接从react导入其次使用白名单内的automattic/包数据层走automattic/api-coreautomattic/api-queries查询/变更定义遵循 packages/api-queries/README.md 的规范query 用queryOptions()、mutation 必须携带meta.statId且回调中只做缓存失效与更新再次考虑白名单内的calypso/库与资源仅限上述表格所列条目其余一律视为禁区新依赖若不在白名单即默认不可用需走 PR review 例外流程。值得补充的是依赖边界不只靠no-restricted-imports一条规则维系同一份 client/dashboard/.eslintrc.js 还通过tanstack/query/exhaustive-deps强制 mutation 依赖完整性、通过no-restricted-syntax禁止手写meta.snackbar避免覆盖 api-queries 工厂自带的meta.statId要求使用app/snackbars/with-snackbar这些规则共同构成了 Dashboard 新架构的防线。结语包导入限制是 wp-calypso Dashboard 架构治理的第一道闸门。它以 client/dashboard/docs/package-imports.md 为政策纲领、以 client/dashboard/.eslintrc.js 为强制手段通过前缀白名单 路径精细规则 PR 例外流程三层机制在复用automattic/生态价值的同时将旧 Calypso 的 Redux 状态、Context providers 与重 UI 隔离在新架构之外。对于任何在 Dashboard 内工作的开发者理解这张白名单的边界与例外机制是写出符合架构演进方向代码的前提。赞分享前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载相关推荐WordPress.com 站点 Dashboard 通知仲裁机制实战指南基于 wp-calypso 的 Single-Notice 不变量设计WordPress.com 站点 Dashboard 通知仲裁机制实战指南基于 wp calypso 的 Single Notice 不变量设计 导读 本文深前端CMSwp-calypso Tracks 事件埋点实践指南从 calypso-analytics 包到 Analytics Middleware 的完整接入方案wp calypso Tracks 事件埋点实践指南从 calypso analytics 包到 Analytics Middleware 的完整接入方案 本前端CMSwp-calypso 依赖安全告警治理Calypso Security Alerts Skill 扫描与分流操作指南wp calypso 依赖安全告警治理Calypso Security Alerts Skill 扫描与分流操作指南 导读 本文基于 wp calypso 仓前端CMS上一篇终极指南fpm处理依赖的艺术——解决包依赖冲突的5种高级方法下一篇Office-Tool本地化工具推荐提升效率的必备软件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考