idkit
Генерация и проверка внутренних идентификаторов. NewV7 отдаёт UUID v7
(RFC 9562) строкой — time-sortable id, у которого старшие биты несут unix-ms. В
отличие от случайного v4, такие id монотонно растут во времени и дают локальность
в B-tree индексах (меньше фрагментации страниц для PK). Validate/IsV7
проверяют строку из внешнего мира. Без зависимостей сверх google/uuid и без I/O.
Импорт
import "git.stit.tech/stit-core/golibinfra/idkit"
Версия и go get — см. корневой README § Использование в проекте.
Быстрый старт
id := idkit.NewV7() // "0190e8a1-1c2d-7e3f-8a4b-5c6d7e8f9a0b"
// Как production-seam для конструктора, принимающего IDGen func() string:
mirror, err := domain.NewEntity(accountID, snap, idkit.NewV7)
// Валидация id, пришедшего из запроса/события:
if err := idkit.Validate(req.EntityID); err != nil {
return fmt.Errorf("entity_id: %w", err)
}
Observability
Кит ничего не эмитит: ни метрик, ни спанов, ни логов.
API
func NewV7() string
func Validate(s string) error
func IsV7(s string) bool
var ErrInvalid = errors.New("idkit: invalid uuid")
| Символ |
Роль |
NewV7() |
Новый id: канонический UUID v7 строкой |
Validate(s) |
nil, если s — канонический UUID (любой версии); иначе ошибка, обёрнутая ErrInvalid |
IsV7(s) |
true, если s — канонический UUID версии 7 с вариантом RFC 4122, т.е. мог быть выдан NewV7 |
ErrInvalid |
Sentinel для errors.Is(err, idkit.ErrInvalid) |
Канонический вид — ровно 36 символов, hex в нижнем регистре, группы
8-4-4-4-12 через дефисы. uuid.Parse из google/uuid шире: он принимает ещё
URN-форму, фигурные скобки, 32 hex без дефисов и верхний регистр. Validate
такие формы отвергает: у сервисов stit id хранится и передаётся ровно в том
виде, в каком его отдал NewV7, поэтому «почти правильный» id — ошибка входа, а
не значение для нормализации.
Инварианты и подводные камни
- В пределах процесса id строго возрастают.
google/uuid держит под
глобальным мьютексом последнее выданное значение (unix_ms << 12 | seq) и
гарантирует, что следующее строго больше: 12 бит rand_a — не случайность, а
sub-ms счётчик (доли наносекунд, при совпадении или откате часов —
инкремент). Поэтому лексикографический порядок строк, выданных одним
процессом, совпадает с порядком вызовов — в том числе внутри одной
миллисекунды.
- Между процессами и узлами порядок только по миллисекундам. Счётчик
локален для процесса, а id из разных процессов в пределах одной мс могут
расходиться с реальным порядком событий; при расхождении системных часов —
на величину расхождения.
ORDER BY id — про порядок вставки, а не про
глобальную истину времени.
- Паника при отказе
crypto/rand. NewV7 оборачивает uuid.NewV7 в Must:
ошибка генератора случайности — невосстановимое состояние процесса, не business-кейс.
Поэтому сигнатура — func() string, удобная как seam без проверки ошибки.
- Только v7. Нужен v4/иной — бери
google/uuid напрямую; idkit намеренно
узкий (один производственный выбор id для сервисов stit).
Validate не проверяет версию. Это проверка формата; «это именно наш
id-формат» — IsV7.