152 lines
3.7 KiB
Markdown
152 lines
3.7 KiB
Markdown
|
# 存储模块使用文档
|
|||
|
|
|
|||
|
|
## 概述
|
|||
|
|
|
|||
|
|
`Storage` 类提供了完整的 CRUD 操作，支持数据持久化、分类查询和全文搜索。
|
|||
|
|
|
|||
|
|
## 初始化
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
from src.core.storage import Storage
|
|||
|
|
|
|||
|
|
# 使用默认数据目录（项目根目录下的 data 文件夹）
|
|||
|
|
storage = Storage()
|
|||
|
|
|
|||
|
|
# 或指定自定义数据目录
|
|||
|
|
storage = Storage("/path/to/data/dir")
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## CRUD 操作
|
|||
|
|
|
|||
|
|
### 创建记录 (Create)
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# 创建新记录
|
|||
|
|
record = storage.create(
|
|||
|
|
title="我的笔记",
|
|||
|
|
content="这是笔记的内容",
|
|||
|
|
category="工作", # 可选，默认为"默认分类"
|
|||
|
|
tags=["重要", "待办"], # 可选
|
|||
|
|
metadata={"priority": 1} # 可选，自定义元数据
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
print(record["id"]) # 自动生成的唯一 ID
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 查询记录 (Read)
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# 根据 ID 查询单个记录
|
|||
|
|
record = storage.get_by_id("20260211180219077144")
|
|||
|
|
if record:
|
|||
|
|
print(record["title"], record["content"])
|
|||
|
|
|
|||
|
|
# 查询所有记录
|
|||
|
|
all_records = storage.get_all()
|
|||
|
|
for record in all_records:
|
|||
|
|
print(f"{record['title']} - {record['category']}")
|
|||
|
|
|
|||
|
|
# 按分类查询
|
|||
|
|
work_records = storage.get_by_category("工作")
|
|||
|
|
|
|||
|
|
# 获取所有分类
|
|||
|
|
categories = storage.get_categories()
|
|||
|
|
print(f"所有分类: {categories}")
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 更新记录 (Update)
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# 更新记录（只更新提供的字段）
|
|||
|
|
updated_record = storage.update(
|
|||
|
|
record_id="20260211180219077144",
|
|||
|
|
title="新的标题", # 可选
|
|||
|
|
content="新的内容", # 可选
|
|||
|
|
category="学习", # 可选
|
|||
|
|
tags=["已完成"], # 可选
|
|||
|
|
metadata={"status": "done"} # 可选，会合并到现有元数据
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
# 更新时间会自动更新
|
|||
|
|
print(updated_record["updated_at"])
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 删除记录 (Delete)
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# 删除记录
|
|||
|
|
success = storage.delete("20260211180219077144")
|
|||
|
|
if success:
|
|||
|
|
print("删除成功")
|
|||
|
|
else:
|
|||
|
|
print("记录不存在")
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 搜索功能
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# 搜索关键词（默认在标题、内容、标签中搜索）
|
|||
|
|
results = storage.search("Python")
|
|||
|
|
|
|||
|
|
# 指定搜索字段
|
|||
|
|
results = storage.search(
|
|||
|
|
"重要",
|
|||
|
|
search_in=["title", "tags"] # 只搜索标题和标签
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
# 处理搜索结果
|
|||
|
|
for record in results:
|
|||
|
|
print(f"找到: {record['title']}")
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 统计信息
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# 获取统计信息
|
|||
|
|
stats = storage.get_stats()
|
|||
|
|
print(f"总记录数: {stats['total_records']}")
|
|||
|
|
print(f"总分类数: {stats['total_categories']}")
|
|||
|
|
print("各分类统计:")
|
|||
|
|
for category, count in stats['categories'].items():
|
|||
|
|
print(f" {category}: {count}")
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 导入导出
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# 导出所有数据
|
|||
|
|
data = storage.export_data()
|
|||
|
|
print(f"导出 {len(data)} 条记录")
|
|||
|
|
|
|||
|
|
# 导入数据（覆盖模式）
|
|||
|
|
storage.import_data(new_data, merge=False)
|
|||
|
|
|
|||
|
|
# 导入数据（合并模式）
|
|||
|
|
storage.import_data(new_data, merge=True) # 只添加不重复的记录
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 数据结构
|
|||
|
|
|
|||
|
|
每条记录包含以下字段：
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
{
|
|||
|
|
"id": "20260211180219077144", # 唯一 ID
|
|||
|
|
"title": "标题", # 标题
|
|||
|
|
"content": "内容", # 内容
|
|||
|
|
"category": "分类", # 分类
|
|||
|
|
"tags": ["标签1", "标签2"], # 标签列表
|
|||
|
|
"metadata": {}, # 自定义元数据
|
|||
|
|
"created_at": "2026-02-11T18:02:19.098002", # 创建时间
|
|||
|
|
"updated_at": "2026-02-11T18:02:19.098002" # 更新时间
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 注意事项
|
|||
|
|
|
|||
|
|
1. **数据持久化**: 所有数据保存在 JSON 文件中（`data/records.json`）
|
|||
|
|
2. **ID 生成**: ID 基于时间戳自动生成，确保唯一性
|
|||
|
|
3. **时间更新**: 更新记录时，`updated_at` 字段会自动更新
|
|||
|
|
4. **元数据**: `metadata` 字段可以存储任意 JSON 兼容的数据
|
|||
|
|
5. **搜索不区分大小写**: 搜索时会忽略大小写
|