缓存与持久化模块
缓存与持久化模块是 DocuSnap-Backend 系统的数据管理组件，负责管理任务状态和处理结果的存储、检索和清理。该模块使用 SQLite 数据库实现轻量级的数据持久化，提高系统性能并保障数据可靠性。
模块职责
缓存与持久化模块的主要职责包括：
- 数据库管理：创建和维护 SQLite 数据库连接和表结构
- 任务状态存储：记录和更新任务的处理状态
- 结果缓存：存储任务处理结果，避免重复计算
- 数据检索：提供任务状态和结果的查询接口
- 缓存清理：定期清理过期的缓存数据，优化存储空间
核心组件
1. 数据库连接管理器
数据库连接管理器负责创建和管理与 SQLite 数据库的连接，确保数据库操作的可靠性和效率。
代码示例：
def get_db_connection():
"""获取数据库连接"""
try:
conn = sqlite3.connect(DATABASE_PATH)
conn.row_factory = sqlite3.Row # 使结果可通过列名访问
return conn
except Exception as e:
raise Exception(f"数据库连接失败: {str(e)}")
def init_db():
"""初始化数据库，创建必要的表"""
try:
conn = get_db_connection()
cursor = conn.cursor()
# 创建任务表
cursor.execute('''
CREATE TABLE IF NOT EXISTS tasks (
id TEXT PRIMARY KEY,
type TEXT NOT NULL,
status TEXT NOT NULL,
result TEXT,
created_at INTEGER NOT NULL,
updated_at INTEGER
)
''')
conn.commit()
conn.close()
except Exception as e:
raise Exception(f"数据库初始化失败: {str(e)}")
2. 任务数据存储器
任务数据存储器负责将任务状态和结果存储到数据库，并在需要时更新这些信息。
代码示例：
def create_task_record(task_id, task_type):
"""创建新的任务记录"""
try:
conn = get_db_connection()
cursor = conn.cursor()
current_time = int(time.time())
cursor.execute(
"INSERT INTO tasks (id, type, status, created_at) VALUES (?, ?, ?, ?)",
(task_id, task_type, 'pending', current_time)
)
conn.commit()
conn.close()
except Exception as e:
raise Exception(f"创建任务记录失败: {str(e)}")
def update_task_result(task_id, status, result=None):
"""更新任务状态和结果"""
try:
conn = get_db_connection()
cursor = conn.cursor()
current_time = int(time.time())
if result:
# 如果提供了结果，将其转换为 JSON 字符串存储
result_json = json.dumps(result, ensure_ascii=False)
cursor.execute(
"UPDATE tasks SET status = ?, result = ?, updated_at = ? WHERE id = ?",
(status, result_json, current_time, task_id)
)
else:
cursor.execute(
"UPDATE tasks SET status = ?, updated_at = ? WHERE id = ?",
(status, current_time, task_id)
)
conn.commit()
conn.close()
except Exception as e:
raise Exception(f"更新任务结果失败: {str(e)}")
3. 缓存查询器
缓存查询器负责从数据库中检索任务状态和结果，支持系统的缓存机制。
代码示例：
def get_task_status(task_id):
"""获取任务状态"""
try:
conn = get_db_connection()
cursor = conn.cursor()
cursor.execute(
"SELECT status, created_at, updated_at FROM tasks WHERE id = ?",
(task_id,)
)
task = cursor.fetchone()
conn.close()
if task:
return {
'status': task['status'],
'created_at': task['created_at'],
'updated_at': task['updated_at']
}
else:
return None
except Exception as e:
raise Exception(f"获取任务状态失败: {str(e)}")
def get_task_result(task_id):
"""获取任务结果"""
try:
conn = get_db_connection()
cursor = conn.cursor()
cursor.execute(
"SELECT status, result, created_at, updated_at FROM tasks WHERE id = ?",
(task_id,)
)
task = cursor.fetchone()
conn.close()
if task and task['result']:
return {
'status': task['status'],
'result': json.loads(task['result']),
'created_at': task['created_at'],
'updated_at': task['updated_at']
}
elif task:
return {
'status': task['status'],
'result': None,
'created_at': task['created_at'],
'updated_at': task['updated_at']
}
else:
return None
except Exception as e:
raise Exception(f"获取任务结果失败: {str(e)}")
4. 数据清理器
数据清理器负责定期清理过期的缓存数据，优化数据库存储空间和查询性能。
代码示例：
def cleanup_expired_tasks(max_age_days=7):
"""清理过期的任务记录"""
try:
conn = get_db_connection()
cursor = conn.cursor()
# 计算过期时间戳（当前时间减去最大保留天数）
expiration_timestamp = int(time.time()) - (max_age_days * 24 * 60 * 60)
# 删除过期的任务记录
cursor.execute(
"DELETE FROM tasks WHERE created_at < ?",
(expiration_timestamp,)
)
deleted_count = cursor.rowcount
conn.commit()
conn.close()
return deleted_count
except Exception as e:
raise Exception(f"清理过期任务失败: {str(e)}")
数据库设计
缓存与持久化模块使用 SQLite 数据库存储任务状态和结果，数据库设计如下：
任务表 (tasks)
| 列名 | 类型 | 描述 |
|---|---|---|
| id | TEXT | 主键，任务唯一标识符 |
| type | TEXT | 任务类型（document, form, form_filling） |
| status | TEXT | 任务状态（pending, processing, completed, error） |
| result | TEXT | 任务结果，JSON 格式 |
| created_at | INTEGER | 创建时间戳 |
| updated_at | INTEGER | 更新时间戳 |
这种设计支持系统的核心缓存需求，同时保持数据库结构的简洁性。
缓存策略
缓存与持久化模块实现了以下缓存策略：
- 结果缓存：
- 存储任务处理结果，避免重复计算
- 相同的输入参数可以直接返回缓存结果
- 提高系统响应速度和资源利用率
- 状态跟踪：
- 记录任务的处理状态（待处理、处理中、已完成、错误）
- 支持客户端查询任务进度
- 实现异步处理模式
- 时间基缓存管理：
- 记录任务的创建和更新时间
- 定期清理过期缓存数据
- 优化存储空间和查询性能
- 错误恢复：
- 记录任务处理错误信息
- 支持错误分析和调试
- 可能的情况下支持任务重试
工作流程
缓存与持久化模块的工作流程如下：
数据存储流程
- 任务创建：
- 系统生成唯一的任务 ID
- 创建任务记录，状态设为”待处理”
- 记录创建时间戳
- 状态更新：
- 任务开始处理时，状态更新为”处理中”
- 记录更新时间戳
- 结果存储：
- 任务完成后，状态更新为”已完成”或”错误”
- 存储处理结果或错误信息
- 更新更新时间戳
数据检索流程
- 状态查询：
- 客户端提供任务 ID
- 系统查询任务状态
- 返回状态信息和时间戳
- 结果查询：
- 客户端提供任务 ID
- 系统查询任务结果
- 如果任务已完成，返回处理结果
- 如果任务未完成，返回当前状态
缓存清理流程
- 定期执行：
- 系统定期（如每天）执行缓存清理
- 也可以在服务器负载较低时手动触发
- 过期判断：
- 根据任务创建时间判断是否过期
- 默认保留期为 7 天
- 数据删除：
- 删除过期的任务记录
- 释放数据库存储空间
事务管理
缓存与持久化模块实现了基本的事务管理，确保数据操作的原子性：
- 连接管理：
- 每个数据库操作获取新的连接
- 操作完成后关闭连接，释放资源
- 事务提交：
- 数据修改操作后显式提交事务
- 确保数据写入磁盘
- 错误处理：
- 捕获并处理数据库操作异常
- 提供详细的错误信息，便于调试
模块接口
缓存与持久化模块提供以下主要接口：
- 对外接口：
get_task_status：获取任务状态get_task_result：获取任务结果
- 对内接口：
get_db_connection：获取数据库连接init_db：初始化数据库create_task_record：创建任务记录update_task_result：更新任务状态和结果cleanup_expired_tasks：清理过期任务
性能考量
缓存与持久化模块的性能优化措施包括：
- 轻量级数据库：
- 使用 SQLite 作为轻量级数据库
- 无需独立的数据库服务器
- 适合中小规模的缓存需求
- 索引优化：
- 对
id字段建立主键索引 - 提高任务查询性能
- 对
- 连接管理：
- 每个操作使用独立的连接
- 避免长时间占用连接资源
- 适合并发访问场景
- 定期清理：
- 清理过期数据，避免数据库膨胀
- 维持查询性能
扩展性
缓存与持久化模块的扩展性体现在：
- 支持多种存储后端：
- 设计支持未来替换为其他数据库系统
- 可以根据需求升级为更强大的数据库
- 可扩展的数据模型：
- 可以添加新的表和字段，支持更复杂的数据需求
- 保持向后兼容性
- 缓存策略优化：
- 可以实现更复杂的缓存策略，如基于使用频率的缓存
- 可以添加缓存预热和缓存失效机制
通过这些设计和实现，缓存与持久化模块为 DocuSnap-Backend 系统提供了高效、可靠的数据存储和检索服务，支持系统的核心功能和性能需求。