# dbtool-cli-v1 Rust 架构方案与执行计划

日期：2026-03-25  
作者：CTO

## 1. 当前真实落地情况

- Paperclip 中已经建立项目 `dbtool-cli-v1`，并已创建第一批工程 issue。
- 配置中的项目根目录是 `/workspace/repo/dbtool-cli-v1`，但截至今天该目录原本并不存在，说明代码仓库尚未真正初始化。
- 当前没有可验证的 Rust workspace、可执行 CLI、demo 数据、测试链路、发布链路或跨平台产物。
- 因此本阶段的真实状态不是“已有实现等待扩展”，而是“需求和任务已经拆出，但代码基线仍未落地”。

## 2. V1 工程目标

V1 只交付 CLI，不交付 GUI。CLI 必须覆盖：

- 连接 PostgreSQL、MySQL、SQLite
- 浏览 schema / table / column
- 执行临时查询
- 执行脚本
- 导出 CSV / JSON

当前阶段明确 gated：

- 完整桌面 GUI
- 插件系统
- 多进程或服务化架构
- 复杂 ORM / migration 编排

## 3. 推荐 Rust workspace 结构

```text
dbtool-cli-v1/
  Cargo.toml
  Cargo.lock
  README.md
  plans/
  backlog/
  apps/
    dbtool-cli/
      Cargo.toml
      src/
  crates/
    db-core/
      Cargo.toml
      src/
    db-drivers/
      Cargo.toml
      src/
    db-config/
      Cargo.toml
      src/
  examples/
    fixtures/
    scripts/
  .github/
    workflows/
```

### crate 边界

#### `apps/dbtool-cli`

- 命令行入口
- 参数解析
- 表格/文本输出
- 调用 `db-core` 用例
- 初期先承载导出命令编排，避免过早拆出额外 crate

#### `crates/db-core`

- 领域模型：连接配置、schema 树、查询请求/响应、导出请求
- 通用错误模型
- 驱动能力 trait
- 应用层用例：connect、inspect、query、run-script、export

#### `crates/db-drivers`

- PostgreSQL / MySQL / SQLite 的具体实现
- 对 `db-core` trait 的适配
- feature flag 控制三类数据库依赖
- 统一管理连接池、SQL 方言差异和 introspection SQL

#### `crates/db-config`

- 连接 profile
- DSN 解析
- 本地配置文件读写
- 环境变量覆盖逻辑

## 4. 驱动抽象策略

V1 不做插件化驱动系统，也不做单独驱动进程。采用“核心 trait + 三个内建实现”的最小可行方案。

### 建议抽象

- `DatabaseKind`
- `ConnectionProfile`
- `DatabaseDriver`
- `CatalogIntrospector`
- `QueryExecutor`

### 设计原则

- `db-core` 只定义能力和标准化返回结构，不依赖具体数据库类型。
- `db-drivers` 内部按 `postgres`、`mysql`、`sqlite` 模块实现，但对上层暴露统一入口。
- 不使用过度抽象的通用连接层来抹平所有数据库差异；差异应在驱动层显式处理并记录。
- 不把 CLI 输出格式、表格渲染、交互提示放进核心 crate。

### 技术选型

- 异步运行时：`tokio`
- CLI 参数：`clap`
- 数据库访问：优先采用 `sqlx`，因为它原生覆盖 PostgreSQL、MySQL、SQLite，能减少多套驱动栈带来的维护成本
- TLS：默认 `rustls`

备注：`sqlx` 当前官方仓库明确覆盖 PostgreSQL、MySQL、SQLite；打包链路可在仓库稳定后再接入 `cargo-dist`，当前不建议先引入额外发布复杂度。

## 5. 依赖关系与推进顺序

### Phase 0：建基线

1. 初始化 Rust workspace
2. 跑通 CLI 二进制和 `--help`
3. 建立基础 README、开发说明、样例目录

### Phase 1：建公共能力

1. 定义 `db-core` trait 与标准返回结构
2. 完成 `db-config`
3. 建立驱动 contract test 基座

### Phase 2：按数据库逐个接入

1. PostgreSQL
2. MySQL
3. SQLite

顺序理由：先做服务型主路径，再覆盖文件型数据库差异。

### Phase 3：补全导出与稳定性

1. CSV / JSON 导出
2. demo fixtures
3. smoke runbook
4. 跨平台打包

## 6. 测试策略

### 单元测试

- `db-config`：profile 解析、环境变量覆盖、路径处理
- `db-core`：查询参数、错误转换、导出请求校验

### contract test

- 对三种数据库复用同一组行为测试：
  - 连接成功
  - 连接失败
  - schema 列举
  - table 描述
  - 简单查询
  - 参数化查询
  - 导出

### 集成测试

- PostgreSQL / MySQL：使用容器启动测试实例
- SQLite：使用临时文件数据库

### CLI smoke test

- `dbtool connect`
- `dbtool inspect`
- `dbtool query`
- `dbtool export`

CLI 输出建议用 snapshot 测试保护，但只用于稳定文本输出，不替代行为测试。

## 7. 打包与发布策略

当前不需要“部署”，需要的是“发布可执行 CLI”。

### 第一阶段

- 先用 CI matrix 生成 macOS、Linux、Windows release binary
- 每个平台至少执行一次 `--help` smoke test
- 产出压缩包和 checksum

### 第二阶段

- 当命令面稳定后，再接入 `cargo-dist` 统一发布描述和产物整理

这个顺序比一开始就引入复杂发布工具更稳妥。

## 8. 前后端与 QA 第一轮职责

### 后端

- 初始化 workspace
- 定义核心抽象
- 按 PostgreSQL → MySQL → SQLite 顺序交付驱动
- 落地导出能力
- 建立打包流水线

### 前端

- 不做 GUI 实现
- 产出未来桌面端信息架构
- 明确连接管理、schema browser、query editor、results table 的交互边界
- 提前识别未来 GUI 对 CLI / core 层的契约要求

### QA

- 建立跨数据库验收矩阵
- 落地 demo fixtures 与 smoke runbook
- 对 connect / inspect / query / export 建可重复回归路径

## 9. 与现有 issue 的对应关系

### 已有 issue

- `CMP-4`：初始化 Rust workspace
- `CMP-5`：PostgreSQL
- `CMP-6`：MySQL
- `CMP-7`：SQLite
- `CMP-8`：CSV / JSON 导出
- `CMP-9`：未来 GUI 信息架构
- `CMP-10`：跨数据库验收矩阵
- `CMP-11`：里程碑、依赖图和交付跟踪

### 已补充的 issue

- `CMP-12`：CLI 打包、发布与跨平台 smoke 流水线
- `CMP-13`：demo 数据库、样例脚本与 smoke runbook

## 10. 当前关键风险

### P0

- 项目路径之前不存在，说明仓库尚未初始化，`CMP-4` 是所有实现工作的真实前置

### P1

- 产品范围文档 `CMP-2` 尚未完成前，部分命令细节和验收文字仍需与 PM 对齐
- 当前只有一名后端工程师，驱动接入和发布链路都压在同一人身上，关键路径较长

### P2

- 没有 demo fixtures 时，QA 和后续 smoke automation 难以尽早稳定

## 11. 招聘建议

当前先不建议立即扩编。

原因：

- 现阶段瓶颈是仓库初始化、架构收敛和第一条实现链路，不是人手数量
- 在 PostgreSQL 主链路和 CI/发布链路跑通前，新增工程师的边际收益有限

触发招聘的条件：

- `CMP-4` 到 `CMP-5` 跑通后，后端仍被 MySQL / SQLite / release pipeline 长时间阻塞
- 或 GUI 方向从“设计基线”升级为并行实现项目