文档：更新和优化项目文档
- 更新 DESIGN.md： - 强调强制 Schema（21 种类型） - 更新核心代码行数为 ~5,400 行 - 优化 ROW1 格式说明（英文） - 完善性能指标和项目成果 - 精简 DOCS.md 和 README.md - 统一文档风格和术语
This commit is contained in:
169
DESIGN.md
169
DESIGN.md
@@ -8,9 +8,9 @@
|
||||
1. **极简架构** - 放弃复杂的 LSM Tree 多层设计，使用简单的两层结构
|
||||
2. **高并发写入** - WAL + MemTable 保证 200,000+ writes/s
|
||||
3. **快速查询** - mmap B+Tree 索引 + 二级索引，1-5 ms 查询性能
|
||||
4. **低内存占用** - mmap 零拷贝，应用层内存 < 200 MB
|
||||
5. **功能完善** - 支持 Schema、索引、条件查询等高级特性
|
||||
6. **生产可用** - 核心代码 5399 行，包含完善的错误处理和数据一致性保证
|
||||
4. **低内存占用** - mmap 零拷贝，应用层内存 < 150 MB
|
||||
5. **功能完善** - 强制 Schema（21 种类型）、索引、条件查询等高级特性
|
||||
6. **生产可用** - 核心代码 ~5,400 行，包含完善的错误处理和数据一致性保证
|
||||
|
||||
## 🏗️ 核心架构
|
||||
|
||||
@@ -19,10 +19,10 @@
|
||||
│ SRDB Architecture │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Application Layer │
|
||||
│ ┌───────────────┐ ┌──────────────────────────┐ │
|
||||
│ │ Database │->│ Table │ │
|
||||
│ │ (Multi-Table) │ │ (Schema + Storage) │ │
|
||||
│ └───────────────┘ └──────────────────────────┘ │
|
||||
│ ┌───────────────┐ ┌──────────────────────────┐ │
|
||||
│ │ Database │->│ Table │ │
|
||||
│ │ (Multi-Table) │ │ (Schema + Storage) │ │
|
||||
│ └───────────────┘ └──────────────────────────┘ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Write Path (High Concurrency) │
|
||||
│ ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
@@ -50,8 +50,10 @@
|
||||
│ │ │ - Leaf Nodes → Data Offset │ │ │
|
||||
│ │ ├─────────────────────────────────────────┤ │ │
|
||||
│ │ │ Data Blocks (Binary Format) │ │ │
|
||||
│ │ │ - 有 Schema: 二进制编码 │ │ │
|
||||
│ │ │ - 无 Schema: JSON 格式 │ │ │
|
||||
│ │ │ - ROW1 Format: Binary Encoding │ │ │
|
||||
│ │ │ [Magic:4B][Seq:8B][Time:8B] │ │ │
|
||||
│ │ │ [Fields:2B][OffsetTable][Data] │ │ │
|
||||
│ │ │ - Supports zero-copy & partial reads │ │ │
|
||||
│ │ └─────────────────────────────────────────┘ │ │
|
||||
│ │ │ │
|
||||
│ │ Secondary Indexes (Optional) │ │
|
||||
@@ -85,38 +87,6 @@
|
||||
|
||||
## 📁 文件组织结构
|
||||
|
||||
### 代码目录结构
|
||||
|
||||
```
|
||||
srdb/ ← 项目根目录
|
||||
├── go.mod ← 模块定义: code.tczkiot.com/wlw/srdb
|
||||
├── DESIGN.md ← 本设计文档
|
||||
├── CLAUDE.md ← Claude Code 指导文档
|
||||
│
|
||||
├── database.go ← 数据库管理 (多表)
|
||||
├── table.go ← 表管理 (带 Schema)
|
||||
├── errors.go ← 错误定义和处理
|
||||
│
|
||||
├── wal.go ← WAL 实现 (Write-Ahead Log)
|
||||
├── memtable.go ← MemTable 实现 (map + sorted slice)
|
||||
├── sstable.go ← SSTable 文件 (读写器、管理器、编码)
|
||||
├── btree.go ← B+Tree 索引 (构建器、读取器)
|
||||
├── version.go ← 版本控制 (MANIFEST 管理)
|
||||
├── compaction.go ← Compaction 压缩合并
|
||||
│
|
||||
├── schema.go ← Schema 定义与验证
|
||||
├── index.go ← 二级索引管理器
|
||||
├── index_btree.go ← 索引 B+Tree 实现
|
||||
├── query.go ← 查询构建器和表达式求值
|
||||
│
|
||||
├── examples/ ← 示例程序目录
|
||||
│ ├── webui/ ← Web UI 管理工具
|
||||
│ └── ... (其他示例)
|
||||
│
|
||||
└── webui/ ← Web UI 静态资源
|
||||
└── ...
|
||||
```
|
||||
|
||||
### 运行时数据目录结构
|
||||
|
||||
```
|
||||
@@ -152,16 +122,16 @@ database_dir/ ← 数据库目录
|
||||
- 崩溃恢复支持
|
||||
|
||||
文件格式:
|
||||
┌─────────────────────────────────────┐
|
||||
│ WAL Entry │
|
||||
├─────────────────────────────────────┤
|
||||
│ CRC32 (4 bytes) │
|
||||
│ Length (4 bytes) │
|
||||
│ Type (1 byte): Put │
|
||||
│ Key (8 bytes): _seq │
|
||||
│ Value Length (4 bytes) │
|
||||
│ Value (N bytes): 序列化的行数据 │
|
||||
└─────────────────────────────────────┘
|
||||
┌───────────────────────────────────────┐
|
||||
│ WAL Entry │
|
||||
├───────────────────────────────────────┤
|
||||
│ CRC32 (4 bytes) │
|
||||
│ Length (4 bytes) │
|
||||
│ Type (1 byte): Put │
|
||||
│ Key (8 bytes): _seq │
|
||||
│ Value Length (4 bytes) │
|
||||
│ Value (N bytes): Serialized row data │
|
||||
└───────────────────────────────────────┘
|
||||
|
||||
性能:
|
||||
- 顺序写入: 极快
|
||||
@@ -334,49 +304,65 @@ func (s *MmapSST) readNode(offset int64) *BTreeNode {
|
||||
- 零拷贝: 无内存分配
|
||||
```
|
||||
|
||||
### 5. Schema 系统 (新增功能)
|
||||
### 5. Schema 系统
|
||||
|
||||
```
|
||||
设计:
|
||||
- 类型定义和验证
|
||||
- 必填字段检查
|
||||
- 唯一性约束
|
||||
- 默认值支持
|
||||
- 强制 Schema（所有表必须定义）
|
||||
- 21 种精确类型映射
|
||||
- Nullable 字段支持
|
||||
- 类型验证和转换
|
||||
- 索引标记（Indexed: true）
|
||||
|
||||
支持的类型（21 种）:
|
||||
1. 有符号整数（5种）: Int, Int8, Int16, Int32, Int64
|
||||
2. 无符号整数（5种）: Uint, Uint8, Uint16, Uint32, Uint64
|
||||
3. 浮点数（2种）: Float32, Float64
|
||||
4. 字符串（1种）: String
|
||||
5. 布尔（1种）: Bool
|
||||
6. 特殊类型（5种）: Byte, Rune, Decimal, Time, Duration
|
||||
7. 复杂类型（2种）: Object (JSON), Array (JSON)
|
||||
|
||||
实现:
|
||||
type Schema struct {
|
||||
Fields []FieldDefinition
|
||||
TableName string
|
||||
Fields []Field
|
||||
}
|
||||
|
||||
type FieldDefinition struct {
|
||||
type Field struct {
|
||||
Name string
|
||||
Type string // "string", "int", "float", "bool"
|
||||
Required bool // 是否必填
|
||||
Unique bool // 是否唯一
|
||||
Default interface{} // 默认值
|
||||
Type FieldType // 21 种类型之一
|
||||
Indexed bool // 是否创建索引
|
||||
Nullable bool // 是否允许 NULL
|
||||
Comment string // 字段注释
|
||||
}
|
||||
|
||||
func (s *Schema) Validate(data map[string]interface{}) error {
|
||||
for _, field := range s.Fields {
|
||||
// 检查必填字段
|
||||
// 检查类型匹配
|
||||
// 应用默认值
|
||||
}
|
||||
// 1. 检查必填字段
|
||||
// 2. 类型验证和转换
|
||||
// 3. Nullable 检查
|
||||
// 4. 返回验证后的数据
|
||||
}
|
||||
|
||||
使用示例:
|
||||
schema := &schema.Schema{
|
||||
Fields: []schema.FieldDefinition{
|
||||
{Name: "name", Type: "string", Required: true},
|
||||
{Name: "age", Type: "int", Required: false},
|
||||
{Name: "email", Type: "string", Unique: true},
|
||||
},
|
||||
}
|
||||
schema, _ := NewSchema("users", []Field{
|
||||
{Name: "name", Type: String, Indexed: false},
|
||||
{Name: "age", Type: Int32, Indexed: false},
|
||||
{Name: "email", Type: String, Indexed: true},
|
||||
{Name: "balance", Type: Decimal, Nullable: true},
|
||||
})
|
||||
|
||||
table, _ := db.CreateTable("users", schema)
|
||||
|
||||
类型转换规则:
|
||||
- 相同类型：直接接受
|
||||
- 兼容类型：自动转换（有符号 ↔ 无符号，需非负）
|
||||
- 类型提升：整数 → 浮点
|
||||
- JSON 兼容：float64 → 整数（需为整数值）
|
||||
- 负数 → 无符号：拒绝
|
||||
```
|
||||
|
||||
### 6. 二级索引 (新增功能)
|
||||
### 6. 二级索引
|
||||
|
||||
```
|
||||
设计:
|
||||
@@ -472,7 +458,7 @@ qb.Where("email", query.EndsWith, "@gmail.com")
|
||||
4. 返回匹配的行
|
||||
```
|
||||
|
||||
### 8. 数据库和表管理 (新增功能)
|
||||
### 8. 数据库和表管理
|
||||
|
||||
```
|
||||
设计:
|
||||
@@ -607,27 +593,6 @@ Flush 流程 (后台):
|
||||
|
||||
## 📊 性能指标
|
||||
|
||||
### 代码规模
|
||||
```
|
||||
核心代码: ~13,000 行 (不含测试和示例)
|
||||
├── table.go: 表管理和存储引擎
|
||||
├── wal.go: WAL 实现
|
||||
├── memtable.go: MemTable 实现
|
||||
├── sstable.go: SSTable 文件读写
|
||||
├── btree.go: B+Tree 索引
|
||||
├── version.go: 版本控制 (MANIFEST)
|
||||
├── compaction.go: Compaction 压缩
|
||||
├── index.go: 二级索引
|
||||
├── query.go: 查询构建器
|
||||
├── schema.go: Schema 验证
|
||||
├── errors.go: 错误处理
|
||||
└── database.go: 数据库管理
|
||||
|
||||
测试代码: ~2000+ 行
|
||||
示例代码: ~1000+ 行
|
||||
总计: 16,000+ 行
|
||||
```
|
||||
|
||||
### 写入性能
|
||||
```
|
||||
单线程: 50,000 writes/s
|
||||
@@ -884,8 +849,8 @@ SRDB 是一个功能完善的高性能 Append-Only 数据库引擎：
|
||||
- ✅ **高并发写入**: WAL + MemTable，200K+ w/s
|
||||
- ✅ **快速查询**: mmap B+Tree + 二级索引，1-5 ms
|
||||
- ✅ **低内存占用**: mmap 零拷贝，< 150 MB
|
||||
- ✅ **功能完善**: Schema、索引、条件查询、多表管理
|
||||
- ✅ **生产可用**: 5399 行核心代码，完善的错误处理和数据一致性
|
||||
- ✅ **功能完善**: 强制 Schema（21 种类型）、索引、条件查询、多表管理
|
||||
- ✅ **生产可用**: ~5,400 行核心代码，完善的错误处理和数据一致性
|
||||
- ✅ **简单可靠**: Append-Only，无更新/删除的复杂性
|
||||
|
||||
**技术亮点:**
|
||||
@@ -912,8 +877,8 @@ SRDB 是一个功能完善的高性能 Append-Only 数据库引擎：
|
||||
- ❌ 传统 OLTP 系统
|
||||
|
||||
**项目成果:**
|
||||
- 核心代码: ~13,000 行
|
||||
- 核心代码: ~5,400 行（精简高效）
|
||||
- 测试代码: ~2,000+ 行
|
||||
- 示例程序: 13+ 个完整示例
|
||||
- 文档: 完善的设计和使用文档
|
||||
- 性能: 达到设计目标
|
||||
- 文档: 完善的设计和使用文档（DESIGN.md、CLAUDE.md、DOCS.md、README.md）
|
||||
- 性能: 达到设计目标（200K+ w/s 写入，1-5 ms 查询）
|
||||
|
||||
Reference in New Issue
Block a user