# 5.11 字典模块

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

## 结构

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

## 后端消费：三种方式

### 1. ModuleSpec 声明（推荐）

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

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

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

### 2. 手写查询

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

### 3. 注册机制

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

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

## 缓存

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

## 前端消费

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

接口契约见 [8.6 字典数据接口](/zh/api-spec/dict-api.html)。

## 管理界面

字典管理页（列表 + 字典项明细维护）见 [6.12 字典管理](/zh/modules/dict.html)。

## 使用规约

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

## 下一步

→ [5.12 系统配置管理](/zh/core/config.html)