test(base36): 添加 Encode 和 EncodeInt64 的模糊测试

为 base36 包添加了两个 fuzz 测试函数，分别用于测试
Encode/Decode 和 EncodeInt64/DecodeToInt64 的正确性。
测试覆盖了字符串和 int64 类型的编码与解码过程，
确保在各种输入下功能的稳定性和正确性。

README.md

@@ -35,12 +35,16 @@ Golang 中可以使用的常用辅助功能工具箱。主要配备以下功能
   - [ ] BlockHash 散列算法
 - 唯一序列号生成器
   - [x] 冰雹 ID 生成器(短主机精简日期版雪花 ID)
-  - [x] UUID 生成器
+  - [x] UUIDv4 生成器
+  - [ ] UUIDv7 生成器
+    - [ ] UUIDv7 比较及排序
+    - [ ] 基于 Base36 的 short UUIDv7 转换器
   - [x] short UUID 生成器
 - 验证码生成器
   - [x] 随机验证码生成算法
 - 序列化算法
   - [x] Base64 算法
+  - [ ] 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())
 }

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)
+		}
+	})
+}