8.5 字典数据接口

概述

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

管理接口（带权限）

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）

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

典型消费流

前端下拉/单选组件初始化：
  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	只能等自然过期（各实例独立）

刷新语义

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

缓存失效注意

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（唯一真相在字典管理页）