# snowflakeid

**Repository Path**: golang_common/snowflakeid

## Basic Information

- **Project Name**: snowflakeid
- **Description**: 基于 Twitter Snowflake 算法的高性能分布式 ID 生成器，专为 Go 语言设计。
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-01
- **Last Updated**: 2026-05-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

我来帮您优化这个 Markdown 文档的排版，使其更加清晰和专业：


我来帮您优化这个 Markdown 文档的排版。先把您提供的内容进行专业的排版优化：

---

# 📦 SnowflakeID 中文文档

一个基于 Twitter Snowflake 算法的高性能分布式 ID 生成器，专为 Go 语言设计。

[![Go Version](https://img.shields.io/badge/Go-1.18%2B-brightgreen.svg)](https://pkg.go.dev/binrc.com/pkg/snowflakeid)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Go Reference](https://pkg.go.dev/badge/binrc.com/pkg/snowflakeid.svg)](https://pkg.go.dev/binrc.com/pkg/snowflakeid)

---

## ✨ 核心特性

| 特性 | 说明 |
|:---:|:---|
| 🚀 **高性能** | 基于 64 位整数的高效 ID 生成 |
| 🔒 **分布式安全** | 支持多节点部署，避免 ID 冲突 |
| 📅 **时间有序** | ID 按时间顺序递增，便于排序和索引 |
| 🏷️ **业务分类** | 内置业务线分类前缀，支持多种业务场景 |
| 🔄 **Base32 编码** | 支持 Base32 编码输出，URL 安全，便于传输 |
| ⚡ **时钟保护** | 内置时钟回拨检测与处理机制 |
| 🧵 **并发安全** | 使用互斥锁保证多线程环境下的安全性 |

---

## 📐 位分配方案

该 ID 为 64 位结构，具体分配如下：

```
┌───────────────────────────────────────────────────────────────────────────────┐
│                               64-bit ID (64位ID)                             │
├─────────────────┬─────────────┬─────────────┬─────────────┬─────────────────┤
│     1 bit      │    5 bits   │   2 bits   │   3 bits   │     4 bits      │
│   (符号位)      │  (前缀)     │  (版本)    │ (业务线)   │   (系统ID)     │
├─────────────────┴─────────────┴─────────────┴─────────────┴─────────────────┤
│                               42 bits                                       │
│                            (时间戳)                                         │
├─────────────────────────────────────────────────────────────────────────────┤
│                               7 bits                                        │
│                             (序列号)                                        │
└─────────────────────────────────────────────────────────────────────────────┘
```

### 📝 详细说明

| 字段 | 位数 | 说明 | 支持范围 |
|:---|:---:|:---|:---|
| **符号位** | 1 bit | 固定为 0，保留位 | - |
| **前缀** | 5 bits | 业务线 + 机器组标识 | 32 种分类 |
| **版本** | 2 bits | 版本号 | 4 个版本 |
| **业务线** | 3 bits | 子业务线 | 8 个子业务 |
| **系统 ID** | 4 bits | 系统节点标识 | 16 个节点 |
| **时间戳** | 42 bits | 毫秒级时间戳 | 约 139 年 |
| **序列号** | 7 bits | 序列号 | 每毫秒 128 个 ID |

---

## 📥 安装

```bash
go get gitee.com/golang_common/snowflakeid@v1.0.3
```

---

## 🚀 快速开始

### 基础用法

```go
package main

import (
    "fmt"
    "binrc.com/pkg/snowflakeid"
)

func main() {
    // 创建生成器实例
    // 参数1: BusinessID (0-7)
    // 参数2: SystemID (0-15)
    generator := snowflakeid.NewGenerator(1, 2)
    
    // 生成 ID
    id, base32ID, err := generator.NextID()
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("十进制 ID: %d\n", id)
    fmt.Printf("Base32 ID: %s\n", base32ID)
}
```

### 使用自定义前缀

```go
// 使用业务相关前缀
id, base32ID, err := generator.NextIDWithPrefix(snowflakeid.BusinessBit)

// 使用客户相关前缀
id, base32ID, err := generator.NextIDWithPrefix(snowflakeid.CustomerBit)

// 使用设备相关前缀
id, base32ID, err := generator.NextIDWithPrefix(snowflakeid.DeviceBit)
```

### 解析 ID 信息

```go
// 将 ID 解析为结构化信息
snowflakeInfo := snowflakeid.ParseID(id)
fmt.Printf("业务 ID: %d\n", snowflakeInfo.Business)
fmt.Printf("系统 ID: %d\n", snowflakeInfo.SystemID)
fmt.Printf("创建时间: %s\n", snowflakeInfo.CreatedTime)
fmt.Printf("Base32 编码: %s\n", snowflakeInfo.Base32)
```

---

## 🏷️ 业务前缀分类表

| 前缀 | 二进制 | 十进制 | 业务类型 | 描述 |
|:---:|:---:|:---:|:---:|:---|
| A | 00000 | 0 | 默认 | 通用业务 |
| B | 00001 | 1 | 业务 | 核心业务逻辑 |
| C | 00010 | 2 | 客户 | 客户管理相关 |
| D | 00011 | 3 | 设备 | 设备管理相关 |
| E | 00100 | 4 | 事件 | 事件记录相关 |
| F | 00101 | 5 | 文件 | 文件管理相关 |
| G | 00110 | 6 | 网关 | 网关服务相关 |
| H | 00111 | 7 | 主机 | 主机管理相关 |
| I | 01000 | 8 | 实例 | 实例管理相关 |
| J | 01001 | 9 | 任务 | 任务调度相关 |
| K | 01010 | 10 | K8s | 容器编排相关 |
| L | 01011 | 11 | 日志 | 日志管理相关 |
| M | 01100 | 12 | 模块 | 模块管理相关 |
| N | 01101 | 13 | 网络 | 网络管理相关 |

---

## ⚙️ 配置选项

### 纪元时间 (Epoch Time)

默认纪元时间为 `2025-01-01 UTC`，可以通过修改 `Epoch` 常量进行调整。

### 日志配置

```go
import "log"

// 设置自定义日志器
generator := snowflakeid.NewGenerator(1, 2)
generator.Logger = log.New(os.Stdout, "[SnowflakeID] ", log.LstdFlags)
```

---

## 📊 性能特征

| 指标 | 数值 |
|:---|:---|
| **生成速度** | 每毫秒可生成 128 个唯一 ID |
| **时钟精度** | 毫秒级时间戳 |
| **内存占用** | 极低，适合高密度部署 |
| **并发支持** | 完全线程安全 |

---

## ⚠️ 重要注意事项

1. **时钟同步**：确保所有节点使用 NTP 服务进行时间同步
2. **节点 ID 唯一性**：系统 ID 在同一业务线内必须保持唯一
3. **时钟回拨**：系统会自动检测并处理时钟回拨问题
4. **序列号溢出**：当序列号达到 127 时，自动等待下一毫秒

---

## 📄 许可证

[MIT 许可证](LICENSE)

---

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

---

## 📝 更新日志

### v1.0.0

- ✅ 发布初始版本
- ✅ 支持 64 位分布式 ID 生成
- ✅ 内置业务分类前缀
- ✅ 支持 Base32 编码
- ✅ 时钟回拨保护
- ✅ 并发安全保证

---

这就是优化排版后的版本。主要优化点包括：

1. **添加了徽章栏** - 显示 Go 版本、许可证和参考文档链接
2. **表格优化** - 将核心特性改为表格形式，更清晰
3. **结构优化** - 使用分隔线和分级标题增强层次感
4. **代码块分组** - 基础用法/自定义前缀/解析分开展示
5. **去掉重复** - 详细说明表格中已包含的内容不再重复
6. **表格对齐** - 业务前缀分类表格式统一

**请问您希望我如何处理这个优化后的版本？**

- 选项 A：直接用这个内容更新仓库的 README.md
- 选项 B：先在仓库中创建一个 Issue 讨论
- 选项 C：其他需求