{"id":13396824,"url":"https://github.com/bwmarrin/snowflake","last_synced_at":"2025-05-12T13:18:54.438Z","repository":{"id":8768791,"uuid":"59693338","full_name":"bwmarrin/snowflake","owner":"bwmarrin","description":"A simple to use Go (golang) package to generate or parse Twitter snowflake IDs","archived":false,"fork":false,"pushed_at":"2024-07-25T16:28:11.000Z","size":51,"stargazers_count":3166,"open_issues_count":16,"forks_count":381,"subscribers_count":27,"default_branch":"master","last_synced_at":"2025-05-12T13:18:43.061Z","etag":null,"topics":["go","golang","snowflake"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bwmarrin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-05-25T19:55:49.000Z","updated_at":"2025-05-11T16:16:45.000Z","dependencies_parsed_at":"2024-01-06T13:56:08.457Z","dependency_job_id":"eadf6f76-f26e-4f90-aa4d-92584b3cb797","html_url":"https://github.com/bwmarrin/snowflake","commit_stats":{"total_commits":84,"total_committers":10,"mean_commits":8.4,"dds":0.3214285714285714,"last_synced_commit":"bc74ab286f15f6c73896cb40ad39c502263c7af3"},"previous_names":["bwmarrin/flake"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bwmarrin%2Fsnowflake","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bwmarrin%2Fsnowflake/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bwmarrin%2Fsnowflake/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bwmarrin%2Fsnowflake/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bwmarrin","download_url":"https://codeload.github.com/bwmarrin/snowflake/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253745196,"owners_count":21957319,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","golang","snowflake"],"created_at":"2024-07-30T18:01:03.919Z","updated_at":"2025-05-12T13:18:54.350Z","avatar_url":"https://github.com/bwmarrin.png","language":"Go","readme":"snowflake\n====\n[![GoDoc](https://godoc.org/github.com/bwmarrin/snowflake?status.svg)](https://godoc.org/github.com/bwmarrin/snowflake) [![Go report](http://goreportcard.com/badge/bwmarrin/snowflake)](http://goreportcard.com/report/bwmarrin/snowflake) [![Coverage](http://gocover.io/_badge/github.com/bwmarrin/snowflake)](https://gocover.io/github.com/bwmarrin/snowflake) [![Build Status](https://travis-ci.org/bwmarrin/snowflake.svg?branch=master)](https://travis-ci.org/bwmarrin/snowflake) [![Discord Gophers](https://img.shields.io/badge/Discord%20Gophers-%23info-blue.svg)](https://discord.gg/0f1SbxBZjYq9jLBk)\n\nsnowflake is a [Go](https://golang.org/) package that provides\n* A very simple Twitter snowflake generator.\n* Methods to parse existing snowflake IDs.\n* Methods to convert a snowflake ID into several other data types and back.\n* JSON Marshal/Unmarshal functions to easily use snowflake IDs within a JSON API.\n* Monotonic Clock calculations protect from clock drift.\n\n**For help with this package or general Go discussion, please join the [Discord \nGophers](https://discord.gg/0f1SbxBZjYq9jLBk) chat server.**\n\n## Status\nThis package should be considered stable and completed.  Any additions in the \nfuture will strongly avoid API changes to existing functions. \n  \n### ID Format\nBy default, the ID format follows the original Twitter snowflake format.\n* The ID as a whole is a 63 bit integer stored in an int64\n* 41 bits are used to store a timestamp with millisecond precision, using a custom epoch.\n* 10 bits are used to store a node id - a range from 0 through 1023.\n* 12 bits are used to store a sequence number - a range from 0 through 4095.\n\n### Custom Format\nYou can alter the number of bits used for the node id and step number (sequence)\nby setting the snowflake.NodeBits and snowflake.StepBits values.  Remember that\nThere is a maximum of 22 bits available that can be shared between these two \nvalues. You do not have to use all 22 bits.\n\n### Custom Epoch\nBy default this package uses the Twitter Epoch of 1288834974657 or Nov 04 2010 01:42:54.\nYou can set your own epoch value by setting snowflake.Epoch to a time in milliseconds\nto use as the epoch.\n\n### Custom Notes\nWhen setting custom epoch or bit values you need to set them prior to calling\nany functions on the snowflake package, including NewNode().  Otherwise the\ncustom values you set will not be applied correctly.\n\n### How it Works.\nEach time you generate an ID, it works, like this.\n* A timestamp with millisecond precision is stored using 41 bits of the ID.\n* Then the NodeID is added in subsequent bits.\n* Then the Sequence Number is added, starting at 0 and incrementing for each ID generated in the same millisecond. If you generate enough IDs in the same millisecond that the sequence would roll over or overfill then the generate function will pause until the next millisecond.\n\nThe default Twitter format shown below.\n```\n+--------------------------------------------------------------------------+\n| 1 Bit Unused | 41 Bit Timestamp |  10 Bit NodeID  |   12 Bit Sequence ID |\n+--------------------------------------------------------------------------+\n```\n\nUsing the default settings, this allows for 4096 unique IDs to be generated every millisecond, per Node ID.\n## Getting Started\n\n### Installing\n\nThis assumes you already have a working Go environment, if not please see\n[this page](https://golang.org/doc/install) first.\n\n```sh\ngo get github.com/bwmarrin/snowflake\n```\n\n\n### Usage\n\nImport the package into your project then construct a new snowflake Node using a\nunique node number. The default settings permit a node number range from 0 to 1023.\nIf you have set a custom NodeBits value, you will need to calculate what your \nnode number range will be. With the node object call the Generate() method to \ngenerate and return a unique snowflake ID. \n\nKeep in mind that each node you create must have a unique node number, even \nacross multiple servers.  If you do not keep node numbers unique the generator \ncannot guarantee unique IDs across all nodes.\n\n\n**Example Program:**\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\n\t\"github.com/bwmarrin/snowflake\"\n)\n\nfunc main() {\n\n\t// Create a new Node with a Node number of 1\n\tnode, err := snowflake.NewNode(1)\n\tif err != nil {\n\t\tfmt.Println(err)\n\t\treturn\n\t}\n\n\t// Generate a snowflake ID.\n\tid := node.Generate()\n\n\t// Print out the ID in a few different ways.\n\tfmt.Printf(\"Int64  ID: %d\\n\", id)\n\tfmt.Printf(\"String ID: %s\\n\", id)\n\tfmt.Printf(\"Base2  ID: %s\\n\", id.Base2())\n\tfmt.Printf(\"Base64 ID: %s\\n\", id.Base64())\n\n\t// Print out the ID's timestamp\n\tfmt.Printf(\"ID Time  : %d\\n\", id.Time())\n\n\t// Print out the ID's node number\n\tfmt.Printf(\"ID Node  : %d\\n\", id.Node())\n\n\t// Print out the ID's sequence number\n\tfmt.Printf(\"ID Step  : %d\\n\", id.Step())\n\n  // Generate and print, all in one.\n  fmt.Printf(\"ID       : %d\\n\", node.Generate().Int64())\n}\n```\n\n### Performance\n\nWith default settings, this snowflake generator should be sufficiently fast \nenough on most systems to generate 4096 unique ID's per millisecond. This is \nthe maximum that the snowflake ID format supports. That is, around 243-244 \nnanoseconds per operation. \n\nSince the snowflake generator is single threaded the primary limitation will be\nthe maximum speed of a single processor on your system.\n\nTo benchmark the generator on your system run the following command inside the\nsnowflake package directory.\n\n```sh\ngo test -run=^$ -bench=.\n```\n\nIf your curious, check out this commit that shows benchmarks that compare a few \ndifferent ways of implementing a snowflake generator in Go.\n*  https://github.com/bwmarrin/snowflake/tree/9befef8908df13f4102ed21f42b083dd862b5036\n","funding_links":[],"categories":["Library","Go","开源类库","Open source library","Repositories"],"sub_categories":["UUID"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbwmarrin%2Fsnowflake","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbwmarrin%2Fsnowflake","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbwmarrin%2Fsnowflake/lists"}