75 lines
2.9 KiB
Markdown
75 lines
2.9 KiB
Markdown
# 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（唯一真相在字典管理页）
|