66 lines
2.4 KiB
Markdown
66 lines
2.4 KiB
Markdown
# @go/db
|
||
|
||
> **Maintainer Statement:** 本项目由 AI 维护。代码源自 github.com/ssgo/db 的重构，支持内存安全防护、读写分离及泛型优化。
|
||
|
||
## 🎯 设计哲学
|
||
|
||
`@go/db` 是一个极致精简、意图优先的数据库抽象层。它不试图取代 SQL，而是通过智能结果绑定与 SQL 自动化生成，消除数据库操作中的样板代码。
|
||
|
||
* **智能绑定**：根据结果容器类型（Struct/Map/Slice/BaseType）自动适配查询逻辑，无需手动 Scan。
|
||
* **内存防御**：集成 `go/safe`，数据库密码在内存中加密存储，使用时物理擦除。
|
||
* **读写分离**：内置连接池管理，支持配置多个只读节点实现自动负载均衡。
|
||
* **驱动透明**：统一 MySQL、PostgreSQL (pgx) 与 SQLite 的 API 差异。
|
||
|
||
## 📦 安装
|
||
|
||
```bash
|
||
go get apigo.cc/go/db
|
||
```
|
||
|
||
## 💡 快速开始
|
||
|
||
```go
|
||
import "apigo.cc/go/db"
|
||
import _ "apigo.cc/go/db/mysql" // 引入驱动
|
||
|
||
// 初始化连接
|
||
d := db.GetDB("mysql://user:pass@host:3306/dbname", nil)
|
||
|
||
// 1. 查询全部结果到 Struct 切片
|
||
var users []User
|
||
d.Query("SELECT * FROM users").To(&users)
|
||
|
||
// 2. 自动化插入
|
||
d.Insert("users", User{Name: "Star", Active: true})
|
||
|
||
// 3. 事务操作
|
||
tx := d.Begin()
|
||
tx.Exec("UPDATE balance SET amount = amount - 10 WHERE id = ?", 1)
|
||
tx.Commit()
|
||
```
|
||
|
||
## 🛠 API 指南
|
||
|
||
### 核心对象
|
||
- **`GetDB(setting string, logger *log.Logger) *DB`**: 通过 DSN 或配置名获取数据库实例。
|
||
- **`DB.Insert/Replace/Update/Delete`**: 自动生成 SQL 并执行，支持 Struct 与 Map。
|
||
- **`QueryResult.To(target any)`**: 将查询结果深度映射到目标容器。
|
||
- **`QueryResult.MapResults() []map[string]any`**: 快捷获取通用结果集。
|
||
|
||
### 结果容器适配规则
|
||
| 容器类型 | 行为 |
|
||
| :--- | :--- |
|
||
| `[]Struct` | 返回所有行，按字段名自动映射 |
|
||
| `Struct` | 返回第一行，按字段名自动映射 |
|
||
| `[]map[string]any` | 返回所有行，保留原始字段名 |
|
||
| `[]BaseType` | 返回所有行，仅取第一列 |
|
||
| `BaseType` | 返回第一行第一列 |
|
||
|
||
### 安全与高级特性
|
||
- **`SetEncryptKeys(key, iv []byte)`**: 配置全局敏感数据加密密钥。
|
||
- **读写分离**: 在 DSN 中配置 `host1,host2,host3`，首个为主库，其余为随机只读库。
|
||
- **SQLite 时间修复**: 自动处理 SQLite 毫秒级 `DATETIME` 格式与标准 `time.Time` 的转换。
|
||
|
||
## 🧪 验证状态
|
||
已通过 SQLite 集成测试。详见：[TEST.md](./TEST.md)
|