81 lines
3.1 KiB
Markdown
81 lines
3.1 KiB
Markdown
# @go/docDB v1.0.9
|
||
|
||
`docDB` 是一个独立的高级文档存储引擎，基于 `@go/tableDB` 构建，提供全自动版本管理、历史存证、流式大文件处理及精细化生命周期钩子。
|
||
|
||
## 📦 安装
|
||
|
||
```bash
|
||
go get apigo.cc/go/docDB
|
||
```
|
||
|
||
## 🛠 核心功能
|
||
|
||
1. **路径驱动**：以 `Path` 作为文档的唯一标识。
|
||
2. **版本管控**：`SetDoc` 强制提升版本号并自动归档旧版；`SetMeta` 仅更新属性不触碰版本。
|
||
3. **智能 ToC**：自动提取 Markdown 目录结构，支持代码块识别；`SetMeta` 更新正文时能自动重算 ToC。
|
||
4. **精细化事件**：提供文档与目录（ToC）的增删改精细钩子，支持搜索引擎与知识库高效同步。
|
||
5. **历史存证**：即使文档被删除，其所有历史版本依然可通过 `GetByVersion` 获取。
|
||
6. **权限隔离**：完全继承 `tableDB` 的 RLS (Row Level Security) 体系。
|
||
|
||
## 🚀 API 指南
|
||
|
||
### 1. 初始化与授权
|
||
|
||
```go
|
||
import (
|
||
"apigo.cc/go/docDB"
|
||
"apigo.cc/go/log"
|
||
)
|
||
|
||
// 获取引擎实例
|
||
engine := docDB.GetDB("sqlite://docs.db", log.DefaultLogger, "", "./storage_root")
|
||
|
||
// 授权
|
||
db := engine.Auth("user_123")
|
||
```
|
||
|
||
### 2. 文档操作
|
||
|
||
- **`SetDoc(doc *Document) error`**：保存文档，提升版本。触发 `OnUpdatedDoc` 和 `OnUpdatedToC`。
|
||
- **`SetMeta(path string, meta map[string]any) error`**：更新元数据，**不提升版本**。若包含 `textContent` 且为 Markdown，会自动触发 `OnRemovedToC` 和 `OnUpdatedToC`。
|
||
- **`Move(oldPath, newPath string) error`**：重命名。触发 `OnRemovedDoc(oldDoc)` -> `OnUpdatedDoc(newDoc)`。
|
||
- **`Get(path string) (*Document, error)`**：获取最新版。
|
||
- **`GetByVersion(path string, version uint64) (*Document, error)`**：获取历史版（含已删除）。
|
||
- **`Remove(path string) error`**：删除文档。触发 `OnRemovedDoc(doc)`。
|
||
|
||
### 3. 生命周期钩子 (Hooks)
|
||
|
||
```go
|
||
// 所有 Hook 统一返回 *Document 对象，方便外部获取 Path, ToC, Metadata 等完整上下文
|
||
engine.Hooks.OnUpdatedDoc = func(doc *docDB.Document) {
|
||
// 文档创建或内容更新时触发 (SetDoc 或 Move 触发)
|
||
}
|
||
engine.Hooks.OnRemovedDoc = func(doc *docDB.Document) {
|
||
// 文档被物理删除或 Move 移除旧路径时触发
|
||
}
|
||
|
||
// 目录(ToC)级事件
|
||
engine.Hooks.OnUpdatedToC = func(doc *docDB.Document) {
|
||
// 目录生成或变更时触发
|
||
}
|
||
engine.Hooks.OnRemovedToC = func(doc *docDB.Document) {
|
||
// 目录失效时触发
|
||
}
|
||
```
|
||
|
||
## 📝 数据结构
|
||
|
||
### Document
|
||
| 字段 | 类型 | 说明 |
|
||
| :--- | :--- | :--- |
|
||
| `Path` | `string` | **核心标识** |
|
||
| `BinaryContent` | `io.Reader` | 瞬态流，用于上传 |
|
||
| `TextContent` | `string` | 正文内容 |
|
||
| `Version` | `uint64` | 版本号 |
|
||
| `ToC` | `[]ToCNode` | 目录树 (自动生成) |
|
||
|
||
## 💡 注意事项
|
||
|
||
- **SetMeta 行为**：`SetMeta` 不会触发 `OnUpdatedDoc`，但如果更新了正文导致目录变化，会触发 ToC 相关事件。
|
||
- **Move 行为**：为了兼容搜索索引等外部系统，`Move` 被抽象为“删除旧路径文档”与“更新新路径文档”的组合操作。
|