5.11 字典模块

概述

字典承载系统内全部枚举取值的显示名（状态、类型、性别……）。读侧经 SerializeMaps 声明自动回填 {field}Text，前端下拉与标签经字典接口取值，实现"枚举定义一处、前后端同源消费"。

结构

gin_dict       字典（code + 名称，如 example_status 案例状态）
gin_dict_item  字典项（value + label + 排序 + 状态，如 1-在用 / 2-停用）

后端消费：三种方式

1. ModuleSpec 声明（推荐）

// internal/service/example.go
var exampleSerializeMaps = map[string]string{
    "status": "example_status",   // 键：行数据枚举字段（snake）；值：字典编码
}

var exampleSpec = ModuleSpec[...]{
    // ...
    SerializeMaps: exampleSerializeMaps,
}

基座在列表/详情读侧按字典自动回填 DTO 中已声明的 StatusText 字段。

2. 手写查询

text := DictGetText(ctx, "example_status", statusValue)   // 导出翻译等场景

3. 注册机制

dict 模块 init → SetDictLookup(查询函数) → base.go 接线

base 不反向引用模块文件，靠变量注入避免循环依赖；未接线时 DictGetText 按未接线回退（空文本）。

缓存

字典项集合按编码缓存（cache: dict:{code}，值为全部字典项 JSON）。字典项变更时主动删除对应键，下次读取回源重建——读多写少场景零额外维护。

前端消费

• 下拉/单选/标签统一走字典接口取选项（不硬编码枚举）
• 与后端 SerializeMaps 同编码，保证前后端显示一致

接口契约见 8.6 字典数据接口。

管理界面

字典管理页（列表 + 字典项明细维护）见 6.12 字典管理。

使用规约

规约	说明
编码命名	小写下划线，模块前缀（example_status）
取值类型	字典值按字符串比对，枚举列用整型存储时基座负责转换
新枚举先建字典	建表注释中的取值必须有对应字典项
禁止硬编码	显示名一律走字典，不写 if-else 映射

下一步

→ 5.12 系统配置管理