101 lines
2.5 KiB
Markdown
101 lines
2.5 KiB
Markdown
# 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)
|