从代码组织到功能抽象:AI 时代的前端工程架构设计

第二部分 · 架构设计

从代码组织到功能抽象:AI 时代的前端工程架构设计

一、为什么需要关注前端项目内部架构?

在实际项目开发中,我们经常会遇到这样的情况:

随着业务功能不断增加,最初简单的项目目录逐渐变得复杂。CSS 样式不断堆积,JS 文件职责越来越模糊,公共组件和业务组件混在一起,第三方组件库的使用方式也逐渐不统一。

与此同时,项目还可能出现:

  • 不同页面之间存在大量重复代码。
  • 全局样式与局部样式相互污染。
  • 请求、响应拦截和接口调用缺乏统一管理。
  • 路由配置和页面文件之间缺少明确关系。
  • 第三方 SDK 重复初始化,资源释放不完整。
  • 不同环境的路径、代理和配置难以统一。
  • 项目打包产物越来越大,页面首次加载缓慢。
  • 不同浏览器和屏幕分辨率下出现布局兼容问题。

这些问题看起来比较分散,但实际上都与前端项目内部的工程组织和架构设计有关。

我认为,前端架构设计并不一定要从大型系统拆分、微前端或者复杂的技术体系开始。

对于实际研发人员而言,项目内部的文件组织、代码封装、样式管理、功能抽象、资源管理和构建优化,同样是非常重要的架构能力。

架构设计的目的,不是让项目拥有更多目录和抽象层,而是让代码更容易理解、功能更容易复用、问题更容易定位,并且能够持续维护和演进。

二、项目目录与文件组织设计

目录结构是整个前端项目的基础。

一个合理的目录结构,不仅需要区分文件类型,还需要考虑文件之间的职责关系和归属关系。

例如:

csharp 复制代码
src/
├── api/                  # 请求与接口管理
├── assets/               # 静态资源
├── components/           # 全局公共组件
├── composables/          # 公共组合式逻辑
├── config/               # 项目统一配置
├── hooks/                # 公共 Hooks
├── layouts/              # 页面布局
├── modules/              # 业务模块
├── router/               # 路由管理
├── services/             # 第三方服务与 SDK
├── store/                # 全局状态
├── styles/               # 全局样式
├── utils/                # 公共工具函数
├── App.vue
└── main.ts

public/                   # 公共静态资源

这里可以采用两种组织方式:

按照文件类型组织: 例如统一管理 CSS、JS、工具函数和公共组件。

按照业务模块组织: 例如设备管理、用户管理、项目管理等模块,将各自的页面、组件、接口和业务逻辑放在对应目录中。

对于中大型项目,我更倾向于两者结合。

全局通用能力统一管理,业务内部功能尽可能就近组织。

这样既方便公共能力复用,也能避免业务代码过度分散。

三、JavaScript / TypeScript 文件管理

JS 和 TS 是前端项目最核心的逻辑载体。

随着项目发展,文件管理需要从简单的代码堆积,逐渐转变为按照职责组织。

需要重点考虑:

  • 页面逻辑与业务逻辑是否需要分离?
  • 公共方法与业务方法如何区分?
  • 一个模块是否需要独立的入口文件?
  • 如何管理模块之间的导入和导出?
  • 如何避免循环依赖?
  • 如何控制单个文件的职责范围?
  • 如何通过 TypeScript 统一数据结构和接口定义?

例如,一个设备管理模块可以按照以下方式组织:

markdown 复制代码
modules/
└── device/
    ├── pages/
    ├── components/
    ├── hooks/
    ├── api/
    ├── utils/
    ├── types/
    └── index.ts

页面负责业务展示和交互,API 负责接口通信,Hooks 负责可复用的响应式逻辑,Utils 负责纯函数处理,Types 负责数据结构定义。

文件拆分的目的,是让职责更清晰,而不是增加目录层级。

四、CSS 工程化与样式管理

CSS 在小型项目中可能不是一个明显的问题,但在长期迭代的项目中,样式管理往往会成为维护成本较高的部分。

例如:

  • 全局样式不断增加。
  • 不同页面出现重复 CSS。
  • 同一个组件存在多处样式覆盖。
  • 第三方组件样式修改影响其他页面。
  • 不同开发人员的命名方式不一致。
  • 主题切换时需要修改大量样式。

因此,需要建立合理的 CSS 文件管理体系。

例如:

css 复制代码
styles/
├── index.scss
├── reset.scss
├── variables.scss
├── mixins.scss
├── common.scss
├── themes/
│   ├── light.scss
│   └── dark.scss
└── modules/
    ├── layout.scss
    └── animation.scss

可以将 CSS 划分为几个层次:

  1. 基础样式:浏览器默认样式重置、字体等。
  2. 全局样式:全局通用的布局和辅助样式。
  3. 设计变量:颜色、间距、字体、边框等。
  4. 主题样式:不同主题下的变量配置。
  5. 组件样式:跟随组件自身管理。
  6. 页面样式:只服务于特定业务页面。

同时,可以根据项目技术栈使用 SCSS、Less、CSS Variables 等方式提高样式组织能力。

五、CSS 样式隔离与作用域管理

样式隔离是组件化开发中非常重要的一部分。

尤其是在多人协作和大型项目中,不同页面、不同组件之间可能存在相同的 CSS 类名,导致样式互相覆盖。

常见方式包括:

  • Vue Scoped:限制组件内部样式选择器的作用范围。
  • CSS Modules:通过构建阶段生成局部唯一的类名。
  • BEM:通过 Block、Element、Modifier 建立明确的命名规范。
  • Shadow DOM:利用浏览器原生能力实现更强的 DOM 和样式封装。

不同方式具有不同的使用场景,并不是隔离程度越高越好。

实际项目还需要考虑第三方组件样式覆盖、动态组件、Teleport、全局主题变量以及组件之间必要的样式共享。

样式隔离的核心目标,是让组件尽可能独立,同时保留必要的样式扩展能力。

六、第三方组件库二次封装

实际开发中,我们经常使用 Element Plus、Ant Design 等第三方组件库。

但是直接在所有业务页面中使用原始组件,长期来看可能产生一些问题:

  • 不同页面使用的组件属性不一致。
  • 表格、弹窗、表单的交互规范不统一。
  • 某些业务需要重复处理相同逻辑。
  • 组件库升级时,修改范围难以控制。
  • 不同开发人员对组件的使用习惯存在差异。

因此,可以根据项目实际情况建立自己的组件封装层。

例如:

csharp 复制代码
components/
├── base/
│   ├── BaseButton.vue
│   ├── BaseDialog.vue
│   ├── BaseTable.vue
│   └── BaseForm.vue
├── business/
│   ├── UserSelector.vue
│   ├── DeviceSelector.vue
│   └── OrganizationTree.vue
└── index.ts

这里需要区分:

  • 基础组件:统一第三方组件的使用规范。
  • 业务组件:封装具有明确业务含义的功能。
  • 功能组件:封装视频播放、文件上传、地图展示等独立能力。

二次封装需要特别注意,不要把第三方组件原本的能力全部重新实现。

例如,封装 Table 时,可以统一分页、加载状态和常用属性,但仍然应该保留必要的插槽、事件和属性透传能力。

封装的目的是降低重复开发成本,而不是制造新的使用门槛。

七、工具函数与公共逻辑抽象

项目中经常会出现一些重复逻辑。

例如日期格式化、数据转换、文件下载、数据校验、权限判断等。

这些功能可以根据使用范围进行合理抽象。

需要区分:

  • 公共工具函数:独立、通用,尽量保持无副作用。
  • 业务工具函数:只服务于特定业务。
  • Hooks / Composables:封装响应式状态和可复用逻辑。
  • Services:负责外部服务、SDK 和网络通信等能力。

不要将所有代码都放进 Utils。

一个合理的抽象应该具有明确的使用场景,而不是仅仅因为某段代码比较长,就将其单独封装。

八、路由与页面组织设计

路由是前端应用的重要入口。

随着业务页面增加,直接在一个文件中维护所有路由配置,会逐渐增加维护难度。

可以按照业务模块拆分:

markdown 复制代码
router/
├── index.ts
├── routes.ts
├── guards.ts
└── modules/
    ├── user.ts
    ├── device.ts
    └── project.ts

需要考虑:

  • 路由与业务模块如何对应?
  • 页面组件如何动态加载?
  • 路由元信息如何管理?
  • 菜单与路由如何关联?
  • 登录状态与路由守卫如何配合?
  • 动态路由如何注册和清理?
  • 页面缓存如何控制?

路由设计不仅是页面跳转管理,也需要考虑页面生命周期和业务模块之间的关系。

九、请求与响应统一管理

请求封装不应该只是简单地创建一个 Axios 实例。

可以将请求基础能力集中管理:

markdown 复制代码
api/
├── request.ts
├── interceptors.ts
├── types.ts
└── modules/
    ├── user.ts
    ├── device.ts
    └── project.ts

统一处理:

  • 请求基础地址。
  • 请求超时。
  • Token 携带。
  • 请求头配置。
  • 请求参数处理。
  • 响应数据解析。
  • 统一错误处理。
  • Token 过期处理。
  • 请求取消与重复请求控制。

不同业务模块只需要维护自己的接口定义。

这样既能保证请求规范统一,也能避免页面直接承担大量网络通信逻辑。

十、登录入口与单点登录设计

这里需要区分登录页面、身份认证和业务接口鉴权。

前端主要负责登录流程交互、认证跳转、认证结果接收,以及后续请求凭证的管理。

可以将认证相关逻辑独立组织:

复制代码
auth/
├── index.ts
├── login.ts
├── callback.ts
├── token.ts
└── guards.ts

需要考虑:

  • 是否存在独立登录页面?
  • 是否接入第三方统一身份认证平台?
  • 是否采用 OAuth 2.0 / OpenID Connect 等认证协议?
  • 登录回调如何处理?
  • Token 如何保存和刷新?
  • 登录状态如何与路由守卫结合?
  • 登出后如何清理用户状态?

单点登录并不是简单地在请求拦截器中携带 Token。

认证协议、身份校验和授权通常由身份认证服务及后端共同完成,前端负责相应的流程接入。

十一、全局状态与数据管理

随着业务复杂度增加,数据管理也需要统一规划。

例如:

  • 页面自身的数据如何管理?
  • 多个页面共享的数据放在哪里?
  • 用户信息、权限信息如何维护?
  • WebSocket 实时数据如何分发?
  • 页面切换时哪些数据需要保留?

可以按照数据使用范围和生命周期划分:

  • 组件状态。
  • 页面状态。
  • 模块状态。
  • 全局状态。
  • 实时业务数据。

不同数据不应该全部放进一个全局状态管理工具。

尤其是高频实时数据,需要考虑更新频率、订阅关系、缓存策略和渲染节奏。

十二、WebSocket 与实时通信管理

对于涉及设备监控、地图展示、实时视频和数字孪生的项目,WebSocket 往往是重要的数据来源。

如果每个业务页面都独立创建 WebSocket 连接,可能导致连接重复、消息重复处理和资源释放不完整。

可以建立统一通信管理层:

markdown 复制代码
services/
└── websocket/
    ├── manager.ts
    ├── connection.ts
    ├── events.ts
    └── types.ts

重点考虑:

  • 连接建立与断开。
  • 心跳与断线重连。
  • 消息类型分发。
  • 多业务模块订阅。
  • 消息数据格式统一。
  • 页面切换时的订阅清理。
  • 高频消息的缓存和节流处理。

对于大量实时数据,还需要考虑 Worker、数据序列化和渲染调度等问题。

十三、第三方 SDK 与功能服务封装

随着前端功能不断丰富,项目中接入的第三方 SDK 也越来越多。

例如:

  • Cesium、Three.js 等三维渲染库。
  • ECharts 等数据可视化库。
  • WebRTC、视频播放器。
  • 地图 SDK。
  • 第三方文件预览和编辑工具。

这些 SDK 不应该简单地在每个页面中重复初始化。

可以根据实际情况建立统一的加载与服务管理机制。

重点关注:

  • SDK 加载时机。
  • 实例创建和复用。
  • 多页面之间的资源共享。
  • 页面离开时的资源释放。
  • SDK 版本与依赖管理。
  • 第三方资源的本地化部署和代理。

尤其对于 Cesium、Three.js 等具有复杂生命周期的工具,还应该将初始化、运行和销毁纳入模块设计。

十四、静态资源与主题管理

静态资源需要区分不同用途。

例如:

  • 项目 Logo、页面图片。
  • SVG 图标。
  • 字体文件。
  • 第三方资源文件。
  • 运行时动态加载的资源。

需要理解 src/assets 与 public 的区别。

前者通常参与构建处理,可以进行模块引用和资源优化;后者适合需要保持固定路径、无需构建处理的静态文件。

主题管理则可以通过 CSS Variables 建立统一的变量体系:

css 复制代码
:root {
  --primary-color: #1677ff;
  --background-color: #ffffff;
  --text-color: #333333;
}

[data-theme="dark"] {
  --primary-color: #409eff;
  --background-color: #141414;
  --text-color: #ffffff;
}

将颜色、字体、间距、边框等设计变量统一管理,减少样式散落在各个组件中的情况。

十五、环境配置与路径代理设计

项目通常存在开发、测试、生产等不同环境。

需要统一管理:

  • API 服务地址。
  • WebSocket 服务地址。
  • 第三方 SDK 地址。
  • 静态资源路径。
  • 环境标识。
  • 不同环境下的功能开关。

例如:

复制代码
.env.development
.env.test
.env.production

开发阶段可以通过 Vite Proxy 或其他开发服务器代理,将前端请求转发到后端服务。

生产环境则可以通过 Nginx 反向代理、网关或专门的资源服务进行转发。

还需要考虑:

  • 跨域问题。
  • 第三方接口访问限制。
  • 内网部署环境。
  • 第三方 SDK 的资源加载。
  • 前端路由 History 模式的回退配置。

需要明确,前端开发代理主要用于开发环境,不能替代生产环境的服务端代理,也不能将密钥等敏感信息放在前端配置中。

十六、前端设计模式与代码抽象

设计模式是前端架构设计中值得深入研究的内容。

它并不是为了让代码看起来更加高级,而是帮助我们解决重复逻辑、复杂判断和模块依赖等问题。

例如:

设计模式 前端实际应用
工厂模式 动态创建不同类型的组件或实例
策略模式 不同业务类型采用不同处理逻辑
观察者模式 事件监听与状态变化通知
发布订阅模式 WebSocket 消息分发
适配器模式 第三方 SDK 与接口数据适配
单例模式 全局服务实例管理
装饰器模式 功能增强与行为扩展
组合模式 菜单、表单、树形组件组织
代理模式 请求代理与对象访问控制

这些模式并不是需要全部使用。

例如,多个业务页面存在相似的条件判断,可以考虑策略模式;不同第三方 SDK 提供相同功能但接口不一致,可以考虑适配器模式。

真正需要掌握的是:

什么时候需要使用设计模式?它解决了什么问题?引入之后又增加了哪些复杂度?

设计模式应该是解决问题的手段,而不是开发任务本身。

十七、前端构建与打包优化

前端项目最终需要经过构建,才能部署到实际运行环境。

随着项目依赖和功能不断增加,打包产物可能越来越大,页面首次加载速度也会受到影响。

因此,构建优化也是前端工程架构的重要组成部分。

需要重点考虑:

1. 构建工具与构建流程

理解 Vite、Webpack 等构建工具的基本工作机制,明确开发环境和生产环境的构建差异。

2. 代码分割

利用动态 import、路由懒加载等方式,将不需要立即执行的代码拆分出来,避免所有业务代码集中在一个入口文件中。

3. Tree Shaking

通过静态分析消除未使用的代码,减少最终构建产物。

4. 第三方依赖优化

分析大型依赖库,合理使用按需加载、依赖去重和组件级引入。

5. 静态资源优化

对图片、字体、CSS、JS 等资源进行压缩和合理处理。

6. 缓存与 CDN

利用文件 Hash、浏览器缓存和 CDN 等方式减少重复下载,提高资源访问效率。

7. 构建产物分析

使用 Bundle Analyzer 等工具分析打包体积,定位体积较大的依赖和重复资源。

8. 多环境构建

统一开发、测试和生产环境的构建配置,避免环境差异造成部署问题。

这里还需要注意,打包优化并不等于一味追求文件体积最小。

过度拆分也可能产生大量网络请求,第三方依赖外置也可能带来版本和加载风险。

真正的优化应该结合实际运行环境,综合考虑资源体积、加载速度、缓存效率和运行性能。

十八、页面兼容与多端适配设计

前端项目最终运行在浏览器和各种显示设备中。

即使代码本身没有问题,也可能因为浏览器差异、屏幕尺寸、分辨率和运行环境不同,出现页面布局异常或功能不兼容。

因此,兼容与适配也应该纳入工程设计。

1. 浏览器兼容

考虑 Chrome、Firefox、Safari、Edge 等浏览器之间的差异,以及国产浏览器、内嵌 WebView 等特殊环境。

重点关注 CSS 特性支持、JavaScript 语法兼容和浏览器 API 差异。

2. JavaScript 兼容

通过构建工具进行语法降级,结合实际目标浏览器配置 Babel、Polyfill 等兼容方案。

需要注意,语法转换和 API 兼容是两个不同的问题。

3. CSS 兼容

考虑 Flex、Grid、定位、滚动条、字体渲染等不同浏览器中的表现差异。

4. 屏幕尺寸适配

针对 PC、平板和移动端采用响应式布局,合理使用媒体查询、Flex、Grid、rem、vw 等技术。

5. 多分辨率适配

针对 1080P、2K、4K 和不同宽高比的显示设备,处理页面布局、字体、图片和组件尺寸。

6. 大屏可视化适配

对于数字孪生和数据可视化项目,还需要考虑:

  • Cesium 容器尺寸变化后的画布调整。
  • ECharts 窗口变化后的重新布局。
  • 视频播放器的比例和分辨率适配。
  • 大屏页面在不同显示比例下的布局。
  • 浏览器缩放导致的布局错乱。

7. 组件级适配

公共组件不应该只在一种固定尺寸下正常工作,还需要考虑不同容器宽度、不同布局环境下的表现。

兼容适配不是简单地让页面能够显示,而是让不同环境下的功能和交互尽可能保持一致。

十九、AI 编程时代的工程架构约束

AI 编程正在改变前端项目的开发方式。

代码生成的速度越来越快,但如果没有明确的项目规范,AI 也容易产生重复封装、错误依赖和不合理的文件组织。

因此,项目内部架构也需要成为 AI 编程的约束基础。

例如:

  • 明确项目目录和文件职责。
  • 明确公共组件与业务组件的边界。
  • 明确 CSS 命名和样式隔离规范。
  • 明确第三方组件的封装与使用方式。
  • 明确工具函数和业务逻辑的归属。
  • 明确模块之间的依赖关系。
  • 明确构建配置和兼容目标。
  • 明确修改已有代码时的范围和验证要求。

AI 应该在现有工程规范中完成开发,而不是每次生成代码时都重新设计一套结构。

未来,开发人员需要做的不仅是让 AI 生成代码,还需要判断生成的代码是否符合项目架构,是否增加了不必要的复杂度,以及是否影响已有功能。

二十、总结:架构设计不是为了增加抽象

通过这些内容,我越来越觉得,前端工程架构设计并没有必要追求复杂。

一个项目可以没有微前端,可以不引入复杂的状态管理,也可以不建立独立的组件平台。

但它应该有清晰的文件组织、合理的功能封装、统一的样式管理,以及明确的代码依赖关系。

同时,还需要考虑代码最终如何构建、资源如何加载、页面如何适应不同浏览器和运行环境。

从源代码组织,到模块协作,再到构建产物和浏览器运行,这才是一个相对完整的前端工程内部架构设计闭环。

我认为,AI 时代前端开发人员真正需要提升的,不只是代码实现能力,而是对代码结构、功能边界、工程成本和技术方案的综合判断能力。

没有一套架构能够适用于所有项目,真正重要的是结合当前项目的实际需求,选择成本合理、易于维护并且能够持续演进的设计方案。

本文仅代表个人在实际项目开发中的一些思考。不同项目有不同的技术背景和业务需求,也欢迎有经验的开发者补充和指导。

相关推荐
颜进强11 分钟前
微信小微AI-评测|文档质量直接被判 0 分:小微团队评测那些没人告诉你的硬指标
前端·ai编程·全栈
Bacon13 分钟前
给项目做一次"全身 CT":Agent Skills 生态里的代码体检全链路
前端·人工智能·后端
颜进强16 分钟前
微信小微AI-提审与发布|评测过了不等于能上线:四道前置条件,缺一道都白提交
前端·ai编程·全栈
颜进强18 分钟前
微信小微AI-【实战二】从零写一个 skill|卡片死活不出来?这 4 个坑我们全踩了一遍
前端·ai编程·全栈
颜进强21 分钟前
微信小微AI-命中效果调优|在 AI 的「选择题」里,怎么让小微更愿意选中你(系列收官)
前端·ai编程·全栈
颜进强22 分钟前
微信小微AI-【实战四】给 Agent 立人设|一份 AGENTS.md,决定小微是靠谱助手还是满嘴跑火车
前端·ai编程·全栈
颜进强22 分钟前
微信小微AI - 【实战一】工程化落地|Taro 主工程里塞进一套原生 AI 代码,我们这样让它们共存
前端·ai编程·全栈
颜进强28 分钟前
微信小微AI-【实战三】接力落地|用户点完 AI 卡片跨进小程序,那几秒才是体验的生死线
前端·ai编程·全栈
费曼学习法30 分钟前
为什么你的 Subagent 拆完反而更慢?我把 12 万 token 的任务重做了一遍
前端