# 数据库客户端前端架构设计文档 **文档版本**：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 架构设计原则 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)