Снежинка

Формат идентификатора

Snowflake — это распределённый генератор уникальных идентификаторов, вдохновлённый Twitter's Snowflake.

По умолчанию идентификатор Snowflake состоит из:

• Идентификатор в целом представляет собой 63-битное целое число, хранящееся в int64.
• 43 бита используются для хранения метки времени с точностью до миллисекунды, используя пользовательскую эпоху. По умолчанию это 61026175693 (UTC 1971-12-08 15:42:55.693). Срок службы (278 лет) больше, чем у Twitter's Snowflake (69 лет).
• 10 бит используются для хранения идентификатора узла — диапазон от 0 до 1023.
• 10 битов используются для хранения порядкового номера — диапазон от 0 до 1023.

Пользовательский формат

Вы можете изменить количество битов, используемых для идентификатора узла и порядкового номера (последовательности), с помощью функций NodeBits(nodeBits uint8) и SeqBits(seqBits uint8), значения которых являются параметрами функции. Помните, что доступно максимум 22 бита, которые можно разделить между этими двумя значениями. Вы не обязаны использовать все 22 бита.

New(NodeBits(16),SeqBits(6))

Пользовательское время начала

По умолчанию этот пакет использует Twitter Epoch 61026175693(UTC 1971-12-08 15:42:55.693). Вы можете установить собственное значение эпохи с помощью функции StartTime(startTime int64).

Как это работает

Каждый раз, когда вы генерируете идентификатор, он работает следующим образом.

• Метка времени с миллисекундной точностью сохраняется с использованием 43 бит идентификатора.
• Затем добавляется идентификатор узла.
• Затем добавляется порядковый номер, начиная с 0 и увеличиваясь для каждого идентификатора, сгенерированного за одну и ту же миллисекунду. Если вы сгенерируете достаточно идентификаторов за одну миллисекунду, чтобы порядковый номер перевернулся или переполнился, функция генерации приостановится до следующей миллисекунды.

Формат по умолчанию показан ниже.

+--------------------------------------------------------------------------+
| 1 Бит Не используется | 43 Бит Метка времени |  10 Бит Идентификатор узла |   10 Бит Порядковый номер |
+--------------------------------------------------------------------------+

При использовании настроек по умолчанию это позволяет генерировать 1024 уникальных идентификатора каждую миллисекунду для каждого идентификатора узла.

Начало работы

Установка

Предполагается, что у вас уже есть работающая среда Go, если нет, пожалуйста, сначала обратитесь к этой странице.

go get github.com/teamlint/snowflake

Использование

Импортируйте пакет в свой проект, затем создайте новый узел Snowflake, используя уникальный номер узла. Настройки по умолчанию позволяют использовать диапазон номеров узлов от 0 до 1023. Если вы установили пользовательское значение NodeBits, вам нужно будет рассчитать, каким будет ваш диапазон номеров узлов. С помощью объекта узла вызовите метод ID(), чтобы сгенерировать и вернуть уникальный идентификатор Snowflake.

Имейте в виду, что каждый создаваемый вами узел должен иметь уникальный номер узла, даже на нескольких серверах. Если вы не сохраняете номера узлов уникальными, генератор не может гарантировать уникальные идентификаторы на всех узлах.

Функция New создаёт новый экземпляр Snowflake.

func New(opts ...Option) (*Snowflake, error)

Настроить Snowflake можно с помощью функции Option:

Тип функции Option:

type Option func(*Options)

type Options struct {
    startTime int64 // Время начала
    node      int64 // Идентификатор узла, 0 - 1023, по умолчанию 0, предпочтительно использовать переменную среды SNOWFLAKE_NODE, затем использовать частный IP-адрес для маскировки идентификатора узла

    timeBits uint8 // Биты времени, по умолчанию 43 бита
    nodeBits uint8 // Биты узла, по умолчанию 10 бит
    seqBits  uint8 // Увеличивающиеся последовательные биты, по умолчанию 10 бит
}

Предоставленные функции Option следующие:

• Опция узла func Node(node int64) Option
• Опция времени начала func StartTime(startTime int64) Option
• Вариант битов узла func NodeBits(nodeBits uint8) Option
• Вариант последовательных битов func SeqBits(seqBits uint8) Option
• Подробный вариант func Verbose() Option

Чтобы получить новый уникальный идентификатор, просто вызовите метод ID.

func (sf *Snowflake) ID() ID

Пример программы:

package main

import (
    "fmt"

    "github.com/teamlint/snowflake"
)

func main() {
  opts := []Option{Verbose(), NodeBits(8), StartTime(1314220021721)}
    sf, err := snowflake.New(opts...)
    if err != nil {
        fmt.Println(err)
        return
    }

    // Generate a

...
``` ```
snowflake ID.
    id := sf.ID()

    // Print out the ID in a few different ways.
    fmt.Printf("Int64  ID: %d\n", id)
    fmt.Printf("String ID: %s\n", id)
    fmt.Printf("Base2  ID: %s\n", id.Base2())
    fmt.Printf("Base64 ID: %s\n", id.Base64())

    // Print out the ID's timestamp
    fmt.Printf("ID Time  : %d\n", id.Time(opts...))

    // Print out the ID's node number
    fmt.Printf("ID Node  : %d\n", id.Node(opts...))

    // Print out the ID's sequence number
    fmt.Printf("ID Step  : %d\n", id.Seq(opts...))

  // Generate and print, all in one.
  fmt.Printf("ID       : %d\n", sf.ID().Int64())
}

Performance

С настройками по умолчанию этот генератор snowflake должен быть достаточно быстрым на большинстве систем для генерации 1024 уникальных идентификаторов в миллисекунду. Это максимум, который поддерживает формат идентификатора snowflake, то есть около 110-112 наносекунд за операцию.

Поскольку генератор snowflake однопоточный, основным ограничением будет максимальная скорость одного процессора в вашей системе.

Чтобы провести тестирование генератора на вашей системе, выполните следующую команду внутри каталога пакета snowflake.

$ go test -run=none -bench=.