rxthinkcmf-wiki/RXThinkCMF_Laravel13_NaiveVue/zh/api-spec/dict-api.md

8.5 字典数据接口

:::tip 概述 字典数据接口分为两组：字典管理（DictController）和字典项管理（DictItemController）。前端通过字典编码获取字典项列表用于下拉框，后台通过管理接口维护字典数据。字典项变更时 DictItemObserver 自动失效缓存。 :::

接口总览

字典管理（DictController）

方法	URL	权限码	说明
GET	/api/dict/page	sys:dict:page	字典分页列表
GET	/api/dict/detail/{id}	sys:dict:detail	字典详情
POST	/api/dict/add	sys:dict:add	添加字典
PUT	/api/dict/update	sys:dict:update	修改字典
DELETE	/api/dict/delete/{id}	sys:dict:delete	删除字典
DELETE	/api/dict/batchDelete	sys:dict:batchDelete	批量删除字典
GET	/api/dict/refreshCache	sys:dict:update	刷新字典缓存（#[DemoAllow] 演示环境放行）

字典项管理（DictItemController）

方法	URL	权限码	说明
GET	/api/dict/item/page	sys:dict:page	字典项分页列表
GET	/api/dict/item/detail/{id}	sys:dict:detail	字典项详情
POST	/api/dict/item/add	sys:dict:add	添加字典项
PUT	/api/dict/item/update	sys:dict:update	修改字典项
DELETE	/api/dict/item/delete/{id}	sys:dict:delete	删除字典项
DELETE	/api/dict/item/batchDelete	sys:dict:batchDelete	批量删除字典项
GET	/api/dict/item/getDictItemList/{code}	—	按编码获取字典项列表

:::tip 批量删除为 DELETE 本项目 batchDelete 系列接口统一为 DELETE 方法（请求体传 ids 数组——DELETE 方法携带 body）。 :::

按编码获取字典项（最常用）

接口信息

项目	说明
URL	GET /api/dict/item/getDictItemList/{code}
权限	无需额外权限注解（已登录即可，位于 auth.jwt 组内）
用途	前端下拉框数据源

请求示例

GET /api/dict/item/getDictItemList/gender
Authorization: Bearer <token>

成功响应

{
    "code": 0,
    "ok": true,
    "msg": "操作成功",
    "data": [
        { "id": 1, "name": "男", "value": "1", "sort": 1, "note": "" },
        { "id": 2, "name": "女", "value": "2", "sort": 2, "note": "" },
        { "id": 3, "name": "保密", "value": "3", "sort": 3, "note": "" }
    ]
}

响应字段

字段	类型	说明
id	number	字典项 ID
name	string	字典项名称（显示标签）
value	string	字典项值（存储值）
sort	number	排序
note	string	备注

常用字典编码（以初始化脚本为准）

编码	说明	字典项
gender	性别	1=男, 2=女, 3=保密
user_status	用户状态	1=正常, 2=禁用
tenant_status	租户状态	1=启用, 0=禁用
example_type	案例类型	1=类型1, 2=类型2, 3=类型3, 4=类型4
example_status	案例状态	1=在用, 2=停用

（完整字典可在「数据管理 → 字典管理」中查看。）

刷新字典缓存

项目	说明
URL	GET /api/dict/refreshCache
权限	sys:dict:update
演示环境	允许执行（标注 #[DemoAllow]）

:::tip 正常情况无需手动刷新 字典项通过后台接口增删改时，DictItemObserver 自动清除对应字典缓存。本接口用于绕过模型直接改库后的手动兜底，或运维批量刷新。 :::

GET /api/dict/refreshCache
Authorization: Bearer <token>

响应：

{
    "code": 0,
    "ok": true,
    "msg": "缓存刷新成功",
    "data": null
}

命令行兜底：php artisan dict:clear-cache。

前端使用

获取字典项

// ui/src/api/common/index.ts（实际代码）
/**
 * 根据字典编码查询字典项数据
 * @param code 字典编码
 * @returns 返回结果
 */
export function getDictItemByCode(code) {
  return http.request({
    url: '/dict/item/getDictItemList/' + code,
    method: 'GET',
  });
}

下拉框使用

<template>
  <n-select
    v-model:value="formData.status"
    :options="statusOptions"
    placeholder="请选择状态"
  />
</template>

<script setup>
import { ref, onMounted } from 'vue';
import { getDictItemByCode } from '@/api/common/index';

const statusOptions = ref([]);

onMounted(async () => {
  const list = await getDictItemByCode('example_status');
  // n-select 的 options 需要 { label, value } 结构
  statusOptions.value = list.map((item) => ({ label: item.name, value: item.value }));
});
</script>

多个字典批量获取

const [genderOptions, statusOptions] = await Promise.all([
  getDictItemByCode('gender'),
  getDictItemByCode('user_status'),
]);

枚举显示名自动翻译

Service 中配置 serializeMaps（需 use HasSerializeMaps）后，查询数据自动补全 {字段名}Text：

protected array $serializeMaps = [
    'status' => 'example_status',
];

// API 响应自动包含 statusText
{ "id": 1, "name": "测试", "status": 1, "statusText": "在用" }

:::tip 缓存机制 DictCacheService 采用两级缓存（请求级 + Redis 持久缓存）。变更一致性由 Observer 保证；详见 4.8 缓存架构设计 与 5.10 字典模块。 :::

后端 DictCacheService 调用

use App\Services\DictCacheService;

// 根据值获取名称
$text = DictCacheService::getText('gender', 1);  // '男'

// 根据名称反向获取值
$value = DictCacheService::getValue('gender', '男');  // '1'

// 获取下拉框选项
$options = DictCacheService::getOptions('gender');
// [['label'=>'男','value'=>'1'], ['label'=>'女','value'=>'2'], ...]

// 批量获取多个字典映射（列表翻译一次取词）
$maps = DictCacheService::getBatchTextMaps(['gender', 'user_status']);

// 清除缓存
DictCacheService::clearCache('gender');    // 清除指定字典
DictCacheService::clearAllCache();         // 清除所有字典