godocdb/design/design.md

基于Go语言KV数据库实现兼容MongoDB的文档数据库系统
本方案设计了一个基于Go语言LevelDB实现的文档数据库系统，支持索引、事务、视图和触发器等高级功能，同时兼容MongoDB的数据操作接口。该系统采用分层键设计存储文档和索引，利用BSON编码处理文档数据，并通过事务管理器和触发器机制实现数据一致性和自动化操作。系统结构轻量高效，适合需要文档数据库特性的中小型应用场景。

一、需求分析
1.1 功能需求
本系统需要实现以下核心功能：

文档存储与查询：支持JSON/BSON格式的文档存储和检索
索引支持：允许为文档字段创建索引，加速查询
事务处理：实现ACID兼容的事务机制
视图管理：支持虚拟表的创建和使用
触发器功能：在特定数据库事件发生时自动执行操作
MongoDB兼容接口：实现与MongoDB驱动兼容的API，特别是Find和聚合查询接口
1.2 非功能需求
性能：读写操作应具有较高效率
可靠性：确保数据持久性和一致性
易用性：提供与MongoDB相似的API接口
轻量级：系统应尽可能轻量，避免不必要的复杂性
1.3 技术选型
经过分析比较，决定采用以下技术方案：

存储引擎：LevelDB（通过github.com/syndtr/goleveldb/leveldb实现）
文档编码：BSON（通过go.mongodb.org/mongo-driver/bson实现）
索引结构：B+树（通过github.com/iancoleman/orderedmap实现）
事务管理：基于LevelDB的WriteBatch和WAL实现
触发器机制：基于事件钩子的Go函数实现
二、系统设计
2.1 架构设计
系统采用分层架构，主要包括以下几个层次：

存储层：基于LevelDB实现，负责底层键值存储
文档管理层：负责文档的编码、解码和存储
索引管理层：负责索引的创建、维护和查询
事务管理层：实现事务的开始、提交和回滚
接口层：实现与MongoDB兼容的API接口
系统架构图如下：

+-------------------+
|   MongoDB兼容API  |
+-------------------+
|    事务管理器      |
+-------------------+
|    视图解析器      |
+-------------------+
|    触发器执行器    |
+-------------------+
|    索引管理层      |
+-------------------+
|    文档管理层      |
+-------------------+
|    LevelDB存储层    |
+-------------------+

2.2 数据存储设计
系统采用分层键设计存储文档和索引：

文档键：集合名:文档ID（如users:12345）
索引键：集合名:字段名:值 → 文档ID列表（如users:name:Alice → [12345, 67890]）
视图元数据：存储在views集合中，包含视图名称和查询条件
触发器元数据：存储在triggers集合中，包含触发器名称、事件类型和执行函数
文档以BSON格式存储，索引使用B+树结构，提高查询效率。

2.3 API接口设计
系统实现与MongoDB兼容的API接口，主要包括：


```go
type Client struct {
    // 客户端连接信息
}

type Database struct {
    name string
    client *Client
}

type Collection struct {
    name string
    db *Database
}

func (client *Client) Database(name string) *Database
func (db *Database) Collection(name string) *Collection

// Find接口
func (coll *Collection) Find(filter) *Cursor

// 插入文档
func (coll *Collection) InsertOne(filter) error
func (coll *Collection) InsertMany(filter) error

// 更新文档
func (coll *Collection) UpdateOne(filter) error
func (coll *Collection) UpdateMany(filter) error

// 删除文档
func (coll *Collection) DeleteOne(filter) error
func (coll *Collection) DeleteMany(filter) error

// 聚合查询
func (coll *Collection) Aggregate(filter) *Cursor

// 创建索引
func (coll *Collection) CreateIndex(filter) error

// 创建视图
func (coll *Collection) CreateView(filter) error

// 创建触发器
func (coll *Collection) CreateTrigger(filter) error
```


2.4 事务设计

系统通过以下方式实现事务：

    事务管理器：封装LevelDB的WriteBatch接口，提供事务的开始、提交和回滚功能
    WAL（Write-Ahead Logging）：实现事务日志记录，确保崩溃恢复和回滚能力
    锁机制：使用互斥锁保证事务操作的并发安全

事务提交时，先将操作记录到WAL日志，再应用到LevelDB。若操作失败，则从WAL日志中读取并执行反向操作实现回滚。
2.5 索引设计

系统采用B+树索引结构，支持以下索引类型：

    单字段索引
    复合索引
    覆盖索引
    唯一索引

索引存储在LevelDB中，键设计为集合名:字段名:值，值为文档ID列表。系统支持动态创建和删除索引。
2.6 视图设计

系统视图基于查询条件定义，存储在views集合中，格式如下：
```go
type View struct {
    Name       string
    Query      string
    Projection  []string
}
```
视图查询时，系统动态解析视图定义并生成实际查询条件，结合索引实现高效查询。

2.7 触发器设计
系统触发器存储在triggers集合中，格式如下：
```go
type Trigger struct {
    Name       string
    collection string
    Type       string // insert|update|delete|before|after
    Function   func(filter) error
}
```
触发器在特定数据库事件发生时自动执行注册的函数。系统支持BEFORE和AFTER类型的触发器，用于在操作前后执行自定义逻辑。

2.8 角色权限管理
系统支持基于角色的权限管理，包括：
- 创建角色
- 删除角色
- 给用户分配角色
- 给角色分配权限    

2.9 数据库备份与恢复
系统支持数据库备份和恢复，包括：
- 数据库备份：将数据库数据导出到文件
- 数据库恢复：将文件中的数据导入到数据库

2.10 客户端/服务器通讯协议

系统采用BSON进行通讯。客户端发送请求，服务器接收请求并处理，然后返回响应。请求格式如下：
```go
type Header struct {
    RequestID int32
    ResponseTo int32
    Auth string // 认证信息
    OpType uint8 // 操作类型 create, modify, find, aggregation
}
type Request struct {
    MessageHeader Header
    OpDoc interface{}
}
```

create操作包括
- 创建/删除集合
- 创建/删除索引
- 创建/删除视图
- 创建/删除触发器
- 创建/删除角色
- 创建/删除用户

modify操作包括
- 插入文档
- 更新文档
- 删除文档

find操作根据查询条件和projection在单个集合中查找文档
aggregation操作根据查询条件和projection在集合中执行聚合操作

// 补充OpDoc数据结构
type CreateCollectionOp struct {
    CollectionName string
}

type InsertDocumentOp struct {
    Document bson.M
}

// 补充协议封装方式
// 使用BSON序列化OpDoc，通过TCP流传输
// 消息格式：
// [Header][BSON(OpDoc)]
// 响应格式：
// [Header][BSON(ResponseDoc)]

2.11 客户端设计
系统采用BSON编码进行通讯协议交互，客户端实现以下核心组件：

- 连接池管理器：维护与服务器的TCP连接池
- 认证模块：实现SCRAM-SHA-256认证机制
- 请求序列化器：将API调用转换为BSON协议消息
- 响应反序列化器：解析服务器返回的BSON响应

客户端连接流程：
1. 建立TCP连接
2. 发起SCRAM认证
3. 维持心跳保持连接活跃

示例代码：
```go
func (coll *Collection) InsertOne(doc interface{}) error {
    // 序列化文档为BSON
    data, _ := bson.Marshal(doc)
    
    // 构建请求包
    req := Request{
        MessageHeader: Header{
            OpType: 0x0A, // insert操作码
        },
        OpDoc: InsertDocumentOp{
            Document: data,
        },
    }
    
    // 发送请求并获取响应
    resp := sendRequest(req)
    return parseResponse(resp)
}
```

2.12 集群架构设计
系统支持水平扩展，采用分片集群架构，包含以下核心组件：

- 配置服务器：存储集群元数据（通过etcd实现）
- 分片节点：存储实际数据的LevelDB实例
- 查询路由器：mongos类似的路由服务，负责请求分发
- 复制集：每个分片支持多副本同步

数据分片策略：
- 支持hash分片和range分片
- 默认使用集合的_id字段作为分片键

复制集实现：
- 主从复制模式
- 写操作先写主节点，再异步复制到从节点
- 故障转移通过raft协议选举新主节点

集群扩容流程：
1. 添加新分片节点
2. 迁移部分数据分片
3. 更新配置服务器元数据
4. 客户端自动感知新节点

2.13 商用增强设计
为满足生产环境需求，需补充以下关键设计：

1. 安全增强设计
   - TLS加密通信：实现mTLS双向认证，加密客户端与服务器通信
   - 数据加密存储：支持AES-256静态数据加密
   - 审计日志：记录所有管理操作和敏感数据访问
   - 细粒度权限控制：基于RBAC模型实现字段级权限控制

2. 监控与告警
   - 内建Prometheus指标暴露端点
   - 关键指标监控：
     * QPS/TPS
     * 延迟分布（p50/p95/p99）
     * 连接数和线程数
     * 存储空间使用
   - 自动告警机制：集成Alertmanager实现阈值告警

3. 运维增强
   - 在线DDL：支持不停机修改表结构
   - 流量控制：实现请求速率限制（QPS限制）
   - 故障诊断：提供诊断信息收集命令
   - 热升级：支持平滑升级不停机服务

4. 备份恢复增强
   - 增量备份：基于WAL实现秒级增量备份
   - PITR（时间点恢复）：结合全量+增量备份实现任意时间点恢复
   - 跨集群复制：支持异步跨数据中心复制

2.14 性能优化策略
为提升生产环境性能，补充以下设计：

1. 缓存优化
   - 实现两级缓存架构（本地缓存+分布式缓存）
   - 热点数据自动缓存机制
   - 缓存预热策略

2. 查询优化
   - 自动索引推荐系统
   - 执行计划分析器
   - 慢查询日志（支持类似MongoDB的profiler）

3. 存储优化
   - 数据压缩（Snappy/Zstandard算法）
   - 列式存储支持分析场景
   - TTL自动过期机制

4. 兼容性增强
   - 完整MongoDB驱动兼容测试套件
   - 支持MongoDB 5.0+所有聚合操作符
   - GridFS兼容接口实现
   - MongoDB副本集协议兼容

2.15 测试验证方案
为确保系统可靠性，补充以下测试设计：

1. 自动化测试框架
   - 单元测试覆盖率要求 >85%
   - 集成测试套件（包含事务、集群等场景）
   - 故障注入测试（模拟网络分区、磁盘满等异常）
   - 压力测试（基准性能验证）

2. 兼容性验证
   - 多版本MongoDB驱动兼容测试
   - 不同操作系统（Linux/CentOS/Ubuntu）验证
   - 容器化环境（Docker/K8s）验证

3. 部署方案设计
   - 单机模式：适用于开发测试
   - 主从复制模式：适用于中小规模部署
   - 分片集群模式：大规模数据场景
   - Kubernetes Operator实现云原生部署
   - 支持Helm Chart一键部署

2.16 非功能性需求设计
为提升系统可维护性和可观测性，补充以下设计：

1. 配置管理系统
   - 配置文件格式：YAML（支持环境变量覆盖）
   - 配置热加载：支持运行时动态加载新配置
   - 配置项示例：
```yaml
server:
  port: 27017
  max_connections: 10000
storage:
  data_dir: /var/lib/godocdb
  wal_size: 100MB
log:
  level: info
  file: /var/log/godocdb.log
  rotation: daily
```

2. 日志系统设计
   - 多级日志（trace/debug/info/warning/error/fatal）
   - 结构化日志输出（JSON格式）
   - 日志分割策略：按大小和时间轮转
   - 日志上下文跟踪：集成OpenTelemetry

3. 错误处理机制
   - 统一错误码体系（兼容MongoDB错误码）
   - 可扩展错误类型（用户可定义错误）
   - 错误上下文信息收集（请求ID、操作类型等）

4. 可观测性增强
   - Prometheus指标暴露端点
   - 关键指标分类：
     * 系统指标（CPU/内存/磁盘）
     * 数据库指标（QPS/TPS/延迟）
     * 组件指标（连接池/事务/锁）

5. 可扩展性设计
   - 插件化架构支持扩展模块
   - 预留监控插件接口
   - 可扩展的日志处理钩子

2.17 紧凑模式设计
------------------
为优化存储资源使用，新增紧凑模式设计：

- 存储管理层重构：
  - 创建StorageManager统一管理LevelDB实例
  - 所有store模块通过StorageManager获取共享db实例
  - 避免重复打开和关闭数据库连接

- 架构调整：
```
+---------------------+
|   StorageManager    |
|  (单实例LevelDB)    |
+---------------------+
      /|\     /|\
       |       |
+---------------------+     +---------------------+
|  DocumentStore      |     |   IndexStore        |
| (从StorageManager   |<--->(从StorageManager   |
| 获取共享db实例)     |     | 获取共享db实例)     |
+---------------------+     +---------------------+
```

- 数据存储优化：
  - 使用分层键设计共享同一LevelDB实例
  - 优化内存使用和文件描述符管理
  - 提供更高效的资源回收机制

2.18 元数据管理设计
------------------
新增元数据管理体系，支持数据库对象管理：

- 核心数据结构：
```go
type Metadata struct {
    Collections []string              `bson:"collections"`  // 存储集合名称列表
    Views       []ViewMetadata        `bson:"views"`        // 存储视图元数据
    Indexes     []IndexMetadata       `bson:"indexes"`      // 存储索引元数据
}

// 视图元数据
type ViewMetadata struct {
    Name       string   `bson:"name"`         // 视图名称
    Query      string   `bson:"query"`        // 查询条件
    Projection []string `bson:"projection"`   // 投影字段
}

// 索引元数据
type IndexMetadata struct {
    Name       string   `bson:"name"`         // 索引名称
    Collection string   `bson:"collection"`   // 关联集合
    Fields     []string `bson:"fields"`       // 索引字段
    Unique     bool     `bson:"unique"`       // 是否唯一
}
```

- 存储设计：
  - 使用固定键"metadata:db_info"存储元数据
  - 所有元数据操作通过BSON序列化/反序列化
  - 元数据更新使用原子操作保证一致性

- 管理接口：
  - CreateCollection/DropCollection
  - CreateIndex/DropIndex
  - CreateView/DropView
  - ListCollections/ListIndexes/ListViews