前端架构设计实战：告别意大利面代码，构建可维护的中后台项目-代码聚汇网

前端架构设计实战：告别意大利面代码，构建可维护的中后台项目

前端架构意大利面代码分层架构

|难度：普通|阅读约 42 分钟

1. 为什么前端代码总写着写着就成了一团乱麻

先别急着聊架构设计，咱们先回忆一个场景：你接手一个做了两年的后台管理系统，打开项目仓库，src 下面密密麻麻铺了四十多个文件夹，有的叫 utils，有的叫 common，还有几个叫 utils2、new_utils。组件目录里一半是页面组件，一半是业务组件，还有几个不知道干什么用的“万能组件”，接收十来个 props，里面塞了七八个 if 分支。你试着改一个按钮的颜色，顺着 props 找了五层组件，最后发现样式写在一个全局 !important 里。

这种代码，前端圈有个很形象的称呼——意大利面代码。面条缠在一起，扯一根带出来一大坨。我说句得罪人的话：很多团队的技术债，不是欠在技术选型上，而是欠在架构的缺失上。

“前端架构设计”听起来是个特别大的词，好像只有大厂架构师才配聊。但实际上，它解决的就是一个特别朴素的问题：当代码量超过一个人脑容量能装下的范围之后，怎么让代码仍然保持可维护、可扩展、可替换。 我见过不少项目，功能都能跑，接口全通着，也没啥技术难点，但就是没人愿意改。原因很简单——改不动，一改就崩，一崩就加班。这种项目的通病，往往不是某段代码写得烂，而是整个项目的“骨架”就没立起来。

这篇文章不聊虚的。我会从“怎么识别意大利面代码”开始，讲清楚一套可以直接落到中后台项目和前端工程里的架构设计思路，包括分层、模块边界、状态治理、依赖规则这些实操内容，最后把我踩过的坑和排查问题的方法一并交代了。适合谁看？写前端两三年、开始负责模块拆分或项目重构的同学，以及团队里需要定前端规范的“半个架构师”。看完不说脱胎换骨，至少下次代码评审的时候，你能有理有据地指出问题，而不是只能憋出一句“这段代码写得有点乱”。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 先给项目做个“体检”：意大利面代码的五个典型症状

2.1 症状一：全局状态里什么都有，谁也说不清被谁改了

这是最典型、也最致命的症状。打开项目，Redux 或者 Pinia 的 store 里躺着二三十个字段，有用户信息、有表单数据、有列表筛选条件、有某个弹窗的开合状态，甚至还有上一次请求的时间戳。你去搜某个字段的所有引用，搜出来四十多处，分布在十几个组件里。

问题不在于全局状态里存了东西，而在于全局状态变成了一个“垃圾中转站”。任何组件想共享点数据，懒得抽公共逻辑，直接往 store 里一扔，完事。日子久了，store 里没有任何层级和职责划分，谁都能读，谁都能写，出了问题你想回滚都不知道改哪里。我在实际项目里见过最离谱的一次，一个“确认弹窗”的 visible 状态放在了全局 store 里，就为了两个兄弟组件通信方便——这就是典型的用全局状态掩盖组件通信设计缺失。

2.2 症状二：组件层级的“无底洞”和“深水炸弹”

展开组件树，一个页面组件下面套了五六层，每一层都只负责传递 props 和回调函数。最底层的子组件想通知最顶层的父组件一件事，所有中间层都得帮着把回调函数往下传一遍。传参链路长了，谁改了参数类型，到处报错，这是“无底洞”。

还有一种相反的情况，单个组件极其庞大，一个文件一千多行，里面既能发请求、又能校验表单、还能渲染表格、顺带处理下载。这种组件我管它叫“深水炸弹”——平时安静地躺在项目里，看着似乎没问题，一旦需求变化，你动一行代码，周边炸一片。

组件设计层面最大的误区，是把“组件复用率”当作最高目标。为了追求复用，把各种不相关的逻辑塞进同一个组件，靠一大堆条件分支来区分。结果就是复用了，但没人能看懂、没人敢改。组件设计的第一目标是职责清晰，其次才是复用。

2.3 症状三：循环依赖像一个八爪鱼，谁都在引用谁

用工具扫一下依赖关系图，你会发现模块之间的依赖关系不是树状的，而是网状的，甚至还有 A -> B -> C -> A 这种循环引用。Webpack 打包的时候喊半天警告，代码里 import 倒是没报错，但这是埋在项目里的定时炸弹。遇到循环依赖，初始化顺序一错，变量是 undefined，报错信息还特别难定位，因为报错位置和真正出问题的地方隔了十万八千里。

循环依赖是架构设计缺失最直观的体现。它说明模块边界是模糊的，谁也不知道自己应该处于哪一层、可以依赖谁。这时候你光靠“大家注意点”是没用的，得靠架构分层和工具约束来硬性解决。

2.4 症状四：公共代码是一个“大杂烩”，而不是“工具箱”

很多项目的 utils 目录就是个大杂烩。里面有格式化日期的，有防抖节流的，有解析 URL 参数的，有生成随机 ID 的，还有两个函数功能百分之八十重合的，一个叫 formatTime，一个叫 timeFormat。更离谱的是，居然是不同人各自封装、各自使用、各自维护的。

公共代码的问题不仅仅是重复，更是缺少演进机制。没人给公共函数做归类和文档，也没有测试用例，谁有需要就直接往里面加。等到公共函数出了问题，影响面是全局性的。我接过一个项目，改一个公共工具函数修 bug，结果因为好几个页面依赖了这个函数的“隐式行为”，修完一个 bug 带出来三个新 bug。从那以后我养成一个习惯：任何公共代码的修改，必须先看所有调用点。

2.5 症状五：没有分层概念，业务逻辑散落在各个角落

最典型的场景：一个列表页，请求数据的逻辑写在组件 useEffect 里，数据转换的逻辑写在渲染函数中间，用户权限的判断散落在三个工具函数里，提交表单的时候在组件里临时拼了一个复杂的 payload。整个项目从头到尾看不到“数据层”“业务层”“视图层”这样的概念边界。

分层不是架构师为了画图好看，而是为了让代码有明确的“居住地”。没有分层，业务逻辑就只能长在组件里，而组件是会反复重写的。今天用 Vue 写，明天换 React，如果你没有独立的业务逻辑层，整个项目等于推到重来。有分层，组件就只是个“壳”，核心业务逻辑放在独立的模块里，无论视图怎么换，底层能力都在。

3. 核心架构方案：三层架构加单向依赖，治本不治标

3.1 先立规矩：依赖方向必须是单向的

架构设计里的第一性原理，不是画分层图，而是确定依赖规则。我推荐的方案是经典的三层架构，额外加一条铁律——依赖只能从上往下，不允许反向依赖，不允许跨层依赖。

三层分别是：

视图层：页面组件、UI 组件，负责渲染和用户交互。
业务层：处理具体业务流程的逻辑，比如“提交订单时要先校验库存再调接口”“列表页加载时要组合三个接口的数据”。
基础设施层：请求库、存储工具、公共函数、第三方 SDK 的封装，这一层最稳定，谁都可以依赖它，但反过来它不允许依赖任何业务和视图内容。

这三层像什么？像公司的组织架构：老板定方向，经理做计划，员工干执行。员工不会跑去给老板安排活，经理也不会替员工写执行细节。代码分层也是这个道理，每一层有自己的职责，跨层干活就是越俎代庖。

注意：跨层依赖往往是项目腐化的起点。比如视图层直接调用基础设施层的本地存储工具，跳过了业务层，看起来省事了，实际上业务逻辑的完整性就没人保证了。将来要是改了存储方案，所有视图层组件都得跟着改，这是典型的架构失控。

3.2 把状态按“生命周期”拆开，而不是一锅炖在全局

刚才提到全局状态变成垃圾中转站是核心痛点。对应到架构设计上，需要对状态做一个分类处理，我习惯把它们分成四类：

状态类型	生命周期	存放位置	典型例子
服务端状态	与后端数据同步	专门的请求层/缓存层	用户列表、订单详情
全局客户端状态	整个应用存活期间	全局 store	登录信息、主题配置
局部组件状态	组件实例存活期间	组件内部	表单输入、下拉框开关
路由状态	与 URL 绑定	路由参数	查询条件、分页页码

这个表格看着简单，但绝大多数项目的问题就是对状态不做区分。表单数据明明属于局部组件状态，非要存到全局 store 里；服务端返回的数据，不走统一的数据请求层，每个组件自己 fetch 一份存到全局里，导致数据不统一、无缓存、重复请求。

我的实际经验是：**能放在组件里就绝不往全局放，能用路由参数表达的就绝不放在 store 里。**全局 store 应该像冰箱，只放需要长期保存的东西，不要把每天买的菜全堆进去。

3.3 模块边界怎么划？一个口诀——高内聚、低耦合、单向依赖

说起来容易做起来难。划分模块边界，我给一个可操作的判断标准：如果你能一句话说清楚这个模块是干嘛的，它大概率是个好模块；如果要说三句以上还绕，边界就没划对。

拿最常见的“用户”模块举例：一句话说清楚——“负责用户登录态和基础信息的存取”。那它就只负责这件事，跟用户相关的权限判断逻辑如果很复杂，单独拆一个“权限”模块，而不是一股脑塞进用户模块。模块之间有交互很正常，但交互要走明确的接口，不允许直接深入另一个模块的内部实现。

还有一个容易踩坑的地方：**不要为了切模块而切模块。**如果整个项目总共才两三个页面，硬拆出十几个业务模块，每个模块就一两个文件，这种“过度架构”比没有架构还恶心。模块的粒度应该跟随业务复杂度走，业务复杂了就拆细一点，业务简单就粗放一点，架构不是一次性定死的东西。

3.4 依赖规则要“硬约束”，不靠自觉，靠工具

人都有偷懒的时候，架构规则光写进文档里没用，得用工具在代码层面强制执行。我这里推荐两个最实用的手段：

第一，ESLint 的 import 规则。 配置 import/no-restricted-paths，明确限制哪些目录之间禁止互相引用。比如视图层不允许直接 import 基础设施层里某些不该暴露的模块，业务层不允许反向 import 视图层。配置完以后，有人写出了违规的跨层依赖，CI 直接报错，比什么文档都管用。

第二，依赖分析工具。 社区里有很多现成的工具，可以自动分析项目的依赖关系图，生成可视化结果。我习惯每周跑一次，看看有没有新增的循环依赖，及时处理掉。这个“硬约束”的思路很关键：架构设计如果没有工具兜底，就只是一张挂在墙上的图纸。

这里给一个 eslint 配置片段参考：

jsonc复制// .eslintrc.js 片段 -- 仅演示思路
module.exports = {
  rules: {
    "import/no-restricted-paths": ["error", {
      zones: [
        // 视图层不允许直接访问基础设施层和业务层之外的模块
        {
          target: "./src/views",
          from: "./src/services", 
          message: "视图层不允许直接访问 services，请通过业务层调用"
        },
        // 业务层不允许反向依赖视图层
        {
          target: "./src/business",
          from: "./src/views",
          message: "业务层不允许依赖视图层，必须保持单向依赖"
        }
      ]
    }]
  }
};

配置文件本身不复杂，关键是你在项目里真的去落地它。我在自己的项目里用这套方案之后，没过多久就拦下了十几个违规引用，省下的调试时间远比配置的时间多。

4. 实操过程：从零到一给一个中后台项目搭好架构

4.1 第一步：盘点现状，画一张“依赖关系图”

先把整个项目的代码盘一遍。我习惯用的方法是，先把所有 import 语句全部导出来，做一个简单的统计和关系整理。你不需要用什么高级工具，直接全局搜索 import ... from，梳理出模块之间的引用方向。当这份关系图画出来，问题往往一目了然：有几条依赖链是绕成环的，有几个“超级模块”被三十个文件引用，有几个组件引用了和自己完全无关的工具函数。

盘点的产出不是一份文档，而是你心里对现状的判断。我做完盘点之后都会先回答三个问题：

目前最痛的混乱点集中在哪个区域？是组件层、还是状态层、还是公共代码？
哪些模块的边界已经比较清晰，可以先保留，不需要大动干戈？
哪些模块必须立刻拆分或重构，优先级最高的三处是什么？

回答完这三个问题，你就有了一张“手术清单”，不要想一次性把整个项目重构完，那不现实，要按优先级逐步推进。

4.2 第二步：搭建目录骨架，给代码一个“归属地”

目录结构是架构设计的物理体现。我基于三层架构的原则，推荐一个标准的中后台项目目录模板：

code复制src/
├── views/            # 视图层：页面级组件，一个路由对应一个目录
│   └── user/
│       ├── user-list/
│       │   ├── index.vue
│       │   ├── use-list-state.ts    # 管理列表页的局部状态
│       │   └── user-list.scss
├── business/         # 业务层：核心业务流程逻辑
│   ├── user/
│   │   ├── login-service.ts
│   │   ├── user-repository.ts
│   │   └── types.ts
│   └── order/
├── services/         # 基础设施层的服务封装：API 请求、WebSocket 等
│   ├── http-client.ts
│   ├── user-api.ts
│   └── order-api.ts
├── common/           # 基础设施层通用工具
│   ├── utils/
│   ├── hooks/
│   └── constants/
├── store/            # 全局 store（仅放全局客户端状态）
│   ├── modules/
│   └── index.ts
└── shared/           # 跨模块共享类型定义、枚举等

这里要解释一下为什么是这种结构：views 里的组件只负责把数据渲染出来和把用户动作传给 business 层。business 层不关心页面长什么样，它只负责业务流程的编排。services 里的 API 封装只管通信，不关心业务规则。common 是纯工具库，谁都可以依赖。store 是全局状态的家，但只有真正需要全局共享的东西才放进来。

这样的目录结构有一个巨大的好处：新人入职之后，看一眼目录就知道自己写的代码应该放哪里，不需要问别人。 代码有归属地，就不容易长乱。

4.3 第三步：核心实现——怎么把业务逻辑“抽”到 business 层

很多同学问：业务逻辑抽离到底抽什么？我这里用最常见的“登录”功能做个完整示例。不看视图层的代码，先看 business 层的实现思路：

typescript复制// src/business/user/login-service.ts
// 注意：这一层完全不知道 Vue 或 React 的存在
import { httpClient } from '@/services/http-client';
import { userRepository } from '@/business/user/user-repository';
import type { LoginParams, LoginResult } from '@/business/user/types';

export async function login(params: LoginParams): Promise<LoginResult> {
  // 步骤一：基础格式校验（业务规则）
  if (!params.account || !params.password) {
    throw new Error('账号和密码不能为空');
  }
  
  // 步骤二：调用基础设施层发送请求
  const { token, userInfo } = await httpClient.post('/auth/login', params);
  
  // 步骤三：持久化会话信息（调用自己模块的仓储函数）
  userRepository.saveSession({ token, userInfo });
  
  // 步骤四：返回标准化结果给视图层
  return { token, userInfo };
}

对应的视图层组件就简单了：

tsx复制// views/login/index.tsx（React 示例如是 Vue 也同理）
import { login } from '@/business/user/login-service';

async function handleSubmit(values: FormValues) {
  const { token, userInfo } = await login(values);
  message.success(`欢迎回来，${userInfo.nickname}`);
}

你发现区别了吗？原来写在组件里的整个登录流程，变成了一个 business 层的纯函数调用。 组件只负责“收集用户输入”和“展示结果提示”，中间的流程不归组件管。以后登录逻辑变了，比如要加个验证码、加一步缓存 token 后跳转，你只需要改 login-service.ts，组件代码一行都不动。

这里面有一个关键细节：userRepository.saveSession 这一层封装。为什么要抽出 repository？因为“保存会话”的具体实现可能用 localStorage、可能用 cookie、可能存 SessionStorage，也可能以后改成拿到内存里。如果视图层直接调用 localStorage.setItem，以后换存储方案又得满项目改。抽一个 repository 层包起来，业务层只关心“保存会话”这个动作，不关心存到哪儿。

这个思想就是所谓的“依赖倒置”——高层模块不依赖底层模块的具体实现，而是依赖抽象。 虽然这个例子里 service 直接 import 了 repository，但它们之间是同一模块的上下位关系，实现上已经做了隔离，而不是让底层实现散落在各个组件里。

4.4 第四步：状态管理的落地策略——全局 store 怎么瘦身

状态处理是架构落地的重点难点。我给自己定了一个执行策略，照着这个策略执行，基本不会乱：

第一优先级——URL。 和页面上下文有关的参数，能放 URL 就放 URL，比如列表的筛选条件、分页页码，用户刷新浏览器后还能保留状态，天然不占内存。

第二优先级——组件局部状态。 后端数据请求之后，如果数据只在这个组件用，直接放在组件内部管理即可，配合请求层做缓存。不要为了“方便其他组件以后用”而提前存全局。

第三优先级——业务层返回结果。 组件通过调用 business 层拿到数据，数据可以短暂保存在服务端状态的缓存里。

最后一级——全局 store。 只有在多个无直接血亲关系的组件之间需要共享实时状态，且这个状态会影响整个应用的渲染时，才放入全局 store。典型例子：用户登录信息、主题色配置、权限列表。

我可以拍胸脯说：80% 的项目把全局 store 里删掉一半字段，代码质量会肉眼可见提升。因为状态被“本地化”之后，每个组件的自洽性更强，读代码的时候不需要在十几个文件里来回跳。

4.5 第五步：组件设计规范——从“万能组件”回归“单一职责”

组件层面，我总结三个原则，每一个都是从惨痛经验里挤出来的：

原则一：组件只做展示和交互，不做业务逻辑。 表格组件只负责渲染表格和处理点击事件，不负责数据过滤和权限判断。数据什么时候加载、怎么转换，那是 business 层的事。

原则二：组件之间通信，优先 props 和事件，其次插槽，最后才是全局状态。 props 把数据传下去，事件把动作传上来，这个“数据单向流”是组件设计的基础体操。很多同学喜欢用全局事件总线或者 store 来做组件间通信，觉得省事，实际上把组件的输入输出关系搞模糊了，代码特别难调试。

原则三：复杂组件内部也要分层。 如果一个组件确实负责很复杂的事情（比如一个编辑器型组件），那就把组件内部拆成子组件和 hooks。页面组件用 hooks 管理内部状态逻辑，子组件专注渲染。这种“组件内部的分层”很容易被忽视，但它是保持组件文件不膨胀的最后一道防线。

给一个 hooks 拆分的示例思路：

typescript复制// views/order/order-list/use-order-list.ts
// 把所有列表页的状态与操作完美收敛，组件里只剩一行调用
import { useEffect } from 'react';
import { getOrderList } from '@/business/order/order-service';

export function useOrderList(query) {
  const [loading, setLoading] = useState(false);
  const [list, setList] = useState([]);
  
  async function loadOrderList() {
    setLoading(true);
    try {
      const res = await getOrderList(query);
      setList(res);
    } finally {
      setLoading(false);
    }
  }
  
  useEffect(() => {
    loadOrderList();
  }, [JSON.stringify(query)]);
  
  return { loading, list, reload: loadOrderList };
}

组件里这样用：

tsx复制function OrderListPage() {
  const { loading, list, reload } = useOrderList(query);
  if (loading) return <Loading />;
  return <OrderTable data={list} onReload={reload} />;
}

文件小、职责单一、易读、易测，这就是组件拆分追求的效果。

5. 常见问题与排查技巧实录：架构落地时的那些“坑”

5.1 问题一：架构规规矩矩，跑个需求发现绕远路了怎么办

这个情况太常见了。比如你按三层架构分了，结果有个小需求只是想在页面上调一个接口、显示一个值，业务层绕了一圈还要写一个 service 方法。这时候团队里就开始有人质疑：这不就是多此一举吗？直接视图层调 API 不香吗？

我的观点是：架构规范要管住“大方向”，允许一定程度的“现场灵活性”，但要有底线。 底线是什么？底线是业务逻辑不写到组件里、数据请求不走基础设施层以外的通道。至于业务层是不是每个接口都要包一层 service，可以根据场景适当简化。比如只读操作，可以直接由视图层调 services 层的 API 方法，不需要经过业务层组装。但如果涉及多步逻辑、涉及状态变更，就必须走 business 层。

这个策略我管它叫“分层粒度弹性化”。架构不是教条，是服务业务的工具。但有一点千万不能弹性：依赖方向。视图层可以调 services，但 services 绝不能反过来依赖视图层，这个红线踩一次，架构就开始崩。

5.2 问题二：老项目重构，不敢动，怎么办

接手一个老项目，满眼都是意大利面，想重构又怕删错了代码上线出事故。我的实操建议是分几步走：

第一步，加“体检报告”。 先把循环依赖、超级模块、重复代码这些清单列出来，不急着改，先把问题量化，让所有人都知道现在长什么样。

第二步，新老共存。 新增代码一律按新架构规范写，老代码先不动。在项目里划一个“隔离区”，老代码目录不动，新功能尽量使用新目录，慢慢形成“新旧清晰”的格局。我见过太多人上来就想把老代码全部重写，结果传统艺能就是推翻重来，紧接着就是返工重写再返工。

第三步，按依赖关系“抽丝剥茧”。 重构老代码的时候，按依赖关系从底层往上拆。先拆公共工具层，再拆业务层，最后再动视图层。因为底层拆完了，上层依赖根基稳了，上层才敢动。千万不能一上来就重写页面组件，那等于在流动的河床上打桩。

第四步，每拆一层就跑一次全量回归测试。 没有测试的老项目，先补关键链路的冒烟测试，再动刀。改架构的过程里，测试是你唯一的安全绳。

5.3 问题三：写了架构文档，但团队没人按这个来

很多“架构设计”，最后死于没人执行。我自己的体会是：光有文档没有工具约束，架构就是空中楼阁。 前面提的 ESLint 规则、依赖分析工具就是第一道锁。除此之外，还要把架构规范嵌到 Code Review 的检查项里，每次 MR 先让机器人跑一下依赖分析脚本，有违规直接拦截。

还有一个容易被忽视的点：架构规范要足够“傻瓜”。 我刚定架构规范的时候，写了四十多页文档，结果团队里没几个人看。后来改成了一张 A4 纸，只写什么代码放什么目录、依赖方向是什么、禁止哪些写法，加上用例代码，反而大家都能遵守了。架构规范文档不是毕业论文，越短越好执行，越贴近代码越好落地。

5.4 问题四：用了这套架构之后，开发速度反而慢了

这是最容易被 immediately 否定的问题。新架构必然引入额外的抽象层，初期开发效率下降是正常的，但如果你持续观察到严重减速，很可能是善意的架构被用歪了。常见歪法：

每个简单接口都套 service + repository + 类型定义，四层文件就为了查一个下拉框数据。
business 层过度设计，方法拆分得太细，一个登录功能拆了七八个函数，其实根本没有复用点。
为“未来的需求”预留抽象，现在根本用不上的接口加了一层又一层。

我建议的简单方法是：业务层的方法至少要被两个地方用到，才值得拆出来做独立函数；一个模块的文件数量，如果三个页面以内撑不起十个文件，就该考虑合并。 要充分认识到，写得烂的新代码、和过度抽象的新代码，对团队的伤害是同级别的。架构服务于团队当前的真实复杂度，而不是服务于想象中的复杂度。

5.5 问题五：多团队共建一个前端应用，怎么避免互相打架

这个场景下，传统的目录分层就不够了，还需要做“模块隔离”。核心思路是：每个业务团队拥有自己的模块目录，模块之间通过对外暴露的接口通信，不允许直接 import 对方的模块内部代码。为了硬性约束，你可以在 ESLint 里配置 no-restricted-imports，把每个模块的对外出口收窄成有限的几个索引文件。这样，团队 A 改了内部实现，团队 B 只要不依赖那点“内部怪癖”，就不会有问题。

这个方案和小型项目里的“业务层”其实是一个思想，只是规模放大了一些。小项目里是“文件和目录”的边界，大项目里是“包和模块”的边界。

6. 工具链选型与落地经验：接近零成本让架构“跑起来”

架构落地离不开工具。我结合自己的实践，给一套低成本落地的组合拳。

6.1 ESLint 不只是查代码风格，更是架构约束的“哨兵”

前面已经提到过 import/no-restricted-paths，这里再推荐两个规则：

import/no-cycle：检测循环依赖，开起来之后项目里所有循环依赖都会被标红，这是治理依赖混乱最直接的一招。
boundaries/elements：来自 eslint-plugin-boundaries 插件，可以让我们定义模块之间的依赖规则，比 no-restricted-paths 更灵活，支持正则匹配目录模式。

放了这两条规则之后，CI 里加一步 npm run lint，有违规就不允许合并。这是架构规范真正开始生效的瞬间。

6.2 依赖分析脚本，治理依赖关系的“体检仪”

我习惯在每个项目里放一个脚本，定期审视全局依赖情况。手动写一个全天候的依赖分析工具当然不现实，但可以定期跑：

bash复制npx madge --circular --extensions ts,tsx src/

madge 这个工具可以快速扫描循环依赖，输出可视化的依赖图，把结果生成一个 dependency-graph.html，我可以定期打开看看模块之间的依赖关系有没有恶化。另外一个比较好用的思考是，当你看到依赖图里某个节点被一圈节点围着、出入度都极高，它就是架构里的“巨型上帝类”，下一步的重构重点就该指向那。

6.3 不要一上来就上重型微前端方案

很多团队一聊到前端架构设计，就想着要不要搞微前端。我的意见非常务实：项目代码量没有到几千个页面、团队没有到几十人、业务没有到需要独立发版的程度，不要上微前端。 微前端解决的是组织协作和独立部署问题，它不解决意大利面代码的问题——相反，如果你连一个应用内部的分层都做不好，拆分出再多的“微应用”也只是把一坨意大利面分装到几个盘子里。

先把单体应用的分层、模块边界、依赖规则做好，这比任何“玄幻架构词汇”都重要。

6.4 一个真正轻量、上手快的落地顺序建议

如果你现在正面对一个“还能跑但不敢动”的项目，这是我推荐的落地顺序，从第 1 条到第 5 条逐步推进，收益最高：

加 no-cycle 和 import/no-restricted-paths 规则，先把循环依赖清理掉。
建立 business 和 shared 目录，新需求一律走新目录，老代码先躺着。
找到最大的那个“万能组件”，把它拆分成 3-5 个单一职责组件。
清点全局 store，把属于局部的状态搬回组件，给全局 store 瘦身。
补关键链路的测试，尤其是业务层的和依赖关系紧密的服务层测试。

这套流程每步都能形成可验证的产出，而且不至于让团队陷入“重构一个月没有需求”的焦虑里。

7. 实操心得：架构设计里最容易被忽视的三件事

文章快结尾了，我不打算做那种“总结全文核心观点”的收尾，就讲三件我在实际项目里体会最深的小事，当是送给打算开始梳理架构的同学的几个私人提醒。

第一件事：架构设计是“公共 APIs 的设计”，不是“文件夹结构的设计”。 文件夹结构只是表象，真正重要的是模块暴露给外界的接口（functions/classes/components）是否清楚、是否稳定。我把一个模块的对外 API 设计比作“店面门脸”，内部怎么装修随便你折腾，但门口挂的招牌和菜单不能天天变。你改了内部实现，调用方完全无感，这才是好架构。文件夹画得再好看，如果模块之间还是在互相扒衣服看内部实现，那也只是表面功夫。

第二件事：一定要容忍“脏代码”的阶段性存在。 我见过太多有洁癖的工程师，一看到不符合规范的代码就想立刻重写，最后把整个迭代节奏拖垮，还搞得团队关系紧张。重构和架构治理不是一次性工程，它应该像日常刷牙一样持续进行。你不需要一天刷完全口牙，每天刷一小块区域就好。阶段性地容许一部分“老代码”继续存在，同时确保新增代码不再变脏，这是最现实、最可持续的推进方式。

第三件事：架构设计的终点是“让新人也能顺利地改代码”。 我们自己写的代码当然怎么看怎么顺眼，但衡量架构好坏的最终标准，是找一个刚入职两周的同事，给他一个小需求，看他能不能在不求助任何人的情况下，找到该改哪个文件、该写哪几行代码。如果能，说明你的架构设计让人在一个陌生的代码库里也能依靠“结构和规矩”找到方向；如果不能，就算你用了再漂亮的技术栈，架构也是失败的。

前端架构设计不是什么高深莫测的玄学，它就是把代码的“居住规则”定好，让每一行代码都待在该待的地方，让后来的人不必在意大利面里翻找那一根肉丸。希望你读完这篇文章，对手里的项目有了新的审视角度——下次打开代码仓库，先别急着写业务，花一点时间立好骨架、划好边界，后面的一百个需求都会因此顺畅很多。