215 lines
6.1 KiB
Markdown
215 lines
6.1 KiB
Markdown
# 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>
|
||
<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>
|
||
```
|
||
|
||
### 多个字典批量获取
|
||
|
||
```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(); // 清除所有字典
|
||
```
|