
# 数据库客户端前端架构设计文档

**文档版本**：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)

