02-第2章-核心概念与架构

第 2 章：核心概念与架构

---

2.1 整体架构设计

sfsDb 采用分层架构设计，从底层存储到高层 API 形成清晰的层次结构。

架构层次

┌─────────────────────────────────────────────────────────┐
│                    应用层 (Application)                   │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │  web 包      │  │  management   │  │  用户应用     │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
└─────────────────────────────────────────────────────────┘
                            │
┌─────────────────────────────────────────────────────────┐
│                   引擎层 (Engine)                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐ │
│  │ engine   │  │  record  │  │  match   │  │  time  │ │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘ │
└─────────────────────────────────────────────────────────┘
                            │
┌─────────────────────────────────────────────────────────┐
│                  存储层 (Storage)                         │
│  ┌───────────────────────────────────────────────────┐  │
│  │              storage 包 (LevelDB 封装)             │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

---

2.2 包结构说明

核心包概览

让我们通过项目的实际代码来理解各个包的作用：

2.2.1 storage 包 - 底层 KV 存储

storage 包是 sfsDb 的最底层，封装了 LevelDB 的操作，提供统一的 KV 存储接口。

核心接口定义 （来自 storage/kv.go）：

// Store KV存储接口
type Store interface {
    // Get 获取指定key的值
    Get(key []byte) ([]byte, error)

    // Put 设置key-value对
    Put(key []byte, value []byte) error

    // Delete 删除指定key
    Delete(key []byte) error

    // GetBatch 创建批量操作对象
    GetBatch() Batch

    // WriteBatch 执行批量操作
    WriteBatch(batch Batch, put ...bool) error

    // Iterator 创建迭代器
    Iterator(start, limit []byte) Iterator

    // Snapshot 创建快照
    Snapshot() (Snapshot, error)

    // Close 关闭存储
    Close() error
}

storage 包的设计原则：

• 抽象接口：通过 Store 接口屏蔽底层实现差异
• 批量操作：支持 Batch 接口优化写入性能
• 迭代器模式：提供 Iterator 接口进行范围查询
• 快照支持：支持 Snapshot 进行一致性读取

2.2.2 engine 包 - 核心引擎

engine 包是 sfsDb 的核心，提供表管理、索引、CRUD 等功能。

Table 结构体定义 （来自 engine/table.go）：

type Table struct {
    id   uint8  // 表id
    name string // 表名
    
    // 半结构，可以随意增加字段
    // 泛型化，字段可以存储任意类型，不限制某种类型
    fields         map[string]any   // 字段映射，string为字段名，any为字段值
    fieldsid       map[uint8]string // id到字段名的映射
    indexs         *Indexs          // 索引集合
    counter        AutoInt          // 自动增值计数器
    kvStore        storage.Store    // 底层KV存储
    fieldIDManager *IDManager       // 字段ID管理器
    indexIDManager *IDManager       // 索引ID管理器
    TableCache                       // 缓存结构体
}

// 缓存结构体
type TableCache struct {
    timeFields          map[string]bool  // 标记字段是否为时间类型
    primaryFields       []string         // 缓存的主键字段列表
    primaryFieldsLoaded bool             // 主键字段列表是否已加载
    fieldTypeLen        map[string]uint8 // 缓存字段类型长度映射
}

engine 包的设计特点：

• 半结构化：支持动态添加字段
• 泛型化：字段可以存储任意类型
• 索引管理：支持多种索引类型
• 自动递增：内置 AutoInt 计数器
• 缓存优化：TableCache 缓存常用数据

---

2.3 数据模型

2.3.1 表结构设计

sfsDb 的表结构设计非常灵活，采用半结构化设计：

// 必须先为表预设字段和数据类型
fields := map[string]any{
    "id":    0,      // 整数类型
    "name":  "",     // 字符串类型
    "age":   0,      // 整数类型
    "email": "",     // 字符串类型
}
table.SetFields(fields)

设计原则 （来自 engine/table.go 注释）：

> 设计原则是当前最简单快捷开发，不考虑通用性和将来扩展要求。

> 除了需要排序的主键和索引需要转换为[]byte外，其他所有字段值，皆转换为字符串存储。

2.3.2 字段类型

sfsDb 支持多种字段类型，通过 util 包进行类型管理：

• 整数类型：int、int8、int16、int32、int64、uint、uint8 等
• 字符串类型：string
• 布尔类型：bool
• 时间类型：time.Time
• 任意类型 ：通过 any 支持

---

2.4 小结

本章我们深入了解了 sfsDb 的整体架构、包结构和数据模型。通过阅读项目的实际代码，我们理解了 sfsDb 的设计思想和核心概念。在下一章中，我们将学习基础 CRUD 操作，所有示例都来自项目的测试代码。

---

本书版本 ：1.0.0
最后更新 ：2026-03-11
sfsDb - 以工业物联网边缘计算为核心场景的高性能嵌入式数据库！🚀
技术栈 - Go、leveldb。纯golang实现。
项目地址 ：GitHub
GitCode 镜像 ：GitCode