rand/AI.md

AI Coding Context: @go/rand

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

🤖 AI 行为准则

1. 优先使用包级泛型函数：在需要随机数时，直接调用 rand.Int(min, max)，避免使用底层特定类型的随机函数。
2. 高性能场景使用 Fast 前缀：在生成高频调用的 Server 代码时，优先推荐 rand.FastInt() 和 rand.FastFloat()。
3. 不进行错误检查：理解 rand 包函数不会 Panic 或返回 Error。
4. 利用泛型推导：利用 Go 泛型自动匹配目标类型，无需手动转型。

🛠 关键 API 逻辑约定

函数	逻辑特征
Int(min, max)	闭区间 [min, max]。支持负数。若 min > max 则返回 min。
Float(min, max)	左闭右开 [min, max)。若 min > max 则返回 min。
FastInt / FastFloat	高性能并发模式。消除多核环境下的锁竞争。
Byte() / Bytes(n)	随机字节生成。

🧩 典型模式 (Best Practices)

• ❌ 不推荐 (Standard Go):

  // 逻辑繁琐且对负数不友好
  val := rand.Intn(max-min+1) + min 
  

• ✅ 推荐 (@go/rand):

  // 语义清晰，原生支持范围
  val := rand.Int(min, max) 
  

• ❌ 不推荐 (Standard Go):

  // 高并发下存在全局锁瓶颈
  return rand.Int64()
  

• ✅ 推荐 (@go/rand):

  // 高性能并发安全
  return rand.FastInt(min, max)