Основы взаимного исключения при файловой интеграции — лучшие практики файловых блокировок и атомарного claim

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

В этой статье взаимное исключение при файловой интеграции рассматривается вокруг файловых блокировок, атомарного claim, схемы temp -> rename и идемпотентности.

Содержание

1. Сначала вывод (в двух словах)
2. Паттерны конкуренции при файловой интеграции (диаграммы)
   • 2.1. Чтение файла в процессе записи
   • 2.2. Несколько воркеров одновременно подхватывают один и тот же файл
   • 2.3. Все останавливаются из-за устаревшей (stale) блокировки
3. Антипаттерны
   • 3.1. Двухшаговая проверка Exists -> Create
   • 3.2. Прямая запись в финальное имя файла
   • 3.3. Считать файл готовым, когда его размер перестал меняться
   • 3.4. Совместное обновление общего файла всеми участниками
   • 3.5. Считать API блокировки универсальным средством
4. Лучшие практики
   • 4.1. Публикация по схеме temp -> close -> rename / replace
   • 4.2. Явное указание завершённости через done / manifest
   • 4.3. Принимающая сторона атомарно берёт claim
   • 4.4. Если полагаетесь на lock-файл, делайте его lease
   • 4.5. Исходить из идемпотентности
5. Псевдокод (фрагменты)
6. Краткое руководство по выбору
7. Итог
8. Источники

Файловая интеграция — область, где «договорённость о передаче» ломается легче, чем сам код. Бывает вполне обычная ситуация: юнит-тесты проходят, но иногда всё ломается именно на боевой общей папке или в ночном пакетном задании, причём воспроизвести проблему трудно.

Причина чаще всего не в самих API файлового ввода-вывода, а в неопределённости трёх вещей:

• когда можно читать;
• кто владеет правом на обработку;
• как восстанавливаться после сбоя.

В этой статье взаимное исключение при файловой интеграции рассматривается не только как вопрос блокировок ОС, а как протокол передачи данных.

Отметим, что код из этой статьи опубликован на GitHub как полный собираемый и запускаемый набор примеров (библиотека, демонстрация конкуренции claim между двумя воркерами и перехвата lease, а также юнит-тесты, воспроизводящие конкуренцию, повреждение данных и устаревшие блокировки).

file-integration-locking-best-practices-komurasoft-style - komurasoft-blog-samples (GitHub)

1. Сначала вывод (в двух словах)

• Самое важное в файловой интеграции — сделать так, чтобы в момент появления финального имени файла состояние уже было «можно читать»
• Состояния «генерируется / опубликовано / в обработке / обработано» нужно выражать через имена файлов и директории
• Если воркеров несколько, перед чтением нужно атомарно брать claim
• lock-файлы и блокировки ОС стоит использовать как вспомогательное средство, а подстраховываться в конце — идемпотентностью

Иными словами, в файловой интеграции суть — не столько взаимное исключение, сколько проектирование протокола передачи. Вызовом одной функции блокировки дело не заканчивается.

2. Паттерны конкуренции при файловой интеграции (диаграммы)

2.1. Чтение файла в процессе записи

Если начать писать сразу под финальным именем файла, происходит именно такая неприятность. В JSON не будет закрывающей скобки, в CSV не хватит строк, а ZIP окажется попросту повреждён.

sequenceDiagram
    participant Sender as Отправитель
    participant Share as Общая папка
    participant Receiver as Получатель

    Sender->>Share: Создаёт orders.csv под финальным именем
    Sender->>Share: Записывает строки с 1-й по 5000-ю
    Receiver->>Share: Обнаруживает orders.csv
    Receiver->>Share: Сразу начинает чтение
    Note over Receiver: Файл ещё не готов
    Sender->>Share: Записывает оставшиеся данные
    Note over Receiver: Не хватает строк / ошибка разбора / обработана только часть

2.2. Несколько воркеров одновременно подхватывают один и тот же файл

При схеме «посмотреть список, открыть, если не обработан» один и тот же файл могут захватить сразу два воркера. Это начало двойного учёта и повторной отправки.

sequenceDiagram
    participant W1 as Воркер 1
    participant W2 as Воркер 2
    participant Dir as incoming

    W1->>Dir: Находит a.csv
    W2->>Dir: Находит a.csv
    W1->>Dir: Начинает чтение
    W2->>Dir: Начинает чтение
    Note over W1,W2: Один и тот же входной файл обрабатывается дважды

2.3. Все останавливаются из-за устаревшей (stale) блокировки

Архитектура, при которой просто кладётся lock-файл, легко зависает при аварийном завершении. Если непонятно, чья это блокировка, жив ли ещё её владелец и до какого момента она действительна, следующий процесс будет ждать вечно.

sequenceDiagram
    participant A as Воркер A
    participant Lock as lock-файл
    participant B as Воркер B

    A->>Lock: Создаёт lock
    Note over A: Аварийно завершается здесь
    B->>Lock: Проверяет наличие lock
    B->>Lock: Откладывает начало обработки
    B->>Lock: Продолжает ждать
    Note over B,Lock: Невозможно понять, устарела ли блокировка, — все останавливаются

3. Антипаттерны

3.1. Двухшаговая проверка Exists -> Create

Проблема здесь в том, что «проверка» и «захват» — это две разные операции. Между ними может вклиниться другой процесс, поэтому взаимного исключения не получается.

sequenceDiagram
    participant A as Процесс A
    participant B as Процесс B
    participant FS as Файловая система

    A->>FS: Проверяет отсутствие lock
    B->>FS: Проверяет отсутствие lock
    FS-->>A: Отсутствует
    FS-->>B: Отсутствует
    A->>FS: Создаёт lock
    B->>FS: Создаёт lock
    Note over A,B: Оба продолжают выполнение

Типичный неудачный пример выглядит так.

if (!File.Exists(lockPath))
{
    File.WriteAllText(lockPath, Environment.ProcessId.ToString());
    ProcessFile();
}

Нужно сделать так, чтобы «создать, если отсутствует» было одной операцией. В .NET для этого используется семейство FileMode.CreateNew, в POSIX-системах — атомарное создание вроде O_CREAT | O_EXCL.

3.2. Прямая запись в финальное имя файла

Если принимающая сторона трактует это так: «раз имя появилось, значит можно читать», то, начав писать напрямую под финальным именем, вы уже проиграли. Базовое правило — не отождествлять видимость файла с тем, что его можно читать.

flowchart LR
    A[Финальное имя становится видимым] --> B[Получатель обнаруживает файл]
    B --> C[Отправитель всё ещё пишет]
    C --> D[Читаются неполные данные]

using var writer = OpenForWrite(finalPath); // Здесь finalPath становится видимым
foreach (var row in rows)
{
    writer.WriteLine(row);
}

Такой подход сам напрашивается на неприятность из раздела 2.1.

3.3. Считать файл готовым, когда его размер перестал меняться

На первый взгляд это удобно, но на деле довольно ненадёжно. Копирование по сети, паузы на стороне отправителя, буферизация и повторные попытки — всё это регулярно вносит колебания.

sequenceDiagram
    participant Sender as Отправитель
    participant Share as Общая папка
    participant Receiver as Получатель

    Sender->>Share: Начинает копирование data.zip
    Sender->>Share: Приостанавливается на середине
    Receiver->>Share: Размер не меняется 10 секунд
    Note over Receiver: Ошибочно считает файл готовым
    Receiver->>Share: Начинает чтение
    Sender->>Share: Возобновляет копирование

if (currentLength == lastLength && stableSeconds >= 10)
{
    return Ready;
}

Если определять завершённость по догадке, общие папки и крупные файлы рано или поздно подставят подножку. Гораздо стабильнее явно указывать завершённость через manifest или done-файл.

3.4. Совместное обновление общего файла всеми участниками

Архитектура, при которой один общий status.csv или counter.json читают и обновляют все подряд, обычно заканчивается тем, что побеждает тот, кто записал последним. Если начать использовать файловую интеграцию как упрощённую БД, именно здесь начинаются мучения.

sequenceDiagram
    participant A as Пакет A
    participant B as Пакет B
    participant F as status.csv

    A->>F: Читает v1
    B->>F: Читает v1
    A->>F: Записывает v2-A
    B->>F: Записывает v2-B
    Note over F: Обновление от A теряется

Есть вариант уйти в append-only, но его семантика колеблется в зависимости от файловой системы и способа размещения. Если действительно нужно совместное обновление, в этом месте лучше не перегружать файловую интеграцию сверх меры.

3.5. Считать API блокировки универсальным средством

API блокировки важны, но они работают, только когда все участники действуют по одному и тому же соглашению. При интеграции разнородных систем безопаснее не переоценивать их.

Дополнительно:

• flock в Linux — это advisory lock, поэтому сторона, игнорирующая договорённость, вполне может писать в файл как ни в чём не бывало
• byte-range lock в Windows игнорируется файлами, отображаемыми в память
• иными словами, не стоит взваливать на одни только блокировки ОС ещё и проектирование уведомления о завершении и владения

4. Лучшие практики

4.1. Публикация по схеме temp -> close -> rename / replace

Это классический путь. Файл, который ещё генерируется, держат под временным именем (temp), а после close переключают на финальное имя. Принимающая сторона следит только за финальным именем.

flowchart LR
    A[Создать уникальное temp-имя] --> B[Записать в temp всё содержимое]
    B --> C[flush / close]
    C --> D[rename / replace в финальное имя в той же директории]
    D --> E[Получатель следит только за финальным именем]

Ключевые моменты:

• temp и final должны находиться в одной директории, по крайней мере на одном томе / в одной файловой системе
• в Windows / .NET можно рассмотреть семейство File.Replace
• договорённость такая: как только видно финальное имя, содержимое уже полностью готово

Если разместить temp на другом диске, rename фактически превращается в копирование, либо Replace завершается ошибкой. Эта предпосылка выглядит незаметной, но она очень важна.

4.2. Явное указание завершённости через done / manifest

Если помимо самих данных явно указывать в отдельном файле, «что именно завершено», принимающая сторона становится устойчивее. Это особенно эффективно при интеграции разнородных систем.

flowchart TD
    A[Сгенерировать data.tmp] --> B[Опубликовать как data.csv]
    B --> C[Создать data.done / manifest.json]
    C --> D[Получатель обнаруживает done / manifest]
    D --> E[Проверяет имя файла, размер и хеш]

В manifest стоит включать примерно такие поля.

• имя целевого файла
• размер
• хеш
• количество записей
• ID интеграции / ключ идемпотентности
• время генерации

Порядок тоже важен. Если разместить done раньше публикации самих данных, это будет не уведомлением о завершении, а предвестником аварии.

4.3. Принимающая сторона атомарно берёт claim

Если за одним и тем же incoming следят несколько воркеров, самый понятный подход — «переместить файл к себе перед чтением». Обрабатывает файл только тот воркер, у которого успешно прошёл rename из incoming в processing/<worker>/.

sequenceDiagram
    participant W1 as Воркер 1
    participant W2 as Воркер 2
    participant IN as incoming
    participant PR as processing

    W1->>IN: Находит a.csv
    W2->>IN: Находит a.csv
    W1->>PR: Выполняет rename a.csv
    W2->>PR: Выполняет rename a.csv
    Note over W1,W2: Владение получает только тот, кто успел первым

На практике удобнее также разделить директории — так проще отслеживать состояние.

flowchart LR
    T[temp] -->|publish| I[incoming]
    I -->|claim| P[processing]
    P -->|успех| A[archive]
    P -->|ошибка| E[error]

Предпосылка та же: rename для claim тоже должен выполняться в пределах одной файловой системы.

4.4. Если полагаетесь на lock-файл, делайте его lease

Если вы используете lock-файл, превращайте его не в пустой файл, а в запись о владении со сроком действия. Блокировка, о владельце которой ничего не известно, рано или поздно обязательно приведёт к спорам.

flowchart TD
    L[lock.json] --> A[ownerId]
    L --> B[host]
    L --> C[pid]
    L --> D[acquiredAt]
    L --> E[expiresAt]
    L --> F[heartbeatAt]

Ключевые моменты:

• создание выполняется атомарно
• прекращение обновлений служит признаком того, что запись устарела (stale)
• удаление, как правило, выполняет только создатель
• заранее продумайте процедуру восстановления на случай, если снятие блокировки не произойдёт

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

4.5. Исходить из идемпотентности

Взаимное исключение важно, но в реальной эксплуатации свести к нулю ситуации «иногда данные приходят дважды» или «повторный запуск на середине» невозможно. В конечном счёте выручает архитектура, которая не ломается, даже если повторно скормить ей тот же самый вход.

flowchart LR
    A[Вход + ключ идемпотентности] --> B{Уже обработано?}
    B -- Да --> C[Считать успехом без повторного выполнения]
    B -- Нет --> D[Выполнить обработку]
    D --> E[Записать в журнал обработанных]

Например, каждому полученному файлу присваивается ID интеграции, который записывается в журнал обработанных. Если сделать так, чтобы результат не задваивался, даже если взаимное исключение однажды нарушится, эксплуатация становится значительно проще.

5. Псевдокод (фрагменты)

5.1. Типичный неудачный паттерн

var lockPath = finalPath + ".lock";

if (!File.Exists(lockPath))
{
    File.WriteAllText(lockPath, "");
    using var writer = OpenForWrite(finalPath); // Прямая запись в финальное имя
    WritePayload(writer);

    File.Delete(lockPath);
}

Проблем здесь три.

• Exists и WriteAllText — это разные операции
• finalPath становится видимым ещё в процессе записи
• при аварийном завершении lock остаётся

5.2. Пример в правильном направлении (в грубом приближении)

var tempPath = MakeTempPathSameDirectory(finalPath);
WritePayload(tempPath);
FlushAndClose(tempPath);

PublishByRenameOrReplace(tempPath, finalPath); // Предполагается одна ФС / один том
PublishDoneFile(finalPath + ".done", new
{
    FileName = Path.GetFileName(finalPath),
    Size = GetFileSize(finalPath),
    Hash = ComputeHash(finalPath),
    IdempotencyKey = integrationId
});

if (!TryClaimBundleByRename(baseName, incomingDir, processingDir))
{
    return; // Другой воркер захватил файл раньше
}

var manifest = ReadDoneFile(Path.Combine(processingDir, baseName + ".done"));
VerifyPayload(Path.Combine(processingDir, baseName), manifest);

if (AlreadyProcessed(manifest.IdempotencyKey))
{
    MoveBundle(processingDir, archiveDir, baseName);
    return;
}

Process(Path.Combine(processingDir, baseName));
RecordProcessed(manifest.IdempotencyKey);
MoveBundle(processingDir, archiveDir, baseName);

Здесь важнее не детали реализации, а порядок действий. Если не смешивать «запись», «публикацию», «захват владения» и «фиксацию обработанности», всё становится заметно устойчивее к поломкам.

6. Краткое руководство по выбору

• При одном writer / одном reader / на одном хосте уже одной схемы temp -> rename часто достаточно для приличной стабильности
• Если потребителей несколько, добавьте claim-rename по схеме incoming -> processing
• При интеграции разнородных систем, NAS или общих папок безопаснее довести дело до manifest / done и идемпотентности
• Если несколько writer’ов хотят обновлять одно и то же логическое состояние, не стоит слишком напрягать файловую интеграцию — стоит рассмотреть БД или очередь
• Блокировки ОС эффективны внутри одной группы приложений с одинаковыми допущениями, но не заменяют протокол передачи

Последний пункт — это ещё и критерий отступления. Действительно бывают проблемы, которые файлами решать тяжело.

7. Итог

Взаимное исключение при файловой интеграции — это не вызов функции блокировки, а определение переходов состояния. В этом суть данной статьи. Состояния «генерируется / опубликовано / в обработке / обработано» выражаются через имена и директории, а двухшаговой проверки Exists -> Create, прямой записи в финальное имя файла, ожидания стабилизации размера, взаимного обновления общего файла и чрезмерного доверия к API блокировки следует избегать. Если поверх этого сочетать temp -> close -> rename / replace, done / manifest, claim-rename, lease и идемпотентность, аварий при интеграции через общие папки удаётся избежать почти полностью.

Секрет файловой интеграции в том, чтобы не отождествлять «файл можно прочитать технически» с тем, что «его уже можно читать по смыслу». Одно только это разделение заметно сокращает число сбоев, которые проявляются исключительно по ночам.

8. Источники

• Полный набор примеров кода для этой статьи (библиотека, демонстрация, юнит-тесты) - komurasoft-blog-samples (GitHub)
• LockFileEx function (Win32)
• Locking and Unlocking Byte Ranges in Files (Win32)
• Moving and Replacing Files (Win32)
• File.Replace Method (.NET)
• rename — POSIX
• open — POSIX (O_CREAT | O_EXCL)
• flock(2) — Linux manual page
• open(2) — Linux manual page

Похожие статьи

Недавние статьи с теми же тегами помогут подробнее изучить близкие темы.

Связанные темы

Эти страницы показывают тему статьи в более широком контексте услуг и решений.

Услуги по этой теме

Статья напрямую связана со следующими услугами.

Частые вопросы

Вопросы, которые часто возникают при консультациях по теме статьи.

Достаточно ли одного лишь API блокировки для взаимного исключения при файловой интеграции?

Часто недостаточно. flock в Linux — это advisory lock (рекомендательная блокировка), поэтому сторона, игнорирующая договорённость, вполне может писать в файл как ни в чём не бывало, а byte-range lock в Windows игнорируется файлами, отображаемыми в память. Блокировки ОС эффективны внутри одной группы приложений с одинаковыми допущениями, но их стоит использовать как вспомогательное средство, а основой делать проектирование протокола передачи — temp -> rename, done/manifest, атомарный claim и идемпотентность.

Как избежать чтения файла, который ещё дописывается?

Классический путь — публикация по схеме temp -> close -> rename/replace. Файл, который ещё генерируется, держат под временным (temp) именем, а после close переключают на финальное имя в той же директории; принимающая сторона следит только за финальным именем. Предпосылка — temp и финальный файл должны находиться в одной директории, по крайней мере на одном томе / в одной файловой системе, а договорённость такая: как только видно финальное имя, содержимое уже полностью готово.

Как не дать нескольким воркерам одновременно обрабатывать один и тот же файл?

Нужно атомарно брать claim до чтения. Конкретно — только тот воркер, у которого успешно прошёл rename из incoming в processing/<worker>/, и обрабатывает файл. Двухшаговая проверка Exists -> Create не даёт взаимного исключения, потому что «проверка» и «захват» — это две разные операции, между которыми может вклиниться другой процесс. Если нужно атомарное создание, используйте семейство FileMode.CreateNew в .NET или O_CREAT | O_EXCL в POSIX.

На что обратить внимание при использовании lock-файла?

Не делайте его просто пустым файлом — превратите в lease (запись о владении) с ownerId, host, pid, acquiredAt, expiresAt и heartbeatAt, у которого есть срок действия. Создавайте его атомарно, используйте прекращение обновлений как признак того, что запись устарела (stale), удаляйте, как правило, только силами того, кто её создал, и заранее продумайте процедуру восстановления на случай, если снятие блокировки не произойдёт. На практике сильнее всего работает подход, при котором не пытаются гарантировать полную согласованность одним lock-файлом, а в конце подстраховываются идемпотентностью.

Об авторе

Страница с профилем автора статьи.

Го Комура

Представитель KomuraSoft LLC

Специализируется на разработке программного обеспечения для Windows, техническом консалтинге и расследовании сбоев, особенно в проектах с унаследованными системами и трудно воспроизводимыми ошибками.