# 8.5 字典数据接口

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

## 接口总览

### 字典管理（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 | 刷新字典缓存 |

### 字典项管理（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}` | — | 按编码获取字典项列表 |

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

### 接口信息

| 项目 | 说明 |
|------|------|
| URL | `GET /api/dict/item/getDictItemList/{code}` |
| 权限 | 无需额外权限（已登录即可） |
| 用途 | 前端下拉框数据源 |

### 请求示例

```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` | number | 字典项 ID |
| `name` | string | 字典项名称（显示标签） |
| `value` | string | 字典项值（存储值） |
| `sort` | number | 排序 |
| `note` | string | 备注 |

### 常用字典编码

| 编码 | 说明 | 字典项 |
|------|------|--------|
| `gender` | 性别 | 1=男, 2=女 |
| `user_status` | 用户状态 | 0=禁用, 1=启用 |
| `article_status` | 文章状态 | 0=草稿, 1=已发布 |
| `tenant_status` | 租户状态 | 0=禁用, 1=启用 |
| `notice_type` | 通知类型 | 1=通知, 2=公告 |
| `example_type` | 案例类型 | 1=基础, 2=进阶, 3=高级 |
| `example_status` | 案例状态 | 0=禁用, 1=启用 |
| `data_scope` | 数据权限 | 1=全部, 2=本部门, 3=仅本人 |

## 刷新字典缓存

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

修改字典数据后需调用此接口刷新缓存，否则新数据不会立即生效。

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

响应：

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

## 前端使用

### 获取字典项

```typescript
// ui/src/api/common/index.ts
export function getDictItemList(code: string) {
  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 { getDictItemList } from '@/api/common/index';

const statusOptions = ref([]);

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

### 多个字典批量获取

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

### 封装为通用 Hook

```typescript
// ui/src/hooks/web/useDict.ts
import { ref, onMounted } from 'vue';
import { getDictItemList } from '@/api/common/index';

export function useDict(code: string) {
  const options = ref([]);
  const loading = ref(false);

  const load = async () => {
    loading.value = true;
    try {
      options.value = await getDictItemList(code);
    } finally {
      loading.value = false;
    }
  };

  onMounted(() => load());

  return { options, loading, reload: load };
}

// 使用
const { options: genderOptions } = useDict('gender');
const { options: statusOptions } = useDict('user_status');
```

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

Logic 中配置 `serializeMaps` 后，查询数据自动补全 `{字段名}Text`：

```php
/**
 * 枚举显示名映射
 *
 * @var array
 */
protected array $serializeMaps = [
    'status' => 'example_status',
];
```

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

:::tip 缓存机制
DictService 采用两级缓存（请求级 + 持久缓存，1小时过期）。修改字典数据后需调用刷新缓存接口，否则新数据不会立即生效。
:::

## 后端 DictService 调用

```php
use app\service\DictService;

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

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

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

// 获取完整字典项（含 id、sort、note）
$items = DictService::getFullItems('gender');

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