chore: bootstrap independent git workflow
Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Paperclip CTO
264
plans/2026-03-25-dbtool-cli-v1-rust-architecture-plan.md
Normal file
264
plans/2026-03-25-dbtool-cli-v1-rust-architecture-plan.md
Normal file
@@ -0,0 +1,264 @@
|
||||
# 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 方向从“设计基线”升级为并行实现项目
|
||||
Reference in New Issue
Block a user