252 lines
6.9 KiB
Markdown
252 lines
6.9 KiB
Markdown
# 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语言特性进行了优化。 |