263 lines
6.1 KiB
Markdown
263 lines
6.1 KiB
Markdown
# src 目录结构规范
|
||
|
||
本文档定义 `src` 目录下的文件组织方式与命名规范。**后续新增与修改的代码必须严格遵循本规范。**
|
||
|
||
## 目录总览
|
||
|
||
```
|
||
src/
|
||
├── pages/ # 页面组件
|
||
├── components/ # 全局公共组件
|
||
├── business-cmp/ # 业务组件（页面专用）
|
||
├── static/ # 静态资源
|
||
├── api/ # 网络请求接口
|
||
├── stores/ # 状态管理（Pinia）
|
||
├── utils/ # 工具函数
|
||
├── types/ # TypeScript 类型定义
|
||
├── hooks/ # Vue Composition API Hooks
|
||
└── styles/ # 全局样式
|
||
```
|
||
|
||
---
|
||
|
||
## 各目录说明
|
||
|
||
### pages — 页面组件
|
||
|
||
存放应用页面级组件，每个页面独立一个文件夹。
|
||
|
||
| 规则 | 说明 |
|
||
|------|------|
|
||
| 文件夹命名 | **kebab-case**（小写 + 连字符） |
|
||
| 示例 | `user-login/`、`home-index/` |
|
||
|
||
**推荐结构：**
|
||
|
||
```
|
||
pages/
|
||
├── user-login/
|
||
│ ├── index.vue # 页面入口
|
||
│ └── components/ # 仅该页面使用的组件（可选）
|
||
│ └── LoginForm.vue
|
||
└── home-index/
|
||
└── index.vue
|
||
```
|
||
|
||
> 页面专属组件优先放在 `pages/<page-name>/components/` 下；若业务组件较多、需跨页面复用但又不属于全局公共组件，可使用 `business-cmp/`。
|
||
|
||
---
|
||
|
||
### components — 全局公共组件
|
||
|
||
存放可在多个页面复用的通用 UI 组件。
|
||
|
||
| 规则 | 说明 |
|
||
|------|------|
|
||
| 文件命名 | **PascalCase**（大驼峰） |
|
||
| 文件扩展名 | `.vue` |
|
||
| 示例 | `AppFooter.vue`、`InputEntry.vue` |
|
||
|
||
**适用场景：**
|
||
|
||
- 按钮、输入框、弹窗等基础 UI 封装
|
||
- 布局类组件（Header、Footer、Sidebar 等）
|
||
- 与具体业务无关、可在任意页面引用的组件
|
||
|
||
---
|
||
|
||
### business-cmp — 业务组件
|
||
|
||
存放与特定业务逻辑绑定、**不对外全局复用**的组件。
|
||
|
||
| 规则 | 说明 |
|
||
|------|------|
|
||
| 组织方式 | 按业务模块或页面分子目录 |
|
||
| 文件命名 | **PascalCase** |
|
||
| 示例 | `business-cmp/order/OrderCard.vue` |
|
||
|
||
**与 `components` 的区别：**
|
||
|
||
| 目录 | 复用范围 | 示例 |
|
||
|------|----------|------|
|
||
| `components/` | 全局、跨业务复用 | `AppFooter.vue` |
|
||
| `business-cmp/` | 特定业务/页面 | `OrderCard.vue` |
|
||
| `pages/xxx/components/` | 仅单个页面 | `LoginForm.vue` |
|
||
|
||
**选择原则：**
|
||
|
||
1. 仅一个页面使用 → `pages/<page>/components/`
|
||
2. 同一业务模块内多页面复用 → `business-cmp/<module>/`
|
||
3. 跨业务、通用 UI → `components/`
|
||
|
||
---
|
||
|
||
### static — 静态资源
|
||
|
||
存放图片、字体、图标等静态文件。
|
||
|
||
| 规则 | 说明 |
|
||
|------|------|
|
||
| 文件/文件夹命名 | **小写**（可用连字符分隔） |
|
||
| 示例 | `logo.png`、`github.svg`、`icon-arrow.png` |
|
||
|
||
**推荐结构：**
|
||
|
||
```
|
||
static/
|
||
├── images/
|
||
│ └── banner.png
|
||
├── icons/
|
||
│ └── home.svg
|
||
└── fonts/
|
||
└── custom-font.woff2
|
||
```
|
||
|
||
---
|
||
|
||
### api — 网络请求接口
|
||
|
||
封装所有后端 API 调用，按业务模块拆分文件。
|
||
|
||
| 规则 | 说明 |
|
||
|------|------|
|
||
| 文件命名 | **kebab-case** 或按模块命名 |
|
||
| 文件扩展名 | `.ts` |
|
||
| 示例 | `user.ts`、`order.ts` |
|
||
|
||
**示例：**
|
||
|
||
```ts
|
||
// api/user.ts
|
||
export function login(data: LoginParams) {
|
||
return request.post<LoginResult>('/user/login', data)
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### stores — 状态管理
|
||
|
||
使用 **Pinia** 管理全局状态，按功能模块拆分 Store。
|
||
|
||
| 规则 | 说明 |
|
||
|------|------|
|
||
| 文件命名 | **kebab-case** 或 `useXxxStore` 风格 |
|
||
| 文件扩展名 | `.ts` |
|
||
| 示例 | `user.ts`、`cart.ts` |
|
||
|
||
**示例：**
|
||
|
||
```ts
|
||
// stores/user.ts
|
||
export const useUserStore = defineStore('user', () => {
|
||
// ...
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
### utils — 工具函数
|
||
|
||
存放与业务无关的纯函数工具。
|
||
|
||
| 规则 | 说明 |
|
||
|------|------|
|
||
| 文件命名 | **kebab-case** |
|
||
| 文件扩展名 | `.ts` |
|
||
| 示例 | `format-date.ts`、`storage.ts` |
|
||
|
||
**适用场景：**
|
||
|
||
- 日期/金额格式化
|
||
- 本地存储封装
|
||
- 通用校验、防抖节流等
|
||
|
||
---
|
||
|
||
### types — TypeScript 类型定义
|
||
|
||
集中管理项目中的 TypeScript 类型与接口。
|
||
|
||
| 规则 | 说明 |
|
||
|------|------|
|
||
| 文件命名 | **kebab-case** |
|
||
| 文件扩展名 | **`.ts`**（必须） |
|
||
| 示例 | `user.ts`、`api-response.ts` |
|
||
|
||
**示例：**
|
||
|
||
```ts
|
||
// types/user.ts
|
||
export interface UserInfo {
|
||
id: number
|
||
name: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### hooks — Composition API Hooks
|
||
|
||
封装可复用的 Vue Composition API 逻辑。
|
||
|
||
| 规则 | 说明 |
|
||
|------|------|
|
||
| 文件命名 | **kebab-case**，以 `use` 开头 |
|
||
| 文件扩展名 | `.ts` |
|
||
| 示例 | `use-auth.ts`、`use-pagination.ts` |
|
||
|
||
**示例：**
|
||
|
||
```ts
|
||
// hooks/use-auth.ts
|
||
export function useAuth() {
|
||
// ...
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### styles — 全局样式
|
||
|
||
存放全局样式、变量、混入等。
|
||
|
||
| 规则 | 说明 |
|
||
|------|------|
|
||
| 文件命名 | **kebab-case** |
|
||
| 文件扩展名 | `.scss` / `.css` |
|
||
| 示例 | `variables.scss`、`reset.scss` |
|
||
|
||
---
|
||
|
||
## 命名规范速查表
|
||
|
||
| 类型 | 命名风格 | 示例 |
|
||
|------|----------|------|
|
||
| 页面文件夹 | kebab-case | `user-login/` |
|
||
| 全局组件文件 | PascalCase | `AppFooter.vue` |
|
||
| 业务/页面组件文件 | PascalCase | `OrderCard.vue` |
|
||
| 静态资源 | 小写 | `logo.png` |
|
||
| API / Store / Utils / Types / Hooks | kebab-case | `user.ts`、`use-auth.ts` |
|
||
| 样式文件 | kebab-case | `variables.scss` |
|
||
|
||
---
|
||
|
||
## 导入路径约定
|
||
|
||
- 全局组件：从 `@/components/` 引入
|
||
- 业务组件：从 `@/business-cmp/` 或页面相对路径引入
|
||
- API：从 `@/api/` 引入
|
||
- 类型：从 `@/types/` 引入
|
||
- 工具：从 `@/utils/` 引入
|
||
- Hooks：从 `@/hooks/` 引入
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **禁止**在 `components/` 中放置与具体业务强耦合的组件。
|
||
2. **禁止**在页面目录外散落页面专属组件。
|
||
3. 新增目录或调整规范前，需同步更新本文档。
|
||
4. 所有 TypeScript 类型定义统一放在 `types/`，避免在业务文件中重复定义相同类型。
|
||
5. 网络请求逻辑统一通过 `api/` 层调用，页面与组件中不直接写请求 URL。
|