hotime/db/HoTimeDB_API参考.md

# 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*