hoteas
6b689f3a1b
- 在 .gitignore 中添加调试日志文件的忽略规则，避免不必要的调试信息被提交 - 修改 application.go 中的 stdout 重定向逻辑，使用 log.CaptureStream 以支持更灵活的日志捕获 - 更新 README 文档，增加对日志重定向功能的说明
215 lines
7.8 KiB
Markdown
215 lines
7.8 KiB
Markdown
# HoTimeDB API 快速参考
|
||
|
||
完整教程见 [HoTimeDB 使用说明](HoTimeDB_使用说明.md)。本文仅收录条件运算符与方法签名速查。
|
||
|
||
---
|
||
|
||
## 条件运算符
|
||
|
||
多条件默认 AND；关键字大小写均可（`ORDER`/`order`）。
|
||
|
||
| 写法 | SQL | 说明 |
|
||
|------|-----|------|
|
||
| `"field": value` | `field = ?` | 等于 |
|
||
| `"field[!]": value` | `field != ?` | 不等于 |
|
||
| `"field[>]": value` | `field > ?` | 大于 |
|
||
| `"field[>=]": value` | `field >= ?` | 大于等于 |
|
||
| `"field[<]": value` | `field < ?` | 小于 |
|
||
| `"field[<=]": value` | `field <= ?` | 小于等于 |
|
||
| `"field[~]": "kw"` | `LIKE '%kw%'` | 包含 |
|
||
| `"field[~!]": "kw"` | `LIKE 'kw%'` | 开头 |
|
||
| `"field[!~]": "kw"` | `LIKE '%kw'` | 结尾 |
|
||
| `"field[~~]": "%kw%"` | `LIKE '%kw%'` | 手动 LIKE |
|
||
| `"field[<>]": [min,max]` | `BETWEEN ? AND ?` | 区间内 |
|
||
| `"field[><]": [min,max]` | `NOT BETWEEN` | 区间外 |
|
||
| `"field": [v1,v2]` | `IN (?,?)` | 集合 |
|
||
| `"field[!]": [v1,v2]` | `NOT IN` | 非集合 |
|
||
| `"field": nil` | `IS NULL` | 空 |
|
||
| `"field[!]": nil` | `IS NOT NULL` | 非空 |
|
||
| `"field[#]": "balance+1"` | `field = balance+1` | 直接表达式 |
|
||
| `"[##]": "a > b"` | `a > b` | 直接 SQL 片段 |
|
||
| `"field[#!]": "1"` | `field != 1` | 非参数化不等 |
|
||
|
||
时间字段推荐 Go 侧传值：`"create_time": Time2Str(time.Now())`（勿用 `NOW()`）。
|
||
|
||
### 逻辑与特殊关键字
|
||
|
||
```go
|
||
Map{"status": 1, "age[>]": 18} // 自动 AND
|
||
Map{"AND": Map{...}} / Map{"OR": Map{...}} // 显式逻辑
|
||
Map{"AND": Map{"status": 1, "OR": Map{...}}} // 嵌套
|
||
Map{"ORDER": "id DESC"} / []string{"a DESC","b"} // ORDER BY
|
||
Map{"GROUP": "dept"} / []string{"a","b"} // GROUP BY
|
||
Map{"HAVING": Map{"COUNT(*).[>]": 5}} // HAVING
|
||
Map{"LIMIT": 20} / []int{10, 20} // LIMIT / offset+limit
|
||
Map{"OFFSET": 20} // 独立 OFFSET
|
||
```
|
||
|
||
---
|
||
|
||
## 方法签名
|
||
|
||
### 连接与元信息
|
||
|
||
| 方法 | 签名 | 说明 |
|
||
|------|------|------|
|
||
| SetConnect | `SetConnect(func() (master, slave *sql.DB))` | 设置连接并 InitDb |
|
||
| InitDb | `InitDb()` | 初始化连接与方言 |
|
||
| GetPrefix | `GetPrefix() string` | 表前缀 |
|
||
| GetType | `GetType() string` | 库类型 |
|
||
| GetDialect | `GetDialect() Dialect` | 方言适配器 |
|
||
| GetLast | `GetLast() *DBError` | 最近一次 SQL 快照 |
|
||
| GetLastError | `GetLastError() error` | 最近错误 |
|
||
| GetLastQuery | `GetLastQuery() string` | 最近 SQL |
|
||
| GetLastData | `GetLastData() []interface{}` | 最近参数 |
|
||
|
||
`Type`：`mysql` / `sqlite3` / `postgres` / `dm`（或 `dameng`）。
|
||
|
||
### CRUD
|
||
|
||
| 方法 | 签名 | 返回 |
|
||
|------|------|------|
|
||
| Select | `Select(table string, qu ...interface{})` | `[]Map` |
|
||
| Get | `Get(table string, qu ...interface{})` | `Map`（自动 LIMIT 1） |
|
||
| Insert | `Insert(table string, data map[string]interface{})` | `int64` 新 ID |
|
||
| Inserts | `Inserts(table string, dataList []Map)` | `int64` 影响行数 |
|
||
| Update | `Update(table string, data Map, where Map)` | `int64` |
|
||
| Upsert | `Upsert(table string, data Map, uniqueKeys Slice, updateColumns ...interface{})` | `int64` |
|
||
| Delete | `Delete(table string, data map[string]interface{})` | `int64` |
|
||
| Page | `Page(page, pageRow int) *HoTimeDB` | 链式分页 |
|
||
| PageSelect | `PageSelect(table string, qu ...interface{})` | `[]Map` |
|
||
|
||
`Select`/`Get`/`PageSelect` 的 `qu` 常见形态：字段；字段+where；join+字段+where。
|
||
|
||
```go
|
||
database.Select("user")
|
||
database.Select("user", "id,name")
|
||
database.Select("user", "*", where)
|
||
database.Select("user", joinSlice, "fields", where)
|
||
database.Get("user", "fields", where)
|
||
database.Insert("user", Map{"name": "a"})
|
||
database.Inserts("user", []Map{{"name": "a"}, {"name": "b"}})
|
||
database.Update("user", Map{"name": "b"}, Map{"id": 1})
|
||
database.Upsert("user", data, Slice{"id"}, Slice{"name", "email"})
|
||
database.Upsert("user", data, Slice{"id"}, "name", "email")
|
||
database.Delete("user", Map{"id": 1})
|
||
database.Page(1, 20).PageSelect("user", "id,name", where)
|
||
```
|
||
|
||
### 聚合
|
||
|
||
| 方法 | 签名 | 返回 |
|
||
|------|------|------|
|
||
| Count | `Count(table string, qu ...interface{})` | `int` |
|
||
| Sum | `Sum(table string, column string, qu ...interface{})` | `float64` |
|
||
| Avg | `Avg(table string, column string, qu ...interface{})` | `float64` |
|
||
| Max | `Max(table string, column string, qu ...interface{})` | `float64` |
|
||
| Min | `Min(table string, column string, qu ...interface{})` | `float64` |
|
||
|
||
`qu` 可为 where，或 join+where。
|
||
|
||
```go
|
||
database.Count("user")
|
||
database.Count("user", where)
|
||
database.Count("user", join, where)
|
||
database.Sum("order", "amount", where)
|
||
database.Avg("order", "amount", where)
|
||
database.Max("order", "amount", where)
|
||
database.Min("order", "amount", where)
|
||
```
|
||
|
||
### 链式构建器
|
||
|
||
```go
|
||
b := database.Table("tablename") // *HotimeDBBuilder
|
||
```
|
||
|
||
| 方法 | 签名 | 说明 |
|
||
|------|------|------|
|
||
| Where / And / Or | `(qu ...interface{}) *HotimeDBBuilder` | 键值或 Map |
|
||
| LeftJoin / RightJoin / InnerJoin / FullJoin | `(table, condition string)` | JOIN |
|
||
| Join | `(qu ...interface{})` | 通用 JOIN Map |
|
||
| Order / Group / Limit | `(qu ...interface{})` | 排序/分组/限制 |
|
||
| Having | `(qu ...interface{})` | HAVING |
|
||
| Page | `(page, pageRow int)` | 分页 |
|
||
| Offset | `(offset int)` | 偏移 |
|
||
| From | `(table string)` | 换表 |
|
||
| Select | `(qu ...interface{}) []Map` | 查询 |
|
||
| Get | `(qu ...interface{}) Map` | 单条 |
|
||
| Count | `() int` | 计数 |
|
||
| Update | `(qu ...interface{}) int64` | 更新 |
|
||
| Delete | `() int64` | 删除 |
|
||
|
||
```go
|
||
database.Table("user").Where("status", 1).Order("id DESC").Page(1, 20).Select("id,name")
|
||
database.Table("order").LeftJoin("user", "order.user_id = user.id").Where("order.status", "paid").Select("order.*, user.name")
|
||
```
|
||
|
||
### JOIN Map 写法
|
||
|
||
| 写法 | 类型 |
|
||
|------|------|
|
||
| `Map{"[>]profile": "user.id = profile.user_id"}` | LEFT |
|
||
| `Map{"[<]department": "user.dept_id = department.id"}` | RIGHT |
|
||
| `Map{"[><]role": "user.role_id = role.id"}` | INNER |
|
||
| `Map{"[<>]group": "user.group_id = group.id"}` | FULL |
|
||
|
||
### 事务与原生 SQL
|
||
|
||
| 方法 | 签名 | 说明 |
|
||
|------|------|------|
|
||
| Action | `Action(func(db HoTimeDB) bool) bool` | `true` 提交 / `false` 回滚 |
|
||
| Query | `Query(query string, args ...interface{}) []Map` | 原生查询 |
|
||
| Exec | `Exec(query string, args ...interface{}) (sql.Result, error)` | 原生执行 |
|
||
|
||
```go
|
||
ok := database.Action(func(tx HoTimeDB) bool {
|
||
if tx.Insert("a", data) == 0 { return false }
|
||
return true
|
||
})
|
||
database.Query("SELECT * FROM user WHERE age > ?", 18)
|
||
database.Exec("UPDATE user SET status = ? WHERE id = ?", 1, 100)
|
||
```
|
||
|
||
---
|
||
|
||
## 方言差异速查
|
||
|
||
| 特性 | MySQL | PostgreSQL | 达梦 DM8 |
|
||
|------|-------|------------|---------|
|
||
| 标识符引号 | \`name\` | `"name"` | `"name"` |
|
||
| 占位符 | `?` | `$1,$2...` | `?` |
|
||
| Upsert | ON DUPLICATE KEY | ON CONFLICT | MERGE INTO |
|
||
| 自增 | AUTO_INCREMENT | SERIAL | IDENTITY(1,1) |
|
||
| 分页 | LIMIT m,n | LIMIT n OFFSET m | 两者皆可 |
|
||
|
||
框架自动适配，业务代码通常无需按库分支。达梦：保留字（`admin`/`user`/`order`）ORM 自动加引号，原生 SQL 需手动双引号；时间统一用 `Time2Str(time.Now())`。
|
||
|
||
```go
|
||
// Type: "postgres" | "dm" | "dameng" | "mysql" | "sqlite3"
|
||
database := &db.HoTimeDB{Type: "dm"}
|
||
database.SetConnect(func() (master, slave *sql.DB) {
|
||
master, _ = sql.Open("dm", "dm://SYSDBA:pwd@127.0.0.1:5236?schema=TEST")
|
||
return master, master
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
## 常用一行模式
|
||
|
||
```go
|
||
// 分页列表
|
||
total := database.Count("user", Map{"status": 1})
|
||
rows := database.Table("user").Where("status", 1).Order("id DESC").Page(page, size).Select("id,name")
|
||
|
||
// 分组统计
|
||
database.Select("order", "user_id, COUNT(*) c, SUM(amount) s", Map{
|
||
"status": "paid", "GROUP": "user_id", "ORDER": "s DESC",
|
||
})
|
||
|
||
// 查错
|
||
if err := database.GetLastError(); err != nil { /* ... */ }
|
||
_ = database.GetLastQuery(); _ = database.GetLastData()
|
||
```
|