snowflake

package module
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Sep 8, 2020 License: BSD-2-Clause Imports: 7 Imported by: 0

README

snowflake - 短ID版本; 53bits

GoDoc Go report Build Status Discord Gophers

Go语言版snowflake ID生成器,原项目参考bwmarrin/snowflake。

本项目是snowflake的short版本,

  • 生成更短的id (15-16位) 用作用户ID使用更合适
  • 生成的ID长度为53bits便于在js上发生交互(js处理超过53bits的整数会失去精度,通常做法是转换为字符串后交给js处理,但是本项目生成的ID天然支持js不需要额外处理)
  • 可以解析snowflake IDs.
  • 可以将snowflake ID转换为其他数据类型.
  • 提供Marshal/Unmarshal方法,用于JSON API.

本项目在原项目基础上调整了二处

  1. Epoch设置为2017-06-28 09:10对应的时间戳
  2. 39位时间戳10ms级,6位节点,8位自增
ID格式
  • ID共使用53bits,兼顾前端js精度问题,可使用170年时间
  • 39 位秒级精度用于存储时间戳, 使用自定义纪元时间.
  • 6 位用来存储节点ID - 范围从 0 到 64.
  • 8 位用来存储自增序列号 - 范围 0 到 256.
自定义开始时间

默认时间开始于 1498612200000(2017-06-28 09:10:00). Twitter 默认的开始时间是 1288834974657 (2010-11-04 01:42:54).

注意事项

如需设置自定义时间纪元或者自定义位数时,必须先设置好,才能使用,否则在使用过程中修改会产生错误

工作原理
  • 使用39位存储时间, 精度为10ms, 即10ms为一个单位。
  • 然后将节点id添加到后续的位中。
  • 然后添加序列号,从0开始,每隔10ms内生成的每个ID递增。如果在同一个时间内生成的id足够多,为防止序列发生翻转或溢出,则生成函数将暂停到下一个10ms。

snowflake short 默认格式如下.

+--------------------------------------------------------------------------+
| 11 Bit Unused | 39 Bit Timestamp |  6 Bit NodeID  |   8 Bit Sequence ID |
+--------------------------------------------------------------------------+

默认设置每个节点每秒可产生25600个ID,最多可以设置64个节点服务器 新浪微博高峰期每秒发送微博数32000个(2012年数据)

本人实测自用笔记本 MacBook Pro 2013(i5 2.4 GHz 8 GB) 高峰期大概每毫秒产生127个ID,远小于4096 (2019年1月数据)

开始使用

安装

需要先安装GoLang的运行环境, 如果没有请移步这里.

go get github.com/zlabwork/snowflake
Usage

导入包,然后通过赋值一个唯一的节点标识构造一个节点Node,默认的节点唯一标识范围0-1023(即10 bits)。如果修改了节点标识位数则对应节点标识范围也应该响应调整。使用Generate()方法生成唯一的snowflake ID

您创建的每个节点都必须有唯一的节点编号,如果不保持节点编号唯一,则不能保证所有节点生成的ID唯一。

实力程序:

package main

import (
	"fmt"
	"github.com/zlabwork/snowflake"
)

func main() {

	// 创建一个节点并设置节点ID=1
	node, err := snowflake.NewNode(1)
	if err != nil {
		fmt.Println(err)
		return
	}

	// 生成一个snowflake ID.
	id := node.Generate()

	// 不同的集中方式输出ID
	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())

	// 打印ID的时间戳
	fmt.Printf("ID Time  : %d\n", id.Time())

	// 打印ID的节点
	fmt.Printf("ID Node  : %d\n", id.Node())

	// 打印ID的序列号
	fmt.Printf("ID Step  : %d\n", id.Step())

	// 生成ID并打印
	fmt.Printf("ID       : %d\n", node.Generate().Int64())
}

Documentation

Overview

Package snowflake provides a very simple Twitter snowflake generator and parser.

Index

Constants

This section is empty.

Variables

View Source
var (
	// Epoch is set to the twitter snowflake epoch of Nov 04 2010 01:42:54 UTC in milliseconds
	// You may customize this to set a different epoch for your application.
	Epoch int64 = 1498612200000

	// NodeBits holds the number of bits to use for Node
	// Remember, you have a total 14 bits to share between Node/Step
	NodeBits uint8 = 6

	// StepBits holds the number of bits to use for Step
	// Remember, you have a total 14 bits to share between Node/Step
	StepBits uint8 = 8
)
View Source
var ErrInvalidBase32 = errors.New("invalid base32")

ErrInvalidBase32 is returned by ParseBase32 when given an invalid []byte

View Source
var ErrInvalidBase58 = errors.New("invalid base58")

ErrInvalidBase58 is returned by ParseBase58 when given an invalid []byte

Functions

This section is empty.

Types

type ID

type ID int64

An ID is a custom type used for a snowflake ID. This is used so we can attach methods onto the ID.

func ParseBase2

func ParseBase2(id string) (ID, error)

ParseBase2 converts a Base2 string into a snowflake ID

func ParseBase32

func ParseBase32(b []byte) (ID, error)

ParseBase32 parses a base32 []byte into a snowflake ID NOTE: There are many different base32 implementations so becareful when doing any interoperation.

func ParseBase36

func ParseBase36(id string) (ID, error)

ParseBase36 converts a Base36 string into a snowflake ID

func ParseBase58

func ParseBase58(b []byte) (ID, error)

ParseBase58 parses a base58 []byte into a snowflake ID

func ParseBase64

func ParseBase64(id string) (ID, error)

ParseBase64 converts a base64 string into a snowflake ID

func ParseBytes

func ParseBytes(id []byte) (ID, error)

ParseBytes converts a byte slice into a snowflake ID

func ParseInt64

func ParseInt64(id int64) ID

ParseInt64 converts an int64 into a snowflake ID

func ParseIntBytes

func ParseIntBytes(id [8]byte) ID

ParseIntBytes converts an array of bytes encoded as big endian integer as a snowflake ID

func ParseString

func ParseString(id string) (ID, error)

ParseString converts a string into a snowflake ID

func (ID) Base2

func (f ID) Base2() string

Base2 returns a string base2 of the snowflake ID

func (ID) Base32

func (f ID) Base32() string

Base32 uses the z-base-32 character set but encodes and decodes similar to base58, allowing it to create an even smaller result string. NOTE: There are many different base32 implementations so becareful when doing any interoperation.

func (ID) Base36

func (f ID) Base36() string

Base36 returns a base36 string of the snowflake ID

func (ID) Base58

func (f ID) Base58() string

Base58 returns a base58 string of the snowflake ID

func (ID) Base64

func (f ID) Base64() string

Base64 returns a base64 string of the snowflake ID

func (ID) Bytes

func (f ID) Bytes() []byte

Bytes returns a byte slice of the snowflake ID

func (ID) Int64

func (f ID) Int64() int64

Int64 returns an int64 of the snowflake ID

func (ID) IntBytes

func (f ID) IntBytes() [8]byte

IntBytes returns an array of bytes of the snowflake ID, encoded as a big endian integer.

func (ID) MarshalJSON

func (f ID) MarshalJSON() ([]byte, error)

MarshalJSON returns a json byte array string of the snowflake ID.

func (ID) Node

func (f ID) Node() int64

Node returns an int64 of the snowflake ID node number DEPRECATED: the below function will be removed in a future release.

func (ID) Step

func (f ID) Step() int64

Step returns an int64 of the snowflake step (or sequence) number DEPRECATED: the below function will be removed in a future release.

func (ID) String

func (f ID) String() string

String returns a string of the snowflake ID

func (ID) Time

func (f ID) Time() int64

Time returns an int64 unix timestamp in milliseconds of the snowflake ID time DEPRECATED: the below function will be removed in a future release.

func (*ID) UnmarshalJSON

func (f *ID) UnmarshalJSON(b []byte) error

UnmarshalJSON converts a json byte array of a snowflake ID into an ID type.

type JSONSyntaxError

type JSONSyntaxError struct {
	// contains filtered or unexported fields
}

A JSONSyntaxError is returned from UnmarshalJSON if an invalid ID is provided.

func (JSONSyntaxError) Error

func (j JSONSyntaxError) Error() string

type Node

type Node struct {
	// contains filtered or unexported fields
}

A Node struct holds the basic information needed for a snowflake generator node

func NewNode

func NewNode(node int64) (*Node, error)

NewNode returns a new snowflake node that can be used to generate snowflake IDs

func (*Node) Generate

func (n *Node) Generate() ID

Generate creates and returns a unique snowflake ID To help guarantee uniqueness - Make sure your system is keeping accurate system time - Make sure you never have multiple nodes running with the same node ID

Jump to

Keyboard shortcuts

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