架构不是一成不变的教条，而是服务于业务的工具。在实践中，应根据项目规模、团队能力和迭代节奏灵活调整，找到最适合当前阶段的平衡点。
在当今快速迭代的前端开发环境中，一个清晰、可维护、可扩展的项目架构，已成为团队高效协作和产品长期演进的基础。尤其在使用 Vue 3 + TypeScript 技术栈构建中大型应用时，合理的架构设计不仅能提升开发体验，更能显著降低后期维护成本，减少成为屎山代码的可能性。
本文将围绕 组件设计、逻辑复用、模块拆分、类型治理 四个核心维度，系统阐述一套我作为前端初学者对于现代前端的理解，提供适用于现代 Vue 项目的架构设计方法论，并提供可落地的实践建议。
本文部分内容还会围绕 Nuxt 这一 SSR 渲染框架展开，因为我目前在和同学一起写一个 Nuxt 项目，这个文章也是给我们自己看的～
一、组件设计：职责分离与复用策略
组件是 Vue 应用的基本构建单元。良好的组件设计应遵循“高内聚、低耦合”原则，并根据用途进行分类管理。
1. 组件分类
-
页面级组件（Views）
存放于src/views/(Vue) 或pages/(Nuxt) ，代表一个完整路由页面，如UserList.vue、OrderDetail.vue。它们通常包含业务逻辑、数据请求和页面布局，不追求复用性。 -
通用 UI 组件（Components）
存放于src/components/，专注于视觉呈现和交互行为，如Button.vue、Modal.vue、DataTable.vue。这类组件应：- 无业务逻辑
- 通过
props接收配置 - 通过
$emit触发事件 - 支持插槽（slots）增强灵活性
-
业务组件（Domain Components）
有时也称为“容器组件”，如UserSearchBox.vue、ProductCard.vue。它们封装了特定业务场景下的 UI 与轻量逻辑，可在多个页面复用，但不跨项目通用。
在 Nuxt 3 中，所有
.vue文件放在components/目录下即可自动注册，无需手动 import，极大简化了组件使用。
2. 何时抽离组件？
- 同一段 UI 结构或逻辑 重复出现两次及以上
- 单个组件代码超过 200 行且职责不清
- 需要在多个页面中复用相同交互行为
3. 组件设计最佳实践
-
使用 TypeScript 定义
props类型，确保类型安全：interface Props { size?: 'small' | 'medium' | 'large'; disabled?: boolean; } const props = defineProps<Props>(); -
避免在组件内部直接调用 API，优先通过外部传入数据或回调函数
-
样式使用 CSS Modules 或 Scoped CSS，防止全局污染
二、逻辑复用：Utils 与 Composables 的分工
随着 Composition API 的普及，逻辑复用不再依赖混入（mixins），而是通过函数组合实现。
1. Utils：纯函数工具库
存放于 src/utils/，用于处理无副作用、无响应式依赖的通用逻辑：
- 日期格式化：
formatDate(date: Date): string - 字符串处理：
camelToKebab(str: string): string - 数学计算、数组操作等
这些函数应是纯函数（相同输入始终返回相同输出），便于测试和复用。
2. Composables：响应式逻辑单元
存放于 src/composables/（Nuxt 3 支持自动导入），用于封装含响应式状态或生命周期依赖的逻辑：
- 数据请求：
useFetch<T>(url: string) - 表单验证：
useFormValidation(rules: ValidationRule[]) - 状态管理：
useAuth()、useCart()
// composables/useCounter.ts
export function useCounter(initial = 0) {
const count = ref(initial);
const increment = () => count.value++;
const reset = () => (count.value = initial);
return { count, increment, reset };
}
在
<script setup>中直接使用：const { count, increment } = useCounter();
3. 分工原则
画个表格可以简单概括性理解一下，具体情况具体分析：
| 特征 | Utils | Composables |
|---|---|---|
| 是否响应式 | 否 | 是 |
| 是否依赖 Vue 上下文 | 否 | 是（如 ref, onMounted） |
| 是否可跨框架使用 | 是（如 React 也可用） | 否（Vue 特有） |
三、模块化拆分：目录结构与关注点分离
合理的目录结构是架构设计的骨架。推荐采用“按功能划分”而非“按技术划分”的组织方式。
典型 Vue 3 + TS 项目结构（Vite/Nuxt）
src/
├── assets/ # 静态资源（图片、字体）
├── components/ # 通用 UI 组件
├── composables/ # 响应式逻辑单元（自动导入）
├── pages/ # 页面组件（Nuxt）或 views/
├── stores/ # Pinia 状态管理模块
├── types/ # TypeScript 类型定义
├── utils/ # 工具函数
├── api/ # API 请求封装（可选）
├── App.vue
└── main.ts
关键模块说明
stores/：每个业务域一个 store，如userStore.ts、productStore.ts，避免单一巨型 store。composables/：按功能命名，如useAuth.ts、useLocalStorage.ts。types/：按实体或模块组织类型文件，便于维护。
这种结构使得新成员能快速定位代码，也便于自动化工具（如 ESLint、TypeScript）进行规则校验。
四、类型治理：从前端定义到前后端协同
TypeScript 的价值不仅在于编译检查，更在于建立前后端对数据结构的共同认知，弥补了 JavaScript 弱类型在团队项目（尤其是前后端分离项目）中的带来的协作问题。
1. 类型定义规范
- 优先使用
interface定义 API 数据结构（支持扩展） - 明确标注可选字段（
?）和联合类型（'active' | 'inactive'） - 避免
any，必要时使用unknown+ 类型守卫
// types/user.ts
export interface User {
id: number;
name: string;
email?: string; // 可能不存在
status: 'active' | 'inactive';
}
2. 与后端协同类型
方案一：基于 OpenAPI 自动生成（推荐）
后端维护 OpenAPI 文档，前端使用 openapi-typescript 自动生成类型：
npx openapi-typescript http://api.example.com/openapi.json -o src/types/api.ts
生成的类型可直接用于请求层，实现端到端类型安全。
方案二：前端先行定义 + 联调对齐
-
前端根据接口文档定义类型
-
封装统一请求函数，注入泛型：
// composables/useApi.ts export function useApi<T>(url: string) { return $fetch<ApiResponse<T>>(url); } -
联调时与后端核对字段名、类型、空值策略
注意：日期通常为
string（ISO 8601），ID 可能为string（防精度丢失），布尔值勿用'true'字符串。
3. 类型与业务解耦
区分“原始 API 类型”和“前端业务类型”：
// 原始 API（下划线命名）
interface RawUser { user_id: number; user_name: string; }
// 前端业务类型（驼峰命名）
interface User { id: number; name: string; }
// 在 API 层转换
function transformUser(raw: RawUser): User {
return { id: raw.user_id, name: raw.user_name };
}
这使得前端代码更符合语义，且不受后端命名风格影响。
五、总结：架构设计的核心思维
现代 Vue 项目架构设计，本质上是对复杂性的管理。其核心思维包括：
- 组合优于继承：通过 Composables 自由组合逻辑，而非依赖类继承。
- 关注点分离：UI、逻辑、状态、类型各司其职，互不干扰。
- 渐进式抽象：先写内联逻辑，发现重复再抽离，避免过度设计。
- 类型即契约：将 TypeScript 作为前后端协作的语言，提前暴露问题。
- 约定优于配置：利用 Nuxt/Vite 的目录约定，减少样板代码。
最终目标是：让项目在增长过程中依然保持清晰、可预测、易维护。无论团队规模如何变化，这套架构都能支撑业务的持续演进。
PS：本文其实写的很泛，所以关于组件设计、方法抽离、类型治理的方法论，各位可以搜搜其他更详细的文章学习一下，帮助项目做得更好。
