Сначала выясните, одинаковы ли записи по бизнес-смыслу. Две организации с похожими названиями могут быть разными юридическими лицами, а один пользователь вправе состоять в нескольких tenants. Возьмите пару дублей и сравните owner, регистрационный идентификатор, домен, момент создания и request trace.

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

Источник дубля виден по временной линии

ПризнакВероятная причинаСледующая проверка
один request id, две строкидвойная обработка handlerграница транзакции
два request id за секундудвойной клик/retryidempotency key
разные worker, один payloadгонка check-then-insertunique constraint
похожие названия, разные реквизитывозможно не дубльручная проверка
дубли после приглашениядва сценария provisioningединый owner команды

Проверка перед INSERT проигрывает гонку

Конструкция «SELECT, если нет — INSERT» без подходящей синхронизации даёт двум транзакциям один ответ «нет». Обе вставляют строку. Последней защитой служит уникальное ограничение, а приложение должно корректно обработать конфликт и получить уже существующую запись.

CREATE UNIQUE INDEX organizations_create_key_uq
ON organizations (owner_user_id, create_key);

INSERT INTO organizations (owner_user_id, create_key, name)
VALUES (:owner, :key, :name)
ON CONFLICT (owner_user_id, create_key) DO NOTHING
RETURNING id;

Если `RETURNING` ничего не вернул, прочитайте ID по тому же ключу. `create_key` может быть idempotency key запроса либо устойчивый нормализованный бизнес-идентификатор. Не используйте nullable-поле, не разобрав поведение NULL: в PostgreSQL уникальные ограничения по умолчанию допускают несколько NULL.

Idempotency key связывается с payload

Клиент генерирует ключ на одну логическую операцию и повторяет его при сетевом retry. Сервер хранит ключ, hash существенного payload и результат. Тот же ключ с тем же payload возвращает прежний organization id; тот же ключ с другим payload получает конфликт, а не молчаливое обновление.

  • Scope ключа включает пользователя или tenant-контекст.
  • Ключ не переносится на другую кнопку «создать».
  • Ответ сохраняется после успешного commit.
  • Retention выбирается по реальному окну повторов.
  • Секреты и полный payload в журнал не копируются.

POST становится безопасным для повтора по контракту

HTTP не объявляет POST идемпотентным автоматически. RFC 9110 допускает повтор неидемпотентного метода только когда клиент знает, что семантика ресурса это позволяет, либо может установить, что запрос не применился. Поэтому ваш endpoint явно документирует idempotency key и одинаковый результат повтора.

ПопыткаСерверОтвет
перваясоздаёт организацию201 + organization id
тот же key/payloadничего не создаёттот же id
тот же key/другой payloadничего не меняет409 conflict
новый key/тот же бизнес-IDсрабатывает business uniqueсуществующая запись/конфликт

Существующие дубли сначала картографируют

  1. Заморозить автоматическое создание по повреждённому пути.
  2. Выбрать canonical organization по подтверждённым данным.
  3. Собрать зависимости: memberships, проекты, счета, роли и audit log.
  4. Перенести ссылки транзакционно или пакетами с журналом.
  5. Оставить alias/redirect со старых IDs, если внешние ссылки живут.
  6. Только после сверки архивировать дубликат и включить constraint.

Удаление второй строки до переноса связей может потерять документы или смешать доступы. Особое внимание — ролям: пользователь, который был owner в одном tenant и guest в другом, не должен получить расширенные права после merge.

Нагрузочный тест подтверждает границу

Отправьте 20 параллельных запросов с одним ключом, затем повторите с разными ключами и одинаковым бизнес-идентификатором. В первом случае все успешные ответы указывают на один ID; во втором правило продукта либо создаёт разные организации, либо выдаёт контролируемый конфликт. Неудачный commit не должен оставлять занятый key без результата.

Для расследования понадобятся обезличенный payload hash, request и idempotency IDs, DDL ограничений, зависимости пары дублей и план отката merge. Названия реальных компаний, налоговые данные и персональные контакты в рабочий пример не включайте.

Проверенные источники