Skip to content

Commit

Permalink
docs: modify readme
Browse files Browse the repository at this point in the history
  • Loading branch information
houseme committed Sep 4, 2024
1 parent 050b545 commit 7cf0c9c
Showing 1 changed file with 31 additions and 31 deletions.
62 changes: 31 additions & 31 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,19 +11,19 @@
[![Production Ready](https://img.shields.io/badge/production-ready-blue.svg)](https://github.com/housemecn/snowflake)
[![License](https://img.shields.io/github/license/housemecn/snowflake.svg?style=flat)](https://github.com/housemecn/snowflake)

## Snowflake简介
## Snowflake 简介

在单机系统中我们会使用自增id作为数据的唯一id,自增id在数据库中有利于排序和索引,但是在分布式系统中如果还是利用数据库的自增id会引起冲突,自增id非常容易被爬虫爬取数据。在分布式系统中有使用uuid作为数据唯一id的,但是uuid是一串随机字符串,所以它无法被排序。
在单机系统中我们会使用自增 id 作为数据的唯一 id,自增 id 在数据库中有利于排序和索引,但是在分布式系统中如果还是利用数据库的自增 id 会引起冲突,自增 id 非常容易被爬虫爬取数据。在分布式系统中有使用 uuid 作为数据唯一 id 的,但是 uuid 是一串随机字符串,所以它无法被排序。

Twitter设计了Snowflake算法为分布式系统生成ID,Snowflake的id是int64类型,它通过datacenterId和workerId来标识分布式系统,下面看下它的组成:
Twitter 设计了 Snowflake 算法为分布式系统生成 ID,Snowflake 的 id 是 int64 类型,它通过 datacenterId 和 workerId 来标识分布式系统,下面看下它的组成:

| 1bit | 41bit | 5bit | 5bit | 12bit |
|---|---|---|---|---|
| 符号位(保留字段) | 时间戳(当前时间-纪元时间) | 数据中心id | 机器id | 自增序列
| 1bit | 41bit | 5bit | 5bit | 12bit |
|-----------|-------------------|---------|-------|-------|
| 符号位(保留字段) | 时间戳 (当前时间 - 纪元时间) | 数据中心 id | 机器 id | 自增序列 |

### 算法简介

在使用Snowflake生成id时,首先会计算时间戳timestamp(当前时间 - 纪元时间),如果timestamp数据超过41bit则异常。同样需要判断datacenterId和workerId不能超过5bit(0-31),在处理自增序列时,如果发现自增序列超过12bit时需要等待,因为当前毫秒下12bit的自增序列被用尽,需要进入下一毫秒后自增序列继续从0开始递增
在使用 Snowflake 生成 id 时,首先会计算时间戳 timestamp(当前时间 - 纪元时间),如果 timestamp 数据超过 41bit 则异常。同样需要判断 datacenterId 和 workerId 不能超过 5bit(0-31),在处理自增序列时,如果发现自增序列超过 12bit 时需要等待,因为当前毫秒下 12bit 的自增序列被用尽,需要进入下一毫秒后自增序列继续从 0 开始递增

---

Expand All @@ -49,7 +49,7 @@ import "github.com/houseme/snowflake"

### ⚠️注意事项

* 在多实例(多个snowflake对象)的并发环境下,请确保每个实例(datacenterId,workerId)的唯一性,否则生成的ID可能冲突
* 在多实例(多个 snowflake 对象)的并发环境下,请确保每个实例(datacenterId,workerId)的唯一性,否则生成的 ID 可能冲突

### 📊 测试

Expand Down Expand Up @@ -79,7 +79,7 @@ func TestLoad() {
defer wg.Done()
val := s.NextVal()
if _, ok := check.Load(val); ok {
// id冲突检查
// id 冲突检查
glog.Error(fmt.Errorf("error#unique: val:%v", val))
return
}
Expand All @@ -102,79 +102,79 @@ func TestLoad() {

## 🗂 使用说明

### 创建Snowflake对象
### 创建 Snowflake 对象

```go
// NewSnowflake(datacenterId, workerId int64) (*Snowflake, error)
// 参数1 (int64): 数据中心ID (可用范围:0-31)
// 参数2 (int64): 机器ID (可用范围:0-31)
// 返回1 (*Snowflake): Snowflake对象 | nil
// 返回2 (error): 错误码
// 参数 1 (int64): 数据中心 ID (可用范围:0-31)
// 参数 2 (int64): 机器 ID (可用范围:0-31)
// 返回 1 (*Snowflake): Snowflake 对象 | nil
// 返回 2 (error): 错误码
s, err := snowflake.NewSnowflake(int64(0), int64(0))
if err != nil {
glog.Error(err)
return
}
```

### 生成唯一ID
### 生成唯一 ID

```go
s, err := snowflake.NewSnowflake(int64(0), int64(0))
// ......
// (s *Snowflake) NextVal() int64
// 返回1 (int64): 唯一ID
// 返回 1 (int64): 唯一 ID
id := s.NextVal()
// ......
```

### 通过ID获取数据中心ID与机器ID
### 通过 ID 获取数据中心 ID 与机器 ID

```go
// ......
// GetDeviceID(sid int64) (datacenterId, workerId int64)
// 参数1 (int64): 唯一ID
// 返回1 (int64): 数据中心ID
// 返回2 (int64): 机器ID
// 参数 1 (int64): 唯一 ID
// 返回 1 (int64): 数据中心 ID
// 返回 2 (int64): 机器 ID
datacenterid, workerid := snowflake.GetDeviceID(id))
```

### 通过ID获取时间戳(创建ID时的时间戳 - epoch)
### 通过 ID 获取时间戳(创建 ID 时的时间戳 - epoch)

```go
// ......
// GetTimestamp(sid int64) (timestamp int64)
// 参数1 (int64): 唯一ID
// 返回1 (int64): 从epoch开始计算的时间戳
// 参数 1 (int64): 唯一 ID
// 返回 1 (int64): 从 epoch 开始计算的时间戳
t := snowflake.GetTimestamp(id)
```

### 通过ID获取生成ID时的时间戳
### 通过 ID 获取生成 ID 时的时间戳

```go
// ......
// GetGenTimestamp(sid int64) (timestamp int64)
// 参数1 (int64): 唯一ID
// 返回1 (int64): 唯一ID生成时的时间戳
// 参数 1 (int64): 唯一 ID
// 返回 1 (int64): 唯一 ID 生成时的时间戳
t := snowflake.GetGenTimestamp(id)
```

### 通过ID获取生成ID时的时间(精确到:秒)
### 通过 ID 获取生成 ID 时的时间(精确到:秒)

```go
// ......
// GetGenTime(sid int64)
// 参数1 (int64): 唯一ID
// 返回1 (string): 唯一ID生成时的时间
// 参数 1 (int64): 唯一 ID
// 返回 1 (string): 唯一 ID 生成时的时间
tStr := snowflake.GetGenTime(id)
```

### 查看时间戳字段使用占比(41bit能存储的范围:从epoch开始往后69年
### 查看时间戳字段使用占比(41bit 能存储的范围:从 epoch 开始往后 69 年

```go
// ......
// GetTimestampStatus() (state float64)
// 返回1 (float64): 时间戳字段使用占比(范围 0.0 - 1.0)
// 返回 1 (float64): 时间戳字段使用占比(范围 0.0 - 1.0)
status := snowflake.GetTimestampStatus()
```
### Performance
Expand Down

0 comments on commit 7cf0c9c

Please sign in to comment.