hotime/db/HoTimeDB_API参考.md

HoTimeDB API 快速参考

⚠️ 重要语法说明

条件查询语法规则：

• 单个条件：可以直接写在Map中
• 多个条件：必须使用AND或OR包装
• 特殊条件：ORDER、GROUP、LIMIT与条件同级

// ✅ 正确：单个条件
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,  // 这样写不支持！
}

基本方法

数据库连接

db.SetConnect(func() (master, slave *sql.DB) { ... })
db.InitDb()

链式查询构建器

// 创建查询构建器
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)

// 基本查询
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)

// 自动添加 LIMIT 1
row := db.Get("table", "fields", whereMap)

插入 (Insert)

id := db.Insert("table", dataMap)
// 返回新插入记录的ID

更新 (Update)

affected := db.Update("table", dataMap, whereMap)
// 返回受影响的行数

删除 (Delete)

affected := db.Delete("table", whereMap)
// 返回删除的行数

聚合函数

计数

count := db.Count("table")
count := db.Count("table", whereMap)
count := db.Count("table", joinSlice, whereMap)

求和

sum := db.Sum("table", "column")
sum := db.Sum("table", "column", whereMap)
sum := db.Sum("table", "column", joinSlice, whereMap)

分页查询

// 设置分页
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 条件

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",
}

LIMIT

Map{
    "LIMIT": []int{10, 20}, // offset 10, limit 20
}
// 或
Map{
    "LIMIT": 20, // limit 20
}

事务处理

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执行

查询

results := db.Query("SELECT * FROM user WHERE age > ?", 18)

执行

result, err := db.Exec("UPDATE user SET status = ? WHERE id = ?", 1, 100)
affected, _ := result.RowsAffected()

错误处理

// 检查最后的错误
if db.LastErr.GetError() != nil {
    fmt.Println("错误:", db.LastErr.GetError())
}

// 查看最后执行的SQL
fmt.Println("SQL:", db.LastQuery)
fmt.Println("参数:", db.LastData)

工具方法

数据库信息

prefix := db.GetPrefix()  // 获取表前缀
dbType := db.GetType()    // 获取数据库类型

设置模式

db.Mode = 0  // 生产模式
db.Mode = 1  // 测试模式
db.Mode = 2  // 开发模式（输出SQL日志）

常用查询模式

分页列表查询

// 获取总数
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

关联查询

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
    `)

统计查询

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",
    })

条件组合查询

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

链式调用完整示例

// 复杂查询链式调用
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