Content-Hash Cache Pattern

Оптимизируйте обработку файлов с помощью SHA-256 хеширования содержимого. Научитесь реализовывать независимые от путей, автоматически инвалидируемые кеши для Claude Code и AI-агентов кодинга.

Инструменты разработчика ★ 112,917 GitHub (112,917 ★)

Этот шаблон предоставляет надежную архитектуру для кэширования дорогостоящих операций обработки файлов, таких как разбор PDF или анализ изображений, используя хеши содержимого SHA-256 в качестве уникальных идентификаторов. В отличие от традиционного кэширования на основе путей, которое ломается при перемещении или переименовании файлов, этот шаблон гарантирует, что попадания в кэш сохраняются при изменениях файловой системы, и автоматически аннулирует результаты в момент изменения содержимого файла. Реализуя обертку на уровне сервиса, он поддерживает чистоту разделения ответственности, сохраняя вашу основную логику обработки чистой и обеспечивая эффективный поиск O(1) для ранее обработанных ресурсов.

Ключевые особенности

01Хеширование содержимого SHA-256 для надежной, независимой от пути идентификации

02Разделение сервисного слоя для поддержания чистых, тестируемых функций обработки

03Автоматическая инвалидация кэша, запускаемая любым изменением содержимого файла

04Файловое хранилище O(1) с использованием хешированных имен файлов для быстрого поиска

05Корректная обработка повреждений, при которой неверные данные считаются промахом кэша

06112,917 GitHub stars

Сценарии использования

01Снижение затрат на API для облачного анализа изображений или сервисов OCR

02Реализация постоянного кэширования для CLI-инструментов, выполняющих масштабные преобразования файлов

03Ускорение конвейеров извлечения текста из PDF, где документы обрабатываются многократно

name	content-hash-cache-pattern
description	Cache expensive file processing results using SHA-256 content hashes — path-independent, auto-invalidating, with service layer separation.
origin	ECC

Content-Hash File Cache Pattern

Cache expensive file processing results (PDF parsing, text extraction, image analysis) using SHA-256 content hashes as cache keys. Unlike path-based caching, this approach survives file moves/renames and auto-invalidates when content changes.

When to Activate

Building file processing pipelines (PDF, images, text extraction)
Processing cost is high and same files are processed repeatedly
Need a --cache/--no-cache CLI option
Want to add caching to existing pure functions without modifying them

Core Pattern

1. Content-Hash Based Cache Key

Use file content (not path) as the cache key:

import hashlib
from pathlib import Path

_HASH_CHUNK_SIZE = 65536  # 64KB chunks for large files

def compute_file_hash(path: Path) -> str:
    """SHA-256 of file contents (chunked for large files)."""
    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()

Why content hash? File rename/move = cache hit. Content change = automatic invalidation. No index file needed.

2. Frozen Dataclass for Cache Entry

from dataclasses import dataclass

@dataclass(frozen=True, slots=True)
class CacheEntry:
    file_hash: str
    source_path: str
    document: ExtractedDocument  # The cached result

3. File-Based Cache Storage

Each cache entry is stored as {hash}.json — O(1) lookup by hash, no index file required.

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  # Treat corruption as cache miss

4. Service Layer Wrapper (SRP)

Keep the processing function pure. Add caching as a separate service layer.

def extract_with_cache(
    file_path: Path,
    *,
    cache_enabled: bool = True,
    cache_dir: Path = Path(".cache"),
) -> ExtractedDocument:
    """Service layer: cache check -> extraction -> cache write."""
    if not cache_enabled:
        return extract_text(file_path)  # Pure function, no cache knowledge

    file_hash = compute_file_hash(file_path)

    # Check cache
    cached = read_cache(cache_dir, file_hash)
    if cached is not None:
        logger.info("Cache hit: %s (hash=%s)", file_path.name, file_hash[:12])
        return cached.document

    # Cache miss -> extract -> store
    logger.info("Cache miss: %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

Key Design Decisions

Decision	Rationale
SHA-256 content hash	Path-independent, auto-invalidates on content change
`{hash}.json` file naming	O(1) lookup, no index file needed
Service layer wrapper	SRP: extraction stays pure, cache is a separate concern
Manual JSON serialization	Full control over frozen dataclass serialization
Corruption returns `None`	Graceful degradation, re-processes on next run
`cache_dir.mkdir(parents=True)`	Lazy directory creation on first write

Best Practices

Hash content, not paths — paths change, content identity doesn't
Chunk large files when hashing — avoid loading entire files into memory
Keep processing functions pure — they should know nothing about caching
Log cache hit/miss with truncated hashes for debugging
Handle corruption gracefully — treat invalid cache entries as misses, never crash

Anti-Patterns to Avoid

# BAD: Path-based caching (breaks on file move/rename)
cache = {"/path/to/file.pdf": result}

# BAD: Adding cache logic inside the processing function (SRP violation)
def extract_text(path, *, cache_enabled=False, cache_dir=None):
    if cache_enabled:  # Now this function has two responsibilities
        ...

# BAD: Using dataclasses.asdict() with nested frozen dataclasses
# (can cause issues with complex nested types)
data = dataclasses.asdict(entry)  # Use manual serialization instead

When to Use

File processing pipelines (PDF parsing, OCR, text extraction, image analysis)
CLI tools that benefit from --cache/--no-cache options
Batch processing where the same files appear across runs
Adding caching to existing pure functions without modifying them

When NOT to Use

Data that must always be fresh (real-time feeds)
Cache entries that would be extremely large (consider streaming instead)
Results that depend on parameters beyond file content (e.g., different extraction configs)

Что это 🧠

Content-Hash Cache Pattern — это архитектурный шаблон для кэширования результатов дорогих операций обработки файлов (например, парсинга PDF, распознавания текста или анализа изображений) с использованием SHA-256 хеша содержимого файла в качестве ключа кэша.

Основная идея: в отличие от классического кэширования по пути к файлу, этот подход не зависит от перемещения или переименования файла — кэш остаётся валидным, пока содержимое не изменится. При изменении содержимого хеш меняется, и запись автоматически инвалидируется (без необходимости вручную чистить кэш). Паттерн также предусматривает чёткое разделение: функция обработки остаётся чистой и не знает о кэше, а кэширование подключается как отдельный сервисный слой.

Как работает ⚙️

1️⃣ Вычисление хеша содержимого

Для генерации ключа кэша используется SHA-256 от содержимого файла (не пути). Крупные файлы читаются чанками по 64 КБ, чтобы не загружать их в память целиком:

# Пример: хеш файла через hashlib
sha256.update(f.read(65536))  # chunked reading
return sha256.hexdigest()

Результат: если файл переместить (mv), хеш останется тем же — кэш действителен. Если исправить одну букву в содержимом — хеш изменится, кэш станет недоступен, файл будет обработан заново.

2️⃣ Структура записи кэша

Каждая запись — замороженный dataclass (@dataclass(frozen=True, slots=True)):

file_hash: хеш SHA-256 (строка).
source_path: исходный путь файла (для отладки и метаинформации).
document: результат обработки (например, ExtractedDocument — готовый объект с данными).

Замороженность (frozen=True) гарантирует неизменность записи после создания — это безопасно при многопоточном/многопроцессном доступе на чтение.

3️⃣ Хранение кэша на диске

Каждая запись сохраняется в отдельный JSON-файл с именем {hash}.json. Файлы хранятся в единой директории кэша (по умолчанию .cache/).

O(1) поиск: для проверки кэша достаточно проверить существование файла с нужным именем — не нужен индексный файл или БД.
Ленивое создание директории: cache_dir.mkdir(parents=True, exist_ok=True) создаёт папку только при первой записи.
Обработка повреждений: если JSON-файл читается с ошибкой (коррупция, битый файл), запись считается кэш-промахом — процесс не падает, а просто перезапускается обработка.

4️⃣ Сервисный слой (SRP)

Ключевое архитектурное решение: функция обработки остаётся чистой — она принимает только путь к файлу и возвращает результат. Вся логика кэширования вынесена в обёртку:

# Пример: pure extraction function
def extract_text(path: Path) -> ExtractedDocument:
    # ... чистая логика, ничего не знает про кэш

# Service layer with caching
def extract_with_cache(file_path, *, cache_enabled=True, cache_dir=Path(".cache")):
    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:
        log("Cache hit: %s", file_path.name)
        return cached.document
    log("Cache miss: %s", file_path.name)
    doc = extract_text(file_path)
    entry = CacheEntry(file_hash, str(file_path), doc)
    write_cache(cache_dir, entry)
    return doc

Благодаря этому разделению можно добавить кэширование к уже существующим функциям без их изменения — просто обернув вызов в extract_with_cache.

5️⃣ Флаг --cache/--no-cache

Паттерн предполагает, что CLI-инструмент предоставляет флаг --cache / --no-cache. Если пользователь явно отключает кэширование — сервисный слой просто вызывает чистую функцию, минуя кэш.

Когда использовать ✅

Конвейеры обработки файлов: парсинг PDF, OCR, извлечение текста, анализ изображений — где каждая операция затратна по времени/ресурсам.
CLI-инструменты, которые обрабатывают одни и те же файлы многократно (например, сбор отчётов, генерация превью).
Пакетная обработка: запуск через find . -name '*.pdf' | xargs your-tool — второй запуск без изменений файлов будет молниеносным.
Добавление кэша к legacy-функциям: можно обернуть вызов extract_with_cache(old_function) без редактирования старого кода.

Когда НЕ использовать ❌

Данные, которые всегда должны быть свежими (реалтайм-ленты, котировки).
Результаты обработки огромных размеров (лучше использовать стриминг, а не сохранять весь объект в JSON).
Результаты, зависящие от параметров обработки (например, разные настройки экстракции для одного файла), — тогда ключ кэша должен включать не только хеш файла, но и хеш параметров.

Важно знать ⚠️

Не кешируйте по путям — это антипаттерн. Путь может измениться (mv, rename), и кэш потеряется.
Чанкуйте большие файлы при хешировании: использование read(65536) в цикле не загружает гигабайтный PDF в память.
Не смешивайте ответственность: функция обработки не должна содержать логику кэша. Используйте сервисный слой.
Логируйте хит/мисс с сокращённым хешем (первые 12 символов) — это помогает при отладке, не засоряя логи.
Коррупция — не краш: если файл кэша повреждён, обрабатываем как промах и пишем новую корректную запись.
Избегайте dataclasses.asdict(): при вложенных frozen dataclasses он может давать сбои. Лучше написать ручную сериализацию/десериализацию.

Паттерн реализован в рамках экосистемы OpenClaw (ECC) и отлично подходит для проектов, где требуется пуленепробиваемое кэширование с минимальным оверхедом и чётким разделением обязанностей.

Установите одной командой.

npx skillfish add affaan-m/everything-claude-code content-hash-cache-pattern

Источник: https://mcpmarket.com/tools/skills/content-hash-cache-pattern