docs(readme): 更新功能列表描述，明确算法封装类型

- 为散列及校验和算法项添加“便捷封装”说明
- 添加 BLAKE2 和 BLAKE3 算法项（未实现）
- 修正冰雹 ID 生成器描述格式
- 补充 UUIDv7 生成器的详细说明

README.md

@@ -23,24 +23,30 @@ Golang 中可以使用的常用辅助功能工具箱。主要配备以下功能
     - [x] Key 导入与导出
   - [x] RSA 签名算法
 - 散列及校验和算法。
-  - [x] Sha512 散列算法
-  - [x] Sha256 散列算法
-  - [x] Sha1 散列算法
-  - [x] MD5 散列算法
-  - [x] CRC8 校验和算法
-  - [x] CRC16 校验和算法
-  - [x] CRC32 校验和算法
-  - [x] CRC64 校验和算法
-  - [x] pHash 图像感知算法
+  - [x] Sha512 散列算法（便捷封装）
+  - [x] Sha256 散列算法（便捷封装）
+  - [x] Sha1 散列算法（便捷封装）
+  - [x] MD5 散列算法（便捷封装）
+  - [x] CRC8 校验和算法（便捷封装）
+  - [x] CRC16 校验和算法（便捷封装）
+  - [x] CRC32 校验和算法（便捷封装）
+  - [x] CRC64 校验和算法（便捷封装）
+  - [x] pHash 图像感知算法（便捷封装）
+  - [ ] BLAKE2 校验和算法（便捷封装）
+  - [ ] BLAKE3 校验和算法（便捷封装）
   - [ ] BlockHash 散列算法
 - 唯一序列号生成器
-  - [x] 冰雹 ID 生成器(短主机精简日期版雪花 ID)
-  - [x] UUID 生成器
+  - [x] 冰雹 ID 生成器（短主机精简日期版雪花 ID）
+  - [x] UUIDv4 生成器
+  - [x] UUIDv7 生成器（自定义时间戳分布式版本）
+    - [x] UUIDv7 比较及排序
+    - [x] 基于 Base36 的 short UUIDv7 转换器
   - [x] short UUID 生成器
 - 验证码生成器
   - [x] 随机验证码生成算法
 - 序列化算法
   - [x] Base64 算法
+  - [x] Base36 算法
   - [x] Hex 直转
 - 常用工具函数
   - [ ] 日期时间函数

serial_code/hail/hail.go

@@ -10,17 +10,17 @@ import (
 )
 
 // 用于记录当前冰雹ID组成内容的数据结构
-type _HailAlgorithm struct {
+type HailAlgorithm struct {
 	hostSerial    int64
 	lastTimestamp int64
 	lastSequence  int64
 	lock          sync.Mutex
 }
 
-var hailAlgorithmInstance *_HailAlgorithm
+var hailAlgorithmInstance *HailAlgorithm
 
 // 获取当前已经完成初始化的冰雹ID生成算法实例，如果尚未完成初始化则会返回未初始化的错误。
-func Get() (*_HailAlgorithm, error) {
+func Get() (*HailAlgorithm, error) {
 	if hailAlgorithmInstance == nil {
 		return nil, &HailAlgorithmNotInitializedError{}
 	}
@@ -29,7 +29,7 @@ func Get() (*_HailAlgorithm, error) {
 
 // 指定一个主机编号，并完成冰雹ID生成算法的初始化。
 func Initialize(hostSerial int64) {
-	hailAlgorithmInstance = &_HailAlgorithm{
+	hailAlgorithmInstance = &HailAlgorithm{
 		hostSerial:    hostSerial,
 		lastTimestamp: types.Timestamp(),
 		lastSequence:  0,
@@ -38,7 +38,7 @@ func Initialize(hostSerial int64) {
 }
 
 // 返回一个可用的时间戳，如果主机发生了时间回拨，那么将等待一秒钟。
-func (h *_HailAlgorithm) timestamp() int64 {
+func (h *HailAlgorithm) timestamp() int64 {
 	for {
 		timestamp := types.Timestamp()
 		if timestamp == h.lastTimestamp {
@@ -54,7 +54,7 @@ func (h *_HailAlgorithm) timestamp() int64 {
 }
 
 // 生成一个冰雹ID。
-func (h *_HailAlgorithm) Generate() int64 {
+func (h *HailAlgorithm) Generate() int64 {
 	h.lock.Lock()
 	defer h.lock.Unlock()
 	timestamp := h.timestamp()
@@ -63,11 +63,11 @@ func (h *_HailAlgorithm) Generate() int64 {
 }
 
 // 生成一个冰雹ID，并将其转换为字符串。
-func (h *_HailAlgorithm) GenerateString() string {
+func (h *HailAlgorithm) GenerateString() string {
 	return fmt.Sprintf("%017d", h.Generate())
 }
 
 // 生成一个冰雹ID，将其转换为字符串并附加指定的前缀
-func (h *_HailAlgorithm) GeneratePrefixedString(prefix string) string {
+func (h *HailAlgorithm) GeneratePrefixedString(prefix string) string {
 	return fmt.Sprintf("%s%s", prefix, h.GenerateString())
 }

serial_code/uuidv7/errors.go

@@ -0,0 +1,13 @@
+package uuidv7
+
+type UUIDv7GeneratorNotInitializedError struct{}
+
+func (e *UUIDv7GeneratorNotInitializedError) Error() string {
+	return "UUIDv7生成器尚未初始化"
+}
+
+type UUIDv7NodeIDExceededError struct{}
+
+func (e *UUIDv7NodeIDExceededError) Error() string {
+	return "UUIDv7节点ID超出范围"
+}

serial_code/uuidv7/uuid.go

@@ -0,0 +1,258 @@
+package uuidv7
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"fmt"
+	"strings"
+	"sync"
+	"time"
+
+	"archgrid.xyz/ag/toolsbox/serialize/base36"
+	"archgrid.xyz/ag/toolsbox/serialize/base64"
+)
+
+const (
+	epoch          = 1645566142222 // 自定义纪元：2022-02-22 22:22:22.222 UTC
+	nodeBits       = 5             // 主机编号容量为0～32
+	sequenceBits   = 18            // 每毫秒生成序列号最大为2^18-1，即262144个
+	maxNodeID      = (1 << nodeBits) - 1
+	maxSequence    = (1 << sequenceBits) - 1
+	timestampShift = nodeBits + sequenceBits
+	nodeShift      = sequenceBits
+)
+
+type UUIDv7Generator struct {
+	locker   sync.Mutex
+	nodeID   int64
+	lastTime int64
+	sequence int64
+}
+
+type UUIDv7Components struct {
+	Timestamp int64    // 毫秒时间戳（相对于自定义纪元）
+	NodeID    int64    // 5位节点ID
+	Sequence  int64    // 18位序列号
+	Version   int      // 版本号（应为7）
+	Variant   int      // 变体（应为2，表示10xx）
+	RawBytes  [16]byte // 原始字节
+}
+
+var generatorInstance *UUIDv7Generator
+
+// 获取UUIDv7生成器实例。如果实例尚未初始化，则返回错误。
+func Generator() (*UUIDv7Generator, error) {
+	if generatorInstance == nil {
+		return nil, &UUIDv7GeneratorNotInitializedError{}
+	}
+	return generatorInstance, nil
+}
+
+// 指定一个主机编号，并完成UUIDv7生成器的初始化。如果主机编号超出范围，则返回错误。
+func Initialize(hostSerial int64) error {
+	if hostSerial < 0 || hostSerial > maxNodeID {
+		return &UUIDv7NodeIDExceededError{}
+	}
+	generatorInstance = &UUIDv7Generator{
+		nodeID:   hostSerial,
+		lastTime: epoch,
+	}
+	return nil
+}
+
+// 获取当前时间对应的新纪元毫秒时间戳。
+func (g *UUIDv7Generator) Now() int64 {
+	return time.Now().UnixMilli() - epoch
+}
+
+// 按顺序生成一个UUIDv7序号组件。
+func (g *UUIDv7Generator) Next() UUIDv7Components {
+	g.locker.Lock()
+	defer g.locker.Unlock()
+	now := g.Now()
+	if now < g.lastTime {
+		// 防止时间回拔的情况，发生回拔时，直接使用上一次的时间戳
+		now = g.lastTime
+	}
+	if now == g.lastTime {
+		g.sequence++
+		if g.sequence > maxSequence {
+			time.Sleep(time.Millisecond)
+			now = g.Now()
+			g.sequence = 0
+		}
+	} else {
+		g.sequence = 0
+	}
+	g.lastTime = now
+	return UUIDv7Components{
+		Timestamp: now,
+		NodeID:    g.nodeID,
+		Sequence:  g.sequence,
+		Version:   7,
+		Variant:   2,
+	}
+}
+
+// 读取随机字节
+func (c *UUIDv7Components) readRandom(bytes []byte) error {
+	_, err := rand.Read(bytes)
+	return err
+}
+
+// 获取UUIDv7原始字节数组
+func (c *UUIDv7Components) Bytes() [16]byte {
+	// 构造 UUID
+	var uuid [16]byte
+	// 时间戳（48 位）
+	timestamp := uint64(c.Timestamp) << timestampShift
+	seqAndNode := (uint64(c.Sequence) << nodeShift) | uint64(c.NodeID)
+	// 写入高位时间戳
+	uuid[0] = byte(timestamp >> 56)
+	uuid[1] = byte(timestamp >> 48)
+	uuid[2] = byte(timestamp >> 40)
+	uuid[3] = byte(timestamp >> 32)
+	uuid[4] = byte(timestamp >> 24)
+	uuid[5] = byte(timestamp >> 16)
+	// 写入低位时间戳 + 版本号（4 位）
+	uuid[6] = byte((timestamp >> 8) | 0x70) // version 7
+	uuid[7] = byte(timestamp)
+	// 写入 seq + node
+	uuid[8] = byte((seqAndNode >> 16) | 0x80) // variant 10xx
+	uuid[9] = byte(seqAndNode >> 8)
+	uuid[10] = byte(seqAndNode)
+	// 剩余位全为 0（可扩展为更多节点 ID 或随机数）
+	randomBytes := make([]byte, 5)
+	if err := c.readRandom(randomBytes); err != nil {
+		// 如果随机数生成失败，使用时间相关值作为后备
+		t := time.Now().UnixNano()
+		randomBytes[0] = byte(t)
+		randomBytes[1] = byte(t >> 8)
+		randomBytes[2] = byte(t >> 16)
+		randomBytes[3] = byte(t >> 24)
+		randomBytes[4] = byte(c.Sequence)
+	}
+	copy(uuid[11:16], randomBytes)
+	return uuid
+}
+
+// 获取UUIDv7字符串
+func (c *UUIDv7Components) String() string {
+	uuid := c.Bytes()
+	return fmt.Sprintf("%x-%x-%x-%x-%x",
+		uuid[0:4],
+		uuid[4:6],
+		uuid[6:8],
+		uuid[8:10],
+		uuid[10:16])
+}
+
+// 获取UUIDv7的Base64格式字符串
+func (c *UUIDv7Components) ToBase64() string {
+	uuid := c.Bytes()
+	return base64.ToBase64(uuid[:])
+}
+
+// 获取UUIDv7的Base36格式字符串
+func (c *UUIDv7Components) ToBase36() string {
+	uuid := c.Bytes()
+	return base36.Encode(uuid[:])
+}
+
+// 与另一个UUIDv7进行比较，按照时间戳、序列号、节点ID进行排序
+func (c *UUIDv7Components) Compare(b *UUIDv7Components) int {
+	if c.Timestamp > b.Timestamp {
+		return 1
+	}
+	if c.Timestamp < b.Timestamp {
+		return -1
+	}
+
+	if c.Sequence > b.Sequence {
+		return 1
+	}
+	if c.Sequence < b.Sequence {
+		return -1
+	}
+
+	if c.NodeID > b.NodeID {
+		return -1
+	}
+	if c.NodeID < b.NodeID {
+		return 1
+	}
+
+	return 0
+}
+
+// 对解析后的UUIDv7进行比较，按照时间戳、序列号、节点ID进行排序
+func CompareUUIDv7(a, b *UUIDv7Components) int {
+	return a.Compare(b)
+}
+
+// 从字节数组解析 UUIDv7
+func ParseUUIDv7FromBytes(data [16]byte) (*UUIDv7Components, error) {
+	// 提取时间戳（前48位）
+	timestamp := (int64(data[0]) << 40) |
+		(int64(data[1]) << 32) |
+		(int64(data[2]) << 24) |
+		(int64(data[3]) << 16) |
+		(int64(data[4]) << 8) |
+		int64(data[5])
+	// 提取版本号（第6字节的高4位）
+	version := int(data[6] >> 4)
+	// 提取变体（第8字节的高2位）
+	variant := int(data[8] >> 6)
+	// 提取序列号和节点ID
+	// 第8字节的低2位 + 第9字节 + 第10字节的高3位组成23位
+	seqAndNode := (int64(data[8]&0x3F) << 16) | // 第8字节低6位
+		(int64(data[9]) << 8) | // 第9字节
+		int64(data[10]) // 第10字节
+	// 分离序列号（高18位）和节点ID（低5位）
+	sequence := seqAndNode >> 5
+	nodeID := seqAndNode & 0x1F
+	return &UUIDv7Components{
+		Timestamp: timestamp,
+		NodeID:    nodeID,
+		Sequence:  sequence,
+		Version:   version,
+		Variant:   variant,
+		RawBytes:  data,
+	}, nil
+}
+
+// 从字符串解析 UUIDv7
+func ParseUUIDv7FromString(uuidStr string) (*UUIDv7Components, error) {
+	// 移除连字符并验证长度
+	cleanStr := strings.ReplaceAll(uuidStr, "-", "")
+	if len(cleanStr) != 32 {
+		return nil, fmt.Errorf("无效的UUIDv7字符串长度")
+	}
+	// 解码十六进制字符串
+	bytes, err := hex.DecodeString(cleanStr)
+	if err != nil {
+		return nil, fmt.Errorf("无效的UUIDv7字符串格式: %v", err)
+	}
+	// 转换为数组
+	var uuidBytes [16]byte
+	copy(uuidBytes[:], bytes)
+	return ParseUUIDv7FromBytes(uuidBytes)
+}
+
+// 从Base64格式字符串解析 UUIDv7
+func ParseUUIDv7FromBase64(base64Str string) (*UUIDv7Components, error) {
+	bytes, err := base64.FromBase64(base64Str)
+	if err != nil {
+		return nil, fmt.Errorf("无效的Base64格式字符串: %v", err)
+	}
+	return ParseUUIDv7FromBytes([16]byte(bytes))
+}
+
+// 从Base36格式字符串解析 UUIDv7
+func ParseUUIDv7FromBase36(base36Str string) (*UUIDv7Components, error) {
+	bytes, err := base36.Decode(base36Str)
+	if err != nil {
+		return nil, fmt.Errorf("无效的Base36格式字符串: %v", err)
+	}
+	return ParseUUIDv7FromBytes([16]byte(bytes))
+}

serialize/base36/base36.go

@@ -0,0 +1,108 @@
+package base36
+
+import (
+	"fmt"
+	"math/big"
+	"strings"
+)
+
+// Encode 将字节数据编码为Base36字符串(大写)，使用=作为padding字符
+func Encode(src []byte) string {
+	if len(src) == 0 {
+		return ""
+	}
+
+	// 将字节转换为big.Int
+	num := new(big.Int).SetBytes(src)
+
+	// 如果输入为全零字节，则直接返回"0"
+	if num.Cmp(big.NewInt(0)) == 0 {
+		return "0"
+	}
+
+	// 进行Base36编码
+	var result strings.Builder
+	base := big.NewInt(36)
+	zero := big.NewInt(0)
+	remainder := new(big.Int)
+
+	// 重复除以36，获取余数作为字符
+	for num.Cmp(zero) > 0 {
+		num.DivMod(num, base, remainder)
+		digit := remainder.Int64()
+
+		if digit < 10 {
+			result.WriteString(fmt.Sprintf("%d", digit))
+		} else {
+			result.WriteString(fmt.Sprintf("%c", 'A'+digit-10))
+		}
+	}
+
+	// 反转字符串，因为我们是从低位开始计算的
+	encoded := result.String()
+	runes := []rune(encoded)
+	for i, j := 0, len(runes)-1; i < j; i, j = i+1, j-1 {
+		runes[i], runes[j] = runes[j], runes[i]
+	}
+
+	return string(runes)
+}
+
+// Decode 将Base36字符串(可为任意大小写)解码为字节数组
+func Decode(src string) ([]byte, error) {
+	if src == "" {
+		return []byte{}, nil
+	}
+
+	// 移除padding字符
+	src = strings.ReplaceAll(src, "=", "")
+	src = strings.ToUpper(src)
+
+	// 使用big.Int进行解码
+	num := big.NewInt(0)
+	base := big.NewInt(36)
+
+	for _, char := range src {
+		var digit int64
+
+		switch {
+		case char >= '0' && char <= '9':
+			digit = int64(char - '0')
+		case char >= 'A' && char <= 'Z':
+			digit = int64(char - 'A' + 10)
+		default:
+			return nil, fmt.Errorf("invalid character %c in base36 string", char)
+		}
+
+		num.Mul(num, base)
+		num.Add(num, big.NewInt(digit))
+	}
+
+	// 转换为字节数组
+	return num.Bytes(), nil
+}
+
+// EncodeToString 是Encode的别名，用于保持与标准库一致的命名
+func EncodeToString(src []byte) string {
+	return Encode(src)
+}
+
+// DecodeString 是Decode的别名，用于保持与标准库一致的命名
+func DecodeString(src string) ([]byte, error) {
+	return Decode(src)
+}
+
+// EncodeInt64 将int64转换为Base36字符串
+func EncodeInt64(num int64) string {
+	return EncodeToString(big.NewInt(num).Bytes())
+}
+
+// DecodeToInt64 将Base36字符串解码为int64
+func DecodeToInt64(src string) (int64, error) {
+	bytes, err := DecodeString(src)
+	if err != nil {
+		return 0, err
+	}
+
+	return new(big.Int).SetBytes(bytes).Int64(), nil
+}

serialize/base36/base36_test.go

@@ -0,0 +1,42 @@
+package base36
+
+import (
+	"fmt"
+	"testing"
+)
+
+func FuzzEncode(f *testing.F) {
+	testCases := []string{"a", "abc", "uuid"}
+	for _, tc := range testCases {
+		f.Add(tc)
+	}
+	f.Fuzz(func(t *testing.T, a string) {
+		encoded := Encode([]byte(a))
+		redecoded, err := Decode(encoded)
+		fmt.Printf("Origin: %s, Encoded: %s\n", a, encoded)
+		if err != nil {
+			t.Errorf("Decode(%q) failed: %v", encoded, err)
+		}
+		if string(redecoded) != a {
+			t.Errorf("Decode(%q) = %q, want %q", encoded, redecoded, a)
+		}
+	})
+}
+
+func FuzzEncodeInt64(f *testing.F) {
+	testCases := []int64{1, 6, 34598347534, 234532543, 2342546456, 34587639284756293}
+	for _, tc := range testCases {
+		f.Add(tc)
+	}
+	f.Fuzz(func(t *testing.T, a int64) {
+		encoded := EncodeInt64(a)
+		redecoded, err := DecodeToInt64(encoded)
+		fmt.Printf("Origin: %d, Encoded: %s\n", a, encoded)
+		if err != nil {
+			t.Errorf("Decode(%q) failed: %v", encoded, err)
+		}
+		if redecoded != a {
+			t.Errorf("Decode(%q) = %q, want %q", encoded, redecoded, a)
+		}
+	})
+}