# 8.5 字典数据接口

:::tip 概述
字典接口分三层：管理接口（dict/dict_item 七件套，带权限）、前端消费接口（dictionary 别名 + getDictItemList，登录即可）、缓存刷新接口。机制详见 [5.10 字典模块](../core/dict)。
:::

## 管理接口（带权限）

```text
dict（/api/dict）七件套：sys:dict:{page|detail|add|update|delete|batchDelete}
  （注意：无 /dict/list——列表经 page 或 /api/dictionary/list 别名）
  GET /api/dict/refreshCache     sys:dict:cache    刷新字典缓存

dict_item（/api/dict/item）七件套：sys:dictitem:{page|detail|add|update|delete|batchDelete}
  （页面用 page；无标准 list）
```

## 前端消费接口（登录即可，无 permission）

```text
GET /api/dictionary/list                字典列表别名（前端 dictionary.ts 调用）
GET /api/dictionary/info                字典详情别名
GET /api/dict/item/getDictItemList/:code   按编码查字典项（走 Redis 缓存）
```

## 典型消费流

```text
前端下拉/单选组件初始化：
  GET /api/dict/item/getDictItemList/{code}
    → 缓存命中直接返回（easygoadmin:dict:item:{code}，TTL 3600s）
    → 返回 [{name:"正常", value:1}, {name:"禁用", value:2}, ...]
  → 组件 options 渲染

行内显示名（{field}Text）：
  后端基座已填充（DictGetText），前端直接展示 statusText——
  不需要再调字典接口
```

## 缓存与刷新

| 层 | TTL | 刷新方式 |
|----|-----|---------|
| Redis `dict:item:{code}` | 3600s | `GET /api/dict/refreshCache`（可全量或按 code 单刷） |
| 进程内 dictTextCache | 300s | 只能等自然过期（各实例独立） |

::: warning 刷新语义
RefreshCache **只刷 Redis 层**——{field}Text 的进程内层仍按 300s 自然过期。改字典文案"接口立即变、{field}Text 最迟 5 分钟变"是预期行为。
:::

## 缓存失效注意

```text
dict_item 增删改不主动清 Redis 缓存（最长 1 小时延迟）——
关键场景（如刚改完下拉选项要立即生效）调 GET /api/dict/refreshCache。
```

## 接口使用速查

| 需求 | 接口 |
|------|------|
| 页面展示字典项下拉 | GET /api/dict/item/getDictItemList/{code} |
| 字典管理页列表 | GET /api/dict/page |
| 字典项管理页列表 | GET /api/dict/item/page?dictId=x |
| 新建字典 | POST /api/dict/add（code 全局唯一） |
| 新建字典项 | POST /api/dict/item/add（name/value/sort） |
| 改文案后立即生效 | GET /api/dict/refreshCache（Redis 层）；{field}Text 等 300s |

## 开发规约

+ 字典编码规范 `{模块snake}_{字段snake}`（user_status / job_execute_policy）
+ 列注释枚举建表 → 生成器自动建字典（幂等）
+ 前端下拉选项优先字典驱动（勿硬编码 options——example 的静态 options 是教学示例）
+ 行内显示名走后端 {field}Text（唯一真相在字典管理页）