第一章：项目概述

本章介绍 VSDB 项目的整体定位、功能特性、技术选型和项目结构。

1.1 项目定位

VSDB 是一个为 Visual Studio Code 设计的全功能数据库客户端扩展。它的核心目标是：

graph TD
    A["VSDB 核心目标"] --> B["一体化数据库管理"]
    A --> C["开发效率提升"]
    A --> D["稳定性保障"]
    A --> E["安全性保证"]
    
    B --> B1["连接管理"]
    B --> B2["结构浏览"]
    B --> B3["数据编辑"]
    B --> B4["SQL执行"]
    
    C --> C1["自动扫描连接"]
    C --> C2["无需切换工具"]
    
    D --> D1["双进程架构"]
    D --> D2["自动恢复"]
    
    E --> E1["SecretStorage"]
    E --> E2["无明文存储"]

与竞品的定位差异

特性	DataGrip	VSDB	DBeaver
独立应用	✓	✗	✓
VSCode 集成	✗	✓	✗
自动扫描	✗	✓	✗
轻量	✗	✓	✗
功能完整度	★★★★★	★★★☆☆	★★★★★
学习成本	中	低	中

VSDB 选择轻量集成路线，牺牲部分高级功能换取无缝的 VSCode 体验。

1.2 功能特性

连接管理

// 核心功能：连接 CRUD
interface ConnectionFeatures {
  add: '手动添加连接';
  scan: '自动扫描项目配置';
  edit: '编辑连接属性';
  delete: '删除连接';
  group: '连接分组';
  color: '颜色标记';
  scope: '项目级/全局';
}

支持的扫描来源：

来源	文件	解析内容
`.env`	`.env`, `.env.local`, `.env.development`	`DATABASE_URL`, `DB_`, `MYSQL_`, `PG_*`
`docker-compose`	`docker-compose.yml`	MySQL/PostgreSQL 服务定义
TypeORM	`ormconfig.json`, `data-source.ts`	连接配置对象
Laravel	`config/database.php`	MySQL/PG 连接数组
Django	`settings.py`	`DATABASES` 字典
Prisma	`schema.prisma`	数据库 URL

数据库浏览

graph TD
    A["连接节点"] --> B["数据库列表"]
    B --> C["表列表"]
    C --> D["列信息"]
    
    B --> E["视图列表"]
    B --> F["存储过程"]
    
    D --> G["类型"]
    D --> H["是否NULL"]
    D --> I["默认值"]
    D --> J["主键"]
    D --> K["自增"]
    
    C --> L["索引"]
    C --> M["约束"]
    C --> N["触发器"]

SQL 编辑器

Monaco 编辑器集成，语法高亮
SQL 关键字自动补全
Ctrl+Enter 快速执行
多结果标签页
执行状态指示

数据操作

graph LR
    subgraph "查询执行"
        Q1["普通查询"]
        Q2["流式查询<br/>(大数据集)"]
    end
    
    subgraph "结果处理"
        R1["分页显示"]
        R2["内联编辑"]
        R3["虚拟滚动"]
    end
    
    subgraph "导入导出"
        E1["CSV"]
        E2["JSON"]
        E3["SQL"]
    end
    
    Q1 --> R1
    Q2 --> R3
    R1 --> E1
    R1 --> E2
    R1 --> E3

辅助功能

查询历史：记录执行的 SQL，支持固定防清理
书签系统：收藏连接、表、查询，支持分组
全局搜索：搜索表名、列名、数据内容

1.3 技术选型

语言与框架

语言: TypeScript
扩展框架: VSCode Extension API
前端框架: React + Vite
编辑器: Monaco Editor
数据库驱动: mysql2 / pg
构建工具: webpack (扩展) + Vite (Webview)
测试框架: Vitest

选型决策记录

决策点	选择	理由
双进程 vs 单进程	双进程	数据库操作隔离，崩溃不影响 VSCode
Worker 通信	child_process IPC	原生支持，无需额外依赖
前端框架	React	Webview 标准方案，生态丰富
编辑器	Monaco	VSCode 同款，语法支持完善
数据库驱动	mysql2 / pg	纯 JS 实现，支持 Promise
流式传输	自定义 chunk	避免大数据集阻塞 IPC

为什么选择 TypeScript

graph TD
    A["TypeScript"] --> B["类型安全"]
    A --> C["VSCode 原生"]
    A --> D["生态丰富"]
    
    B --> B1["IPC协议类型化"]
    B --> B2["配置验证"]
    
    C --> C1["调试支持"]
    C --> C2["开发体验"]
    
    D --> D1["数据库驱动"]
    D --> D2["UI 框架"]

1.4 项目结构

vsdb/
├── src/                    # 扩展源代码
│   ├── extension.ts        # 扩展入口，命令注册
│   ├── core/               # 核心管理模块
│   │   ├── connectionManager.ts  # 连接 CRUD
│   │   ├── ipcManager.ts        # Worker 通信
│   │   ├── storage.ts           # 配置存储
│   │   ├── scanner.ts           # 扫描协调器
│   │   ├── historyManager.ts    # 查询历史
│   │   ├── bookmarkManager.ts   # 书签管理
│   │   └── searchEngine.ts      # 全局搜索
│   ├── scanner/            # 配置解析器
│   │   ├── envParser.ts          # .env 解析
│   │   ├── dockerComposeParser.ts # docker-compose 解析
│   │   └eworkParser.ts           # 框架配置解析
│   ├── shared/             # 共享类型和常量
│   │   ├── types.ts              # 类型定义
│   │   ├── constants.ts          # 常量定义
│   ├── ui/                 # UI 层
│   │   ├── tree/                 # TreeView
│   │   │   ├── treeProvider.ts   # 树数据提供者
│   │   │   ├── treeItems.ts      # 树节点类型
│   │   │   └commands.ts          # 树命令
│   │   ├── webview/              # Webview Panel
│   │   │   ├── sqlEditor.ts      # SQL 编辑器
│   │   │   ├── dataGrid.ts       # 数据网格
│   │   │   ├── connectionForm.ts # 连接表单
│   │   │   ├── tableStructure.ts # 表结构面板
│   │   │   ├── importExport.ts   # 导入导出
│   ├── worker/             # Worker 进程
│   │   ├── worker.ts             # Worker 入口
│   │   ├── driver/               # 数据库驱动
│   │   │   ├── mysql.ts          # MySQL 驱动
│   │   │   ├── postgresql.ts     # PostgreSQL 驱动
│   │   │   ├── schema/           # Schema Inspector
│   │   │   ├── mysqlSchema.ts    # MySQL Schema
│   │   │   ├── pgSchema.ts       # PostgreSQL Schema
│   │   ├── queryQueue.ts         # 查询队列
├── webview-ui/             # Webview React 应用
│   ├── src/
│   │   ├── App.tsx              # 入口组件
│   │   ├── main.tsx             # React 入口
│   │   ├── components/
│   │   │   ├── SqlEditor.tsx    # SQL 编辑器组件
│   │   │   ├── DataGrid.tsx     # 数据网格组件
│   │   │   ├── GridToolbar.tsx  # 工具栏
│   │   │   ├── ResultPanel.tsx  # 结果面板
│   │   │   ├── ImportExport.tsx # 导入导出组件
│   ├── package.json
│   ├── vite.config.ts
├── __tests__/              # 测试目录
│   ├── core/
│   │   ├── ipcManager.test.ts
│   │   ├── connectionManager.test.ts
│   ├── scanner/
│   │   ├── envParser.test.ts
│   ├── fixtures/
│   │   ├── config/
│   │   │   ├── database.yml
│   │   │   ├── ormconfig.json
│   │   ├── docker-compose.yaml
├── dist/                   # 构建输出
├── resources/              # 资源文件 (图标等)
├── docs/                   # 设计文档
├── package.json            # 扩展配置
├── tsconfig.json           # TypeScript 配置
├── webpack.config.js       # webpack 配置
├── vite.config.ts          # Vite 配置
└── CLAUDE.md               # Claude Code 指导文件

1.5 关键文件说明

入口文件

文件	作用
`src/extension.ts`	扩展入口，注册命令、视图、初始化管理器
`src/worker/worker.ts`	Worker 入口，处理 IPC 消息，路由到驱动

核心管理器

文件	作用
`src/core/connectionManager.ts`	连接 CRUD，项目级/全局存储协调
`src/core/ipcManager.ts`	Worker 生命周期，请求/响应匹配，崩溃恢复
`src/core/storage.ts`	JSON 文件存储 + SecretStorage
`src/core/scanner.ts`	协调多个 Parser 执行扫描

类型定义

文件	作用
`src/shared/types.ts`	所有接口定义：DbConnection, WorkerRequest, QueryResult 等
`src/shared/constants.ts`	常量：默认端口、命令 ID、视图 ID

1.6 构建与开发

构建命令

# 生产构建
npm run compile

# 开发监听
npm run watch

# 构建 Webview
npm run build:webview

# 运行测试
npm run test

# 测试监听
npm run test:watch

# Lint
npm run lint

# 打包扩展
vsce package

开发流程

graph TD
    A["克隆项目"] --> B["npm install"]
    B --> C["npm run compile"]
    C --> D["cd webview-ui && npm install"]
    D --> E["npm run build"]
    E --> F["F5 启动调试"]
    
    F --> G["修改代码"]
    G --> H{"Webview 变更?"}
    H -->|是| I["rebuild webview"]
    H -->|否| J["自动重编译"]
    I --> K["刷新 Webview"]
    J --> K
    K --> G

调试配置

.vscode/launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Run Extension",
      "type": "extensionHost",
      "request": "launch",
      "runtimeExecutable": "${execPath}",
      "args": ["--extensionDevelopmentPath=${workspaceFolder}"]
    }
  ]
}

1.7 小结

本章介绍了 VSDB 的：

定位：VSCode 内的轻量数据库客户端
功能：连接管理、结构浏览、SQL 编辑、数据操作
技术选型：TypeScript + 双进程架构 + React Webview
项目结构：核心模块、扫描引擎、Worker、UI 层

下一章将深入介绍核心概念和数据模型。

Keyboard shortcuts

VSDB 技术文档