From 46921e8930af28adacdbf97b683f8eb2c1eb6b7e Mon Sep 17 00:00:00 2001 From: Star Date: Wed, 22 Apr 2026 10:45:26 +0800 Subject: [PATCH] docs: finalize README and AI manuals --- AI.md | 28 ++++++++++++++-------------- README.md | 44 +++++++++++++++++++++++--------------------- 2 files changed, 37 insertions(+), 35 deletions(-) diff --git a/AI.md b/AI.md index 7b21026..ac67ebb 100644 --- a/AI.md +++ b/AI.md @@ -1,43 +1,43 @@ # AI Coding Context: @go/rand -本索引供 AI 模型理解 `@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 会自动推导类型。 +1. **优先使用包级泛型函数**：在需要随机数时，直接调用 `rand.Int(min, max)`，避免使用底层特定类型的随机函数。 +2. **高性能场景使用 Fast 前缀**：在生成高频调用的 Server 代码时，优先推荐 `rand.FastInt()` 和 `rand.FastFloat()`。 +3. **不进行错误检查**：理解 `rand` 包函数不会 Panic 或返回 Error。 +4. **利用泛型推导**：利用 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)` | 专门用于处理字节流随机化需求。 | +| `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)**: ```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) + // 高性能并发安全 + return rand.FastInt(min, max) ``` diff --git a/README.md b/README.md index e521a03..abb4fe0 100644 --- a/README.md +++ b/README.md @@ -4,17 +4,27 @@ ## 🎯 设计哲学 -* **极简 API**：不再需要根据类型选择 `Int32N` 或 `Uint64N`。一个 `Int(min, max)` 搞定所有整数，一个 `Float(min, max)` 搞定所有浮点数。 -* **需求导向**：我们认为“范围随机”是业务中最直观的需求。因此，所有函数默认支持 `[min, max]` 或 `[min, max)` 区间，无需手动计算偏移。 -* **零摩擦防御**：遵循“No-Panic”准则。即使传入错误的区间（如 `min > max`），库也会平滑处理并返回合理边界，绝不导致进程崩溃。 -* **极致性能**：提供 `Fast` 系列函数，通过 `sync.Pool` 维护高性能 PCG 生成器池，彻底解决多核环境下的全局锁竞争瓶颈。 +* **极简 API**：不再需要区分类型名。一个 `Int(min, max)` 搞定所有。 +* **需求导向**：所有函数默认支持范围随机，无需手动计算偏移。 +* **零摩擦防御**：遵循“No-Panic”准则，自动处理反向区间等异常输入。 +* **极致性能**：通过 `Fast` 系列函数彻底解决多核环境下的全局锁竞争瓶颈。 -## 🚀 核心特性 +## 🛠 API Reference -* **全类型泛型支持**：支持 `int`, `int64`, `uint32`, `float64` 等所有基础数字类型。 -* **负数区间支持**：原生支持如 `rand.Int(-100, 100)` 这样的跨零随机。 -* **高性能并发**：`FastInt` 和 `FastFloat` 在高并发场景下比标准库快数倍。 -* **便捷工具**：`Byte()`, `Bytes(n)`, `Perm(n)`, `Shuffle()` 一应俱全。 +### 基础随机函数 (基于标准库全局生成器) +- `func Int[T IntegerType](min, max T) T`：获取 `[min, max]` 闭区间随机整数。 +- `func Float[T FloatType](min, max T) T`：获取 `[min, max)` 左闭右开区间随机浮点数。 + +### 高性能随机函数 (基于 PCG 无锁池) +在高并发 Server 场景下，推荐使用以下函数以获得极致吞吐量。 +- `func FastInt[T IntegerType](min, max T) T` +- `func FastFloat[T FloatType](min, max T) T` + +### 字节与切片 +- `func Byte() byte` +- `func Bytes(n int) []byte` +- `func Perm(n int) []int` +- `func Shuffle(n int, swap func(i, j int))` ## 📦 安装 @@ -27,20 +37,12 @@ go get apigo.cc/go/rand ```go 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 字节随机切片 +// 字节处理 +key := rand.Bytes(16) ```