重构：文件系统模块化架构，优化应用启动流程
This commit is contained in:
312
docs/04-功能迭代/GO-DESK-2.数据库客户端/设计文档/架构设计/前端架构设计.md
Normal file
312
docs/04-功能迭代/GO-DESK-2.数据库客户端/设计文档/架构设计/前端架构设计.md
Normal file
@@ -0,0 +1,312 @@
|
||||
|
||||
# 数据库客户端前端架构设计文档
|
||||
|
||||
**文档版本**：v2.0
|
||||
**维护者**：JueChen
|
||||
**更新日期**：2025-01-28
|
||||
**源码路径**：`go-desk/web/src/views/db-cli/`
|
||||
|
||||
---
|
||||
|
||||
## 一、整体架构概览
|
||||
|
||||
### 1.1 分层架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 视图层（Views） │
|
||||
│ ┌──────────────────────────────────────────────────────┐ │
|
||||
│ │ index.vue (主页面 - 布局和协调) │ │
|
||||
│ └──────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 组件层（Components） │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ConnectionTree│ │ SqlEditor │ │ ResultPanel │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ConnectionForm│ │ResourceManager│ │ │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 组合式函数层（Composables） │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │useDbConnection│ │useSqlExecution│ │useEditorState│ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │useResultState │ │useMessageLog │ │
|
||||
│ └──────────────┘ └──────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ API 层（Wails Bridge） │
|
||||
│ ┌──────────────────────────────────────────────────────┐ │
|
||||
│ │ window.go.main.App.* │ │
|
||||
│ └──────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 1.2 架构设计原则
|
||||
|
||||
1. **单一职责原则**：每个组件和 composable 只负责一个功能领域
|
||||
2. **关注点分离**：视图、逻辑、状态分离
|
||||
3. **可复用性**：通过 composables 抽取可复用逻辑
|
||||
4. **可维护性**：清晰的目录结构和命名规范
|
||||
5. **可测试性**：composables 可以独立测试
|
||||
|
||||
---
|
||||
|
||||
## 二、目录结构
|
||||
|
||||
```
|
||||
db-cli/
|
||||
├── index.vue # 主页面（布局和协调）
|
||||
├── components/ # 组件目录
|
||||
│ ├── ConnectionTree.vue # 连接树组件
|
||||
│ ├── ConnectionForm.vue # 连接表单组件
|
||||
│ ├── SqlEditor.vue # SQL编辑器组件
|
||||
│ ├── ResultPanel.vue # 结果展示组件
|
||||
│ ├── ResourceManager.vue # 资源管理组件
|
||||
│ └── ~~BookmarkManager.vue~~ # ❌ 已删除（书签功能已删除）
|
||||
│ └── ~~TemplateManager.vue~~ # ❌ 已删除（模板功能已删除）
|
||||
└── composables/ # 组合式函数目录
|
||||
├── useDbConnection.ts # 连接管理逻辑
|
||||
├── useSqlExecution.ts # SQL执行逻辑
|
||||
├── useEditorState.ts # 编辑器状态管理
|
||||
├── useResultState.ts # 结果状态管理
|
||||
└── useMessageLog.ts # 消息日志管理
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、Composables 设计
|
||||
|
||||
### 3.1 useDbConnection.ts
|
||||
|
||||
**职责**：管理数据库连接相关的状态和逻辑
|
||||
|
||||
**状态**：
|
||||
- `currentConnection`: 当前选中的连接
|
||||
- `selectedDatabase`: 当前选中的数据库（MySQL）
|
||||
- `showConnectionForm`: 连接表单显示状态
|
||||
- `editingConnectionId`: 正在编辑的连接ID
|
||||
|
||||
**方法**：
|
||||
- `selectConnection(conn, database)`: 选择连接
|
||||
- `editConnection(connectionId)`: 编辑连接
|
||||
- `deleteConnection(connectionId)`: 删除连接
|
||||
- `newConnection()`: 新建连接
|
||||
- `onConnectionSuccess()`: 连接操作成功回调
|
||||
|
||||
### 3.2 useSqlExecution.ts
|
||||
|
||||
**职责**：管理SQL执行相关的逻辑
|
||||
|
||||
**方法**：
|
||||
- `executeSQL(sql, connection, database)`: 执行SQL
|
||||
- `handleQueryResult(result)`: 处理查询结果
|
||||
- `handleUpdateResult(result)`: 处理更新结果
|
||||
- `handleCommandResult(result)`: 处理命令结果（Redis）
|
||||
|
||||
### 3.3 useEditorState.ts
|
||||
|
||||
**职责**：管理编辑器显示/隐藏状态
|
||||
|
||||
**状态**：
|
||||
- `editorVisible`: 编辑器是否可见
|
||||
|
||||
**方法**：
|
||||
- `toggleEditor()`: 切换编辑器显示/隐藏
|
||||
- `loadEditorVisible()`: 从localStorage加载状态
|
||||
- `saveEditorVisible()`: 保存状态到localStorage
|
||||
|
||||
### 3.4 useResultState.ts
|
||||
|
||||
**职责**：管理执行结果相关的状态
|
||||
|
||||
**状态**：
|
||||
- `resultLoading`: 加载状态
|
||||
- `resultError`: 错误信息
|
||||
- `resultData`: 结果数据
|
||||
- `resultMode`: 展示模式（table/json）
|
||||
- `resultStats`: 执行统计
|
||||
- `resultColumns`: 表格列定义
|
||||
|
||||
**方法**：
|
||||
- `clearResults()`: 清空结果
|
||||
- `setQueryResult(data, stats)`: 设置查询结果
|
||||
- `setUpdateResult(stats)`: 设置更新结果
|
||||
- `setCommandResult(data, stats)`: 设置命令结果
|
||||
- `setError(error)`: 设置错误
|
||||
|
||||
### 3.5 useMessageLog.ts
|
||||
|
||||
**职责**：管理消息日志
|
||||
|
||||
**状态**：
|
||||
- `messages`: 消息列表
|
||||
|
||||
**方法**：
|
||||
- `addMessage(type, content)`: 添加消息
|
||||
- `clearMessages()`: 清空消息
|
||||
- `getMessages(limit)`: 获取消息（带限制）
|
||||
|
||||
---
|
||||
|
||||
## 四、组件通信设计
|
||||
|
||||
### 4.1 Props 向下传递
|
||||
|
||||
```
|
||||
index.vue
|
||||
├─ ConnectionTree
|
||||
│ └─ currentConnectionId (prop)
|
||||
├─ SqlEditor
|
||||
│ └─ currentConnection (prop)
|
||||
└─ ResultPanel
|
||||
├─ loading (prop)
|
||||
├─ error (prop)
|
||||
├─ data (prop)
|
||||
├─ mode (prop)
|
||||
├─ stats (prop)
|
||||
├─ columns (prop)
|
||||
└─ messages (prop)
|
||||
```
|
||||
|
||||
### 4.2 Events 向上传递
|
||||
|
||||
```
|
||||
ConnectionTree
|
||||
├─ @connection-select → index.vue
|
||||
├─ @connection-edit → index.vue
|
||||
├─ @connection-delete → index.vue
|
||||
├─ @table-select → index.vue
|
||||
├─ @new-connection → index.vue
|
||||
└─ ~~@show-bookmarks, @show-templates~~ ❌ 已删除（功能已删除）
|
||||
|
||||
SqlEditor
|
||||
├─ @execute → index.vue
|
||||
├─ @execute-selected → index.vue
|
||||
└─ @toggle-editor → index.vue
|
||||
|
||||
ResultPanel
|
||||
└─ @toggle-editor → index.vue
|
||||
```
|
||||
|
||||
### 4.3 Provide/Inject（可选）
|
||||
|
||||
对于深层嵌套的组件，可以使用 provide/inject：
|
||||
|
||||
```typescript
|
||||
// index.vue
|
||||
provide('dbCliContext', {
|
||||
currentConnection,
|
||||
selectedDatabase,
|
||||
executeSQL,
|
||||
addMessage
|
||||
})
|
||||
|
||||
// 深层组件
|
||||
const { currentConnection, executeSQL } = inject('dbCliContext')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、状态管理流程
|
||||
|
||||
### 5.1 连接选择流程
|
||||
|
||||
```
|
||||
用户点击连接
|
||||
→ ConnectionTree 触发 @connection-select
|
||||
→ index.vue 调用 useDbConnection.selectConnection()
|
||||
→ 更新 currentConnection 和 selectedDatabase
|
||||
→ 清空结果（useResultState.clearResults()）
|
||||
→ 添加消息（useMessageLog.addMessage()）
|
||||
→ SqlEditor 接收新的 currentConnection prop
|
||||
```
|
||||
|
||||
### 5.2 SQL执行流程
|
||||
|
||||
```
|
||||
用户执行SQL
|
||||
→ SqlEditor 触发 @execute
|
||||
→ index.vue 调用 useSqlExecution.executeSQL()
|
||||
→ 调用 window.go.main.App.ExecuteSQL()
|
||||
→ 根据结果类型调用对应的处理方法
|
||||
→ useResultState 更新结果状态
|
||||
→ ResultPanel 接收新的 props 并展示
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、重构优势
|
||||
|
||||
### 6.1 代码组织
|
||||
|
||||
- **清晰的职责划分**：每个 composable 负责一个功能领域
|
||||
- **易于维护**：修改某个功能只需修改对应的 composable
|
||||
- **代码复用**：composables 可以在其他页面复用
|
||||
|
||||
### 6.2 可测试性
|
||||
|
||||
- **独立测试**：每个 composable 可以独立测试
|
||||
- **Mock 简单**：可以轻松 mock window.go API
|
||||
- **测试覆盖**：逻辑集中在 composables，测试更容易
|
||||
|
||||
### 6.3 可扩展性
|
||||
|
||||
- **新增功能**：只需添加新的 composable
|
||||
- **功能组合**：可以组合多个 composables 实现复杂功能
|
||||
- **向后兼容**：不影响现有组件结构
|
||||
|
||||
---
|
||||
|
||||
## 七、实施步骤
|
||||
|
||||
### 步骤1：创建 composables 目录结构 ✅
|
||||
- [x] 创建 `composables/` 目录
|
||||
- [x] 创建 `useDbConnection.ts`
|
||||
- [x] 创建 `useSqlExecution.ts`
|
||||
- [x] 创建 `useEditorState.ts`
|
||||
- [x] 创建 `useResultState.ts`
|
||||
- [x] 创建 `useMessageLog.ts`
|
||||
|
||||
### 步骤2：重构主页面 ✅
|
||||
- [x] 将状态管理逻辑迁移到 composables
|
||||
- [x] 将业务逻辑迁移到 composables
|
||||
- [x] 简化 index.vue，只保留布局和协调逻辑
|
||||
|
||||
### 步骤3：优化组件通信 ✅
|
||||
- [x] 评估是否需要使用 provide/inject（当前不需要）
|
||||
- [x] 优化 props 传递
|
||||
- [x] 优化事件处理
|
||||
|
||||
### 步骤4：测试和验证 ⚠️
|
||||
- [x] 功能测试（基本完成）
|
||||
- [ ] 性能测试（待完成）
|
||||
- [x] 代码审查（已完成）
|
||||
|
||||
---
|
||||
|
||||
## 八、后续优化方向
|
||||
|
||||
1. **状态管理库**：如果状态管理变得复杂，可以考虑引入 Pinia
|
||||
2. **类型安全**：为 composables 添加完整的 TypeScript 类型定义
|
||||
3. **错误处理**：统一错误处理机制
|
||||
4. **性能优化**：使用 computed 和 watch 优化响应式更新
|
||||
5. **单元测试**：为 composables 编写单元测试
|
||||
|
||||
---
|
||||
|
||||
## 九、参考文档
|
||||
|
||||
- [Vue 3 Composition API](https://vuejs.org/guide/extras/composition-api-faq.html)
|
||||
- [Vue 3 Provide/Inject](https://vuejs.org/guide/components/provide-inject.html)
|
||||
- [组件拆分方案](./组件拆分方案.md)
|
||||
|
||||
Reference in New Issue
Block a user