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

**文档版本**：v2.0  
**维护者**：JueChen  
**更新日期**：2026-01-28  
**源码路径**：`go-desk/`

---

## 一、整体架构概览

### 1.1 分层架构

```
┌─────────────────────────────────────────────────────────────┐
│                   接口层（API Layer）                         │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  app.go (Wails App 接口)                              │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                   服务层（Service Layer）                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ConnectionSvc │  │  SqlExecSvc  │  │ ResourceSvc │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
│  ┌──────────────┐  ┌──────────────┐                        │
│  │  TabSvc      │  │  BookmarkSvc │                        │
│  └──────────────┘  └──────────────┘                        │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                   数据访问层（Data Access Layer）              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │  Storage     │  │  DBClient    │  │   Models     │      │
│  │  (SQLite)    │  │  (Pool)      │  │              │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                   基础设施层（Infrastructure Layer）            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   Crypto     │  │  Filesystem  │  │   System     │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
```

### 1.2 架构设计原则

1. **单一职责原则**：每个服务只负责一个业务领域
2. **依赖倒置原则**：接口定义在服务层，实现在数据访问层
3. **关注点分离**：接口、业务逻辑、数据访问分离
4. **可测试性**：通过接口抽象，便于单元测试
5. **可扩展性**：新增功能只需添加新的服务

---

## 二、目录结构

```
go-desk/
├── main.go                    # 应用入口
├── app.go                     # Wails App 接口（精简后）
├── internal/
│   ├── api/                   # API 接口层（新增）
│   │   ├── connection_api.go  # 连接管理接口
│   │   ├── sql_api.go         # SQL执行接口
│   │   ├── resource_api.go    # 资源管理接口
│   │   └── tab_api.go         # 标签页接口
│   │
│   ├── service/                # 服务层（新增）
│   │   ├── connection_service.go  # 连接管理服务
│   │   ├── sql_exec_service.go    # SQL执行服务
│   │   ├── resource_service.go    # 资源管理服务
│   │   └── tab_service.go         # 标签页服务
│   │
│   ├── storage/                # 数据访问层
│   │   ├── sqlite.go           # SQLite 初始化
│   │   ├── models/             # 数据模型
│   │   │   ├── connection.go
│   │   │   ├── sql_tab.go
│   │   │   ├── bookmark.go
│   │   │   └── template.go
│   │   └── repository/         # 数据仓库（新增）
│   │       ├── connection_repo.go
│   │       ├── tab_repo.go
│   │       ├── bookmark_repo.go
│   │       └── template_repo.go
│   │
│   ├── dbclient/               # 数据库客户端
│   │   ├── pool.go             # 连接池管理
│   │   ├── mysql.go            # MySQL 客户端
│   │   ├── redis.go            # Redis 客户端
│   │   └── mongo.go            # MongoDB 客户端
│   │
│   ├── crypto/                 # 加密工具
│   ├── filesystem/             # 文件系统
│   └── system/                 # 系统信息
```

---

## 三、服务层设计

### 3.1 ConnectionService

**职责**：管理数据库连接配置

**方法**：
- `SaveConnection(conn *models.DbConnection) error`
- `ListConnections() ([]models.DbConnection, error)`
- `GetConnection(id uint) (*models.DbConnection, error)`
- `DeleteConnection(id uint) error`
- `TestConnection(conn *models.DbConnection) error`

**依赖**：
- `ConnectionRepository`：数据访问接口

### 3.2 SqlExecService

**职责**：执行 SQL 语句

**方法**：
- `ExecuteSQL(connectionId uint, sqlStr string, database string) (*SqlResult, error)`
- `GetDatabases(connectionId uint) ([]string, error)`
- `GetTables(connectionId uint, database string) ([]string, error)`

**依赖**：
- `ConnectionService`：获取连接配置
- `ConnectionPool`：获取数据库客户端

### 3.3 ResourceService

**职责**：管理书签和模板

**方法**：
- `SaveBookmark(bookmark *models.Bookmark) error`
- `ListBookmarks(connectionId uint) ([]models.Bookmark, error)`
- `DeleteBookmark(id uint) error`
- `SaveTemplate(template *models.Template) error`
- `ListTemplates() ([]models.Template, error)`
- `DeleteTemplate(id uint) error`

**依赖**：
- `BookmarkRepository`：书签数据访问
- `TemplateRepository`：模板数据访问

### 3.4 TabService

**职责**：管理 SQL 标签页

**方法**：
- `SaveTabs(tabs []models.SqlTab) error`
- `ListTabs() ([]models.SqlTab, error)`
- `DeleteTab(id uint) error`

**依赖**：
- `TabRepository`：标签页数据访问

---

## 四、数据访问层设计

### 4.1 Repository 模式

使用 Repository 模式封装数据访问逻辑，提供统一的接口：

```go
type ConnectionRepository interface {
    Save(conn *models.DbConnection) error
    FindAll() ([]models.DbConnection, error)
    FindByID(id uint) (*models.DbConnection, error)
    Delete(id uint) error
}
```

### 4.2 实现方式

- `ConnectionRepository`：使用 GORM 实现
- `TabRepository`：使用 GORM 实现
- `BookmarkRepository`：使用 GORM 实现
- `TemplateRepository`：使用 GORM 实现

---

## 五、接口层设计

### 5.1 API 接口

将 `app.go` 中的方法按功能分组到不同的 API 文件中：

- `connection_api.go`：连接管理相关接口
- `sql_api.go`：SQL 执行相关接口
- `resource_api.go`：资源管理相关接口
- `tab_api.go`：标签页相关接口

### 5.2 App 结构体

`app.go` 只负责：
- 初始化服务
- 委托调用到对应的 API 接口

---

## 六、重构优势

### 6.1 代码组织

- **清晰的职责划分**：每个服务只负责一个业务领域
- **易于维护**：修改某个功能只需修改对应的服务
- **代码复用**：服务可以在多个 API 中复用

### 6.2 可测试性

- **独立测试**：每个服务可以独立测试
- **Mock 简单**：可以轻松 mock Repository
- **测试覆盖**：逻辑集中在服务层，测试更容易

### 6.3 可扩展性

- **新增功能**：只需添加新的服务和 API
- **功能组合**：可以组合多个服务实现复杂功能
- **向后兼容**：不影响现有接口

---

## 七、实施步骤

### 步骤1：创建目录结构 ✅
- [x] 创建 `internal/api/` 目录
- [x] 创建 `internal/service/` 目录
- [x] 创建 `internal/storage/repository/` 目录

### 步骤2：实现 Repository 层 ✅
- [x] 定义 Repository 接口
- [x] 实现 ConnectionRepository
- [x] 实现 TabRepository
- [x] 实现 BookmarkRepository
- [x] 实现 TemplateRepository

### 步骤3：实现 Service 层 ✅
- [x] 实现 ConnectionService
- [x] 实现 SqlExecService
- [x] 实现 ResourceService
- [x] 实现 TabService

### 步骤4：实现 API 层 ✅
- [x] 实现 connection_api.go
- [x] 实现 sql_api.go
- [x] 实现 resource_api.go
- [x] 实现 tab_api.go

### 步骤5：重构 app.go ✅
- [x] 连接管理方法迁移到 ConnectionAPI ✅
- [x] SQL执行方法迁移到 SqlAPI ✅
- [x] 书签管理方法迁移到 ResourceAPI ✅
- [x] 模板管理方法迁移到 ResourceAPI ✅
- [x] 标签页管理方法迁移到 TabAPI ✅
- [x] 表结构和索引查询方法迁移到 SqlAPI ✅
- [x] 删除重复代码（parseRedisCommand）✅
- [x] 简化 app.go，只保留初始化逻辑 ✅

### 步骤6：测试和验证 ⚠️
- [x] 功能测试（基本完成）
- [ ] 单元测试（待完成）
- [x] 代码审查（已完成）

---

## 八、后续优化方向

1. **依赖注入**：使用依赖注入框架管理服务依赖
2. **错误处理**：统一错误处理机制
3. **日志系统**：引入结构化日志
4. **配置管理**：统一配置管理
5. **中间件**：添加认证、限流等中间件

---

## 九、参考文档

- [Go 项目布局标准](https://github.com/golang-standards/project-layout)
- [Clean Architecture in Go](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)

