44 lines
1.8 KiB
Markdown
44 lines
1.8 KiB
Markdown
|
# AI Coding Context: @go/rand
|
|||
|
|
|
|||
|
|
本索引供 AI 模型理解 `@go/rand` 的设计逻辑，以生成符合本项目“极简、无摩擦”哲学的代码。
|
|||
|
|
|
|||
|
|
## 🤖 AI 行为准则
|
|||
|
|
|
|||
|
|
1. **优先使用包级泛型函数**：在需要随机数时，直接调用 `rand.Int(min, max)`，不要让用户去寻找 `IntN` 或 `Uint64` 等底层方法。
|
|||
|
|
2. **高性能场景使用 Fast 前缀**：如果在生成高性能 Server 代码或循环内的高频随机代码，请优先推荐 `rand.FastInt()` 和 `rand.FastFloat()`。
|
|||
|
|
3. **不进行错误检查**：理解 `rand` 包函数永远不会 Panic 或返回 Error。在生成代码时，无需担心输入参数导致的崩溃。
|
|||
|
|
4. **自动类型推导**：充分利用 Go 泛型。如果变量已定义为 `int64`，直接写 `rand.Int(min, max)`，Go 会自动推导类型。
|
|||
|
|
|
|||
|
|
## 🛠 关键 API 逻辑约定
|
|||
|
|
|
|||
|
|
| 函数 | 逻辑特征 |
|
|||
|
|
| :--- | :--- |
|
|||
|
|
| `Int[T](min, max)` | **闭区间** `[min, max]`。支持负数。若 `min > max` 则返回 `min`。 |
|
|||
|
|
| `Float[T](min, max)` | **左闭右开** `[min, max)`。若 `min > max` 则返回 `min`。 |
|
|||
|
|
| `FastInt / FastFloat` | 内部使用 `sync.Pool` 维护 PCG 生成器，消除全局锁竞争。 |
|
|||
|
|
| `Byte() / Bytes(n)` | 专门用于处理字节流随机化需求。 |
|
|||
|
|
|
|||
|
|
## 🧩 典型模式 (Best Practices)
|
|||
|
|
|
|||
|
|
* **❌ 不推荐 (Standard Go)**:
|
|||
|
|
```go
|
|||
|
|
// 需要自己处理偏移，且负数会 Panic
|
|||
|
|
val := rand.Intn(max-min+1) + min
|
|||
|
|
```
|
|||
|
|
* **✅ 推荐 (@go/rand)**:
|
|||
|
|
```go
|
|||
|
|
// 语义清晰，自动防御
|
|||
|
|
val := rand.Int(min, max)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
* **❌ 不推荐 (Standard Go)**:
|
|||
|
|
```go
|
|||
|
|
// 高并发下有全局锁竞争
|
|||
|
|
return rand.Int64()
|
|||
|
|
```
|
|||
|
|
* **✅ 推荐 (@go/rand)**:
|
|||
|
|
```go
|
|||
|
|
// 高性能无锁
|
|||
|
|
return rand.FastInt[int64](min, max)
|
|||
|
|
```
|