14 KiB

Raw Permalink Blame History

Gomog HTTP API 参考文档

版本: v1.0.0-alpha
最后更新: 2026-03-14
基础路径: /api/v1

📖 目录

概述
认证与授权
数据库管理
集合管理
文档操作
查询操作
聚合操作
索引管理
错误处理
响应格式

概述

协议

传输协议: HTTP/1.1 或 HTTP/2
数据格式: JSON
字符编码: UTF-8
默认端口: 8080

基础 URL

http://localhost:8080/api/v1/{database}/{collection}/{operation}

URL 参数说明

参数	说明	示例
`{database}`	数据库名称	`testdb`
`{collection}`	集合名称	`users`
`{operation}`	操作类型	`find`, `insert`, `update` 等

HTTP 方法

方法	用途
POST	执行数据库操作（查询、插入、更新、删除等）
GET	获取元数据信息

数据库管理

列出所有数据库

端点: POST /api/v1/admin/listDatabases

请求:

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

响应:

{
  "ok": 1,
  "databases": [
    {"name": "testdb", "sizeOnDisk": 1024, "empty": false},
    {"name": "prod", "sizeOnDisk": 2048, "empty": false}
  ],
  "totalSize": 3072,
  "totalSizeMb": 3
}

列出当前数据库的集合

端点: POST /api/v1/{database}/listCollections

请求:

curl -X POST http://localhost:8080/api/v1/testdb/listCollections

响应:

{
  "ok": 1,
  "collections": [
    {"name": "users", "type": "collection"},
    {"name": "orders", "type": "collection"}
  ]
}

集合管理

创建集合

Gomog 会在首次插入数据时自动创建集合，无需手动创建。

删除集合

端点: POST /api/v1/{database}/{collection}/drop

请求:

curl -X POST http://localhost:8080/api/v1/testdb/users/drop

响应:

{
  "ok": 1,
  "nIndexesWas": 1
}

重命名集合

端点: POST /api/v1/{database}/{collection}/renameCollection

请求:

curl -X POST http://localhost:8080/api/v1/testdb/users/renameCollection \
  -H "Content-Type: application/json" \
  -d '{"to": "members"}'

响应:

{
  "ok": 1
}

文档操作

插入文档

端点: POST /api/v1/{database}/{collection}/insert

请求参数:

参数	类型	必填	说明
`documents`	array	✅	要插入的文档数组
`ordered`	boolean	❌	是否按顺序插入（默认 true）

请求示例:

curl -X POST http://localhost:8080/api/v1/testdb/users/insert \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "name": "Alice",
        "age": 30,
        "email": "alice@example.com"
      },
      {
        "name": "Bob",
        "age": 25,
        "email": "bob@example.com"
      }
    ]
  }'

响应:

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

错误响应:

{
  "ok": 0,
  "errmsg": "duplicate key error",
  "code": 11000
}

查询操作

查询文档

端点: POST /api/v1/{database}/{collection}/find

请求参数:

参数	类型	必填	说明
`filter`	object	❌	查询条件（默认 `{}`）
`projection`	object	❌	字段投影
`sort`	object	❌	排序规则
`skip`	number	❌	跳过文档数
`limit`	number	❌	返回文档数限制

请求示例:

curl -X POST http://localhost:8080/api/v1/testdb/users/find \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "age": {"$gte": 25, "$lte": 30},
      "department": "技术部"
    },
    "projection": {
      "name": 1,
      "email": 1,
      "_id": 0
    },
    "sort": {"age": -1},
    "limit": 10
  }'

响应:

{
  "ok": 1,
  "cursor": {
    "firstBatch": [
      {"name": "Alice", "email": "alice@example.com"},
      {"name": "Bob", "email": "bob@example.com"}
    ],
    "id": 0,
    "ns": "testdb.users"
  }
}

查询单个文档

端点: POST /api/v1/{database}/{collection}/findOne

请求参数: 同 find

请求示例:

curl -X POST http://localhost:8080/api/v1/testdb/users/findOne \
  -H "Content-Type: application/json" \
  -d '{"filter": {"email": "alice@example.com"}}'

响应:

{
  "ok": 1,
  "value": {
    "_id": "20240101120000.000000000",
    "name": "Alice",
    "age": 30,
    "email": "alice@example.com"
  }
}

统计文档数

端点: POST /api/v1/{database}/{collection}/count

请求参数:

参数	类型	必填	说明
`filter`	object	❌	查询条件（默认 `{}`）
`limit`	number	❌	最大计数限制
`skip`	number	❌	跳过文档数

请求示例:

curl -X POST http://localhost:8080/api/v1/testdb/users/count \
  -H "Content-Type: application/json" \
  -d '{"filter": {"age": {"$gte": 25}}}'

响应:

{
  "ok": 1,
  "n": 15
}

更新操作

更新单个文档

端点: POST /api/v1/{database}/{collection}/update

请求参数:

参数	类型	必填	说明
`filter`	object	✅	查询条件
`update`	object	✅	更新操作
`upsert`	boolean	❌	不存在则插入（默认 false）
`multi`	boolean	❌	更新多个（默认 false）

请求示例:

curl -X POST http://localhost:8080/api/v1/testdb/users/update \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"name": "Alice"},
    "update": {
      "$set": {"age": 31},
      "$inc": {"loginCount": 1}
    }
  }'

响应:

{
  "ok": 1,
  "n": 1,
  "nModified": 1,
  "matchedCount": 1,
  "modifiedCount": 1,
  "upsertedId": null
}

更新多个文档

请求示例:

curl -X POST http://localhost:8080/api/v1/testdb/users/update \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"department": "技术部"},
    "update": {"$inc": {"salary": 1000}},
    "multi": true
  }'

Upsert 操作

请求示例:

curl -X POST http://localhost:8080/api/v1/testdb/users/update \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"email": "charlie@example.com"},
    "update": {
      "$setOnInsert": {
        "email": "charlie@example.com",
        "name": "Charlie",
        "age": 28
      }
    },
    "upsert": true
  }'

响应:

{
  "ok": 1,
  "n": 1,
  "nModified": 0,
  "upsertedId": "20240101120002.000000000"
}

删除操作

删除单个文档

端点: POST /api/v1/{database}/{collection}/delete

请求参数:

参数	类型	必填	说明
`filter`	object	✅	查询条件
`multi`	boolean	❌	删除多个（默认 false）

请求示例:

curl -X POST http://localhost:8080/api/v1/testdb/users/delete \
  -H "Content-Type: application/json" \
  -d '{"filter": {"email": "alice@example.com"}}'

响应:

{
  "ok": 1,
  "n": 1,
  "deletedCount": 1
}

删除多个文档

请求示例:

curl -X POST http://localhost:8080/api/v1/testdb/users/delete \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"status": "inactive"},
    "multi": true
  }'

聚合操作

执行聚合管道

端点: POST /api/v1/{database}/{collection}/aggregate

请求参数:

参数	类型	必填	说明
`pipeline`	array	✅	聚合管道数组
`cursor`	object	❌	游标选项
`explain`	boolean	❌	是否返回执行计划

请求示例:

curl -X POST http://localhost:8080/api/v1/testdb/orders/aggregate \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline": [
      {
        "$match": {
          "status": "completed",
          "createdAt": {"$gte": "2024-01-01"}
        }
      },
      {
        "$group": {
          "_id": "$customerId",
          "totalAmount": {"$sum": "$amount"},
          "orderCount": {"$sum": 1},
          "avgAmount": {"$avg": "$amount"}
        }
      },
      {
        "$sort": {"totalAmount": -1}
      },
      {
        "$limit": 10
      }
    ]
  }'

响应:

{
  "ok": 1,
  "cursor": {
    "firstBatch": [
      {
        "_id": "cust_001",
        "totalAmount": 15000,
        "orderCount": 5,
        "avgAmount": 3000
      },
      {
        "_id": "cust_002",
        "totalAmount": 12000,
        "orderCount": 4,
        "avgAmount": 3000
      }
    ],
    "id": 0,
    "ns": "testdb.orders"
  }
}

支持的聚合阶段

详见聚合管道文档

索引管理

创建索引

端点: POST /api/v1/{database}/{collection}/createIndex

请求参数:

参数	类型	必填	说明
`keys`	object	✅	索引键定义
`unique`	boolean	❌	是否唯一索引
`name`	string	❌	索引名称
`background`	boolean	❌	后台创建（默认 false）

请求示例:

curl -X POST http://localhost:8080/api/v1/testdb/users/createIndex \
  -H "Content-Type: application/json" \
  -d '{
    "keys": {"email": 1},
    "unique": true,
    "name": "idx_email_unique"
  }'

响应:

{
  "ok": 1,
  "createdCollectionAutomatically": false,
  "numIndexesBefore": 1,
  "numIndexesAfter": 2,
  "note": "all indexes already exist"
}

列出索引

端点: POST /api/v1/{database}/{collection}/getIndexes

请求:

curl -X POST http://localhost:8080/api/v1/testdb/users/getIndexes

响应:

{
  "ok": 1,
  "indexes": [
    {
      "v": 2,
      "key": {"_id": 1},
      "name": "_id_",
      "ns": "testdb.users"
    },
    {
      "v": 2,
      "key": {"email": 1},
      "name": "idx_email_unique",
      "unique": true,
      "ns": "testdb.users"
    }
  ]
}

删除索引

端点: POST /api/v1/{database}/{collection}/dropIndex

请求参数:

参数	类型	必填	说明
`index`	string	✅	索引名称

请求示例:

curl -X POST http://localhost:8080/api/v1/testdb/users/dropIndex \
  -H "Content-Type: application/json" \
  -d '{"index": "idx_email_unique"}'

响应:

{
  "ok": 1,
  "nIndexesWas": 2
}

错误处理

错误响应格式

{
  "ok": 0,
  "errmsg": "错误描述信息",
  "code": 错误码,
  "codeName": "错误名称"
}

常见错误码

错误码	错误名称	说明
1	InternalError	内部错误
2	BadValue	参数值错误
7	NoSuchKey	键不存在
11000	DuplicateKey	重复键值
26	NamespaceNotFound	集合不存在
43	NamespaceExists	集合已存在
52	InvalidPipelineOperator	无效的聚合操作符

错误处理示例

请求重复键值:

// 请求
{
  "documents": [{"email": "existing@example.com"}]
}

// 响应
{
  "ok": 0,
  "errmsg": "duplicate key error",
  "code": 11000,
  "codeName": "DuplicateKey"
}

响应格式

成功响应

{
  "ok": 1,
  // 其他响应数据...
}

分页响应

{
  "ok": 1,
  "cursor": {
    "firstBatch": [...],
    "nextBatch": [...],
    "id": 12345,
    "ns": "database.collection"
  }
}

批量操作响应

{
  "ok": 1,
  "n": 10,
  "insertedIds": {"0": "id1", "1": "id2"},
  "upsertedIds": {},
  "matchedCount": 10,
  "modifiedCount": 8,
  "deletedCount": 0
}

高级查询

查询操作符

详见查询操作符文档

比较操作符

{
  "filter": {
    "age": {"$gt": 25},
    "salary": {"$gte": 5000, "$lte": 10000},
    "status": {"$in": ["active", "pending"]}
  }
}

逻辑操作符

{
  "filter": {
    "$or": [
      {"age": {"$lt": 25}},
      {"salary": {"$gt": 8000}}
    ]
  }
}

元素操作符

{
  "filter": {
    "tags": {"$elemMatch": {"$eq": "important"}},
    "score": {"$exists": true}
  }
}

更新操作符

详见更新操作符文档

字段更新

{
  "update": {
    "$set": {"status": "active"},
    "$unset": {"tempField": ""},
    "$rename": {"oldName": "newName"}
  }
}

数组操作

{
  "update": {
    "$push": {"scores": 95},
    "$addToSet": {"tags": "new"},
    "$pull": {"items": {"price": {"$lt": 100}}}
  }
}

算术更新

{
  "update": {
    "$inc": {"viewCount": 1},
    "$mul": {"price": 0.9}
  }
}

性能优化

使用投影

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

使用索引

# 为常用查询字段创建索引
{"keys": {"email": 1, "status": 1}}

限制结果集

# 总是使用 limit
{"limit": 100}

避免全表扫描

# ❌ 不推荐
{"filter": {"$expr": {"$gt": ["$field1", "$field2"]}}}

# ✅ 推荐
{"filter": {"field1": {"$gt": 100}}}

最佳实践

1. 批量操作

# 批量插入而不是逐条插入
{"documents": [{...}, {...}, {...}]}

2. 合理使用 upsert

# 使用 $setOnInsert 避免覆盖现有数据
{
  "filter": {"email": "user@example.com"},
  "update": {"$setOnInsert": {"name": "User"}},
  "upsert": true
}

3. 事务性操作

对于需要事务的场景，使用 PostgreSQL 或 DM8 作为底层数据库。

4. 监控慢查询

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

附录

HTTP 状态码

状态码	说明
200	成功
400	请求参数错误
404	资源不存在
500	服务器内部错误

数据类型映射

MongoDB	SQLite	PostgreSQL
String	TEXT	VARCHAR
Number	REAL	DOUBLE PRECISION
Integer	INTEGER	BIGINT
Boolean	INTEGER	BOOLEAN
Array	JSONB	JSONB
Object	JSONB	JSONB
Date	DATETIME	TIMESTAMP

维护者: Gomog Team
许可证: MIT

14 KiB Raw Permalink Blame History Unescape Escape

Gomog HTTP API 参考文档

📖 目录

概述

协议

基础 URL

URL 参数说明

HTTP 方法

数据库管理

列出所有数据库

列出当前数据库的集合

集合管理

创建集合

删除集合

重命名集合

文档操作

插入文档

查询操作

查询文档

查询单个文档

统计文档数

更新操作

更新单个文档

更新多个文档

Upsert 操作

删除操作

删除单个文档

删除多个文档

聚合操作

执行聚合管道

支持的聚合阶段

索引管理

创建索引

列出索引

删除索引

错误处理

错误响应格式

常见错误码

错误处理示例

响应格式

成功响应

分页响应

批量操作响应

高级查询

查询操作符

比较操作符

逻辑操作符

元素操作符

更新操作符

字段更新

数组操作

算术更新

性能优化

使用投影

使用索引

限制结果集

避免全表扫描

最佳实践

1. 批量操作

2. 合理使用 upsert

3. 事务性操作

4. 监控慢查询

附录

HTTP 状态码

数据类型映射

14 KiB

Raw Permalink Blame History