rand/README.md

@go/rand

@go/rand 是一个专注于极简调用与极致性能的 Go 随机数库。它通过泛型消除了传统库中繁琐的类型分支，并针对高并发场景进行了底层优化。

🎯 设计哲学

• 极简 API：不再需要根据类型选择 Int32N 或 Uint64N。一个 Int(min, max) 搞定所有整数，一个 Float(min, max) 搞定所有浮点数。
• 需求导向：我们认为“范围随机”是业务中最直观的需求。因此，所有函数默认支持 [min, max] 或 [min, max) 区间，无需手动计算偏移。
• 零摩擦防御：遵循“No-Panic”准则。即使传入错误的区间（如 min > max），库也会平滑处理并返回合理边界，绝不导致进程崩溃。
• 极致性能：提供 Fast 系列函数，通过 sync.Pool 维护高性能 PCG 生成器池，彻底解决多核环境下的全局锁竞争瓶颈。

🚀 核心特性

• 全类型泛型支持：支持 int, int64, uint32, float64 等所有基础数字类型。
• 负数区间支持：原生支持如 rand.Int(-100, 100) 这样的跨零随机。
• 高性能并发：FastInt 和 FastFloat 在高并发场景下比标准库快数倍。
• 便捷工具：Byte(), Bytes(n), Perm(n), Shuffle() 一应俱全。

📦 安装

go get apigo.cc/go/rand

💡 快速开始

import "apigo.cc/go/rand"

// 1. 基础随机 (默认使用全局生成器)
num := rand.Int(1, 100)        // 返回 [1, 100] 的 int
val := rand.Int[int64](0, 1e12) // 返回大数 int64

// 2. 负数范围
score := rand.Int(-50, -10)   // 完美支持

// 3. 浮点随机
prob := rand.Float(0.0, 1.0)  // 返回 [0, 1.0) 的 float64

// 4. 高并发场景 (推荐)
// 在高并发 Server 中使用 Fast 系列函数以消除锁竞争
userID := rand.FastInt(1000, 9999)

// 5. 字节处理
key := rand.Bytes(16) // 生成 16 字节随机切片