D. Utility 函数速查
:::tip 说明
utility/ 13 个基础包的常用入口速查。全部包无业务语义、不 import internal。
:::
apperr
| API |
说明 |
| apperr.New(code, msg) |
构造业务错误 |
| apperr.Newf(code, format, args...) |
格式化业务错误 |
| .Code() |
取码（response 映射用） |
业务代码经 consts 别名引用（CodeXxx 哨兵）。
cache
| API |
说明 |
| Init / Close / InMemory |
生命周期与模式查询 |
| Set / Get / Del / Exists |
基础读写（TTL 秒） |
| SetNX |
不存在才写（锁） |
| Incr |
计数（限流） |
| ZAdd/ZRem/ZRangeByScore/ZCard/ZRemRangeByScore |
有序集合（在线会话） |
| PING / Info / DBSize |
Redis 原始（监控） |
captcha
| API |
说明 |
| Generate(ctx) |
返回 (key, dataURL) |
| Verify(ctx, key, code) |
校验（一码一用） |
config
| API |
说明 |
| config.String(key, def) |
字符串 |
| config.Bool(key, def) |
布尔 |
| （数值型同族） |
配置读取统一入口 |
crypto
| API |
说明 |
| GenerateSalt() |
随机盐 |
| HashPassword(password, salt) |
bcrypt 哈希 |
| VerifyPassword(hashed, password, salt) |
恒时比对 |
| IsBcrypt(hashed) |
格式识别 |
excel
| API |
说明 |
| ReadSheet(file) |
(headers, rows, err)，剥表头跳空行 |
| WriteSheet(dir, baseName, headers, rows) |
写 xlsx，返回 fileName/filePath |
ip2region
IP → 归属地（消费 xdb 数据库文件），登录/操作日志采集用。
jwt
| API |
说明 |
| Sign(ctx, tokenType, userID, tenantID, username, realname) |
签发双令牌 |
| Parse(ctx, tokenStr) |
解析校验（Claims） |
| ExpireDuration(ctx, tokenType) |
有效期 |
logger
结构化 zap：Infof/Warnf/Errorf 等，支持 ctx 追踪字段（trace_id 自动关联）。
response
| API |
说明 |
| Ok / OkMsg / Page |
成功信封 |
| Fail / FailCode |
失败信封（401 原码透出） |
| Write / WriteWithCode |
写出并记录（中间件读取） |
| DeniedReason / GetDeniedReason |
拒绝原因传递 |
upload
| API |
说明 |
| SaveTemp |
两段式第一段 |
| SaveFromTemp / SaveFromTempMulti |
转正 |
| GetFileUrl |
相对路径 → 访问 URL |
| SafeJoin |
路径穿越防护 |
| BaseDir / TempBaseDir / GetAccessBase |
目录基址 |
ua / validator
ua：User-Agent 解析（OS/浏览器）。validator：binding 标签校验引擎（router 绑定层调用）。
相关
