214 lines
6.3 KiB
Markdown
214 lines
6.3 KiB
Markdown
# 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*
|