what
82f57deec8
老代码库（git.fsdpf.net/go/db 现在的 master）用的是链式字符串拼接的 db.Builder， 这个仓库是另开的新项目，架构 fork 自 doug-martin/goqu（表达式树 + 方言渲染）， 两边历史不相关。记录当前仓库的整体能力（SelectDataset 系列、exp 表达式树、 engine 连接管理、schema 建表迁移），并说明还在用老 API 的项目应该去 v1-legacy 分支。
51 lines
3.1 KiB
Markdown
51 lines
3.1 KiB
Markdown
# git.fsdpf.net/go/db（master）
|
||
|
||
数据库访问层，架构上 fork 自 [doug-martin/goqu](https://github.com/doug-martin/goqu)：不是链式
|
||
拼字符串的 Builder，而是先构造一棵 `exp` 表达式树，再由方言（dialect）相关的 `sqlgen` 渲染成
|
||
具体 SQL + 绑定参数。配合 `req-v2`/`orm-v2` 等 "-v2" 系列项目使用。
|
||
|
||
## 这个仓库有什么
|
||
|
||
### 查询构造：`SelectDataset`/`InsertDataset`/`UpdateDataset`/`DeleteDataset`
|
||
|
||
- `db.From(table ...interface{}) *SelectDataset`：起一个查询，`.Select(...)`/`.Where(...)`/
|
||
`.Join(...)`/`.GroupBy(...)`/`.Order(...)` 等链式方法都是在往同一棵表达式树上追加/替换子句
|
||
（`Clauses`），不是拼字符串，所以中间状态可以安全地复制、按条件分支修改。
|
||
- `Executor()`/`ScanStructs`/`ScanStruct`/`GetRecords()`：真正执行查询、把结果扫进结构体或
|
||
`map[string]any`。`ToSQL()` 只生成 SQL 文本，不落库，方便测试断言/调试。
|
||
- `.WithHook(hook)`：给这次查询挂一个 `exec.Hooks` 实现（`Before`/`After` 两个阶段），这是
|
||
`req-v2/resx` 包用来做字段级脱敏、行级权限过滤、变更留痕的挂载点——`db-v2` 本身不关心权限，
|
||
只提供"查询执行前后可以介入改写"这个机制。
|
||
|
||
### 表达式树：`exp` 包
|
||
|
||
- `exp.IdentifierExpression`（`db.I`/`db.C`/`db.T`，标识符：列/表/schema）、
|
||
`exp.LiteralExpression`（`db.L`/`db.V`，字面量/原样 SQL 片段）、
|
||
`exp.AliasedExpression`（`.As(...)`）、`exp.SQLFunctionExpression`（`db.Func`/`db.COUNT`/
|
||
`db.COALESCE` 等聚合与常用函数）、`exp.CaseExpression`（`db.Case()`）、
|
||
`exp.WindowExpression`（`db.W()`，窗口函数）。
|
||
- 这棵树是 immutable/copy-on-write 风格的：每次链式调用返回新的（或者原地更新的）`Clauses`，
|
||
不会有隐式的跨查询共享状态问题。
|
||
|
||
### 连接与方言
|
||
|
||
- `engine.Engine`：多连接管理，`engine.Open(cfgs map[string]DBConfig)` 从配置建立连接池，
|
||
`engine.Mock(cfgs map[string]MockDBConfig)` 用 `sqlmock` 建 mock 连接（测试专用）；
|
||
`Engine.Connection(name string) *db.Database` 按连接名取出可以直接 `.From(...)` 发查询的
|
||
`*db.Database`。
|
||
- `dialect/mysql`/`dialect/sqlite3`/`dialect/duckdb`：具体方言实现，通过 `import _
|
||
"git.fsdpf.net/go/db/dialect/mysql"` 这种匿名 import 注册进 `sqlgen`，不用的方言不用编译进去。
|
||
- `dialect/sqlite3/vtab`：SQLite 虚拟表（Virtual Table）支持，给需要把非关系数据源伪装成表的
|
||
场景用（`sqlite3`/`vtable` build tag 控制是否编译）。
|
||
|
||
### 建表/迁移：`schema` 包
|
||
|
||
- `schema.Blueprint`/`ColumnDefinition`：描述表结构（列类型、长度、默认值、可空性等），
|
||
`schema/dialect/*` 按方言生成 `CREATE TABLE`/`ALTER TABLE` 语句。
|
||
|
||
## 分支状态
|
||
|
||
`master` 是持续开发中的新架构，**跟老仓库 `v1-legacy` 分支历史不相关**（`db-v2` 是另开的新
|
||
项目，不是从老代码库演化过来的），API 完全不兼容。还在用老版 `db.Builder`（`Table`/`Find`/
|
||
`Paginate`/`Chunk` 那一套）的老项目，参见 `v1-legacy` 分支。
|