W1 收官：架构守卫规则库 v0.1 全文公开
经过第一周（W1）对前端架构分层（Clean Architecture）、单向依赖流动原则、循环依赖危害以及规则灰度上线 SOP 的全方位建设，我们正式发布并开源公开团队内部沉淀的 前端架构守卫规则库 v0.1（Architecture Guard Rules v0.1） 完整配置。
很多团队之所以无法阻挡代码库向“屎山”退化，根本原因在于架构约束始终停留在“口头共识”或“PPT 架构图”上。一旦业务工期紧逼，没有被机器代码锁死的设计原则就会被轻易践踏。
本文全文公开基于 dependency-cruiser 构建的生产级配置文件 .dependency-cruiser.js，包含 10 条不可逾越的前端架构红线，可直接作为企业级 Vue 3 / React / Monorepo 工程的架构守卫底座。
架构拓扑分层契约总览
在我们的架构体系中，代码目录被严格定义为 4 个层级，依赖关系必须且只能由高层级向低层级单向流动：
┌─────────────────────────────────────────────────────────────┐
│ Layer 4: 业务应用与页面层 (apps/*, src/views/*, src/pages/*) │
└──────────────────────────────┬──────────────────────────────┘
│ (单向依赖)
▼
┌─────────────────────────────────────────────────────────────┐
│ Layer 3: 业务领域与状态层 (src/stores/*, src/services/*) │
└──────────────────────────────┬──────────────────────────────┘
│ (单向依赖)
▼
┌─────────────────────────────────────────────────────────────┐
│ Layer 2: 业务通用组件与 Composables (src/features/*, hooks) │
└──────────────────────────────┬──────────────────────────────┘
│ (单向依赖)
▼
┌─────────────────────────────────────────────────────────────┐
│ Layer 1: 纯公共基础设施层 (packages/components, utils, types)│
└─────────────────────────────────────────────────────────────┘
生产级规则库全文：.dependency-cruiser.js
/** @type {import('dependency-cruiser').IConfiguration} */
module.exports = {
forbidden: [
// =========================================================================
// 1. 核心分层守卫：底层基础设施严禁反向依赖上层业务 (Blocker)
// =========================================================================
{
name: 'arch-no-shared-to-business-leak',
comment: '【铁律 1】公共基础层 (components/utils/hooks) 严禁反向引用业务视图 (views) 或业务状态 (stores)',
severity: 'error',
from: {
path: '^src/(components|utils|hooks)/|^packages/(components|utils)/',
},
to: {
path: '^src/(views|pages|stores|services|features)/',
},
},
// =========================================================================
// 2. 领域隔离守卫：禁止跨业务页面视图相互引用 (Blocker)
// =========================================================================
{
name: 'arch-no-cross-view-coupling',
comment: '【铁律 2】业务视图之间严禁横向相互引用私有组件，跨域复用必须重构下沉至公共组件层',
severity: 'error',
from: {
path: '^src/views/([^/]+)/',
},
to: {
path: '^src/views/([^/]+)/',
pathNot: '^src/views/$1/', // 禁止引用除当前业务域以外的其他 views 目录
},
},
// =========================================================================
// 3. 循环依赖零容忍：彻底根治模块时序死锁 (Blocker)
// =========================================================================
{
name: 'arch-no-circular-dependencies',
comment: '【铁律 3】零容忍模块间循环依赖，防止运行时变量 undefined 与热更新失效',
severity: 'error',
from: {},
to: {
circular: true,
},
},
// =========================================================================
// 4. 单向数据流守卫：纯展示型 Dumb 组件禁止直接消费 Store (Warning)
// =========================================================================
{
name: 'arch-no-ui-component-direct-store',
comment: '【铁律 4】基础 UI 组件应为纯展示组件 (Dumb UI)，通过 Props 接收数据，严禁直接绑定全局 Store',
severity: 'warn',
from: {
path: '^src/components/',
},
to: {
path: '^src/stores/',
},
},
// =========================================================================
// 5. 门面模式封装守卫：禁止越过 index.ts 访问子包私有 internal (Blocker)
// =========================================================================
{
name: 'arch-no-deep-internal-imports',
comment: '【铁律 5】外部模块仅允许导入子模块公开导出的 index.ts，严禁穿透引用 internal/ 内部私有实现',
severity: 'error',
from: {
path: '^src/',
pathNot: '^src/features/([^/]+)/',
},
to: {
path: '^src/features/([^/]+)/internal/',
},
},
// =========================================================================
// 6. 淘汰库阻断守卫：严禁使用已被废弃或存在性能黑洞的依赖 (Blocker)
// =========================================================================
{
name: 'arch-no-deprecated-libraries',
comment: '【铁律 6】禁止使用 moment.js 或 lodash 全量顶级包，统一使用 dayjs 和 lodash-es',
severity: 'error',
from: {
path: '^src/',
},
to: {
path: '^(moment|lodash)$',
},
},
// =========================================================================
// 7. 测试代码隔离：生产源码严禁引用测试夹具与 Mock (Blocker)
// =========================================================================
{
name: 'arch-no-test-code-in-production',
comment: '【铁律 7】生产业务源码严禁引入 __tests__、*.spec.ts 或 mock/ 目录下的测试辅助代码',
severity: 'error',
from: {
path: '^src/',
pathNot: '(__tests__|\\.spec\\.|\\.test\\.)',
},
to: {
path: '(__tests__|fixtures|mock|vitest)',
},
},
// =========================================================================
// 8. 路由懒加载守卫：顶层路由入口禁止直接静态引用庞大视图 (Warning)
// =========================================================================
{
name: 'arch-require-dynamic-route-imports',
comment: '【铁律 8】路由配置文件中禁止静态 import 业务页面组件，必须使用动态 import() 保证路由级代码分割',
severity: 'warn',
from: {
path: '^src/router/routes\\.ts$',
},
to: {
path: '^src/views/',
// 标记为静态依赖时报警
dynamic: false,
},
},
// =========================================================================
// 9. Monorepo 边界守卫：底层 Package 禁止跨边界引用 App 源码 (Blocker)
// =========================================================================
{
name: 'arch-monorepo-subpackage-isolation',
comment: '【铁律 9】Monorepo 子包必须具备独立发布能力，严禁相对路径越界引用 apps/ 宿主源码',
severity: 'error',
from: {
path: '^packages/([^/]+)/',
},
to: {
path: '^apps/|\\.\\./\\.\\./apps/',
},
},
// =========================================================================
// 10. 全局状态隔离：Store 之间严禁双向交叉引用 (Blocker)
// =========================================================================
{
name: 'arch-no-circular-stores',
comment: '【铁律 10】Pinia / Zustand Store 之间严禁双向依赖，必须通过服务层或组件中转',
severity: 'error',
from: {
path: '^src/stores/use([^/]+)Store\\.ts$',
},
to: {
path: '^src/stores/use([^/]+)Store\\.ts$',
pathNot: '^src/stores/use$1Store\\.ts$',
circular: true,
},
},
],
// 基础配置选项
options: {
doNotFollow: {
path: 'node_modules',
},
tsPreCompilationDeps: true,
tsConfig: {
fileName: './tsconfig.json',
},
enhancedResolveOptions: {
exportsFields: ['exports'],
conditionNames: ['import', 'require', 'node', 'default'],
},
reporterOptions: {
dot: {
collapsePattern: 'node_modules/|src/views/[^/]+',
},
},
},
};
团队落地标准执行命令
在 package.json 中配置以下标准化脚本：
{
"scripts": {
"guard:check": "depcruise --config .dependency-cruiser.js src",
"guard:diff": "depcruise --config .dependency-cruiser.js --focus $(git diff --name-only origin/main | paste -sd '|' -) src",
"guard:graph": "depcruise --config .dependency-cruiser.js --output-type dot src | dot -T svg > architecture-topology.svg"
}
}
W1 收官寄语
第一周（9/1 ～ 9/6）共 60 篇深度专栏文章，我们完成了从 AI 规则定义、Schema 驱动界面、研发流插桩、火焰图解析、IDE 横评，到 React 并发切片、Vue3 响应式、Vite 预构建、渲染图层与架构守卫规则库的完整基建筑底。
在接下来的 第二周（W2：9/7 ～ 9/13） 中，我们将全面深入“误报分类学与治理实验、可访问性（a11y）自动验收、单测生成与变异测试、Suspense 深度数据流、Vite 插件实战开发以及 Flat Config 迁移”等深水区攻坚，敬请持续关注！
转载自 CSDN-专业IT技术社区
原文链接：https://blog.csdn.net/cannonmonster01/article/details/164426261
