12 KiB
12 KiB
数据库客户端前端架构设计文档
文档版本：v2.0
维护者：JueChen
更新日期：2026-01-28
源码路径：go-desk/frontend/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 架构设计原则
- 单一职责原则：每个组件和 composable 只负责一个功能领域
- 关注点分离：视图、逻辑、状态分离
- 可复用性：通过 composables 抽取可复用逻辑
- 可维护性：清晰的目录结构和命名规范
- 可测试性：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): 执行SQLhandleQueryResult(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：
// 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 目录结构 ✅
- 创建
composables/目录 - 创建
useDbConnection.ts - 创建
useSqlExecution.ts - 创建
useEditorState.ts - 创建
useResultState.ts - 创建
useMessageLog.ts
步骤2：重构主页面 ✅
- 将状态管理逻辑迁移到 composables
- 将业务逻辑迁移到 composables
- 简化 index.vue，只保留布局和协调逻辑
步骤3：优化组件通信 ✅
- 评估是否需要使用 provide/inject（当前不需要）
- 优化 props 传递
- 优化事件处理
步骤4：测试和验证 ⚠️
- 功能测试（基本完成）
- 性能测试（待完成）
- 代码审查（已完成）
八、后续优化方向
- 状态管理库：如果状态管理变得复杂，可以考虑引入 Pinia
- 类型安全：为 composables 添加完整的 TypeScript 类型定义
- 错误处理：统一错误处理机制
- 性能优化：使用 computed 和 watch 优化响应式更新
- 单元测试：为 composables 编写单元测试