hotime/db/HoTimeDB_API参考.md

# HoTimeDB API 快速参考

## 条件查询语法规则

**新版本改进：**
- 多条件自动用 AND 连接，无需手动包装
- 关键字支持大小写（如 `LIMIT` 和 `limit` 都有效）
- 新增 `HAVING` 和独立 `OFFSET` 支持

```go
// ✅ 推荐：简化语法（多条件自动 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
}
```

## 基本方法

### 数据库连接
```go
database.SetConnect(func() (master, slave *sql.DB) { ... })
database.InitDb()
```

### 链式查询构建器
```go
// 创建查询构建器
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)
```go
// 基本查询
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)
```go
// 自动添加 LIMIT 1
row := database.Get("table", "fields", whereMap)
```

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

### 批量插入 (BatchInsert) - 新增
```go
// 使用 []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)
```go
affected := database.Update("table", dataMap, whereMap)
// 返回受影响的行数
```

### Upsert - 新增
```go
// 使用 Slice 格式
affected := database.Upsert("table", 
    dataMap,                    // 插入数据
    Slice{"unique_key"},        // 唯一键
    Slice{"col1", "col2"},      // 冲突时更新的字段
)

// 也支持可变参数
affected := database.Upsert("table", dataMap, Slice{"id"}, "col1", "col2")
// 返回受影响的行数
```

### 删除 (Delete)
```go
affected := database.Delete("table", whereMap)
// 返回删除的行数
```

## 聚合函数

### 计数
```go
count := database.Count("table")
count := database.Count("table", whereMap)
count := database.Count("table", joinSlice, whereMap)
```

### 求和
```go
sum := database.Sum("table", "column")
sum := database.Sum("table", "column", whereMap)
```

### 平均值 - 新增
```go
avg := database.Avg("table", "column")
avg := database.Avg("table", "column", whereMap)
```

### 最大值 - 新增
```go
max := database.Max("table", "column")
max := database.Max("table", "column", whereMap)
```

### 最小值 - 新增
```go
min := database.Min("table", "column")
min := database.Min("table", "column", whereMap)
```

## 分页查询
```go
// 设置分页
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 条件
```go
// 简化语法（推荐）
whereMap := Map{
    "status": 1,
    "age[>]": 18,
}
// 生成: WHERE `status`=? AND `age`>?

// 显式 AND（向后兼容）
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", // 支持小写
}
```

### HAVING - 新增
```go
Map{
    "GROUP": "dept_id",
    "HAVING": Map{
        "COUNT(*).[>]": 5,
    },
}
```

### LIMIT
```go
Map{
    "LIMIT": []int{10, 20}, // offset 10, limit 20
}
// 或
Map{
    "limit": 20, // limit 20，支持小写
}
```

### OFFSET - 新增
```go
Map{
    "LIMIT": 10,
    "OFFSET": 20, // 独立的 OFFSET
}
```

## 事务处理
```go
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执行

### 查询
```go
results := database.Query("SELECT * FROM user WHERE age > ?", 18)
```

### 执行
```go
result, err := database.Exec("UPDATE user SET status = ? WHERE id = ?", 1, 100)
affected, _ := result.RowsAffected()
```

## PostgreSQL 支持 - 新增

```go
// 配置 PostgreSQL
database := &db.HoTimeDB{
    Type: "postgres", // 设置类型
}

// 框架自动处理差异：
// - 占位符: ? -> $1, $2, $3...
// - 引号: `name` -> "name"
// - Upsert: ON DUPLICATE KEY -> ON CONFLICT
```

## 错误处理
```go
// 检查最后的错误
if database.LastErr.GetError() != nil {
    fmt.Println("错误:", database.LastErr.GetError())
}

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

## 工具方法

### 数据库信息
```go
prefix := database.GetPrefix()  // 获取表前缀
dbType := database.GetType()    // 获取数据库类型
dialect := database.GetDialect() // 获取方言适配器
```

### 设置模式
```go
database.Mode = 0  // 生产模式
database.Mode = 1  // 测试模式
database.Mode = 2  // 开发模式（输出SQL日志）
```

## 常用查询模式

### 分页列表查询
```go
// 获取总数
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
```

### 关联查询
```go
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
    `)
```

### 统计查询
```go
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",
    })
```

### 批量操作
```go
// 批量插入（使用 []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"},
)
```

## 链式调用完整示例

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