# 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 绑定层调用）。

## 相关

- [4.7 基座与公共体系](/zh/architecture/base-system.html)