245 lines
4.8 KiB
Markdown
245 lines
4.8 KiB
Markdown
# Gomog - MongoDB 风格文档服务器
|
||
|
||
Gomog 是一个使用 Go 语言开发的中间层服务器，提供 MongoDB 风格的 CRUD 操作和聚合查询接口，底层使用关系型数据库的 JSON 字段存储文档数据。
|
||
|
||
## 特性
|
||
|
||
- **MongoDB 风格 API**: 提供类似 MongoDB 的 find/insert/update/delete 操作和聚合管道
|
||
- **多数据库支持**: 通过适配器模式支持 SQLite、PostgreSQL、达梦 DM8 等多种关系型数据库
|
||
- **内存查询引擎**: 在内存中实现查询过滤和聚合逻辑，高性能处理
|
||
- **双协议支持**: 同时支持 HTTP/REST 和 TCP 两种通信协议
|
||
- **灵活的 JSON 存储**: 利用现代关系型数据库的 JSON/JSONB 类型
|
||
|
||
## 快速开始
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
make deps
|
||
```
|
||
|
||
### 配置
|
||
|
||
复制配置文件示例：
|
||
|
||
```bash
|
||
cp config.yaml.example config.yaml
|
||
```
|
||
|
||
编辑 `config.yaml` 配置数据库连接和其他参数。
|
||
|
||
### 运行
|
||
|
||
```bash
|
||
# 开发模式运行
|
||
make run
|
||
|
||
# 或构建后运行
|
||
make build
|
||
./bin/gomog -config config.yaml
|
||
```
|
||
|
||
### 使用 Docker
|
||
|
||
```bash
|
||
# 构建镜像
|
||
make docker-build
|
||
|
||
# 运行容器
|
||
make docker-run
|
||
```
|
||
|
||
## API 使用示例
|
||
|
||
### 插入文档
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/v1/testdb/users/insert \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"documents": [
|
||
{"name": "Alice", "age": 25, "email": "alice@example.com"},
|
||
{"name": "Bob", "age": 30, "email": "bob@example.com"}
|
||
]
|
||
}'
|
||
```
|
||
|
||
### 查询文档
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/v1/testdb/users/find \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"filter": {"age": {"$gte": 25}},
|
||
"projection": {"name": 1, "email": 1},
|
||
"sort": {"age": -1},
|
||
"limit": 10
|
||
}'
|
||
```
|
||
|
||
### 更新文档
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/v1/testdb/users/update \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"updates": [{
|
||
"q": {"name": "Alice"},
|
||
"u": {"$set": {"age": 26}}
|
||
}]
|
||
}'
|
||
```
|
||
|
||
### 删除文档
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/v1/testdb/users/delete \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"deletes": [{
|
||
"q": {"name": "Bob"},
|
||
"limit": 1
|
||
}]
|
||
}'
|
||
```
|
||
|
||
### 聚合查询
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/v1/testdb/orders/aggregate \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"pipeline": [
|
||
{"$match": {"status": "completed"}},
|
||
{"$group": {
|
||
"_id": "$customer_id",
|
||
"total": {"$sum": "$amount"},
|
||
"count": {"$sum": 1}
|
||
}},
|
||
{"$sort": {"total": -1}},
|
||
{"$limit": 10}
|
||
]
|
||
}'
|
||
```
|
||
|
||
## 支持的查询操作符
|
||
|
||
### 比较操作符
|
||
- `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`
|
||
- `$in`, `$nin`
|
||
- `$regex`
|
||
|
||
### 逻辑操作符
|
||
- `$and`, `$or`, `$nor`, `$not`
|
||
|
||
### 元素操作符
|
||
- `$exists`, `$type`
|
||
|
||
### 数组操作符
|
||
- `$all`, `$elemMatch`, `$size`
|
||
|
||
## 支持的聚合阶段
|
||
|
||
- `$match` - 过滤文档
|
||
- `$group` - 分组聚合
|
||
- `$sort` - 排序
|
||
- `$project` - 字段投影
|
||
- `$limit` - 限制结果数量
|
||
- `$skip` - 跳过指定数量的文档
|
||
- `$unwind` - 展开数组
|
||
- `$lookup` - 左连接
|
||
- `$count` - 计数
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
gomog/
|
||
├── cmd/
|
||
│ └── server/ # 应用程序入口
|
||
├── internal/
|
||
│ ├── config/ # 配置管理
|
||
│ ├── protocol/ # 协议层（HTTP/TCP）
|
||
│ ├── parser/ # 请求解析
|
||
│ ├── engine/ # 查询和聚合引擎
|
||
│ ├── storage/ # 存储层
|
||
│ └── database/ # 数据库适配器
|
||
├── pkg/
|
||
│ ├── types/ # 类型定义
|
||
│ └── errors/ # 错误定义
|
||
├── Makefile
|
||
└── config.yaml.example
|
||
```
|
||
|
||
## 数据库配置
|
||
|
||
### SQLite
|
||
|
||
```yaml
|
||
database:
|
||
type: "sqlite"
|
||
dsn: "gomog.db"
|
||
```
|
||
|
||
### PostgreSQL
|
||
|
||
```yaml
|
||
database:
|
||
type: "postgres"
|
||
dsn: "postgres://user:password@localhost:5432/gomog?sslmode=disable"
|
||
```
|
||
|
||
### 达梦 DM8
|
||
|
||
```yaml
|
||
database:
|
||
type: "dm8"
|
||
dsn: "user/password@localhost:5236"
|
||
```
|
||
|
||
## 开发
|
||
|
||
### 运行测试
|
||
|
||
```bash
|
||
make test
|
||
```
|
||
|
||
### 代码格式化
|
||
|
||
```bash
|
||
make fmt
|
||
```
|
||
|
||
### 构建所有平台
|
||
|
||
```bash
|
||
make build-linux
|
||
make build-darwin
|
||
make build-windows
|
||
```
|
||
|
||
## 技术栈
|
||
|
||
- **语言**: Go 1.21+
|
||
- **数据库驱动**:
|
||
- SQLite: github.com/mattn/go-sqlite3
|
||
- PostgreSQL: github.com/lib/pq
|
||
- 达梦 DM8: 官方驱动或 ODBC
|
||
- **配置**: gopkg.in/yaml.v3
|
||
- **日志**: 标准库 log（可升级到 zap）
|
||
|
||
## 注意事项
|
||
|
||
1. **数据一致性**: 内存与数据库的数据同步采用写时异步持久化策略
|
||
2. **内存管理**: 大数据集建议定期重启服务或使用分页加载
|
||
3. **事务支持**: 当前版本简化处理，后续将完善事务支持
|
||
4. **索引优化**: 主要依赖内存查询，后续可添加热点字段索引
|
||
|
||
## 许可证
|
||
|
||
MIT License
|
||
|
||
## 贡献
|
||
|
||
欢迎提交 Issue 和 Pull Request！
|