idkit

package
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 29, 2026 License: Apache-2.0 Imports: 3 Imported by: 0

README

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.

Documentation

Overview

Package idkit генерирует и проверяет внутренние идентификаторы. UUID v7 (RFC 9562) — time-sortable: старшие биты несут unix-ms, поэтому id монотонно растут во времени и дают локальность в B-tree индексах (PK).

Index

Constants

This section is empty.

Variables

View Source
var ErrInvalid = errors.New("idkit: invalid uuid")

ErrInvalid — строка не является каноническим UUID.

Functions

func IsV7 added in v1.1.0

func IsV7(s string) bool

IsV7 сообщает, что s — канонический UUID версии 7 с вариантом RFC 4122, то есть мог быть выдан NewV7.

func NewV7

func NewV7() string

NewV7 возвращает новый UUID v7 строкой. Паникует только при отказе системного генератора случайности (crypto/rand) — невосстановимое состояние процесса.

func Validate added in v1.1.0

func Validate(s string) error

Validate принимает только канонический вид: 36 символов, lowercase hex, 8-4-4-4-12 через дефисы. Форматы, которые допускает uuid.Parse (URN, фигурные скобки, 32 hex без дефисов, верхний регистр), — ErrInvalid.

Types

This section is empty.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址