14 KiB

Raw Blame History

Gomog 用户手册

版本: v1.0.0-alpha
最后更新: 2026-03-14
许可证: MIT

📖 目录

简介
快速开始
安装与配置
基本使用
高级功能
最佳实践
故障排查
常见问题

简介

什么是 Gomog？

Gomog 是一个兼容 MongoDB 风格 API 的内存查询引擎，支持多数据库适配（SQLite、PostgreSQL、达梦 DM8）。它提供了丰富的聚合管道、查询操作符和更新操作符，让你能够以熟悉的方式操作关系型数据库。

核心特性

✅ MongoDB 风格 API: 熟悉的查询语法，零学习成本
✅ 多数据库支持: SQLite、PostgreSQL、达梦 DM8
✅ 完整的聚合管道: 18+ 个聚合阶段，50+ 个聚合表达式
✅ 丰富的查询操作符: 16+ 个查询操作符
✅ 强大的更新操作符: 17+ 个更新操作符
✅ HTTP 和 TCP 双协议: RESTful API 和 MongoDB 线协议支持
✅ 高性能: 内存优化，并发安全

适用场景

快速原型开发
数据分析和报表
遗留系统现代化
多数据库统一访问层
教学和实验环境

快速开始

1. 下载与安装

# 从源码编译
git clone https://github.com/gomog/gomog.git
cd gomog
make build

# 或使用 Docker
docker pull gomog:latest

2. 配置文件

复制示例配置文件：

cp config.yaml.example config.yaml

编辑 config.yaml：

server:
  http_addr: ":8080"
  tcp_addr: ":27017"
  mode: "dev"

database:
  type: "sqlite"
  dsn: "gomog.db"
  max_open: 10
  max_idle: 5

log:
  level: "info"
  format: "text"

3. 启动服务

# 直接运行
./bin/gomog -config config.yaml

# 或使用 make
make run

# Docker 运行
docker run -p 8080:8080 -p 27017:27017 gomog:latest

4. 验证安装

# HTTP 健康检查
curl http://localhost:8080/health

# 插入测试数据
curl -X POST http://localhost:8080/api/v1/testdb/users/insert \
  -H "Content-Type: application/json" \
  -d '{"documents": [{"name": "Alice", "age": 30}]}'

# 查询数据
curl -X POST http://localhost:8080/api/v1/testdb/users/find \
  -H "Content-Type: application/json" \
  -d '{"filter": {"age": {"$gt": 25}}}'

安装与配置

系统要求

操作系统: Linux, macOS, Windows
Go 版本: 1.21+
内存: 最少 512MB，推荐 1GB+
磁盘: 最少 100MB 可用空间

安装方式

方式一：源码编译（推荐）

# 克隆仓库
git clone https://github.com/gomog/gomog.git
cd gomog

# 编译
make build

# 验证
./bin/gomog --version

方式二：Docker

# 拉取镜像
docker pull gomog:latest

# 运行
docker run -d \
  --name gomog \
  -p 8080:8080 \
  -p 27017:27017 \
  -v $(pwd)/data:/data \
  gomog:latest

方式三：包管理器（待提供）

# Ubuntu/Debian
sudo apt install gomog

# CentOS/RHEL
sudo yum install gomog

# macOS (Homebrew)
brew install gomog

配置详解

服务器配置

server:
  # HTTP 监听地址
  # 格式：[host]:port
  # 默认：":8080"
  http_addr: ":8080"
  
  # TCP 监听地址（MongoDB 线协议）
  # 格式：[host]:port
  # 默认：":27017"
  tcp_addr: ":27017"
  
  # 运行模式
  # 可选值：dev, prod
  # dev: 详细日志，调试信息
  # prod: 精简日志，性能优化
  mode: "dev"

数据库配置

database:
  # 数据库类型
  # 可选值：sqlite, postgres, dm8
  type: "sqlite"
  
  # 数据源名称
  # SQLite: 文件路径或 :memory:
  # PostgreSQL: postgresql://user:pass@host:port/dbname?sslmode=disable
  # DM8: dm://user:pass@host:port/dbname
  dsn: "gomog.db"
  
  # 最大打开连接数
  # 默认：10
  max_open: 10
  
  # 最大空闲连接数
  # 默认：5
  max_idle: 5
  
  # 连接最大生命周期（可选）
  # 格式：时间 Duration 字符串
  # 默认："4h"
  max_lifetime: "4h"

日志配置

log:
  # 日志级别
  # 可选值：debug, info, warn, error
  # debug: 所有日志
  # info: 常规信息
  # warn: 警告信息
  # error: 错误信息
  level: "info"
  
  # 日志格式
  # 可选值：text, json
  # text: 人类可读格式
  # json: 结构化 JSON 格式
  format: "text"
  
  # 日志输出文件（可选）
  # 默认：stdout
  output: "/var/log/gomog/gomog.log"

环境变量

Gomog 支持通过环境变量覆盖配置文件：

环境变量	配置项	示例
`GOMOG_HTTP_ADDR`	server.http_addr	`GOMOG_HTTP_ADDR=:9000`
`GOMOG_TCP_ADDR`	server.tcp_addr	`GOMOG_TCP_ADDR=:27018`
`GOMOG_DB_TYPE`	database.type	`GOMOG_DB_TYPE=postgres`
`GOMOG_DB_DSN`	database.dsn	`GOMOG_DB_DSN=mydb.db`
`GOMOG_LOG_LEVEL`	log.level	`GOMOG_LOG_LEVEL=debug`

基本使用

数据库和集合管理

创建数据库

Gomog 会自动创建不存在的数据库，无需手动创建。

创建集合

同样，集合会在首次插入数据时自动创建。

列出所有数据库

curl -X POST http://localhost:8080/api/v1/admin/listDatabases

列出所有集合

curl -X POST http://localhost:8080/api/v1/{database}/listCollections

CRUD 操作

插入（Insert）

# 单条插入
curl -X POST http://localhost:8080/api/v1/testdb/users/insert \
  -H "Content-Type: application/json" \
  -d '{"documents": [{"name": "Alice", "age": 30}]}'

# 批量插入
curl -X POST http://localhost:8080/api/v1/testdb/users/insert \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {"name": "Bob", "age": 25},
      {"name": "Charlie", "age": 35}
    ]
  }'

查询（Find）

# 查询所有
curl -X POST http://localhost:8080/api/v1/testdb/users/find \
  -H "Content-Type: application/json" \
  -d '{}'

# 条件查询
curl -X POST http://localhost:8080/api/v1/testdb/users/find \
  -H "Content-Type: application/json" \
  -d '{"filter": {"age": {"$gt": 28}}}'

# 投影（选择字段）
curl -X POST http://localhost:8080/api/v1/testdb/users/find \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"age": {"$gt": 28}},
    "projection": {"name": 1, "age": 1}
  }'

更新（Update）

# 更新单个文档
curl -X POST http://localhost:8080/api/v1/testdb/users/update \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"name": "Alice"},
    "update": {"$set": {"age": 31}}
  }'

# 更新多个文档
curl -X POST http://localhost:8080/api/v1/testdb/users/update \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {},
    "update": {"$inc": {"age": 1}},
    "multi": true
  }'

# Upsert（不存在则插入）
curl -X POST http://localhost:8080/api/v1/testdb/users/update \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"name": "David"},
    "update": {"$setOnInsert": {"name": "David", "age": 28}},
    "upsert": true
  }'

删除（Delete）

# 删除单个文档
curl -X POST http://localhost:8080/api/v1/testdb/users/delete \
  -H "Content-Type: application/json" \
  -d '{"filter": {"name": "Alice"}}'

# 删除多个文档
curl -X POST http://localhost:8080/api/v1/testdb/users/delete \
  -H "Content-Type: application/json" \
  -d '{"filter": {"age": {"$lt": 30}}, "multi": true}'

聚合操作

# 简单聚合
curl -X POST http://localhost:8080/api/v1/testdb/users/aggregate \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline": [
      {"$match": {"age": {"$gte": 30}}},
      {"$group": {
        "_id": "$department",
        "count": {"$sum": 1},
        "avgAge": {"$avg": "$age"}
      }}
    ]
  }'

高级功能

聚合管道

Gomog 支持完整的 MongoDB 聚合管道，包括：

1. 数据过滤

{
  "pipeline": [
    {"$match": {"status": "active"}},
    {"$limit": 10},
    {"$skip": 5}
  ]
}

2. 数据转换

{
  "pipeline": [
    {"$addFields": {"fullName": {"$concat": ["$firstName", " ", "$lastName"]}}},
    {"$project": {"_id": 0, "fullName": 1, "email": 1}}
  ]
}

3. 数据分组

{
  "pipeline": [
    {"$group": {
      "_id": "$category",
      "total": {"$sum": "$amount"},
      "average": {"$avg": "$price"}
    }}
  ]
}

4. 数据排序

{
  "pipeline": [
    {"$sort": {"created_at": -1}},
    {"$limit": 10}
  ]
}

5. 关联查询（Lookup）

{
  "pipeline": [
    {"$lookup": {
      "from": "orders",
      "localField": "_id",
      "foreignField": "userId",
      "as": "orders"
    }}
  ]
}

文本搜索

curl -X POST http://localhost:8080/api/v1/testdb/articles/aggregate \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline": [
      {"$match": {"$text": {"$search": "database performance"}}},
      {"$sort": {"score": {"$meta": "textScore"}}}
    ]
  }'

窗口函数

curl -X POST http://localhost:8080/api/v1/testdb/sales/aggregate \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline": [{
      "$setWindowFields": {
        "partitionBy": "$region",
        "sortBy": {"date": 1},
        "output": {
          "runningTotal": {
            "$sum": "$amount",
            "window": {"documents": ["unbounded", "current"]}
          },
          "rank": {"$documentNumber": {}}
        }
      }
    }]
  }'

递归查找

curl -X POST http://localhost:8080/api/v1/testdb/orgs/aggregate \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline": [{
      "$graphLookup": {
        "from": "orgs",
        "startWith": "$parentId",
        "connectFromField": "_id",
        "connectToField": "parentId",
        "as": "subOrgs",
        "maxDepth": 5
      }
    }]
  }'

最佳实践

性能优化

1. 合理使用索引

# 为常用查询字段创建索引
curl -X POST http://localhost:8080/api/v1/testdb/users/createIndex \
  -H "Content-Type: application/json" \
  -d '{"keys": {"email": 1}, "unique": true}'

2. 避免全表扫描

# ❌ 不推荐：全表扫描
{"filter": {"$expr": {"$gt": ["$age", 25]}}}

# ✅ 推荐：使用索引
{"filter": {"age": {"$gt": 25}}}

3. 限制返回结果

# 总是使用 limit 限制返回数量
{"limit": 100}

4. 使用投影减少数据传输

# 只返回需要的字段
{"projection": {"name": 1, "email": 1}}

数据安全

1. 输入验证

始终在应用层验证用户输入，不要完全依赖数据库验证。

2. 参数化查询

使用 Gomog 的参数化机制，避免注入攻击。

3. 权限控制

在生产环境中使用数据库的权限控制机制。

监控与日志

1. 启用慢查询日志

log:
  level: "debug"
  slow_query_threshold: "100ms"

2. 监控关键指标

QPS（每秒查询数）
平均响应时间
错误率
连接池使用率

故障排查

常见问题

1. 无法启动服务

症状: 启动时报错 "address already in use"

解决:

# 检查端口占用
lsof -i :8080
lsof -i :27017

# 修改配置文件使用其他端口
server:
  http_addr: ":8081"
  tcp_addr: ":27018"

2. 数据库连接失败

症状: "failed to connect to database"

解决:

# 检查数据库配置
cat config.yaml | grep -A 5 database

# 验证数据库服务是否运行
# PostgreSQL
pg_isready -h localhost -p 5432

# SQLite
ls -la gomog.db

3. 查询性能慢

症状: 查询响应时间超过预期

解决:

# 1. 查看执行计划
curl -X POST http://localhost:8080/api/v1/testdb/users/explain \
  -H "Content-Type: application/json" \
  -d '{"filter": {"age": {"$gt": 25}}}'

# 2. 添加索引
curl -X POST http://localhost:8080/api/v1/testdb/users/createIndex \
  -H "Content-Type: application/json" \
  -d '{"keys": {"age": 1}}'

# 3. 优化查询
# 避免使用 $expr，改用原生操作符

4. 内存不足

症状: OOM killer 杀死进程

解决:

# 限制连接池大小
database:
  max_open: 5
  max_idle: 2

日志分析

查看日志

# 实时查看日志
tail -f /var/log/gomog/gomog.log

# 搜索错误
grep "ERROR" /var/log/gomog/gomog.log

日志级别说明

DEBUG: 详细调试信息，包含所有查询和响应
INFO: 常规运行信息
WARN: 警告信息，不影响正常运行
ERROR: 错误信息，需要关注

常见问题

Q: Gomog 与 MongoDB 有什么区别？

A: Gomog 是一个兼容 MongoDB 风格 API 的查询引擎，底层可以使用 SQLite、PostgreSQL 等关系型数据库。它不是 MongoDB 的直接替代品，而是提供了一种熟悉的方式来操作关系型数据库。

Q: 支持哪些 MongoDB 操作符？

A: Gomog 支持 16+ 个查询操作符、17+ 个更新操作符、18+ 个聚合阶段和 50+ 个聚合表达式。详见 API 参考文档。

Q: 如何在生产环境使用？

设置 mode: "prod"
配置合适的连接池大小
启用日志持久化
配置监控告警
定期备份数据

Q: 是否支持事务？

A: 取决于底层数据库。PostgreSQL 和达梦 DM8 支持事务，SQLite 支持有限的事务。

Q: 如何备份数据？

SQLite: 直接复制 .db 文件
PostgreSQL: 使用 pg_dump
DM8: 使用 DM 的备份工具

Q: 性能如何？

A: 对于中小规模数据集（<100 万条记录），Gomog 能提供亚秒级的查询响应。对于大规模数据，建议使用原生数据库客户端以获得最佳性能。

获取帮助

文档: /manual 目录
示例: API_EXAMPLES.md
问题反馈: GitHub Issues
社区讨论: GitHub Discussions

维护者: Gomog Team
许可证: MIT

14 KiB Raw Blame History Unescape Escape

Gomog 用户手册

📖 目录

简介

什么是 Gomog？

核心特性

适用场景

快速开始

1. 下载与安装

2. 配置文件

3. 启动服务

4. 验证安装

安装与配置

系统要求

安装方式

方式一：源码编译（推荐）

方式二：Docker

方式三：包管理器（待提供）

配置详解

服务器配置

数据库配置

日志配置

环境变量

基本使用

数据库和集合管理

创建数据库

创建集合

列出所有数据库

列出所有集合

CRUD 操作

插入（Insert）

查询（Find）

更新（Update）

删除（Delete）

聚合操作

高级功能

聚合管道

1. 数据过滤

2. 数据转换

3. 数据分组

4. 数据排序

5. 关联查询（Lookup）

文本搜索

窗口函数

递归查找

最佳实践

性能优化

1. 合理使用索引

2. 避免全表扫描

3. 限制返回结果

4. 使用投影减少数据传输

数据安全

1. 输入验证

2. 参数化查询

3. 权限控制

监控与日志

1. 启用慢查询日志

2. 监控关键指标

故障排查

常见问题

1. 无法启动服务

2. 数据库连接失败

3. 查询性能慢

4. 内存不足

日志分析

查看日志

日志级别说明

常见问题

Q: Gomog 与 MongoDB 有什么区别？

Q: 支持哪些 MongoDB 操作符？

Q: 如何在生产环境使用？

Q: 是否支持事务？

Q: 如何备份数据？

Q: 性能如何？

获取帮助

14 KiB

Raw Blame History