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