hotime/db/HoTimeDB_使用说明.md

# HoTimeDB ORM 使用说明书

## 概述

HoTimeDB是一个基于Golang实现的轻量级ORM框架，参考PHP Medoo设计，提供简洁的数据库操作接口。支持MySQL、SQLite、PostgreSQL等数据库，并集成了缓存、事务、链式查询等功能。

## 目录

- [快速开始](#快速开始)
- [数据库配置](#数据库配置)
- [基本操作](#基本操作)
  - [查询(Select)](#查询select)
  - [获取单条记录(Get)](#获取单条记录get)
  - [插入(Insert)](#插入insert)
  - [批量插入(BatchInsert)](#批量插入batchinsert)
  - [更新(Update)](#更新update)
  - [Upsert操作](#upsert操作)
  - [删除(Delete)](#删除delete)
- [链式查询构建器](#链式查询构建器)
- [条件查询语法](#条件查询语法)
- [JOIN操作](#join操作)
- [分页查询](#分页查询)
- [聚合函数](#聚合函数)
- [事务处理](#事务处理)
- [缓存机制](#缓存机制)
- [PostgreSQL支持](#postgresql支持)
- [高级特性](#高级特性)

## 快速开始

### 初始化数据库连接

```go
import (
    "code.hoteas.com/golang/hotime/db"
    "code.hoteas.com/golang/hotime/common"
    "database/sql"
    _ "github.com/go-sql-driver/mysql"
)

// 创建连接函数
func createConnection() (master, slave *sql.DB) {
    master, _ = sql.Open("mysql", "user:password@tcp(localhost:3306)/database")
    // slave是可选的，用于读写分离
    slave = master // 或者连接到从数据库
    return
}

// 初始化HoTimeDB
database := &db.HoTimeDB{
    Type: "mysql", // 可选：mysql, sqlite3, postgres
}
database.SetConnect(createConnection)
```

## 数据库配置

### 基本配置

```go
type HoTimeDB struct {
    *sql.DB
    ContextBase
    DBName string
    *cache.HoTimeCache
    Log         *logrus.Logger
    Type        string    // 数据库类型：mysql, sqlite3, postgres
    Prefix      string    // 表前缀
    LastQuery   string    // 最后执行的SQL
    LastData    []interface{} // 最后的参数
    ConnectFunc func(err ...*Error) (*sql.DB, *sql.DB)
    LastErr     *Error
    limit       Slice
    *sql.Tx     // 事务对象
    SlaveDB     *sql.DB // 从数据库
    Mode        int     // 0生产模式,1测试模式,2开发模式
    Dialect     Dialect // 数据库方言适配器
}
```

### 设置表前缀

```go
database.Prefix = "app_"
```

### 设置运行模式

```go
database.Mode = 2 // 开发模式，会输出SQL日志
```

## 基本操作

### 查询(Select)

#### 基本查询

```go
// 查询所有字段
users := database.Select("user")

// 查询指定字段
users := database.Select("user", "id,name,email")

// 查询指定字段(数组形式)
users := database.Select("user", []string{"id", "name", "email"})

// 单条件查询
users := database.Select("user", "*", common.Map{
    "status": 1,
})

// 多条件查询（自动用 AND 连接）
users := database.Select("user", "*", common.Map{
    "status": 1,
    "age[>]": 18,
})
// 生成: WHERE `status`=? AND `age`>?
```

#### 复杂条件查询

```go
// 简化语法：多条件自动用 AND 连接
users := database.Select("user", "*", common.Map{
    "status": 1,
    "age[>]": 18,
    "name[~]": "张",
})
// 生成: WHERE `status`=? AND `age`>? AND `name` LIKE ?

// 显式 AND 条件（与上面等效）
users := database.Select("user", "*", common.Map{
    "AND": common.Map{
        "status": 1,
        "age[>]": 18,
        "name[~]": "张",
    },
})

// OR 条件
users := database.Select("user", "*", common.Map{
    "OR": common.Map{
        "status": 1,
        "type": 2,
    },
})

// 混合条件（嵌套 AND/OR）
users := database.Select("user", "*", common.Map{
    "AND": common.Map{
        "status": 1,
        "OR": common.Map{
            "age[<]": 30,
            "level[>]": 5,
        },
    },
})

// 带 ORDER BY、LIMIT 等特殊条件（关键字支持大小写）
users := database.Select("user", "*", common.Map{
    "status": 1,
    "age[>]": 18,
    "ORDER": "id DESC",  // 或 "order": "id DESC"
    "LIMIT": 10,         // 或 "limit": 10
})

// 带多个特殊条件
users := database.Select("user", "*", common.Map{
    "OR": common.Map{
        "level": "vip",
        "balance[>]": 1000,
    },
    "ORDER": []string{"created_time DESC", "id ASC"},
    "GROUP": "department",
    "LIMIT": []int{0, 20}, // offset 0, limit 20
})

// 使用 HAVING 过滤分组结果
users := database.Select("user", "dept_id, COUNT(*) as cnt", common.Map{
    "GROUP": "dept_id",
    "HAVING": common.Map{
        "cnt[>]": 5,
    },
})

// 使用独立 OFFSET
users := database.Select("user", "*", common.Map{
    "status": 1,
    "LIMIT": 10,
    "OFFSET": 20,
})
```

### 获取单条记录(Get)

```go
// 获取单个用户
user := database.Get("user", "*", common.Map{
    "id": 1,
})

// 获取指定字段
user := database.Get("user", "id,name,email", common.Map{
    "status": 1,
})
```

### 插入(Insert)

```go
// 基本插入
id := database.Insert("user", common.Map{
    "name": "张三",
    "email": "zhangsan@example.com",
    "age": 25,
    "status": 1,
    "created_time[#]": "NOW()", // [#]表示直接插入SQL函数
})

// 返回插入的ID
fmt.Println("插入的用户ID:", id)
```

### 批量插入(BatchInsert)

```go
// 批量插入多条记录（使用 []Map 格式，更直观）
affected := database.BatchInsert("user", []common.Map{
    {"name": "张三", "email": "zhang@example.com", "age": 25},
    {"name": "李四", "email": "li@example.com", "age": 30},
    {"name": "王五", "email": "wang@example.com", "age": 28},
})
// 生成: INSERT INTO `user` (`age`, `email`, `name`) VALUES (?, ?, ?), (?, ?, ?), (?, ?, ?)

fmt.Printf("批量插入 %d 条记录\n", affected)

// 支持 [#] 标记直接插入 SQL 表达式
affected := database.BatchInsert("log", []common.Map{
    {"user_id": 1, "action": "login", "created_time[#]": "NOW()"},
    {"user_id": 2, "action": "logout", "created_time[#]": "NOW()"},
})
```

### 更新(Update)

```go
// 基本更新
affected := database.Update("user", common.Map{
    "name": "李四",
    "email": "lisi@example.com",
    "updated_time[#]": "NOW()",
}, common.Map{
    "id": 1,
})

// 条件更新（多条件自动 AND 连接）
affected := database.Update("user", common.Map{
    "status": 0,
}, common.Map{
    "age[<]": 18,
    "status": 1,
})

fmt.Println("更新的记录数:", affected)
```

### Upsert操作

Upsert（插入或更新）：如果记录存在则更新，不存在则插入。

```go
// Upsert 操作（使用 Slice 格式）
affected := database.Upsert("user", 
    common.Map{
        "id": 1,
        "name": "张三",
        "email": "zhang@example.com",
        "login_count": 1,
    },
    common.Slice{"id"},                           // 唯一键（用于冲突检测）
    common.Slice{"name", "email", "login_count"}, // 冲突时更新的字段
)

// MySQL 生成:
// INSERT INTO user (id,name,email,login_count) VALUES (?,?,?,?)
// ON DUPLICATE KEY UPDATE name=VALUES(name), email=VALUES(email), login_count=VALUES(login_count)

// PostgreSQL 生成:
// INSERT INTO "user" (id,name,email,login_count) VALUES ($1,$2,$3,$4)
// ON CONFLICT (id) DO UPDATE SET name=EXCLUDED.name, email=EXCLUDED.email, login_count=EXCLUDED.login_count

// 使用 [#] 标记直接 SQL 更新
affected := database.Upsert("user",
    common.Map{
        "id": 1,
        "name": "张三",
        "login_count[#]": "login_count + 1", // 直接 SQL 表达式
    },
    common.Slice{"id"},
    common.Slice{"name", "login_count"},
)

// 也支持可变参数形式
affected := database.Upsert("user",
    common.Map{"id": 1, "name": "张三"},
    common.Slice{"id"},
    "name", "email", // 可变参数
)
```

### 删除(Delete)

```go
// 根据ID删除
affected := database.Delete("user", common.Map{
    "id": 1,
})

// 条件删除（多条件自动 AND 连接）
affected := database.Delete("user", common.Map{
    "status": 0,
    "created_time[<]": "2023-01-01",
})

fmt.Println("删除的记录数:", affected)
```

## 链式查询构建器

HoTimeDB提供了链式查询构建器，让查询更加直观：

```go
// 基本链式查询
users := database.Table("user").
    Where("status", 1).
    And("age[>]", 18).
    Order("created_time DESC").
    Limit(10, 20). // offset, limit
    Select()

// 链式获取单条记录
user := database.Table("user").
    Where("id", 1).
    Get()

// 链式更新
affected := database.Table("user").
    Where("id", 1).
    Update(common.Map{
        "name": "新名称",
        "updated_time[#]": "NOW()",
    })

// 链式删除
affected := database.Table("user").
    Where("status", 0).
    Delete()

// 链式统计
count := database.Table("user").
    Where("status", 1).
    Count()
```

### 链式条件组合

```go
// 复杂条件组合
users := database.Table("user").
    Where("status", 1).
    And("age[>=]", 18).
    Or(common.Map{
        "level[>]": 5,
        "vip": 1,
    }).
    Order("created_time DESC", "id ASC").
    Group("department").
    Having(common.Map{"COUNT(*).[>]": 5}). // 新增 HAVING 支持
    Limit(0, 20).
    Offset(10). // 新增独立 OFFSET 支持
    Select("id,name,email,age")
```

## 条件查询语法

HoTimeDB支持丰富的条件查询语法，类似于Medoo：

### 基本比较

```go
// 等于
"id": 1

// 不等于
"id[!]": 1

// 大于
"age[>]": 18

// 大于等于
"age[>=]": 18

// 小于
"age[<]": 60

// 小于等于
"age[<=]": 60
```

### 模糊查询

```go
// LIKE %keyword%
"name[~]": "张"

// LIKE keyword% (右边任意)
"name[~!]": "张"

// LIKE %keyword (左边任意)
"name[!~]": "san"

// 手动LIKE（需要手动添加%）
"name[~~]": "%张%"
```

### 区间查询

```go
// BETWEEN
"age[<>]": []int{18, 60}

// NOT BETWEEN
"age[><]": []int{18, 25}
```

### IN查询

```go
// IN
"id": []int{1, 2, 3, 4, 5}

// NOT IN
"id[!]": []int{1, 2, 3}
```

### NULL查询

```go
// IS NULL
"deleted_at": nil

// IS NOT NULL
"deleted_at[!]": nil
```

### 直接SQL

```go
// 直接插入SQL表达式（注意防注入）
"created_time[#]": "> DATE_SUB(NOW(), INTERVAL 1 DAY)"

// 字段直接赋值（不使用参数化查询）
"update_time[#]": "NOW()"

// 直接SQL片段
"[##]": "user.status = 1 AND user.level > 0"
```

## JOIN操作

### 链式JOIN

```go
// LEFT JOIN
users := database.Table("user").
    LeftJoin("profile", "user.id = profile.user_id").
    LeftJoin("department", "user.dept_id = department.id").
    Where("user.status", 1).
    Select("user.*, profile.avatar, department.name AS dept_name")

// RIGHT JOIN
users := database.Table("user").
    RightJoin("order", "user.id = order.user_id").
    Select()

// INNER JOIN
users := database.Table("user").
    InnerJoin("profile", "user.id = profile.user_id").
    Select()

// FULL JOIN
users := database.Table("user").
    FullJoin("profile", "user.id = profile.user_id").
    Select()
```

### 传统JOIN语法

```go
users := database.Select("user", 
    common.Slice{
        common.Map{"[>]profile": "user.id = profile.user_id"},
        common.Map{"[>]department": "user.dept_id = department.id"},
    },
    "user.*, profile.avatar, department.name AS dept_name",
    common.Map{
        "user.status": 1,
    },
)
```

### JOIN类型说明

- `[>]`: LEFT JOIN
- `[<]`: RIGHT JOIN  
- `[><]`: INNER JOIN
- `[<>]`: FULL JOIN

## 分页查询

### 基本分页

```go
// 设置分页：页码3，每页20条
users := database.Page(3, 20).PageSelect("user", "*", common.Map{
    "status": 1,
})

// 链式分页
users := database.Table("user").
    Where("status", 1).
    Page(2, 15). // 第2页，每页15条
    Select()
```

### 分页信息获取

```go
// 获取总数
total := database.Count("user", common.Map{
    "status": 1,
})

// 计算分页信息
page := 2
pageSize := 20
offset := (page - 1) * pageSize
totalPages := (total + pageSize - 1) / pageSize

fmt.Printf("总记录数: %d, 总页数: %d, 当前页: %d\n", total, totalPages, page)
```

## 聚合函数

### 计数

```go
// 总数统计
total := database.Count("user")

// 条件统计
activeUsers := database.Count("user", common.Map{
    "status": 1,
})

// JOIN统计
count := database.Count("user", 
    common.Slice{
        common.Map{"[>]profile": "user.id = profile.user_id"},
    },
    common.Map{
        "user.status": 1,
        "profile.verified": 1,
    },
)
```

### 求和

```go
// 基本求和
totalAmount := database.Sum("order", "amount")

// 条件求和
paidAmount := database.Sum("order", "amount", common.Map{
    "status": "paid",
    "created_time[>]": "2023-01-01",
})
```

### 平均值

```go
// 基本平均值
avgAge := database.Avg("user", "age")

// 条件平均值
avgAge := database.Avg("user", "age", common.Map{
    "status": 1,
})
```

### 最大值/最小值

```go
// 最大值
maxAge := database.Max("user", "age")

// 最小值
minAge := database.Min("user", "age")

// 条件最大值
maxBalance := database.Max("user", "balance", common.Map{
    "status": 1,
})
```

## 事务处理

```go
// 事务操作
success := database.Action(func(tx db.HoTimeDB) bool {
    // 在事务中执行多个操作
    
    // 扣减用户余额
    affected1 := tx.Update("user", common.Map{
        "balance[#]": "balance - 100",
    }, common.Map{
        "id": 1,
    })
    
    if affected1 == 0 {
        return false // 回滚
    }
    
    // 创建订单
    orderId := tx.Insert("order", common.Map{
        "user_id": 1,
        "amount": 100,
        "status": "paid",
        "created_time[#]": "NOW()",
    })
    
    if orderId == 0 {
        return false // 回滚
    }
    
    return true // 提交
})

if success {
    fmt.Println("事务执行成功")
} else {
    fmt.Println("事务回滚")
    fmt.Println("错误:", database.LastErr.GetError())
}
```

## 缓存机制

HoTimeDB集成了缓存功能，可以自动缓存查询结果：

### 缓存配置

```go
import "code.hoteas.com/golang/hotime/cache"

// 设置缓存
database.HoTimeCache = &cache.HoTimeCache{
    // 缓存配置
}
```

### 缓存行为

- 查询操作会自动检查缓存
- 增删改操作会自动清除相关缓存
- 缓存键格式：`表名:查询MD5`
- `cached`表不会被缓存

### 缓存清理

```go
// 手动清除表缓存
database.HoTimeCache.Db("user*", nil) // 清除user表所有缓存
```

## PostgreSQL支持

HoTimeDB 支持 PostgreSQL 数据库，自动处理语法差异。

### PostgreSQL 配置

```go
import (
    "code.hoteas.com/golang/hotime/db"
    _ "github.com/lib/pq" // PostgreSQL 驱动
)

database := &db.HoTimeDB{
    Type: "postgres", // 设置数据库类型为 postgres
    Prefix: "app_",
}

database.SetConnect(func(err ...*common.Error) (master, slave *sql.DB) {
    dsn := "host=localhost port=5432 user=postgres password=secret dbname=mydb sslmode=disable"
    master, _ = sql.Open("postgres", dsn)
    return master, master
})
```

### 主要差异

| 特性 | MySQL | PostgreSQL |
|------|-------|------------|
| 标识符引号 | \`name\` | "name" |
| 占位符 | ? | $1, $2, $3... |
| Upsert | ON DUPLICATE KEY UPDATE | ON CONFLICT DO UPDATE |

所有这些差异由框架自动处理，无需手动调整代码。

## 高级特性

### 调试模式

```go
// 设置调试模式
database.Mode = 2

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

### 主从分离

```go
func createConnection() (master, slave *sql.DB) {
    // 主库连接
    master, _ = sql.Open("mysql", "user:password@tcp(master:3306)/database")
    
    // 从库连接
    slave, _ = sql.Open("mysql", "user:password@tcp(slave:3306)/database")
    
    return master, slave
}

database.SetConnect(createConnection)
// 查询会自动使用从库，增删改使用主库
```

### 原生SQL执行

```go
// 执行查询SQL
results := database.Query("SELECT * FROM user WHERE age > ? AND status = ?", 18, 1)

// 执行更新SQL
result, err := database.Exec("UPDATE user SET last_login = NOW() WHERE id = ?", 1)
if err.GetError() == nil {
    affected, _ := result.RowsAffected()
    fmt.Println("影响行数:", affected)
}
```

## 特殊语法详解

### 条件标记符说明

| 标记符 | 功能 | 示例 | 生成SQL |
|--------|------|------|---------|
| `[>]` | 大于 | `"age[>]": 18` | `age > 18` |
| `[<]` | 小于 | `"age[<]": 60` | `age < 60` |
| `[>=]` | 大于等于 | `"age[>=]": 18` | `age >= 18` |
| `[<=]` | 小于等于 | `"age[<=]": 60` | `age <= 60` |
| `[!]` | 不等于/NOT IN | `"id[!]": 1` | `id != 1` |
| `[~]` | LIKE模糊查询 | `"name[~]": "张"` | `name LIKE '%张%'` |
| `[!~]` | 左模糊 | `"name[!~]": "张"` | `name LIKE '%张'` |
| `[~!]` | 右模糊 | `"name[~!]": "张"` | `name LIKE '张%'` |
| `[~~]` | 手动LIKE | `"name[~~]": "%张%"` | `name LIKE '%张%'` |
| `[<>]` | BETWEEN | `"age[<>]": [18,60]` | `age BETWEEN 18 AND 60` |
| `[><]` | NOT BETWEEN | `"age[><]": [18,25]` | `age NOT BETWEEN 18 AND 25` |
| `[#]` | 直接SQL | `"time[#]": "NOW()"` | `time = NOW()` |
| `[##]` | SQL片段 | `"[##]": "a > b"` | `a > b` |
| `[#!]` | 不等于直接SQL | `"status[#!]": "1"` | `status != 1` |
| `[!#]` | 不等于直接SQL | `"status[!#]": "1"` | `status != 1` |

### 特殊关键字（支持大小写）

| 关键字 | 功能 | 示例 |
|--------|------|------|
| `ORDER` / `order` | 排序 | `"ORDER": "id DESC"` |
| `GROUP` / `group` | 分组 | `"GROUP": "dept_id"` |
| `LIMIT` / `limit` | 限制 | `"LIMIT": 10` |
| `OFFSET` / `offset` | 偏移 | `"OFFSET": 20` |
| `HAVING` / `having` | 分组过滤 | `"HAVING": Map{"cnt[>]": 5}` |
| `DISTINCT` / `distinct` | 去重 | 在 SELECT 中使用 |

## 常见问题

### Q1: 多条件查询需要用 AND 包装吗？
A1: 不再需要！现在多条件会自动用 AND 连接。当然，使用 `AND` 包装仍然有效（向后兼容）。

### Q2: 如何处理事务中的错误？
A2: 在 `Action` 函数中返回 `false` 即可触发回滚，所有操作都会被撤销。

### Q3: 缓存何时会被清除？
A3: 执行 `Insert`、`Update`、`Delete`、`Upsert`、`BatchInsert` 操作时会自动清除对应表的缓存。

### Q4: 如何执行复杂的原生SQL？
A4: 使用 `Query` 方法执行查询，使用 `Exec` 方法执行更新操作。

### Q5: 主从分离如何工作？
A5: 查询操作自动使用从库（如果配置了），增删改操作使用主库。

### Q6: 如何处理NULL值？
A6: 使用 `nil` 作为值，查询时使用 `"field": nil` 表示 `IS NULL`。

### Q7: PostgreSQL 和 MySQL 语法有区别吗？
A7: 框架会自动处理差异（占位符、引号等），代码无需修改。

---

*文档版本: 2.0*  
*最后更新: 2026年1月*

> 本文档基于HoTimeDB源码分析生成，如有疑问请参考源码实现。该ORM框架参考了PHP Medoo的设计理念，但根据Golang语言特性进行了适配和优化。