9.8 KiB

Raw Permalink Blame History

Gomog API 使用示例

本文档提供详细的 API 使用示例，帮助你快速上手 Gomog 服务器。

基础配置

默认服务器地址：

HTTP: http://localhost:8080
TCP: localhost:27017

API 路径格式：/api/v1/{database}/{collection}/{operation}

插入操作 (Insert)

单条插入

curl -X POST http://localhost:8080/api/v1/testdb/users/insert \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "name": "张三",
        "age": 28,
        "email": "zhangsan@example.com",
        "department": "技术部",
        "skills": ["Go", "Python", "Linux"],
        "created_at": "2024-01-01T00:00:00Z"
      }
    ]
  }'

响应：

{
  "ok": 1,
  "n": 1,
  "insertedIds": {
    "0": "20240101120000.000000000"
  }
}

批量插入

curl -X POST http://localhost:8080/api/v1/testdb/users/insert \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {"name": "李四", "age": 32, "department": "产品部"},
      {"name": "王五", "age": 25, "department": "技术部"},
      {"name": "赵六", "age": 30, "department": "设计部"}
    ],
    "ordered": true
  }'

查询操作 (Find)

基本查询

curl -X POST http://localhost:8080/api/v1/testdb/users/find \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"department": "技术部"}
  }'

条件查询

比较操作符

# 年龄大于 28
curl -X POST http://localhost:8080/api/v1/testdb/users/find \
  -H "Content-Type: application/json" \
  -d '{"filter": {"age": {"$gt": 28}}}'

# 年龄小于等于 30
curl -X POST http://localhost:8080/api/v1/testdb/users/find \
  -H "Content-Type: application/json" \
  -d '{"filter": {"age": {"$lte": 30}}}'

# 年龄在范围内
curl -X POST http://localhost:8080/api/v1/testdb/users/find \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "age": {"$gte": 25, "$lte": 30}
    }
  }'

逻辑操作符

# OR 查询
curl -X POST http://localhost:8080/api/v1/testdb/users/find \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "$or": [
        {"department": "技术部"},
        {"department": "产品部"}
      ]
    }
  }'

# AND 查询
curl -X POST http://localhost:8080/api/v1/testdb/users/find \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "$and": [
        {"age": {"$gt": 25}},
        {"department": "技术部"}
      ]
    }
  }'

数组操作符

# IN 查询
curl -X POST http://localhost:8080/api/v1/testdb/users/find \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "department": {"$in": ["技术部", "产品部"]}
    }
  }'

# 包含所有指定技能
curl -X POST http://localhost:8080/api/v1/testdb/users/find \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "skills": {"$all": ["Go", "Python"]}
    }
  }'

投影（选择字段）

# 只返回 name 和 email
curl -X POST http://localhost:8080/api/v1/testdb/users/find \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"department": "技术部"},
    "projection": {"name": 1, "email": 1, "_id": 1}
  }'

排序

# 按年龄降序
curl -X POST http://localhost:8080/api/v1/testdb/users/find \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {},
    "sort": {"age": -1}
  }'

# 多字段排序
curl -X POST http://localhost:8080/api/v1/testdb/users/find \
  -H "Content-Type: application/json" \
  -d '{
    "sort": {"department": 1, "age": -1}
  }'

分页

# 跳过前 10 条，取 20 条
curl -X POST http://localhost:8080/api/v1/testdb/users/find \
  -H "Content-Type: application/json" \
  -d '{
    "skip": 10,
    "limit": 20
  }'

更新操作 (Update)

单条更新

curl -X POST http://localhost:8080/api/v1/testdb/users/update \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {
        "q": {"name": "张三"},
        "u": {"$set": {"age": 29, "email": "zhangsan.new@example.com"}}
      }
    ]
  }'

批量更新

curl -X POST http://localhost:8080/api/v1/testdb/users/update \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {
        "q": {"department": "技术部"},
        "u": {"$set": {"status": "active"}},
        "multi": true
      }
    ]
  }'

数值操作

# 递增年龄
curl -X POST http://localhost:8080/api/v1/testdb/users/update \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {
        "q": {"name": "李四"},
        "u": {"$inc": {"age": 1}}
      }
    ]
  }'

# 乘以系数
curl -X POST http://localhost:8080/api/v1/testdb/orders/update \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {
        "q": {"category": "electronics"},
        "u": {"$mul": {"price": 0.9}}
      }
    ]
  }'

移除字段

curl -X POST http://localhost:8080/api/v1/testdb/users/update \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {
        "q": {"name": "王五"},
        "u": {"$unset": {"temp_field": 1}}
      }
    ]
  }'

数组操作

# 推入数组
curl -X POST http://localhost:8080/api/v1/testdb/users/update \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {
        "q": {"name": "张三"},
        "u": {"$push": {"skills": "Java"}}
      }
    ]
  }'

# 从数组中移除
curl -X POST http://localhost:8080/api/v1/testdb/users/update \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {
        "q": {"name": "张三"},
        "u": {"$pull": {"skills": "Python"}}
      }
    ]
  }'

删除操作 (Delete)

删除单个文档

curl -X POST http://localhost:8080/api/v1/testdb/users/delete \
  -H "Content-Type: application/json" \
  -d '{
    "deletes": [
      {
        "q": {"name": "赵六"},
        "limit": 1
      }
    ]
  }'

删除多个文档

curl -X POST http://localhost:8080/api/v1/testdb/users/delete \
  -H "Content-Type: application/json" \
  -d '{
    "deletes": [
      {
        "q": {"department": "设计部"},
        "limit": 0
      }
    ]
  }'

聚合查询 (Aggregate)

简单聚合

分组统计

# 按部门统计人数
curl -X POST http://localhost:8080/api/v1/testdb/users/aggregate \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline": [
      {
        "$group": {
          "_id": "$department",
          "count": {"$sum": 1},
          "avg_age": {"$avg": "$age"}
        }
      }
    ]
  }'

过滤后分组

# 统计技术部员工信息
curl -X POST http://localhost:8080/api/v1/testdb/users/aggregate \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline": [
      {"$match": {"department": "技术部"}},
      {
        "$group": {
          "_id": null,
          "total": {"$sum": 1},
          "max_age": {"$max": "$age"},
          "min_age": {"$min": "$age"}
        }
      }
    ]
  }'

复杂聚合管道

多阶段处理

# 计算各部门活跃员工的平均年龄，并排序
curl -X POST http://localhost:8080/api/v1/testdb/users/aggregate \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline": [
      {"$match": {"status": "active"}},
      {
        "$group": {
          "_id": "$department",
          "avg_age": {"$avg": "$age"},
          "employee_count": {"$sum": 1}
        }
      },
      {"$sort": {"avg_age": -1}},
      {"$limit": 5}
    ]
  }'

字段投影和计算

curl -X POST http://localhost:8080/api/v1/testdb/users/aggregate \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline": [
      {"$match": {"department": "技术部"}},
      {
        "$project": {
          "name": 1,
          "age": 1,
          "skill_count": {"$size": "$skills"},
          "upper_name": {"$toUpper": "$name"}
        }
      }
    ]
  }'

数组展开

# 展开 skills 数组
curl -X POST http://localhost:8080/api/v1/testdb/users/aggregate \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline": [
      {"$unwind": "$skills"},
      {
        "$group": {
          "_id": "$skills",
          "users": {"$push": "$name"}
        }
      }
    ]
  }'

左连接 Lookup

# 关联用户和订单
curl -X POST http://localhost:8080/api/v1/testdb/users/aggregate \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline": [
      {
        "$lookup": {
          "from": "testdb.orders",
          "localField": "_id",
          "foreignField": "user_id",
          "as": "orders"
        }
      }
    ]
  }'

计数

curl -X POST http://localhost:8080/api/v1/testdb/users/aggregate \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline": [
      {"$match": {"status": "active"}},
      {"$count": "active_count"}
    ]
  }'

错误处理

常见错误响应

集合不存在

{
  "ok": 0,
  "error": "collection not found",
  "status": 500
}

无效请求

{
  "ok": 0,
  "error": "invalid request body",
  "status": 400
}

未知操作

{
  "ok": 0,
  "error": "unknown operation: invalid",
  "status": 400
}

最佳实践

1. 批量操作

尽量使用批量插入和批量更新，减少网络往返。

2. 合理使用投影

只查询需要的字段，减少数据传输量。

3. 添加索引

虽然主要在内存查询，但对于大数据集，考虑在数据库层添加索引。

4. 分页查询

使用 skip 和 limit 进行分页，避免一次性加载大量数据。

5. 聚合优化

将 $match 放在管道前面，尽早过滤数据。

TCP 协议示例

如果使用 TCP 协议，消息格式如下：

{
  "operation": "find",
  "collection": "testdb.users",
  "params": {
    "filter": {"age": {"$gte": 25}}
  }
}

发送到 localhost:27017 即可。

9.8 KiB Raw Permalink Blame History