# Gomog 用户手册与 API 文档

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

---

## 📚 文档导航

本目录包含 Gomog 的完整用户手册和 API 参考文档。

### 快速开始

1. **新用户必读**: [用户指南](USER_GUIDE.md) - 完整的入门教程
2. **快速参考**: [快速参考手册](QUICK_REFERENCE.md) - 常用命令速查
3. **示例代码**: [API 使用示例](../doc/API_EXAMPLES.md) - 实际使用案例

---

## 📖 文档分类

### 📘 用户指南

| 文档 | 说明 | 适合人群 |
|------|------|----------|
| [USER_GUIDE.md](USER_GUIDE.md) | **完整用户手册** - 安装、配置、使用、最佳实践 | 所有用户 |
| [QUICK_REFERENCE.md](QUICK_REFERENCE.md) | **快速参考手册** - 操作符、命令、错误码速查 | 所有用户 |

### 🌐 API 参考

#### HTTP API

| 文档 | 说明 | 适合人群 |
|------|------|----------|
| [HTTP_API.md](HTTP_API.md) | **HTTP API 完整参考** - RESTful API、端点、参数、示例 | 后端开发者 |
| [QUERY_OPERATORS.md](QUERY_OPERATORS.md) | **查询操作符参考** - 16+ 个查询操作符详解 | 查询开发者 |
| [UPDATE_OPERATORS.md](UPDATE_OPERATORS.md) | **更新操作符参考** - 17+ 个更新操作符详解 | 查询开发者 |

#### TCP 协议

| 文档 | 说明 | 适合人群 |
|------|------|----------|
| [TCP_PROTOCOL.md](TCP_PROTOCOL.md) | **TCP 协议参考** - MongoDB Wire Protocol 兼容实现 | 客户端开发者 |

### 🔧 高级功能

| 文档 | 说明 | 适合人群 |
|------|------|----------|
| [AGGREGATION_PIPELINE.md](AGGREGATION_PIPELINE.md) | **聚合管道完整参考** - 18+ 阶段、50+ 表达式 | 数据分析师 |

---

## 🎯 按使用场景查找

### 我是新手，第一次使用 Gomog

1. 阅读 [用户指南](USER_GUIDE.md) 了解基本概念
2. 查看 [快速参考](QUICK_REFERENCE.md) 熟悉常用命令
3. 参考 [API 使用示例](../doc/API_EXAMPLES.md) 上手实践

### 我想使用 HTTP API 开发应用

1. 查阅 [HTTP API 参考](HTTP_API.md) 了解所有端点
2. 参考 [查询操作符](QUERY_OPERATORS.md) 构建复杂查询
3. 查看 [更新操作符](UPDATE_OPERATORS.md) 实现数据更新

### 我想使用 MongoDB 客户端连接

1. 阅读 [TCP 协议参考](TCP_PROTOCOL.md) 了解连接方式
2. 查看各语言示例（Node.js、Python、Go）
3. 参考 [快速参考](QUICK_REFERENCE.md) 熟悉命令映射

### 我想进行复杂数据分析

1. 学习 [聚合管道参考](AGGREGATION_PIPELINE.md)
2. 查看实用示例（电商分析、用户行为、社交网络）
3. 参考 [性能优化](AGGREGATION_PIPELINE.md#性能调优) 章节

### 我需要排查问题

1. 查看 [用户指南 - 故障排查](USER_GUIDE.md#故障排查) 章节
2. 参考 [快速参考 - 错误码](QUICK_REFERENCE.md#错误码速查)
3. 查阅 [常见问题](USER_GUIDE.md#常见问题)

---

## 📊 文档统计

| 类别 | 文档数 | 总大小 |
|------|--------|--------|
| 用户指南 | 2 | ~30KB |
| API 参考 | 4 | ~80KB |
| 高级功能 | 1 | ~25KB |
| **总计** | **7** | **~135KB** |

---

## 🔍 快速查找表

### 常用操作

| 操作 | HTTP API | MongoDB Shell | 文档链接 |
|------|---------|---------------|----------|
| 插入文档 | `POST /insert` | `insertOne()` | [HTTP API](HTTP_API.md#插入文档) |
| 查询文档 | `POST /find` | `find()` | [HTTP API](HTTP_API.md#查询文档) |
| 更新文档 | `POST /update` | `updateOne()` | [HTTP API](HTTP_API.md#更新操作) |
| 删除文档 | `POST /delete` | `deleteOne()` | [HTTP API](HTTP_API.md#删除操作) |
| 聚合管道 | `POST /aggregate` | `aggregate()` | [HTTP API](HTTP_API.md#聚合操作) |
| 创建索引 | `POST /createIndex` | `createIndex()` | [HTTP API](HTTP_API.md#索引管理) |

### 常用操作符

| 类型 | 操作符 | 说明 | 文档链接 |
|------|--------|------|----------|
| 比较 | `$eq`, `$ne`, `$gt`, `$lt` | 基本比较 | [查询操作符](QUERY_OPERATORS.md#比较操作符) |
| 逻辑 | `$and`, `$or`, `$not` | 逻辑运算 | [查询操作符](QUERY_OPERATORS.md#逻辑操作符) |
| 数组 | `$all`, `$elemMatch`, `$size` | 数组操作 | [查询操作符](QUERY_OPERATORS.md#数组操作符) |
| 更新 | `$set`, `$inc`, `$push` | 字段更新 | [更新操作符](UPDATE_OPERATORS.md) |
| 聚合 | `$match`, `$group`, `$sort` | 聚合阶段 | [聚合管道](AGGREGATION_PIPELINE.md) |

---

## 💡 学习路径建议

### 基础篇（1-2 天）

1. ✅ 阅读 [用户指南](USER_GUIDE.md) 第 1-3 章
2. ✅ 完成 [快速开始](USER_GUIDE.md#快速开始) 示例
3. ✅ 熟悉 [快速参考](QUICK_REFERENCE.md)

### 进阶篇（3-5 天）

1. ✅ 深入学习 [HTTP API](HTTP_API.md)
2. ✅ 掌握 [查询操作符](QUERY_OPERATORS.md)
3. ✅ 练习 [更新操作符](UPDATE_OPERATORS.md)

### 高级篇（1-2 周）

1. ✅ 精通 [聚合管道](AGGREGATION_PIPELINE.md)
2. ✅ 了解 [TCP 协议](TCP_PROTOCOL.md)
3. ✅ 实践 [最佳实践](USER_GUIDE.md#最佳实践)

---

## 📝 文档更新记录

| 日期 | 文档 | 更新内容 |
|------|------|----------|
| 2026-03-14 | 所有文档 | 初始版本发布 |

---

## 🆘 获取帮助

### 文档相关问题

- 查看对应文档的详细说明
- 参考示例代码
- 查阅常见问题

### 技术问题

- GitHub Issues: 提交 bug 报告
- GitHub Discussions: 发起讨论
- 社区论坛：寻求社区帮助

### 联系方式

- **项目主页**: https://github.com/gomog/gomog
- **问题反馈**: https://github.com/gomog/gomog/issues
- **讨论区**: https://github.com/gomog/gomog/discussions

---

## 📋 文档结构

```
manual/
├── README.md                  # 本文档索引
├── USER_GUIDE.md              # 用户指南
├── QUICK_REFERENCE.md         # 快速参考手册
├── HTTP_API.md                # HTTP API 参考
├── TCP_PROTOCOL.md            # TCP 协议参考
├── AGGREGATION_PIPELINE.md    # 聚合管道参考
├── QUERY_OPERATORS.md         # 查询操作符参考
└── UPDATE_OPERATORS.md        # 更新操作符参考
```

---

## ⭐ 推荐资源

### 官方文档

- [MongoDB 官方文档](https://www.mongodb.com/docs/)
- [BSON 规范](http://bsonspec.org/)

### 社区资源

- MongoDB University 免费课程
- Stack Overflow MongoDB 标签
- Reddit r/mongodb 社区

---

**维护者**: Gomog Team  
**贡献者**: 查看 GitHub 贡献者列表  
**许可证**: MIT

---

*最后更新：2026-03-14*