70 lines
3.5 KiB
Markdown
70 lines
3.5 KiB
Markdown
# D. 公共函数速查
|
||
|
||
:::tip 概述
|
||
后端共享能力速查：logic/base.go 15 个导出函数 + module_spec/data_scope 包级函数 + utility 九包。纪律：base.go 只依赖 dao/utility/consts，导出上限 15。
|
||
:::
|
||
|
||
## logic/base.go（共享能力层）
|
||
|
||
| 函数 | 职责 |
|
||
|------|------|
|
||
| SaveFileFields(ctx, data, fields, saveDir) | 单文件字段批量转正（原地更新 map） |
|
||
| SaveMultiFileFields(ctx, data, fields, saveDir) | 逗号多文件字段批量转正 |
|
||
| SaveFileField(ctx, fileUrl, saveDir) | 单值便捷版 |
|
||
| SaveMultiFileField(ctx, fileUrls, saveDir) | 逗号串便捷版 |
|
||
| LocalizeContentFields(ctx, content, saveDir) | 富文本存库本地化（[IMG_URL] 占位符化） |
|
||
| ExpandContentFields(ctx, content) | 富文本读取还原（**唯一还原出口**） |
|
||
| DictGetText(ctx, code, value) | 字典值 → 显示名（进程内 300s） |
|
||
| SerializeMapOnRead(ctx, data, fieldDict) | map 行补 {field}Text |
|
||
| LogTypeText(v int) | 操作日志类型 → 中文（静态表） |
|
||
| CheckUnique(ctx, m, column, value, excludeId, label) | 唯一性快速校验（TOCTOU，真值靠 uk_*） |
|
||
| WithTrans(ctx, fn) | 事务包裹（错误自动回滚） |
|
||
| ChunkQuery(ctx, build, size, fn) | 分块遍历（导出防 OOM，默认 500/页） |
|
||
| BuildTree[T](rows, idOf, pidOf, childrenOf, less) | 泛型平铺转树 |
|
||
| CleanTemp(ctx, expireDays) | 清理上传临时日期目录 |
|
||
| fillUserCount(column, list) | 按外键统计引用数（内部，level/position 复用） |
|
||
|
||
## logic 包级共享函数
|
||
|
||
| 函数 | 位置 | 职责 |
|
||
|------|------|------|
|
||
| ResolveCityNames(ctx, codes, sep) | city.go | 区划编码 → 名称串 |
|
||
| ResolveCityCodes(ctx, cityInfo) | city.go | 名称串 → 四级编码 |
|
||
| LoadIdentity / LoadTenant | auth.go | 身份/租户加载（中间件接线） |
|
||
| ApplyDataScope(deptColumn) | data_scope.go | 行级数据权限工厂 |
|
||
| RegisterJobHandler(name, h) | job_handler.go | 本地任务处理器注册（重名 panic） |
|
||
| FillTextFields(ctx, target, maps) | module_spec.go | {field}Text 结构体填充 |
|
||
|
||
## utility 基础能力包
|
||
|
||
| 包 | 主要 API | 职责 |
|
||
|----|---------|------|
|
||
| utility/cache | Init/Set/Get/Del/Exists/SetNX/UsingMemory | 统一缓存门面（Redis 优先、内存降级） |
|
||
| utility/captcha | Generate/Verify | 验证码（一次性、bypassCode） |
|
||
| utility/crypto | GenerateSalt/HashPassword/VerifyPassword/IsBcrypt | bcrypt 双重加盐 |
|
||
| utility/excel | ReadSheet/WriteSheet | excelize 封装（FileOpener 兼容两种） |
|
||
| utility/ip2region | City/Location | xdb 归属地（懒加载+读锁） |
|
||
| utility/jwt | Sign/Parse/ExpireDuration | HS256 双令牌 |
|
||
| utility/response | Ok/Fail/Write | 统一信封写出 |
|
||
| utility/ua | ParseOS/ParseBrowser | UA 解析 |
|
||
| utility/upload | SaveTemp/SaveFromTemp/SaveFromTempMulti/GetFileUrl/BaseDir | 两段式上传 |
|
||
|
||
## consts 常量包
|
||
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| biz_err.go | 17 个业务错误码（1/400/401/403/429/500 + 1001-1015） |
|
||
| cache_key.go | Redis 键前缀 easygoadmin: |
|
||
| context_key.go | 上下文读写（consts.GetXxx(ctx)） |
|
||
| log_type.go | 41 个日志类型常量 + LogTypeMap/LogTypeNames |
|
||
|
||
## 使用优先级建议
|
||
|
||
```text
|
||
1. spec 声明能表达 → 用声明（FileFields/SerializeMaps/UniqueFields/DataScope）
|
||
2. spec 钩子能表达 → 用钩子（Before/After）
|
||
3. 需要底层能力 → base.go / utility（组合调用）
|
||
4. 跨模块业务复用 → logic 包级函数（放具体模块文件顶部）
|
||
5. 新横切能力 → 评估进 base.go（≤15 导出）或拆 base/ 子包
|
||
```
|