431 lines
8.7 KiB
Markdown
431 lines
8.7 KiB
Markdown
# HoTimeDB API 快速参考
|
||
|
||
## ⚠️ 重要语法说明
|
||
|
||
**条件查询语法规则：**
|
||
- 单个条件：可以直接写在Map中
|
||
- 多个条件：必须使用`AND`或`OR`包装
|
||
- 特殊条件：`ORDER`、`GROUP`、`LIMIT`与条件同级
|
||
|
||
```go
|
||
// ✅ 正确：单个条件
|
||
Map{"status": 1}
|
||
|
||
// ✅ 正确：多个条件用AND包装
|
||
Map{
|
||
"AND": Map{
|
||
"status": 1,
|
||
"age[>]": 18,
|
||
},
|
||
}
|
||
|
||
// ✅ 正确：条件 + 特殊参数
|
||
Map{
|
||
"AND": Map{
|
||
"status": 1,
|
||
"age[>]": 18,
|
||
},
|
||
"ORDER": "id DESC",
|
||
"LIMIT": 10,
|
||
}
|
||
|
||
// ❌ 错误：多个条件不用AND包装
|
||
Map{
|
||
"status": 1,
|
||
"age[>]": 18, // 这样写不支持！
|
||
}
|
||
```
|
||
|
||
## 基本方法
|
||
|
||
### 数据库连接
|
||
```go
|
||
db.SetConnect(func() (master, slave *sql.DB) { ... })
|
||
db.InitDb()
|
||
```
|
||
|
||
### 链式查询构建器
|
||
```go
|
||
// 创建查询构建器
|
||
builder := db.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.Page(page, pageSize)
|
||
|
||
// 执行查询
|
||
builder.Select(fields...) // 返回 []Map
|
||
builder.Get(fields...) // 返回 Map
|
||
builder.Count() // 返回 int
|
||
builder.Update(data) // 返回 int64
|
||
builder.Delete() // 返回 int64
|
||
```
|
||
|
||
## CRUD 操作
|
||
|
||
### 查询 (Select)
|
||
```go
|
||
// 基本查询
|
||
data := db.Select("table")
|
||
data := db.Select("table", "field1,field2")
|
||
data := db.Select("table", []string{"field1", "field2"})
|
||
data := db.Select("table", "*", whereMap)
|
||
|
||
// 带JOIN查询
|
||
data := db.Select("table", joinSlice, "fields", whereMap)
|
||
```
|
||
|
||
### 获取单条 (Get)
|
||
```go
|
||
// 自动添加 LIMIT 1
|
||
row := db.Get("table", "fields", whereMap)
|
||
```
|
||
|
||
### 插入 (Insert)
|
||
```go
|
||
id := db.Insert("table", dataMap)
|
||
// 返回新插入记录的ID
|
||
```
|
||
|
||
### 更新 (Update)
|
||
```go
|
||
affected := db.Update("table", dataMap, whereMap)
|
||
// 返回受影响的行数
|
||
```
|
||
|
||
### 删除 (Delete)
|
||
```go
|
||
affected := db.Delete("table", whereMap)
|
||
// 返回删除的行数
|
||
```
|
||
|
||
## 聚合函数
|
||
|
||
### 计数
|
||
```go
|
||
count := db.Count("table")
|
||
count := db.Count("table", whereMap)
|
||
count := db.Count("table", joinSlice, whereMap)
|
||
```
|
||
|
||
### 求和
|
||
```go
|
||
sum := db.Sum("table", "column")
|
||
sum := db.Sum("table", "column", whereMap)
|
||
sum := db.Sum("table", "column", joinSlice, whereMap)
|
||
```
|
||
|
||
## 分页查询
|
||
```go
|
||
// 设置分页
|
||
db.Page(page, pageSize)
|
||
|
||
// 分页查询
|
||
data := db.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 条件
|
||
```go
|
||
whereMap := Map{
|
||
"AND": Map{
|
||
"status": 1,
|
||
"age[>]": 18,
|
||
},
|
||
}
|
||
```
|
||
|
||
### OR 条件
|
||
```go
|
||
whereMap := Map{
|
||
"OR": Map{
|
||
"status": 1,
|
||
"type": 2,
|
||
},
|
||
}
|
||
```
|
||
|
||
### 嵌套条件
|
||
```go
|
||
whereMap := Map{
|
||
"AND": Map{
|
||
"status": 1,
|
||
"OR": Map{
|
||
"age[<]": 30,
|
||
"level[>]": 5,
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
## JOIN 语法
|
||
|
||
### 传统语法
|
||
```go
|
||
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
|
||
}
|
||
```
|
||
|
||
### 链式语法
|
||
```go
|
||
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
|
||
```go
|
||
Map{
|
||
"ORDER": []string{"created_time DESC", "id ASC"},
|
||
}
|
||
// 或
|
||
Map{
|
||
"ORDER": "created_time DESC",
|
||
}
|
||
```
|
||
|
||
### GROUP BY
|
||
```go
|
||
Map{
|
||
"GROUP": []string{"department", "level"},
|
||
}
|
||
// 或
|
||
Map{
|
||
"GROUP": "department",
|
||
}
|
||
```
|
||
|
||
### LIMIT
|
||
```go
|
||
Map{
|
||
"LIMIT": []int{10, 20}, // offset 10, limit 20
|
||
}
|
||
// 或
|
||
Map{
|
||
"LIMIT": 20, // limit 20
|
||
}
|
||
```
|
||
|
||
## 事务处理
|
||
```go
|
||
success := db.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执行
|
||
|
||
### 查询
|
||
```go
|
||
results := db.Query("SELECT * FROM user WHERE age > ?", 18)
|
||
```
|
||
|
||
### 执行
|
||
```go
|
||
result, err := db.Exec("UPDATE user SET status = ? WHERE id = ?", 1, 100)
|
||
affected, _ := result.RowsAffected()
|
||
```
|
||
|
||
## 错误处理
|
||
```go
|
||
// 检查最后的错误
|
||
if db.LastErr.GetError() != nil {
|
||
fmt.Println("错误:", db.LastErr.GetError())
|
||
}
|
||
|
||
// 查看最后执行的SQL
|
||
fmt.Println("SQL:", db.LastQuery)
|
||
fmt.Println("参数:", db.LastData)
|
||
```
|
||
|
||
## 工具方法
|
||
|
||
### 数据库信息
|
||
```go
|
||
prefix := db.GetPrefix() // 获取表前缀
|
||
dbType := db.GetType() // 获取数据库类型
|
||
```
|
||
|
||
### 设置模式
|
||
```go
|
||
db.Mode = 0 // 生产模式
|
||
db.Mode = 1 // 测试模式
|
||
db.Mode = 2 // 开发模式（输出SQL日志）
|
||
```
|
||
|
||
## 常用查询模式
|
||
|
||
### 分页列表查询
|
||
```go
|
||
// 获取总数
|
||
total := db.Count("user", Map{"status": 1})
|
||
|
||
// 分页数据
|
||
users := db.Table("user").
|
||
Where("status", 1).
|
||
Order("created_time DESC").
|
||
Page(page, pageSize).
|
||
Select("id,name,email,created_time")
|
||
|
||
// 计算分页信息
|
||
totalPages := (total + pageSize - 1) / pageSize
|
||
```
|
||
|
||
### 关联查询
|
||
```go
|
||
orders := db.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
|
||
`)
|
||
```
|
||
|
||
### 统计查询
|
||
```go
|
||
stats := db.Select("order",
|
||
"user_id, COUNT(*) as order_count, SUM(amount) as total_amount",
|
||
Map{
|
||
"AND": Map{
|
||
"status": "paid",
|
||
"created_time[>]": "2023-01-01",
|
||
},
|
||
"GROUP": "user_id",
|
||
"ORDER": "total_amount DESC",
|
||
})
|
||
```
|
||
|
||
### 条件组合查询
|
||
```go
|
||
products := db.Table("product").
|
||
Where("status", 1).
|
||
And(Map{
|
||
"OR": Map{
|
||
"category_id": []int{1, 2, 3},
|
||
"tags[~]": "热销",
|
||
},
|
||
}).
|
||
And(Map{
|
||
"price[<>]": []float64{10.0, 1000.0},
|
||
}).
|
||
Order("sort DESC", "created_time DESC").
|
||
Limit(0, 20).
|
||
Select()
|
||
```
|
||
|
||
## 链式调用完整示例
|
||
|
||
```go
|
||
// 复杂查询链式调用
|
||
result := db.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").
|
||
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
|
||
`)
|
||
```
|
||
|
||
---
|
||
|
||
*快速参考版本: 1.0* |