5.11 字典配置与使用

概述

本节是 {field}Text 字典驱动的使用手册：如何声明、填充链路如何工作、文案如何修改生效、常见坑有哪些。后端声明一处，全链路（列表/详情/导出）自动带显示名。

使用三步

1. 建表时列注释写枚举：  status int DEFAULT 1 COMMENT '状态：1-正常 2-禁用'
   （生成器自动创建字典 user_status + 字典项；或字典管理页手工建）

2. logic 模块头部声明映射：
   var userSerializeMaps = map[string]string{
       "status": "user_status",
   }
   挂进 spec：SerializeMaps: userSerializeMaps

3. api/v1 行结构体加 Text 字段：
   Status     int    `json:"status"`
   StatusText string `json:"statusText"`   // 状态显示名（dict_item 解析）

读取时基座自动填充，前端直接展示 statusText。

填充链路（机制详解）

spec.SerializeMaps 声明 {字段: 字典编码}
        │
        ▼
基座 FillTextFields（结构体存在 {Field}Text string 字段即自动填充，
                    反射计划按类型缓存）
        │
        ▼
DictGetText(ctx, code, value)
        │ 查 dict→dict_item 的 name
        ▼
进程内缓存 dictTetxCache（{code}:{value} → 显示名，TTL 300s）
        │ 未命中回源 Redis（dict:item:{code}，3600s）→ 数据库
        ▼
返回显示名；查无此项返回原值（不报错）

map 场景（非结构体，如导出行）用 SerializeMapOnRead(ctx, row, maps) 原地补 row[field+"Text"]。

修改文案如何生效

场景	生效时间
字典管理页改 dict_item.name	进程内缓存最迟 5 分钟（300s）自然过期
需要立即全实例生效	调 GET /api/dict/refreshCache（刷 Redis 层；进程内层仍等过期）
新增字典项	同上（旧值缓存不受影响）

三层缓存认知

Redis 层（3600s，refreshCache 主动刷）→ 进程内层（300s，只等过期）→ 无缓存。改文案"看起来没生效"通常是进程内层未过期，等 5 分钟或重启。

导出中的字典文本

导出不走结构体填充，显式调用（真实模式，摘自 example 导出）：

data = append(data, []any{
    r["name"].String(),
    DictGetText(ctx, "example_type", r["type"]),
    DictGetText(ctx, "example_status", r["status"]),
})

枚举列输出字典文本，Excel 直接可读（导出=所见）。

前端消费

1. 行内 {field}Text：直接展示后端返回的 statusText（首选——文案唯一真相在字典）
2. 筛选下拉选项：调 /api/dict/item/getDictItemList/:code 拿字典项驱动 Select
   （example 模块 querySchemas 的 options 是静态示例；真实模块建议字典驱动）
3. 表单单选/多选：同上，按字典编码取选项

命名与例外

编码规范：{模块snake}_{字段snake}（user_status / job_execute_policy / example_status）
公共字典：role_data_scope（数据范围）等不带模块前缀

例外：operation_log.type 存注解常量值（0-40/99），用静态表 LogTypeText
     （consts.LogTypeNames），不走字典——数值与 gmeta logType 绑定，改动会破坏存量日志

常见问题

症状	原因与处理
{field}Text 全是数字	spec 未声明 SerializeMaps / 结构体无 {Field}Text 字段 / 字典编码写错
部分值有文本部分没有	dict_item 缺该 value 的项
改了文案没变化	进程内 300s 缓存未过期；调 refreshCache 只刷 Redis 层
生成器没建字典	列注释格式不对（须 字段：1-x 2-y 形式）或非 MySQL 库内省不到注释
查询返回原值	DictGetText 设计为"查无返回原值"——排查 dict/dict_item 数据