# 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` 组内） |
| 用途 | 前端下拉框数据源 |

### 请求示例

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

### 成功响应

```json
{
    "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` **自动清除**对应字典缓存。本接口用于**绕过模型直接改库**后的手动兜底，或运维批量刷新。
:::

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

响应：

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

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

## 前端使用

### 获取字典项

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

### 下拉框使用

```vue
<template>
  <el-select v-model="formData.status" placeholder="请选择状态">
    <el-option
      v-for="item in statusOptions"
      :key="item.value"
      :label="item.name"
      :value="item.value"
    />
  </el-select>
</template>

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

const statusOptions = ref([]);

onMounted(async () => {
  statusOptions.value = await getDictItemByCode('example_status');
});
</script>
```

### 多个字典批量获取

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

### 枚举显示名自动翻译

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

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

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

:::tip 缓存机制
`DictCacheService` 采用两级缓存（请求级 + Redis 持久缓存）。变更一致性由 Observer 保证；详见 [4.8 缓存架构设计](/zh/architecture/cache.html) 与 [5.10 字典模块](/zh/core/dict.html)。
:::

## 后端 DictCacheService 调用

```php
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();         // 清除所有字典
```