3.5 KiB
3.5 KiB
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 |
使用优先级建议
1. spec 声明能表达 → 用声明（FileFields/SerializeMaps/UniqueFields/DataScope）
2. spec 钩子能表达 → 用钩子（Before/After）
3. 需要底层能力 → base.go / utility（组合调用）
4. 跨模块业务复用 → logic 包级函数（放具体模块文件顶部）
5. 新横切能力 → 评估进 base.go（≤15 导出）或拆 base/ 子包