HoTimeDB API 快速参考
条件查询语法规则
新版本改进：
- 多条件自动用 AND 连接，无需手动包装
- 关键字支持大小写（如
LIMIT 和 limit 都有效）
- 新增
HAVING 和独立 OFFSET 支持
// ✅ 推荐：简化语法（多条件自动 AND）
Map{"status": 1, "age[>]": 18}
// 生成: WHERE `status`=? AND `age`>?
// ✅ 仍然支持：显式 AND 包装（向后兼容）
Map{
"AND": Map{
"status": 1,
"age[>]": 18,
},
}
// ✅ 混合条件和特殊关键字
Map{
"status": 1,
"age[>]": 18,
"ORDER": "id DESC", // 或 "order": "id DESC"
"LIMIT": 10, // 或 "limit": 10
}
基本方法
数据库连接
database.SetConnect(func() (master, slave *sql.DB) { ... })
database.InitDb()
链式查询构建器
// 创建查询构建器
builder := database.Table("tablename")
// 设置条件
builder.Where(key, value)
builder.And(key, value) 或 builder.And(map)
builder.Or(key, value) 或 builder.Or(map)
// JOIN操作
builder.LeftJoin(table, condition)
builder.RightJoin(table, condition)
builder.InnerJoin(table, condition)
builder.FullJoin(table, condition)
builder.Join(map) // 通用JOIN
// 排序和分组
builder.Order(fields...)
builder.Group(fields...)
builder.Limit(args...)
builder.Having(map) // 新增
// 分页
builder.Page(page, pageSize)
builder.Offset(offset) // 新增
// 执行查询
builder.Select(fields...) // 返回 []Map
builder.Get(fields...) // 返回 Map
builder.Count() // 返回 int
builder.Update(data) // 返回 int64
builder.Delete() // 返回 int64
CRUD 操作
查询 (Select)
// 基本查询
data := database.Select("table")
data := database.Select("table", "field1,field2")
data := database.Select("table", []string{"field1", "field2"})
data := database.Select("table", "*", whereMap)
// 带JOIN查询
data := database.Select("table", joinSlice, "fields", whereMap)
获取单条 (Get)
// 自动添加 LIMIT 1
row := database.Get("table", "fields", whereMap)
插入 (Insert)
id := database.Insert("table", dataMap)
// 返回新插入记录的ID
批量插入 (BatchInsert) - 新增
// 使用 []Map 格式，更直观简洁
affected := database.BatchInsert("table", []Map{
{"col1": "val1", "col2": "val2", "col3": "val3"},
{"col1": "val4", "col2": "val5", "col3": "val6"},
})
// 返回受影响的行数
// 支持 [#] 标记直接 SQL
affected := database.BatchInsert("log", []Map{
{"user_id": 1, "created_time[#]": "NOW()"},
{"user_id": 2, "created_time[#]": "NOW()"},
})
更新 (Update)
affected := database.Update("table", dataMap, whereMap)
// 返回受影响的行数
Upsert - 新增
// 使用 Slice 格式
affected := database.Upsert("table",
dataMap, // 插入数据
Slice{"unique_key"}, // 唯一键
Slice{"col1", "col2"}, // 冲突时更新的字段
)
// 也支持可变参数
affected := database.Upsert("table", dataMap, Slice{"id"}, "col1", "col2")
// 返回受影响的行数
删除 (Delete)
affected := database.Delete("table", whereMap)
// 返回删除的行数
聚合函数
计数
count := database.Count("table")
count := database.Count("table", whereMap)
count := database.Count("table", joinSlice, whereMap)
求和
sum := database.Sum("table", "column")
sum := database.Sum("table", "column", whereMap)
平均值 - 新增
avg := database.Avg("table", "column")
avg := database.Avg("table", "column", whereMap)
最大值 - 新增
max := database.Max("table", "column")
max := database.Max("table", "column", whereMap)
最小值 - 新增
min := database.Min("table", "column")
min := database.Min("table", "column", whereMap)
分页查询
// 设置分页
database.Page(page, pageSize)
// 分页查询
data := database.Page(page, pageSize).PageSelect("table", "fields", whereMap)
条件语法参考
比较操作符
| 写法 |
SQL |
说明 |
"field": value |
field = ? |
等于 |
"field[!]": value |
field != ? |
不等于 |
"field[>]": value |
field > ? |
大于 |
"field[>=]": value |
field >= ? |
大于等于 |
"field[<]": value |
field < ? |
小于 |
"field[<=]": value |
field <= ? |
小于等于 |
模糊查询
| 写法 |
SQL |
说明 |
"field[~]": "keyword" |
field LIKE '%keyword%' |
包含 |
"field[~!]": "keyword" |
field LIKE 'keyword%' |
以...开头 |
"field[!~]": "keyword" |
field LIKE '%keyword' |
以...结尾 |
"field[~~]": "%keyword%" |
field LIKE '%keyword%' |
手动LIKE |
范围查询
| 写法 |
SQL |
说明 |
"field[<>]": [min, max] |
field BETWEEN ? AND ? |
区间内 |
"field[><]": [min, max] |
field NOT BETWEEN ? AND ? |
区间外 |
集合查询
| 写法 |
SQL |
说明 |
"field": [v1, v2, v3] |
field IN (?, ?, ?) |
在集合中 |
"field[!]": [v1, v2, v3] |
field NOT IN (?, ?, ?) |
不在集合中 |
NULL查询
| 写法 |
SQL |
说明 |
"field": nil |
field IS NULL |
为空 |
"field[!]": nil |
field IS NOT NULL |
不为空 |
直接SQL
| 写法 |
SQL |
说明 |
"field[#]": "NOW()" |
field = NOW() |
直接SQL函数 |
"[##]": "a > b" |
a > b |
直接SQL片段 |
"field[#!]": "1" |
field != 1 |
不等于(不参数化) |
逻辑连接符
AND 条件
// 简化语法（推荐）
whereMap := Map{
"status": 1,
"age[>]": 18,
}
// 生成: WHERE `status`=? AND `age`>?
// 显式 AND（向后兼容）
whereMap := Map{
"AND": Map{
"status": 1,
"age[>]": 18,
},
}
OR 条件
whereMap := Map{
"OR": Map{
"status": 1,
"type": 2,
},
}
嵌套条件
whereMap := Map{
"AND": Map{
"status": 1,
"OR": Map{
"age[<]": 30,
"level[>]": 5,
},
},
}
JOIN 语法
传统语法
joinSlice := Slice{
Map{"[>]profile": "user.id = profile.user_id"}, // LEFT JOIN
Map{"[<]department": "user.dept_id = department.id"}, // RIGHT JOIN
Map{"[><]role": "user.role_id = role.id"}, // INNER JOIN
Map{"[<>]group": "user.group_id = group.id"}, // FULL JOIN
}
链式语法
builder.LeftJoin("profile", "user.id = profile.user_id")
builder.RightJoin("department", "user.dept_id = department.id")
builder.InnerJoin("role", "user.role_id = role.id")
builder.FullJoin("group", "user.group_id = group.id")
特殊字段语法
ORDER BY
Map{
"ORDER": []string{"created_time DESC", "id ASC"},
}
// 或
Map{
"order": "created_time DESC", // 支持小写
}
GROUP BY
Map{
"GROUP": []string{"department", "level"},
}
// 或
Map{
"group": "department", // 支持小写
}
HAVING - 新增
Map{
"GROUP": "dept_id",
"HAVING": Map{
"COUNT(*).[>]": 5,
},
}
LIMIT
Map{
"LIMIT": []int{10, 20}, // offset 10, limit 20
}
// 或
Map{
"limit": 20, // limit 20，支持小写
}
OFFSET - 新增
Map{
"LIMIT": 10,
"OFFSET": 20, // 独立的 OFFSET
}
事务处理
success := database.Action(func(tx HoTimeDB) bool {
// 在这里执行数据库操作
// 返回 true 提交事务
// 返回 false 回滚事务
id := tx.Insert("table", data)
if id == 0 {
return false // 回滚
}
affected := tx.Update("table2", data2, where2)
if affected == 0 {
return false // 回滚
}
return true // 提交
})
原生SQL执行
查询
results := database.Query("SELECT * FROM user WHERE age > ?", 18)
执行
result, err := database.Exec("UPDATE user SET status = ? WHERE id = ?", 1, 100)
affected, _ := result.RowsAffected()
PostgreSQL 支持 - 新增
// 配置 PostgreSQL
database := &db.HoTimeDB{
Type: "postgres", // 设置类型
}
// 框架自动处理差异：
// - 占位符: ? -> $1, $2, $3...
// - 引号: `name` -> "name"
// - Upsert: ON DUPLICATE KEY -> ON CONFLICT
错误处理
// 检查最后的错误
if database.LastErr.GetError() != nil {
fmt.Println("错误:", database.LastErr.GetError())
}
// 查看最后执行的SQL
fmt.Println("SQL:", database.LastQuery)
fmt.Println("参数:", database.LastData)
工具方法
数据库信息
prefix := database.GetPrefix() // 获取表前缀
dbType := database.GetType() // 获取数据库类型
dialect := database.GetDialect() // 获取方言适配器
设置模式
database.Mode = 0 // 生产模式
database.Mode = 1 // 测试模式
database.Mode = 2 // 开发模式（输出SQL日志）
常用查询模式
分页列表查询
// 获取总数
total := database.Count("user", Map{"status": 1})
// 分页数据
users := database.Table("user").
Where("status", 1).
Order("created_time DESC").
Page(page, pageSize).
Select("id,name,email,created_time")
// 计算分页信息
totalPages := (total + pageSize - 1) / pageSize
关联查询
orders := database.Table("order").
LeftJoin("user", "order.user_id = user.id").
LeftJoin("product", "order.product_id = product.id").
Where("order.status", "paid").
Select(`
order.*,
user.name as user_name,
product.title as product_title
`)
统计查询
stats := database.Select("order",
"user_id, COUNT(*) as order_count, SUM(amount) as total_amount",
Map{
"status": "paid",
"created_time[>]": "2023-01-01",
"GROUP": "user_id",
"ORDER": "total_amount DESC",
})
批量操作
// 批量插入（使用 []Map 格式）
affected := database.BatchInsert("user", []Map{
{"name": "用户1", "email": "user1@example.com", "status": 1},
{"name": "用户2", "email": "user2@example.com", "status": 1},
{"name": "用户3", "email": "user3@example.com", "status": 1},
})
// Upsert（插入或更新，使用 Slice 格式）
affected := database.Upsert("user",
Map{"id": 1, "name": "新名称", "email": "new@example.com"},
Slice{"id"},
Slice{"name", "email"},
)
链式调用完整示例
// 复杂查询链式调用
result := database.Table("order").
LeftJoin("user", "order.user_id = user.id").
LeftJoin("product", "order.product_id = product.id").
Where("order.status", "paid").
And("order.created_time[>]", "2023-01-01").
And(Map{
"OR": Map{
"user.level": "vip",
"order.amount[>]": 1000,
},
}).
Group("user.id").
Having(Map{"total_amount[>]": 500}).
Order("total_amount DESC").
Page(1, 20).
Select(`
user.id,
user.name,
user.email,
COUNT(order.id) as order_count,
SUM(order.amount) as total_amount
`)
快速参考版本: 2.0
更新日期: 2026年1月
hoteas
f2f1fcc9aa