DBView 开发日志 ① — 项目起步与技术架构解析

DBView 开发日志 ① — 项目起步与技术架构解析

日期： 2026-06-05 项目： DBView — Database Visual Explorer（数据库可视化工具） 状态： v1.0 功能开发完成

---

一、缘起：为什么要做 DBView

在日常开发工作中，我们经常需要同时操作多种数据库：

• MySQL — 最常见的业务数据库
• PostgreSQL — 越来越多项目转向的开源数据库
• SQLite — 嵌入式、移动端、测试环境的标配
• Oracle — 企业级遗留系统的常客

市面上虽然不乏优秀的数据库管理工具（Navicat、DataGrip、DBeaver、HeidiSQL 等），但它们大多是通用型产品，功能繁重、启动缓慢，且鲜有基于 Web 技术构建的现代化体验。

DBView 的初心： 做一个轻量、快速、界面现代的数据库可视化管理工具，基于 Electron + React 技术栈，开箱支持四大主流数据库，满足日常开发中最核心的浏览、查询、编辑需求。

---

二、技术选型

层面	选择	理由
桌面框架	Electron 35	成熟的跨平台桌面方案，Web 技术栈复用
构建工具	electron-vite 3	极快的冷启动和热重载，原生 Electron 支持
前端框架	React 19	最新的 Concurrent 特性，性能优秀
UI 组件库	Ant Design 5	企业级组件库，开箱即用的表格/表单/树等
状态管理	Zustand 5	极简的 React 状态管理，无 boilerplate
CSS 方案	Ant Design CSS-in-JS + CSS 变量	原生支持暗色主题切换
国际化	i18next + react-i18next	成熟生态，Ant Design 联动支持
SQL 编辑器	CodeMirror 6	高性能代码编辑器，SQL 语法高亮支持
密码加密	Node.js crypto (AES-256-GCM)	连接密码安全存储
包管理	pnpm	更快的安装速度和磁盘效率

数据库驱动选型

DatabaseDriver (接口)
├── MySQLDriver    → mysql2
├── PostgreSQLDriver → pg
├── SQLiteDriver   → better-sqlite3
└── OracleDriver   → oracledb

每个驱动均实现统一的 DatabaseDriver 接口，通过 DriverFactory 工厂类按数据库类型创建实例。这种策略模式确保了新增数据库类型的扩展性。

---

三、架构设计：经典的三层 IPC 模式

┌──────────────────────────────────────────────────┐
│                  Renderer 进程                    │
│  ┌─────────┐ ┌──────────┐ ┌───────────────────┐  │
│  │ React UI│ │ Zustand  │ │ Components        │  │
│  │ (Pages) │ │ (Stores) │ │ (DataTable/Editor)│  │
│  └────┬────┘ └──────────┘ └───────────────────┘  │
│       │          contextBridge (preload)          │
├───────┴──────────────────────────────────────────┤
│                  Preload 桥接层                    │
│        暴露安全的 IPC API 到渲染进程               │
├──────────────────────────────────────────────────┤
│                   Main 进程                       │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐  │
│  │ IPC      │ │ DB       │ │ Service          │  │
│  │ Handlers │ │ Drivers  │ │ (ConnectionMgr)  │  │
│  └──────────┘ └──────────┘ └──────────────────┘  │
└──────────────────────────────────────────────────┘

3.1 渲染层（Renderer）

React 19 前端，主要包含：

• 页面层： 连接管理页（ConnectionPage）、数据库工作区页（待整合）
• 组件层： 数据表格（DataTable）、SQL 编辑器（SqlEditor）、数据库树（DatabaseTree）、结构编辑器（SchemaEditor）、连接分组（ConnectionGroups）等
• 状态层： 通过 Zustand store 管理连接状态、编辑器状态、UI 主题、国际化偏好
• 服务层： 通过 preload 暴露的 API 与主进程通信

3.2 预加载层（Preload）

作为安全桥接层，通过 contextBridge 向渲染进程暴露受限的 API，只传递序列化数据，不暴露 Node.js 完整能力：

// preload/index.ts — 暴露的 API 示例
contextBridge.exposeInMainWorld('api', {
  connection: {
    list: () => ipcRenderer.invoke('connection:list', ...),
    create: (config) => ipcRenderer.invoke('connection:create', config),
    connect: (id) => ipcRenderer.invoke('connection:connect', id),
    disconnect: (id) => ipcRenderer.invoke('connection:disconnect', id),
  },
  database: {
    getDatabases: (connId) => ipcRenderer.invoke('db:databases', connId),
    getTables: (connId, db) => ipcRenderer.invoke('db:tables', connId, db),
    getColumns: (connId, db, table) => ipcRenderer.invoke('db:columns', connId, db, table),
    executeQuery: (connId, sql) => ipcRenderer.invoke('db:query', connId, sql),
  },
  // ...
})

3.3 主进程层（Main）

Node.js 主进程负责所有数据库连接和操作：

• IPC Handlers — 处理渲染进程的请求，分发到对应服务
• Database Drivers — 四种数据库驱动的具体实现
• Connection Manager — 连接池管理、生命周期控制
• Store — 连接配置持久化（AES 加密）、查询历史持久化

---

四、v1.0 已完成功能总览

截至 2026 年 6 月 5 日，DBView v1.0 的 10 大模块已全部开发完成：

✅ 数据库驱动扩展

• PostgreSQL、SQLite、Oracle 三种数据库驱动的完整实现
• 统一的 DatabaseDriver 接口 + DriverFactory 工厂注册机制
• 各数据库类型专有的连接配置表单

✅ 查询取消机制

• AbortController 模式实现查询中断
• 每个查询分配唯一 ID，维护信号映射
• 前端 SQL 编辑器的取消执行按钮

✅ 数据导出

• 支持 CSV（含 BOM 头、特殊字符转义）
• 支持 JSON 格式化导出
• 支持 SQL INSERT 语句导出
• 支持导出当前页 / 导出全部（含分页拉取 + 进度显示）

✅ SQL 编辑器增强

• CodeMirror 6 深度集成，SQL 语法高亮
• sql-formatter 格式化（按数据库类型选择方言）
• 快捷键：Ctrl+Enter 执行、Ctrl+S 格式化
• 查询历史持久化存储和浏览

✅ 表数据编辑

• 行内编辑模式（类似 Excel 体验）
• 单元格双击进入编辑，输入框/下拉框切换
• 修改追踪：记录变更的单元格、原始值和新值
• 添加/删除行功能（含确认对话框）
• 批量保存：生成 UPDATE/INSERT/DELETE 并顺序执行

✅ 表结构编辑

• 可视化表结构编辑（添加/修改/删除列、索引）
• DDL 预览对话框（执行前确认）
• 支持 MySQL / PG / SQLite / Oracle 的 ALTER TABLE 语法生成

✅ 国际化

• i18next + react-i18next 框架接入
• 中英文翻译文件完整覆盖
• Ant Design ConfigProvider 语言联动
• 语言偏好持久化

✅ 暗色主题

• 支持亮色 / 暗色 / 跟随系统三种模式
• Ant Design 主题算法自动切换
• CodeMirror One Dark 主题联动
• 自定义 CSS 变量覆盖

✅ 连接分组管理

• 分组 CRUD（创建/重命名/删除）
• 连接表单增加分组选择
• 连接列表按分组显示/折叠

✅ 存储过程和函数浏览

• MySQL 驱动扩展：查询 Proc/Func 列表和定义源码
• PostgreSQL 驱动扩展：查询 Proc/Func
• Oracle 驱动扩展：查询 Proc/Func
• 数据库树增加"存储过程"和"函数"节点
• 存储过程/函数查看和执行对话框

---

五、开发工具链：Claude Code + OpenSpec 实战

这个项目是 Claude Code（AI 编程代理）+ OpenSpec（结构化规格管理）组合的典型实践：

开发流程

OpenSpec 规格定义 → Claude Code 任务规划 → 代码实现 → 验证完成

1. 规格先行： 在 openspec/ 目录下定义功能规格（spec.md），明确范围、接口、行为
2. 任务拆分： 将大功能拆解为可独立完成的小任务（tasks.md），每个任务可被 Claude Code 独立执行
3. AI 驱动开发： Claude Code 基于规格和任务描述自动生成代码
4. 人工审核： 开发者审核 AI 生成的代码，确保质量和安全性

项目结构

dbview/
├── src/
│   ├── main/           # Electron 主进程
│   │   ├── db/         # 数据库驱动（4种）
│   │   ├── ipc/        # IPC 处理器
│   │   ├── services/   # 业务服务
│   │   └── store/      # 持久化存储
│   ├── preload/        # 安全桥接层
│   └── renderer/       # React 前端
│       ├── components/ # UI 组件
│       ├── layouts/    # 布局
│       ├── pages/      # 页面
│       ├── stores/     # 状态管理
│       ├── hooks/      # 自定义 Hook
│       ├── services/   # API 调用
│       ├── locales/    # 国际化
│       └── types/      # 类型定义
├── openspec/
│   ├── specs/          # 通用规格
│   └── changes/
│       └── dbview-v1/  # v1.0 版本规格
│           ├── design.md    # 设计文档
│           ├── proposal.md  # 变更提案
│           ├── tasks.md     # 任务列表
│           └── specs/       # 各功能规格
└── package.json

---

六、经验与反思

做得好的

• 驱动扩展架构设计合理： 工厂模式让新增数据库类型非常顺滑，每个驱动只需实现约定的接口即可接入
• IPC 分层清晰： 三层架构（Renderer → Preload → Main）让安全性和职责边界都很明确
• 规格驱动开发： OpenSpec 的规格先行策略大幅减少了开发中的返工

后续可以改进的

• 测试覆盖： 目前以功能实现为主，后续需要补充单元测试和集成测试
• 错误处理精细化： 部分场景的错误提示可以更友好
• 打包配置： Oracle 原生驱动（oracledb）和 SQLite（better-sqlite3）的打包需要特别处理

---

七、下期预告

下一期开发日志将深入讲解 数据库驱动架构设计与实现，包括：

• DatabaseDriver 接口的设计考量
• 四种数据库驱动的实现对比
• 查询取消机制的跨驱动实现
• 驱动测试策略

敬请期待！

---

DBView 开发日志系列 — 记录一个数据库可视化工具从 0 到 1 的完整历程