randomx —— 安全随机 token 生成
验证码 / API key / one-time token / 会话 id 这些"猜不到"的东西, 统一走 crypto/rand,不要用
math/rand。
功能
randomx 提供一组加密学安全 + URL-safe 的随机串生成器,目标是替掉散落在
业务代码里的 fmt.Sprintf("%d", rand.Int()) 和 uuid.New().String():
| 函数 | 产出 | 典型场景 |
|---|---|---|
Token(n) |
n 字符 URL-safe | 通用 token / 会话 id / JTI |
String() |
32 字符 URL-safe | 替代 fmt.Sprintf("%d", rand.Int()) |
MustToken(n) |
同 Token,失败 panic |
需要"绝不能返回空"的场合 |
NumericCode(n) |
n 位纯数字(允许前导 0) | 短信验证码 |
PINCode(n) |
同上 | 4~6 位密码 |
AlnumCode(n) |
n 位大小写字母+数字 | 通用 |
InviteCode(n) |
n 位无易混字符 | 人眼要读的邀请码 / 兑换码 |
Hex(n) |
n 字节 的 hex(2n 字符) | secret key / hash salt |
Base64(n) |
n 字节 的 base64(无 padding) | header / cookie |
FromCharset(n, charset) |
自定义字符集 | 特殊需求 |
Entropy(n, charsetLen) |
熵估算(bit) | 决定"该发多长的验证码" |
为什么不用 math/rand
math/rand 是伪随机的:seed 可见、状态可推。Go 1.20 起全局 rand 会被
随机播种,但只要攻击者拿到一次输出(或 seed),后续序列就完全可预测 ——
用它生成 token 等于把 token 送出去。
math/rand 的正确用途是抖动 / 采样 / 打散(比如 retryx 的退避抖动),
那种场景不需要不可预测性,追求的反而是快。
为什么不是 uuid
uuid 固定 36 字符且含 4 个连字符,做文件名 / URL 参数不好看;
randomx 支持任意长度,字符集全部 URL-safe(无 + / =,不用转义)。
配置
代码侧
该包无 yaml 配置,也没有构造选项 —— 全是包级函数,直接调。
字符集常量:
| 常量 | 内容 | 说明 |
|---|---|---|
CharsetURLSafe |
A-Za-z0-9-_ |
默认(Token 走这个),64 字符 = 6 bit/字符 |
CharsetAlphaNum |
A-Za-z0-9 |
62 字符 |
CharsetNoConfusing |
大写字母(去掉 I/L/O/Q)+ 2-9 |
32 字符 = 5 bit/字符,排除 0/O/Q、1/I/L,给人眼读 |
CharsetNumeric |
0-9 |
10 字符 = 3.32 bit/字符 |
yaml 侧
该包无 yaml 配置。
使用方法
// 通用 token:URL-safe,适合 header / cookie / 上传 ID
id := randomx.Token(32)
// 短信验证码:纯数字,允许前导 0
code := randomx.NumericCode(6)
// 邀请码:排除易混字符(0/O/Q、1/I/L),人眼能读
invite := randomx.InviteCode(8)
// 密钥 / 盐:hex 编码,长度按**字节**
salt := randomx.Hex(16) // 16 字节 = 32 字符 = 128 bit
// 熵估算 —— 决定"该发多长的验证码"时用这个
e := randomx.Entropy(6, len(randomx.CharsetNumeric))
框架里的实际用法:JWT 的 JTI 和会话 id 都是 randomx.Token(16)
(internal/pkg/auth/jwt.go / session.go)。
注意事项
- ⚠️
Token(n)的 n 是字符数,不是字节数 —— 熵 = n × log2(字符集长度)。 URL-safe 字符集是 64 个字符 ⇒ 每字符 6 bit。Token(32)= 192 bit, 不是 256 bit(包头注释里"43 字节原始熵 → 256 位"那句与实现对不上)。Hex(n)/Base64(n)的 n 才是字节数。 ⚠️ 框架里就有这个口径错位:internal/pkg/auth/jwt.go的常量叫jtiRandomBytes = 16,注释写"16 字节 = 128 bit",但传给randomx.Token的是字符数 ⇒ 实际熵是 16 × 6 = 96 bit。session.go的sessionIDBytes同理。够用,但别按注释里的 128 bit 去算碰撞概率。 - ⚠️
MustToken(0)会 panic,而且 panic 信息极具误导性 (crypto/rand failed (impossible))。原因是Token(0)合法地返回空串,MustToken把"空串"一律当成"crypto/rand 失败"。n <= 0的其它函数 (Token/Hex/Base64/FromCharset)都只是返回空串,不 panic。 - ⚠️
FromCharset的字符集长度会被截成byte:csLen := byte(len(charset))。字符集长度正好是 256 的倍数时csLen变成 0,buf[i] % csLen直接 divide by zero panic。 自定义字符集时长度控制在 255 以内。 - ⚠️
FromCharset有模偏置:buf[i] % csLen,而buf[i]只有 256 种取值。 字符集长度不是 256 的因数时,前256 % csLen个字符会比其余的多约1/26的概率。CharsetNumeric(10 个)上,数字0~5比6~9略常见一点 —— 做短信验证码时无所谓,做长期有效的凭据时 优先用 64 字符的 URL-safe 字符集。 - ⚠️
rand.Read失败时返回空串,没有 error 返回值。Token/Hex/Base64/FromCharset在crypto/rand失败时一律返回"", 调用方分不清"熵源坏了"和"参数不合法"。需要区分就用MustToken(它会 panic), 但要先自己挡掉n <= 0。 - ⚠️ 短信验证码用
NumericCode而不是Token—— 但要注意NumericCode(6)只有约 19.9 bit 熵(6 × 3.32),必须配合频次限制用 (见smslimit),单靠长度不够。 - ⚠️ 别把 randomx 用在"需要可复现"的场景。它是不可预测的;
要可复现就明确用
math/rand并自己管 seed。