内容哈希文件缓存模式 (Content-Hash File Cache Pattern)

内容哈希文件缓存模式 (Content-Hash File Cache Pattern)

使用 SHA-256 内容哈希（而非文件路径）作为缓存键，缓存高昂的文件处理结果（如 PDF 解析、文本提取、图像分析）。与基于路径的缓存不同，这种方法在文件移动/重命名后依然有效，并在内容变化时自动失效。

何时激活

• 构建文件处理流水线（Pipeline），如 PDF、图像或文本提取
• 处理成本高昂且需要重复处理相同文件
• 需要提供 --cache/--no-cache 命令行选项
• 希望在不修改现有纯函数（Pure Functions）的情况下为其添加缓存功能

核心模式

1. 基于内容哈希的缓存键

使用文件内容（而非路径）作为缓存键：

import hashlib
from pathlib import Path

_HASH_CHUNK_SIZE = 65536  # 大文件采用 64KB 分块读取

def compute_file_hash(path: Path) -> str:
    """计算文件内容的 SHA-256 哈希值（针对大文件进行分块）。"""
    if not path.is_file():
        raise FileNotFoundError(f"File not found: {path}")
    sha256 = hashlib.sha256()
    with open(path, "rb") as f:
        while True:
            chunk = f.read(_HASH_CHUNK_SIZE)
            if not chunk:
                break
            sha256.update(chunk)
    return sha256.hexdigest()

为什么使用内容哈希？ 文件重命名/移动 = 缓存命中。内容更改 = 自动失效。无需索引文件。

2. 用于缓存条目的冻结数据类 (Frozen Dataclass)