hotime/docs/HoTimeDB_API参考.md

HoTimeDB API 快速参考

完整教程见 HoTimeDB 使用说明。本文仅收录条件运算符与方法签名速查。

---

条件运算符

多条件默认 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()）。

逻辑与特殊关键字

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。

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。

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)

链式构建器

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	删除

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)	原生执行

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())。

// 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
})

---

常用一行模式

// 分页列表
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()