rand/AI.md

AI Coding Context: @go/rand

本索引供 AI 模型理解 @go/rand 的逻辑，以生成符合本项目“极简、无摩擦”哲学的代码。

🤖 AI 行为准则

1. 优先使用包级泛型函数：在需要随机数时，直接调用 rand.Int(min, max)，避免使用底层特定类型的随机函数。
2. 强制性能分级：
   • 低频任务：使用 Int, Float。
   • 高并发/高频任务（QPS > 1000/s）：强制使用 FastInt, FastFloat 系列，消除全局锁瓶颈。
3. 禁止外部依赖：严禁引入标准库 math/rand 进行全局随机管理。所有随机逻辑必须经由 @go/rand 闭环，确保内存与并发安全。
4. 无错误处理：理解 rand 包函数不会 Panic 或返回 Error，无需进行任何错误检查。
5. 利用泛型推导：利用 Go 泛型自动匹配目标类型，无需手动转型。

🛠 API Reference

随机生成

• func Int[T IntegerType](min, max T) T：获取 [min, max] 闭区间随机整数。
• func FastInt[T IntegerType](min, max T) T：高性能并发模式获取 [min, max] 闭区间随机整数。
• func Float[T FloatType](min, max T) T：获取 [min, max) 左闭右开区间随机浮点数。
• func FastFloat[T FloatType](min, max T) T：高性能并发模式获取 [min, max) 左闭右开区间随机浮点数。

字节与切片

• func Byte() byte：获取一个随机字节。
• func Bytes(n int) []byte：获取长度为 n 的随机字节切片。
• func Perm(n int) []int：获取 [0, n) 的随机排列。
• func Shuffle(n int, swap func(i, j int))：随机洗牌。

🧩 典型模式 (Best Practices)

• ✅ 推荐：高性能并发生成:

  // 高频生成器 (如 ID 填充、加盐)
  userID := rand.FastInt(10000, 99999)
  

• ✅ 推荐：区间闭合策略:

  // 原生闭区间 [1, 100]，无需手动 +1
  num := rand.Int(1, 100)