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

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

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

## 何時啟用

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

## 核心模式

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

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

```python
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)

```python
from dataclasses import dataclass

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

### 3. 基於檔案的快取儲存

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

```python
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 原則)

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

```python
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)` | 在第一次寫入時延遲建立目錄 |

## 最佳實踐

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

## 應避免的反模式

```python
# 錯誤 (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)。
- 快取條目體積異常巨大的情況 (可考慮改用串流處理)。
- 結果取決於檔案內容以外的參數 (例如不同的擷取配置)。
