561 lines
15 KiB
Markdown
561 lines
15 KiB
Markdown
# StarDB
|
||
|
||
StarDB 是对 Go `database/sql` 的轻量封装，目标是把常见的数据库操作做得更直白：
|
||
- 少量 API 覆盖日常 CRUD、事务、批量写入、结构体映射。
|
||
- 兼容原生 `database/sql` 心智，不引入重量级依赖。
|
||
- 在可读性、可调试性和性能之间做实用平衡。
|
||
|
||
适合：
|
||
- 想保留 SQL 控制权，但不想反复写样板代码。
|
||
- 需要轻量 ORM 映射（不是全功能 ORM）。
|
||
- 需要在生产里追踪 SQL（可选 Hook + 慢 SQL 阈值）。
|
||
|
||
不适合：
|
||
- 需要完整领域模型关系管理、自动迁移、复杂查询 DSL 的项目。
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
go get b612.me/stardb
|
||
```
|
||
|
||
要求：
|
||
- Go `>= 1.16`
|
||
- 自行选择并导入数据库驱动（本库只封装 `database/sql`）
|
||
|
||
## 常见 DSN 示例
|
||
|
||
下面示例都可以直接用于 `db.Open(driver, dsn)`，替换为实际账号、密码、库名即可。
|
||
|
||
### MySQL（`github.com/go-sql-driver/mysql`）
|
||
|
||
```go
|
||
import _ "github.com/go-sql-driver/mysql"
|
||
|
||
dsn := "app:secret@tcp(127.0.0.1:3306)/demo?charset=utf8mb4&parseTime=true&loc=Local"
|
||
if err := db.Open("mysql", dsn); err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
```
|
||
|
||
常用参数说明：
|
||
- `charset=utf8mb4`：避免字符集问题。
|
||
- `parseTime=true`：把 `DATETIME/TIMESTAMP` 解析为 `time.Time`。
|
||
- `loc=Local`：指定时间解析时区（也可改成 `Asia/Shanghai`）。
|
||
|
||
### PostgreSQL（`github.com/lib/pq`）
|
||
|
||
```go
|
||
import _ "github.com/lib/pq"
|
||
|
||
dsn := "host=127.0.0.1 port=5432 user=postgres password=secret dbname=demo sslmode=disable"
|
||
if err := db.Open("postgres", dsn); err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
```
|
||
|
||
也可以用 URL 形式：
|
||
|
||
```go
|
||
urlDSN := "postgres://postgres:secret@127.0.0.1:5432/demo?sslmode=disable"
|
||
if err := db.Open("postgres", urlDSN); err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
```
|
||
|
||
### SQLite（`modernc.org/sqlite`）
|
||
|
||
```go
|
||
import _ "modernc.org/sqlite"
|
||
|
||
// 文件数据库
|
||
if err := db.Open("sqlite", "file:demo.db"); err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
|
||
// 内存数据库（适合测试）
|
||
if err := db.Open("sqlite", "file::memory:?cache=shared"); err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
```
|
||
|
||
Windows 路径建议使用 `file:C:/data/demo.db` 这种写法，跨平台更稳。
|
||
|
||
## 能力概览
|
||
|
||
| 能力 | 主要 API | 说明 |
|
||
|---|---|---|
|
||
| 连接与连接池 | `Open` `Close` `Ping` `SetPoolConfig` | 保留原生 `sql.DB` 用法 |
|
||
| 常规查询 | `Query` `QueryContext` | 自动解析为 `StarRows` |
|
||
| 流式查询 | `QueryRaw` `ScanEach` | 大结果集不必全量进内存 |
|
||
| 流式 ORM | `ScanEachORM` | 逐行映射结构体 |
|
||
| 安全取值 | `Get*` `GetNull*` | 明确错误与 NULL 语义 |
|
||
| 结构体 ORM | `rows.Orm` | 支持单个、切片、数组映射 |
|
||
| 命名参数 | `QueryX` `ExecX` | `:field` 绑定结构体字段 |
|
||
| 结构体写入 | `Insert` `Update` | 通过 `db` tag 生成 SQL |
|
||
| 批量写入 | `BatchInsert` `BatchInsertStructs` `SetBatchInsertMaxRows` `SetBatchInsertMaxParams` | 多行插入，支持按行数/参数阈值分片 |
|
||
| 事务 | `Begin/Commit/Rollback` `WithTx` | 手动或托管事务 |
|
||
| 可观测性 | `SetSQLHooks` `SetSQLSlowThreshold` `SetSQLFingerprintEnabled` `SetSQLFingerprintMode` `SetSQLFingerprintKeepComments` `SetSQLFingerprintCounterEnabled` `SQLFingerprintCounters` `ResetSQLFingerprintCounters` `SQLHookMetaFromContext` `BatchExecMetaFromContext` | Before/After Hook，默认关闭，支持指纹策略、命中计数与批量分片元信息 |
|
||
| 方言占位符 | `SetPlaceholderStyle` | `?` / `$1,$2...` |
|
||
| 查询构建 | `QueryBuilder` | 支持 `JOIN/GROUP BY/HAVING` |
|
||
|
||
## 场景选型
|
||
|
||
| 场景 | 首选 API | 说明 |
|
||
|---|---|---|
|
||
| 中小结果集查询 | `Query` + `rows.Orm` | 读取方便，开发效率高 |
|
||
| 大结果集查询 | `ScanEach` / `ScanEachORM` | 逐行处理，避免全量缓存 |
|
||
| 需要底层 `Scan` 控制 | `QueryRaw` | 直接返回 `*sql.Rows` |
|
||
| 批量写入 | `BatchInsert` + 分片阈值 | 控制单条 SQL 大小与参数数量 |
|
||
| SQL 可观测 | `SetSQLHooks` + `SetSQLSlowThreshold` + 指纹配置 | 支持慢 SQL、指纹、分片元信息 |
|
||
|
||
## 快速开始
|
||
|
||
```go
|
||
package main
|
||
|
||
import (
|
||
"log"
|
||
|
||
"b612.me/stardb"
|
||
_ "modernc.org/sqlite"
|
||
)
|
||
|
||
type User struct {
|
||
ID int64 `db:"id"`
|
||
Name string `db:"name"`
|
||
Age int `db:"age"`
|
||
}
|
||
|
||
func main() {
|
||
db := stardb.NewStarDB()
|
||
if err := db.Open("sqlite", "test.db"); err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
defer db.Close()
|
||
|
||
rows, err := db.Query("SELECT id, name, age FROM users WHERE age >= ?", 18)
|
||
if err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
defer rows.Close()
|
||
|
||
var users []User
|
||
if err := rows.Orm(&users); err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
|
||
log.Printf("users: %d", len(users))
|
||
}
|
||
```
|
||
|
||
## 接入流程
|
||
|
||
按下面顺序接入，可在开发阶段先固定运行边界：
|
||
|
||
1. 建立连接并设置连接池。
|
||
2. 在查询路径中区分内存模式与流式模式。
|
||
3. 在批量写入路径设置分片阈值（按行数和参数数）。
|
||
4. 启用 SQL Hook、慢 SQL 阈值、指纹策略。
|
||
5. 在调用侧统一使用 `errors.Is` 判定错误类别。
|
||
|
||
一个常用初始化示例：
|
||
|
||
```go
|
||
db := stardb.NewStarDB()
|
||
if err := db.Open("mysql", dsn); err != nil {
|
||
return err
|
||
}
|
||
|
||
db.SetPoolConfig(&stardb.PoolConfig{
|
||
MaxOpenConns: 25,
|
||
MaxIdleConns: 5,
|
||
ConnMaxLifetime: time.Hour,
|
||
ConnMaxIdleTime: 10 * time.Minute,
|
||
})
|
||
|
||
db.SetBatchInsertMaxRows(500)
|
||
db.SetBatchInsertMaxParams(60000)
|
||
|
||
db.SetSQLSlowThreshold(200 * time.Millisecond)
|
||
db.SetSQLFingerprintEnabled(true)
|
||
db.SetSQLFingerprintMode(stardb.SQLFingerprintMaskLiterals)
|
||
db.SetSQLFingerprintKeepComments(false)
|
||
```
|
||
|
||
## API 指南
|
||
|
||
### 1) 连接与连接池
|
||
|
||
```go
|
||
db := stardb.NewStarDB()
|
||
_ = db.Open("mysql", "user:pass@tcp(localhost:3306)/app")
|
||
|
||
db.SetPoolConfig(&stardb.PoolConfig{
|
||
MaxOpenConns: 25,
|
||
MaxIdleConns: 5,
|
||
ConnMaxLifetime: time.Hour,
|
||
ConnMaxIdleTime: 10 * time.Minute,
|
||
})
|
||
```
|
||
|
||
也可以直接拿到底层连接：
|
||
|
||
```go
|
||
raw := db.DB()
|
||
raw.SetMaxOpenConns(50)
|
||
```
|
||
|
||
### 2) 三种查询模式
|
||
|
||
#### A. 内存模式（默认）
|
||
|
||
`Query` 会把结果解析为 `StarRows`，适合中小结果集：
|
||
|
||
```go
|
||
rows, err := db.Query("SELECT * FROM users WHERE active = ?", true)
|
||
if err != nil { /* ... */ }
|
||
defer rows.Close()
|
||
|
||
for i := 0; i < rows.Length(); i++ {
|
||
row := rows.Row(i)
|
||
_ = row.MustString("name")
|
||
}
|
||
```
|
||
|
||
#### B. 原生流式模式
|
||
|
||
`QueryRaw` 返回 `*sql.Rows`，完全按原生 `Scan` 处理：
|
||
|
||
```go
|
||
rawRows, err := db.QueryRaw("SELECT id, name FROM users")
|
||
if err != nil { /* ... */ }
|
||
defer rawRows.Close()
|
||
```
|
||
|
||
#### C. 回调流式模式（常用）
|
||
|
||
`ScanEach` 逐行回调，避免全量缓存：
|
||
|
||
关闭内存预读时，使用 `QueryRaw` / `ScanEach` / `ScanEachORM`，不使用 `Query`。
|
||
|
||
```go
|
||
err := db.ScanEach("SELECT id, name FROM users", func(row *stardb.StarResult) error {
|
||
id := row.MustInt64("id")
|
||
name := row.MustString("name")
|
||
_ = id
|
||
_ = name
|
||
return nil
|
||
})
|
||
```
|
||
|
||
可通过 `stardb.ErrScanStopped` 提前终止：
|
||
|
||
```go
|
||
count := 0
|
||
_ = db.ScanEach("SELECT * FROM users", func(row *stardb.StarResult) error {
|
||
count++
|
||
if count >= 1000 {
|
||
return stardb.ErrScanStopped
|
||
}
|
||
return nil
|
||
})
|
||
```
|
||
|
||
### 3) 流式 ORM（逐行映射）
|
||
|
||
`ScanEachORM` 将每行映射到结构体，再回调。
|
||
|
||
```go
|
||
var model User
|
||
var users []User
|
||
|
||
err := db.ScanEachORM("SELECT id, name, age FROM users", &model, func(target interface{}) error {
|
||
u := *(target.(*User)) // 注意拷贝一份，target 会被复用
|
||
users = append(users, u)
|
||
return nil
|
||
})
|
||
```
|
||
|
||
同样支持 `Tx` / `Stmt`：
|
||
- `tx.ScanEachORM(...)`
|
||
- `stmt.ScanEachORM(...)`
|
||
|
||
### 4) 结果读取与 NULL 语义
|
||
|
||
#### Must 系列（无错误，失败给零值）
|
||
- `MustString` `MustInt64` `MustFloat64` `MustBool` ...
|
||
|
||
#### 安全系列（带错误）
|
||
- `GetString` `GetInt64` `GetFloat64`
|
||
- `GetNullString` `GetNullInt64` `GetNullFloat64` `GetNullBool` `GetNullTime`
|
||
|
||
```go
|
||
name, err := row.GetString("name")
|
||
age, err := row.GetNullInt64("age")
|
||
if age.Valid {
|
||
// use age.Int64
|
||
}
|
||
```
|
||
|
||
### 5) ORM 映射
|
||
|
||
```go
|
||
type User struct {
|
||
ID int64 `db:"id"`
|
||
Name string `db:"name"`
|
||
}
|
||
|
||
var u User
|
||
_ = rows.Orm(&u)
|
||
|
||
var list []User
|
||
_ = rows.Orm(&list)
|
||
```
|
||
|
||
严格列检查（字段/SQL 变更敏感场景可开启）：
|
||
|
||
```go
|
||
db.SetStrictORM(true)
|
||
```
|
||
|
||
若结构体 tag 大范围调整，可清理反射缓存：
|
||
|
||
```go
|
||
stardb.ClearReflectCache()
|
||
```
|
||
|
||
### 6) 命名参数绑定
|
||
|
||
```go
|
||
type Filter struct {
|
||
Name string `db:"name"`
|
||
MinAge int `db:"min_age"`
|
||
}
|
||
|
||
f := Filter{Name: "Alice", MinAge: 18}
|
||
rows, err := db.QueryX(&f,
|
||
"SELECT * FROM users WHERE name = ? AND age >= ?",
|
||
":name", ":min_age")
|
||
```
|
||
|
||
### 7) 写入能力
|
||
|
||
#### Insert / Update
|
||
|
||
```go
|
||
_, _ = db.Insert(&user, "users", "id") // id 作为自增字段跳过
|
||
_, _ = db.Update(&user, "users", "id") // id 作为主键
|
||
```
|
||
|
||
#### BatchInsert
|
||
|
||
```go
|
||
columns := []string{"name", "email", "age"}
|
||
values := [][]interface{}{
|
||
{"Alice", "alice@example.com", 25},
|
||
{"Bob", "bob@example.com", 30},
|
||
}
|
||
_, _ = db.BatchInsert("users", columns, values)
|
||
```
|
||
|
||
如需避免单条 SQL 过大（参数过多），可打开分片：
|
||
|
||
```go
|
||
db.SetBatchInsertMaxRows(500) // 0 或负数表示关闭分片（默认）
|
||
db.SetBatchInsertMaxParams(60000) // 0 表示自动识别常见驱动参数上限
|
||
```
|
||
|
||
分片模式下会在一个事务里按块执行，避免部分写入成功。
|
||
自动识别当前覆盖：SQLite `999`、PostgreSQL `65535`、MySQL `65535`、SQL Server `2100`。
|
||
|
||
分片行为细节：
|
||
- 分片阈值按更严格条件生效：`min(maxRows, maxParams/列数)`（忽略未设置项）。
|
||
- 分片关闭条件：`maxRows <= 0` 且 `maxParams <= 0` 且未命中驱动自动阈值。
|
||
- 分片执行失败会回滚整个批次。
|
||
- 分片结果语义：
|
||
- `RowsAffected()` 返回所有分片累计值。
|
||
- `LastInsertId()` 返回最后一个分片的 insert id。
|
||
|
||
#### BatchInsertStructs
|
||
|
||
```go
|
||
users := []User{{Name: "Alice"}, {Name: "Bob"}}
|
||
_, _ = db.BatchInsertStructs("users", users, "id")
|
||
```
|
||
|
||
### 8) 事务
|
||
|
||
#### 手动事务
|
||
|
||
```go
|
||
tx, err := db.Begin()
|
||
if err != nil { /* ... */ }
|
||
defer tx.Rollback()
|
||
|
||
if _, err := tx.Exec("UPDATE users SET age = age + 1 WHERE id = ?", 1); err != nil {
|
||
return err
|
||
}
|
||
return tx.Commit()
|
||
```
|
||
|
||
#### 托管事务（常用）
|
||
|
||
```go
|
||
err := db.WithTx(func(tx *stardb.StarTx) error {
|
||
if _, err := tx.Exec("UPDATE users SET age = ? WHERE id = ?", 26, 1); err != nil {
|
||
return err
|
||
}
|
||
if _, err := tx.Exec("INSERT INTO logs (msg) VALUES (?)", "age updated"); err != nil {
|
||
return err
|
||
}
|
||
return nil
|
||
})
|
||
```
|
||
|
||
`WithTx` 规则：
|
||
- `fn` 返回 `nil` -> `Commit`
|
||
- `fn` 返回错误 -> `Rollback`
|
||
- `fn` panic -> `Rollback` 后继续抛出 panic
|
||
|
||
### 9) SQL Hook 与慢 SQL 阈值
|
||
|
||
默认关闭；仅在显式设置时生效。
|
||
|
||
```go
|
||
db.SetSQLSlowThreshold(200 * time.Millisecond)
|
||
db.SetSQLFingerprintEnabled(true) // 可选：在 Hook context 附带 SQL 指纹
|
||
db.SetSQLFingerprintMode(stardb.SQLFingerprintMaskLiterals) // 可选：指纹里脱敏数字/字符串字面量
|
||
db.SetSQLFingerprintKeepComments(false) // 默认 false：指纹不保留 SQL 注释
|
||
db.SetSQLFingerprintCounterEnabled(true) // 可选：记录指纹命中次数（内存级）
|
||
|
||
db.SetSQLHooks(
|
||
func(ctx context.Context, query string, args []interface{}) {
|
||
// before
|
||
},
|
||
func(ctx context.Context, query string, args []interface{}, d time.Duration, err error) {
|
||
// after
|
||
if hookMeta, ok := stardb.SQLHookMetaFromContext(ctx); ok {
|
||
_ = hookMeta.Fingerprint
|
||
}
|
||
if meta, ok := stardb.BatchExecMetaFromContext(ctx); ok {
|
||
// chunked batch insert metadata
|
||
// meta.ChunkIndex / meta.ChunkCount / meta.ChunkRows ...
|
||
}
|
||
},
|
||
)
|
||
```
|
||
|
||
阈值行为：
|
||
- `threshold <= 0`：`After` 每次都触发
|
||
- `threshold > 0`：仅在“慢于阈值”或“执行出错”时触发
|
||
- 打开 `SetSQLFingerprintEnabled(true)` 后，可从 `SQLHookMetaFromContext` 获取 SQL 指纹
|
||
- 指纹模式：`SQLFingerprintBasic`（默认，仅归一化）/ `SQLFingerprintMaskLiterals`（归一化 + 字面量脱敏）
|
||
- `SetSQLFingerprintKeepComments(true)` 可保留注释文本（默认关闭，利于聚合）
|
||
- `SetSQLFingerprintCounterEnabled(true)` 后，可通过 `SQLFingerprintCounters()` 查看命中次数，`ResetSQLFingerprintCounters()` 清空
|
||
- 若是分片批量写入，Hook 可通过 `BatchExecMetaFromContext` 读取分片元信息
|
||
|
||
Hook 上下文字段说明：
|
||
- `SQLHookMetaFromContext(ctx)`：
|
||
- `Fingerprint`：按配置生成的 SQL 指纹。
|
||
- `BatchExecMetaFromContext(ctx)`（仅分片批量写入）：
|
||
- `ChunkIndex`：当前分片序号（从 1 开始）
|
||
- `ChunkCount`：总分片数
|
||
- `ChunkRows`：当前分片行数
|
||
- `TotalRows`：本次批量总行数
|
||
- `ColumnCount`：本次写入列数
|
||
|
||
### 10) 占位符方言
|
||
|
||
```go
|
||
db.SetPlaceholderStyle(stardb.PlaceholderQuestion) // 默认
|
||
// 或
|
||
db.SetPlaceholderStyle(stardb.PlaceholderDollar) // ? -> $1,$2...
|
||
```
|
||
|
||
### 11) QueryBuilder
|
||
|
||
```go
|
||
query, args := stardb.NewQueryBuilder("users u").
|
||
Select("u.id", "u.name", "COUNT(o.id) AS order_count").
|
||
Join("LEFT JOIN orders o ON o.user_id = u.id").
|
||
Where("u.active = ?", true).
|
||
GroupBy("u.id", "u.name").
|
||
Having("COUNT(o.id) > ?", 2).
|
||
OrderBy("order_count DESC").
|
||
Limit(20).
|
||
Offset(0).
|
||
Build()
|
||
|
||
_ = query
|
||
_ = args
|
||
```
|
||
|
||
## 错误处理
|
||
|
||
库内置可判定错误，调用侧使用 `errors.Is` 做分支处理：
|
||
|
||
```go
|
||
if errors.Is(err, stardb.ErrDBNotInitialized) {
|
||
// 未初始化
|
||
}
|
||
if errors.Is(err, stardb.ErrColumnNotFound) {
|
||
// 字段/列不匹配
|
||
}
|
||
if errors.Is(err, stardb.ErrNoInsertValues) {
|
||
// 批量插入空数据
|
||
}
|
||
```
|
||
|
||
常见错误类别：
|
||
- 生命周期：`ErrDBNotInitialized` `ErrTxNotInitialized` `ErrStmtNotInitialized`
|
||
- 参数校验：`ErrQueryEmpty` `ErrTargetNil` `ErrTargetNotPointer` ...
|
||
- 映射问题：`ErrColumnNotFound` `ErrFieldNotFound`
|
||
- 批量写入：`ErrNoInsertColumns` `ErrNoInsertValues` `ErrBatchRowValueCountMismatch`
|
||
- 流式回调：`ErrScanFuncNil` `ErrScanORMFuncNil`
|
||
|
||
## 使用边界
|
||
|
||
1. 这是轻量封装，不是全功能 ORM。
|
||
- 不做模型关系管理（has-many/association）
|
||
- 不做自动迁移
|
||
- 不做复杂查询 DSL
|
||
|
||
2. 大结果集优先用流式 API。
|
||
- `Query` 适合中小结果集
|
||
- `ScanEach` / `ScanEachORM` 更稳
|
||
|
||
3. 日志 Hook 按需打开。
|
||
- 生产环境最好配合慢 SQL 阈值，减少噪音
|
||
|
||
4. `ScanEachORM` 回调里的 target 会复用。
|
||
- 需要持久化时请拷贝结构体值
|
||
|
||
## 测试、竞态与基准
|
||
|
||
```bash
|
||
# 根模块
|
||
go test ./...
|
||
|
||
go test -race ./...
|
||
|
||
go test -run ^$ -bench BenchmarkQueryBuilder_ -benchmem ./...
|
||
|
||
# testing 子模块（集成测试/基准）
|
||
cd testing
|
||
go test ./...
|
||
go test -race ./...
|
||
go test -run ^$ -bench "Benchmark(QueryX|Orm|ScanEach|BatchInsert)" -benchmem
|
||
```
|
||
|
||
## 支持数据库驱动
|
||
|
||
本库兼容所有实现 `database/sql` 的驱动。常见示例：
|
||
- SQLite: `_ "modernc.org/sqlite"`
|
||
- MySQL: `_ "github.com/go-sql-driver/mysql"`
|
||
- PostgreSQL: `_ "github.com/lib/pq"`
|
||
|
||
## License
|
||
|
||
Apache License 2.0
|