gomog/API_EXAMPLES.md

# Gomog API 使用示例

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

## 基础配置

默认服务器地址：
- HTTP: `http://localhost:8080`
- TCP: `localhost:27017`

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

---

## 插入操作 (Insert)

### 单条插入

```bash
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"
      }
    ]
  }'
```

**响应：**
```json
{
  "ok": 1,
  "n": 1,
  "insertedIds": {
    "0": "20240101120000.000000000"
  }
}
```

### 批量插入

```bash
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)

### 基本查询

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

### 条件查询

#### 比较操作符

```bash
# 年龄大于 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}
    }
  }'
```

#### 逻辑操作符

```bash
# 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": "技术部"}
      ]
    }
  }'
```

#### 数组操作符

```bash
# 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"]}
    }
  }'
```

### 投影（选择字段）

```bash
# 只返回 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}
  }'
```

### 排序

```bash
# 按年龄降序
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}
  }'
```

### 分页

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

---

## 更新操作 (Update)

### 单条更新

```bash
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"}}
      }
    ]
  }'
```

### 批量更新

```bash
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
      }
    ]
  }'
```

### 数值操作

```bash
# 递增年龄
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}}
      }
    ]
  }'
```

### 移除字段

```bash
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}}
      }
    ]
  }'
```

### 数组操作

```bash
# 推入数组
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)

### 删除单个文档

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

### 删除多个文档

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

---

## 聚合查询 (Aggregate)

### 简单聚合

#### 分组统计

```bash
# 按部门统计人数
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"}
        }
      }
    ]
  }'
```

#### 过滤后分组

```bash
# 统计技术部员工信息
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"}
        }
      }
    ]
  }'
```

### 复杂聚合管道

#### 多阶段处理

```bash
# 计算各部门活跃员工的平均年龄，并排序
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}
    ]
  }'
```

#### 字段投影和计算

```bash
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"}
        }
      }
    ]
  }'
```

### 数组展开

```bash
# 展开 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

```bash
# 关联用户和订单
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"
        }
      }
    ]
  }'
```

### 计数

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

---

## 错误处理

### 常见错误响应

#### 集合不存在
```json
{
  "ok": 0,
  "error": "collection not found",
  "status": 500
}
```

#### 无效请求
```json
{
  "ok": 0,
  "error": "invalid request body",
  "status": 400
}
```

#### 未知操作
```json
{
  "ok": 0,
  "error": "unknown operation: invalid",
  "status": 400
}
```

---

## 最佳实践

### 1. 批量操作
尽量使用批量插入和批量更新，减少网络往返。

### 2. 合理使用投影
只查询需要的字段，减少数据传输量。

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

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

### 5. 聚合优化
将 $match 放在管道前面，尽早过滤数据。

---

## TCP 协议示例

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

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

发送到 `localhost:27017` 即可。