Стратегии UUID: решение по моделированию
Выбирает правила генерации идентификаторов и публичного раскрытия, чтобы сортируемые идентификаторы не раскрывали нежелательную информацию о времени создания, последовательности арендаторов или объёмах через URL, логи и API.
Статус пакета: пакет справочной информации с поддержкой ИИ. Статическая проверка пакета пройдена; сценарии реализации ещё не выполнены, требуется экспертная проверка перед стабильным использованием.
Решение
Первичные ключи и публичные идентификаторы ресурсов должны выбираться в рамках одной политики, а не как отдельные значения по умолчанию. Если хранилище данных выигрывает от кластеризации с упорядочиванием по времени, команда может использовать формат сортируемого идентификатора на границах сохранения, одновременно сохраняя отдельный непрозрачный суррогат для любых URL или ссылок для клиентов. Случайные идентификаторы остаются допустимыми там, где упорядочивание не даёт операционных преимуществ, а риск раскрытия уже низок. Решение связывает три аспекта: как генерируются идентификаторы, подразумевает ли порядок байтов последовательность создания и какие поверхности могут раскрывать исходное значение или его редактированную/хэшированную форму.
Область применения
- Стратегия генерации идентификаторов, обработка коллизий и миграция с устаревших форматов.
- Поля сортировки и пагинации, доступные в API списков.
- Публичные URL, поля ответов API, структурированные логи и экспорт аналитики.
- Защита от перебора для угадываемых или последовательных публичных токенов.
Вне этой области
- Распределённое выделение ID в планетарном масштабе (воркеры в стиле snowflake).
- Форматы токенов аутентификации и идентификаторы сессий.
- Выбор ключей шардинга базы данных, выходящий за рамки эффектов порядка идентификаторов.
Контракт
- Каждая сохранённая сущность объявляет одно каноническое поле идентификатора и, при необходимости, отдельный публичный суррогат; суррогат — единственное значение, разрешённое в URL, видимых в браузере.
- Форматы сортируемых идентификаторов могут использоваться для индексации хранения, но API списков сортируют по явному полю временной метки или курсора, а не позволяют клиентам выводить порядок из сырых байтов идентификатора.
- Коллизия при вставке расходует одну попытку из профиля collision_retry_limit, который учитывает все попытки вставки, включая начальную генерацию; после исчерпания лимита запись завершается с ошибкой конфликта без тихого перезаписывания.
- Структурированные логи и экспорт поддержки хранят не более настроенного префикса хэша от исходного идентификатора, если потребляющая система не находится на одобренном аварийном пути с аудитом.
- Поиск ресурсов по идентификатору или суррогату между арендаторами отклоняет подсказки о существовании для арендаторов вне области видимости с той же формой ошибки, что и "не найдено", если включена защита от перебора.
- Во время миграции устаревшие форматы идентификаторов остаются читаемыми в объявленном окне двойного чтения; ответы содержат как канонические, так и устаревшие псевдонимы, не рассматривая ни один из них как доказательство владения.
Руководство по реализации
- Генерируйте идентификаторы на уровне приложения или в выделённом сервисе ID, чтобы политика была тестируемой независимо от настроек ORM по умолчанию.
- Если выбран формат с упорядочиванием по времени, документируйте точность временной метки, встроенной в идентификатор, и проверяйте, что её нельзя восстановить из публичных суррогатов.
- Связывайте курсоры пагинации с подписанными кортежами поля сортировки и идентификатора, а не раскрывайте клиентам сырые монотонные последовательности.
Обработка сбоев и меры безопасности
- Откат часов или несоответствие версии генератора не должны приводить к дублированию значений или тихому нарушению объявленного контракта UUIDv7/сортируемости. Используйте монотонный UUIDv7 с рандомизированным хвостом, сохраняющим версию и политику порядка; если такая реализация недоступна, завершайте запись с ошибкой и оповещайте, а не записывайте UUIDv4 в колонку, предназначенную только для UUIDv7.
- Никогда не логируйте полные идентификаторы в логах доступа веб-сервера, если профиль требует редактирования; хэшируйте при приёме, если downstream-инструменты не могут фильтровать.
- Ограничивайте частоту неаутентифицированных запросов по суррогату и по префиксу идентификатора, чтобы снизить сканирование ссылок для совместного доступа.
Проверка и эксплуатация
- Измеряйте частоту повторных попыток при коллизиях, срабатывания ограничений перебора и ошибки разрешения двойного чтения во время миграции.
- Тестируйте, что публичные URL, полезные нагрузки API и строки логов соответствуют матрице раскрытия в
uuid-policy.yaml. - Докажите, что конечные точки списков не выдают монотонные публичные последовательные номера при включённой защите от перебора.
- Смоделируйте откат часов и проверьте, что каждая успешная резервная реализация остаётся валидным UUIDv7 и не убывает в пределах задокументированной области генератора.
Примеры, похожие на исполняемые, в этом пакете являются фикстурами и контрактами приёмки. Выполните статическую проверку структуры пакета и метаданных, затем реализуйте и выполните сценарии в целевом репозитории.
Предположения при принятии
- Имена и числовые значения в
example.yaml— это профиль принятия, а не универсальные значения по умолчанию. - Команда, принимающая пакет, должна сопоставить акторов, классы данных, словарь ошибок и владение со своей системой.
- Терминология RFC 9562 используется описательно; команда выбирает конкретные библиотеки генераторов, подходящие для своего стека.