hotime/db/README.md

# HoTimeDB ORM 文档集合

这是HoTimeDB ORM框架的完整文档集合，包含使用说明、API参考、示例代码和测试数据。

## ⚠️ 重要更新说明

**语法修正通知**：经过对源码的深入分析，发现HoTimeDB的条件查询语法有特定规则：
- ✅ **单个条件**：可以直接写在Map中 
- ⚠️ **多个条件**：必须使用`AND`或`OR`包装
- 📝 所有文档和示例代码已按正确语法更新

## 📚 文档列表

### 1. [HoTimeDB_使用说明.md](./HoTimeDB_使用说明.md)
**完整使用说明书** - 详细的功能介绍和使用指南
- 🚀 快速开始
- ⚙️ 数据库配置
- 🔧 基本操作 (CRUD)
- 🔗 链式查询构建器
- 🔍 条件查询语法
- 🔄 JOIN操作
- 📄 分页查询
- 📊 聚合函数
- 🔐 事务处理
- 💾 缓存机制
- ⚡ 高级特性

### 2. [HoTimeDB_API参考.md](./HoTimeDB_API参考.md)
**快速API参考手册** - 开发时的速查手册
- 📖 基本方法
- 🔧 CRUD操作
- 📊 聚合函数
- 📄 分页查询
- 🔍 条件语法参考
- 🔗 JOIN语法
- 🔐 事务处理
- 🛠️ 工具方法

### 3. [示例代码文件](../examples/hotimedb_examples.go)
**完整示例代码集合** - 可运行的实际应用示例（语法已修正）
- 🏗️ 基本初始化和配置
- 📝 基本CRUD操作
- 🔗 链式查询操作
- 🤝 JOIN查询操作
- 🔍 条件查询语法
- 📄 分页查询
- 📊 聚合函数查询
- 🔐 事务处理
- 💾 缓存机制
- 🔧 原生SQL执行
- 🚨 错误处理和调试
- ⚡ 性能优化技巧
- 🎯 完整应用示例

### 4. [test_tables.sql](./test_tables.sql)
**测试数据库结构** - 快速搭建测试环境
- 🏗️ 完整的表结构定义
- 📊 测试数据插入
- 🔍 索引优化
- 👁️ 视图示例
- 🔧 存储过程示例

## 🎯 核心特性

### 🌟 主要优势
- **类Medoo语法**: 参考PHP Medoo设计，语法简洁易懂
- **链式查询**: 支持流畅的链式查询构建器
- **条件丰富**: 支持丰富的条件查询语法
- **事务支持**: 完整的事务处理机制
- **缓存集成**: 内置查询结果缓存
- **读写分离**: 支持主从数据库配置
- **类型安全**: 基于Golang的强类型系统

### 🔧 支持的数据库
- ✅ MySQL
- ✅ SQLite
- ✅ 其他标准SQL数据库

## 🚀 快速开始

### 1. 安装依赖
```bash
go mod init your-project
go get github.com/go-sql-driver/mysql
go get github.com/sirupsen/logrus
```

### 2. 创建测试数据库
```bash
mysql -u root -p < test_tables.sql
```

### 3. 基本使用
```go
import (
    "code.hoteas.com/golang/hotime/db"
    "code.hoteas.com/golang/hotime/common"
    "database/sql"
    _ "github.com/go-sql-driver/mysql"
)

// 初始化数据库
database := &db.HoTimeDB{
    Prefix: "app_",
    Mode:   2, // 开发模式
}

database.SetConnect(func() (master, slave *sql.DB) {
    master, _ = sql.Open("mysql", "user:pass@tcp(localhost:3306)/dbname")
    return master, master
})

// 链式查询（链式语法支持单独Where然后用And添加条件）
users := database.Table("user").
    Where("status", 1).       // 链式中可以单独Where
    And("age[>]", 18).        // 用And添加更多条件
    Order("created_time DESC").
    Limit(0, 10).
    Select("id,name,email")

// 或者使用传统语法（多个条件必须用AND包装）
users2 := database.Select("user", "id,name,email", common.Map{
    "AND": common.Map{
        "status": 1,
        "age[>]": 18,
    },
    "ORDER": "created_time DESC",
    "LIMIT": []int{0, 10},
})
```

## ⚠️ 重要语法规则

**条件查询语法规则：**
- ✅ **单个条件**：可以直接写在Map中
- ✅ **多个条件**：必须使用`AND`或`OR`包装
- ✅ **特殊参数**：`ORDER`、`GROUP`、`LIMIT`与条件同级

```go
// ✅ 正确：单个条件
Map{"status": 1}

// ✅ 正确：多个条件用AND包装  
Map{
    "AND": Map{
        "status": 1,
        "age[>]": 18,
    },
    "ORDER": "id DESC",
}

// ❌ 错误：多个条件不用AND包装
Map{
    "status": 1,
    "age[>]": 18,  // 不支持！
}
```

## 📝 条件查询语法速查

| 语法 | SQL | 说明 |
|------|-----|------|
| `"field": value` | `field = ?` | 等于 |
| `"field[!]": value` | `field != ?` | 不等于 |
| `"field[>]": value` | `field > ?` | 大于 |
| `"field[>=]": value` | `field >= ?` | 大于等于 |
| `"field[<]": value` | `field < ?` | 小于 |
| `"field[<=]": value` | `field <= ?` | 小于等于 |
| `"field[~]": "keyword"` | `field LIKE '%keyword%'` | 包含 |
| `"field[<>]": [min, max]` | `field BETWEEN ? AND ?` | 区间内 |
| `"field": [v1, v2, v3]` | `field IN (?, ?, ?)` | 在集合中 |
| `"field": nil` | `field IS NULL` | 为空 |
| `"field[#]": "NOW()"` | `field = NOW()` | 直接SQL |

## 🔗 JOIN语法速查

| 语法 | SQL | 说明 |
|------|-----|------|
| `"[>]table"` | `LEFT JOIN` | 左连接 |
| `"[<]table"` | `RIGHT JOIN` | 右连接 |
| `"[><]table"` | `INNER JOIN` | 内连接 |
| `"[<>]table"` | `FULL JOIN` | 全连接 |

## 🛠️ 链式方法速查

```go
db.Table("table")           // 指定表名
  .Where(key, value)        // WHERE条件
  .And(key, value)          // AND条件
  .Or(map)                  // OR条件
  .LeftJoin(table, on)      // LEFT JOIN
  .Order(fields...)         // ORDER BY
  .Group(fields...)         // GROUP BY
  .Limit(offset, limit)     // LIMIT
  .Page(page, pageSize)     // 分页
  .Select(fields...)        // 查询
  .Get(fields...)           // 获取单条
  .Count()                  // 计数
  .Update(data)             // 更新
  .Delete()                 // 删除
```

## ⚡ 性能优化建议

### 🔍 查询优化
- 使用合适的索引字段作为查询条件
- IN查询会自动优化为BETWEEN（连续数字）
- 避免SELECT *，指定需要的字段
- 合理使用LIMIT限制结果集大小

### 💾 缓存使用
- 查询结果会自动缓存
- 增删改操作会自动清除缓存
- `cached`表不参与缓存

### 🔐 事务处理
- 批量操作使用事务提高性能
- 事务中避免长时间操作
- 合理设置事务隔离级别

## 🚨 注意事项

### 🔒 安全相关
- 使用参数化查询防止SQL注入
- `[#]`语法需要注意防止注入
- 敏感数据加密存储

### 🎯 最佳实践
- 开发时设置`Mode = 2`便于调试
- 生产环境设置`Mode = 0`
- 合理设置表前缀
- 定期检查慢查询日志

## 🤝 与PHP Medoo的差异

1. **类型系统**: 使用`common.Map`和`common.Slice`
2. **错误处理**: Golang风格的错误处理
3. **链式调用**: 提供更丰富的链式API
4. **缓存集成**: 内置缓存功能
5. **并发安全**: 需要注意并发使用

## 📞 技术支持

- 📧 查看源码：`hotimedb.go`
- 📖 参考文档：本目录下的各个文档文件
- 🔧 示例代码：运行`HoTimeDB_示例代码.go`中的示例

---

**HoTimeDB ORM框架 - 让数据库操作更简单！** 🎉

> 本文档基于HoTimeDB源码分析生成，参考了PHP Medoo的设计理念，并根据Golang语言特性进行了优化。