5.8 KiB

Raw Blame History

name	description
content-hash-cache-pattern	使用 SHA-256 內容雜湊值 (Content Hash) 快取昂貴的檔案處理結果 — 與路徑無關、自動失效且服務層分離。

內容雜湊檔案快取模式 (Content-Hash File Cache Pattern)

使用 SHA-256 內容雜湊值作為快取鍵 (Cache keys)，快取高成本的檔案處理結果（如 PDF 解析、文字擷取、影像分析）。與基於路徑的快取不同，此方法在檔案移動或重新命名時仍能保持有效，且在內容變更時會自動失效。

何時啟用

建立檔案處理流水線 (PDF、影像、文字擷取)。
處理成本很高，且經常重複處理相同的檔案。
需要 --cache/--no-cache CLI 選項。
想要在不修改現有純函式的前提下為其添加快取功能。

核心模式

1. 基於內容雜湊的快取鍵

使用檔案內容（而非路徑）作為快取鍵：

import hashlib
from pathlib import Path

_HASH_CHUNK_SIZE = 65536  # 針對大型檔案使用 64KB 的分塊
import hashlib
from pathlib import Path

def compute_file_hash(path: Path) -> str:
    """計算檔案內容的 SHA-256 (針對大型檔案進行分塊處理)。"""
    if not path.is_file():
        raise FileNotFoundError(f"檔案不存在：{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()

為什麼要用內容雜湊？ 檔案重新命名或移動 = 快取命中 (Cache hit)。內容變更 = 自動失效。不需要索引檔。

2. 快取條目的凍結資料類別 (Frozen Dataclass)

from dataclasses import dataclass

@dataclass(frozen=True, slots=True)
class CacheEntry:
    file_hash: str
    source_path: str
    document: ExtractedDocument  # 快取的結果

3. 基於檔案的快取儲存

每個快取條目都儲存為 {hash}.json — 透過雜湊值實現 O(1) 查找，無需索引檔。

import json
from typing import Any

def write_cache(cache_dir: Path, entry: CacheEntry) -> None:
    cache_dir.mkdir(parents=True, exist_ok=True)
    cache_file = cache_dir / f"{entry.file_hash}.json"
    data = serialize_entry(entry)
    cache_file.write_text(json.dumps(data, ensure_ascii=False), encoding="utf-8")

def read_cache(cache_dir: Path, file_hash: str) -> CacheEntry | None:
    cache_file = cache_dir / f"{file_hash}.json"
    if not cache_file.is_file():
        return None
    try:
        raw = cache_file.read_text(encoding="utf-8")
        data = json.loads(raw)
        return deserialize_entry(data)
    except (json.JSONDecodeError, ValueError, KeyError):
        return None  # 將損壞的檔案視為快取未命中

4. 服務層包裝器 (符合 SRP 原則)

保持處理函式的純淨性。將快取功能作為獨立的服務層添加。

def extract_with_cache(
    file_path: Path,
    *,
    cache_enabled: bool = True,
    cache_dir: Path = Path(".cache"),
) -> ExtractedDocument:
    """服務層：檢查快取 -> 執行擷取 -> 寫入快取。"""
    if not cache_enabled:
        return extract_text(file_path)  # 純函式，不涉及快取邏輯

    file_hash = compute_file_hash(file_path)

    # 檢查快取
    cached = read_cache(cache_dir, file_hash)
    if cached is not None:
        logger.info("快取命中: %s (hash=%s)", file_path.name, file_hash[:12])
        return cached.document

    # 快取未命中 -> 執行擷取 -> 儲存結果
    logger.info("快取未命中: %s (hash=%s)", file_path.name, file_hash[:12])
    doc = extract_text(file_path)
    entry = CacheEntry(file_hash=file_hash, source_path=str(file_path), document=doc)
    write_cache(cache_dir, entry)
    return doc

關鍵設計決策

決策	理由
SHA-256 內容雜湊	與路徑無關，內容變更時自動失效
`{hash}.json` 檔案命名	O(1) 查找，無需索引檔
服務層包裝器	SRP 原則：擷取邏輯保持純淨，快取是獨立的關注點
手動 JSON 序列化	完整控制凍結資料類別的序列化過程
損壞時回傳 `None`	優雅降級，下次執行時重新處理
`cache_dir.mkdir(parents=True)`	在第一次寫入時延遲建立目錄

最佳實踐

對內容進行雜湊，而非路徑 — 路徑會變，但內容身分不變。
雜湊時 對大型檔案進行分塊 — 避免將整個檔案載入記憶體。
保持處理函式純淨 — 它們不應感知任何快取邏輯。
記錄快取命中/未命中 並附帶簡短的雜湊值以利偵錯。
優雅處理損壞情形 — 將無效的快取條目視為未命中，絕不崩潰。

應避免的反模式

# 錯誤 (BAD)：基於路徑的快取 (檔案移動/重命名後會失效)
cache = {"/path/to/file.pdf": result}

# 錯誤 (BAD)：在處理函式內部添加快取邏輯 (違反 SRP 原則)
def extract_text(path, *, cache_enabled=False, cache_dir=None):
    if cache_enabled:  # 現在這個函式負擔了兩項職責
        ...

# 錯誤 (BAD)：對巢狀的凍結資料類別使用 dataclasses.asdict()
# (在處理複雜巢狀型別時可能會導致問題)
data = dataclasses.asdict(entry)  # 請改用手動序列化

何時使用

檔案處理流水線 (PDF 解析、OCR、文字擷取、影像分析)。
受益於 --cache/--no-cache 選項的 CLI 工具。
當相同檔案會跨執行週期出現時的批次處理。
在不修改現有純函式的前提下為其添加快取。

何時「不」使用

必須始終保持最新的資料 (即時饋送 Real-time feeds)。
快取條目體積異常巨大的情況 (可考慮改用串流處理)。
結果取決於檔案內容以外的參數 (例如不同的擷取配置)。

5.8 KiB Raw Blame History