数据字典

数据字典用于管理系统中的枚举值和配置项，如状态、类型、性别等。通过字典编码统一管理，前端可通过 useDictStore 获取字典选项，避免硬编码。模块位于 application/dict/。

模块结构

application/dict/
├── models.py       # 字典模型
├── forms.py        # 表单验证
├── services.py     # 业务逻辑层
├── views.py        # 视图层
└── urls.py         # 路由配置

application/dict_item/
├── models.py       # 字典项模型
├── forms.py        # 表单验证
├── services.py     # 业务逻辑层
├── views.py        # 视图层
└── urls.py         # 路由配置

字典模型

字典类型（Dict）

# application/dict/models.py
class Dict(BaseModel):
    """字典模型类"""
    class Meta:
        db_table = 'django_dict'

    name = models.CharField(max_length=150, verbose_name='字典名称')
    code = models.CharField(max_length=150, verbose_name='字典编码')
    sort = models.IntegerField(default=0, verbose_name='字典排序')
    note = models.CharField(max_length=255, null=True, blank=True, verbose_name='字典备注')

字典项（DictItem）

# application/dict_item/models.py
class DictItem(BaseModel):
    """字典项模型类"""
    class Meta:
        db_table = 'django_dict_item'

    name = models.CharField(max_length=150, verbose_name='字典项名称')
    value = models.CharField(max_length=150, verbose_name='字典项值')
    dict_id = models.IntegerField(default=0, verbose_name='字典ID')
    sort = models.IntegerField(default=0, verbose_name='字典项顺序')
    note = models.CharField(max_length=255, null=True, blank=True, verbose_name='字典项备注')

API 接口

字典管理

接口	方法	权限节点	说明
/dict/page	GET	sys:dict:page	字典分页列表
/dict/detail/<int:id>	GET	sys:dict:detail	字典详情
/dict/add	POST	sys:dict:add	新增字典
/dict/update	PUT	sys:dict:update	编辑字典
/dict/delete/<int:id>	DELETE	sys:dict:delete	删除字典

字典项管理

接口	方法	权限节点	说明
/dict/item/page	GET	sys:dictItem:page	字典项分页列表
/dict/item/detail/<int:id>	GET	sys:dictItem:detail	字典项详情
/dict/item/getDictItemList/{code}	GET	需登录	按编码获取字典项
/dict/item/add	POST	sys:dictItem:add	新增字典项
/dict/item/update	PUT	sys:dictItem:update	编辑字典项
/dict/item/delete/<int:id>	DELETE	sys:dictItem:delete	删除字典项

后端获取字典

# 通过字典编码获取字典项列表
from application.dict_item import services as dict_item_services

# 获取状态字典
status_list = dict_item_services.get_by_dict_code("sys_status")
# 返回: [{"label": "正常", "value": "1"}, {"label": "停用", "value": "2"}]

前端使用

前端通过 useDictStore 获取字典数据：

import { useDictStore } from '@/store/dict'

const dictStore = useDictStore()

// 获取字典选项
const statusOptions = dictStore.getDict('sys_status')
// [{label: "正常", value: "1"}, {label: "停用", "value": "2"}]

在组件中使用

<template>
    <!-- el-select 下拉选择 -->
    <el-select v-model="form.status" placeholder="请选择状态">
        <el-option
            v-for="item in statusOptions"
            :key="item.value"
            :label="item.label"
            :value="item.value"
        />
    </el-select>

    <!-- el-tag 标签展示 -->
    <el-tag v-if="form.status === '1'">正常</el-tag>
    <el-tag v-else type="danger">停用</el-tag>
</template>

字典缓存

前端字典数据通过 Pinia Store 缓存，首次获取后缓存在内存中：

// store/dict.ts
export const useDictStore = defineStore('dict', {
    state: () => ({
        dictMap: new Map<string, any[]>(),
    }),
    actions: {
        async getDict(code: string) {
            if (this.dictMap.has(code)) {
                return this.dictMap.get(code);
            }
            const res = await getDictItemList(code);
            this.dictMap.set(code, res);
            return res;
        },
        // 清除缓存（字典数据变更时调用）
        clearDict() {
            this.dictMap.clear();
        }
    }
});

常用字典示例

字典编码	说明	字典项
sys_status	系统状态	正常(1)、停用(2)
sys_gender	性别	男(1)、女(2)
operation_type	操作类型	新增(1)、修改(2)、删除(3) 等
menu_type	菜单类型	菜单(0)、节点(1)

Redis 缓存机制

字典数据支持 Redis 缓存，减少数据库查询：

1. 首次查询：从数据库读取 → 写入 Redis 缓存 → 返回
2. 后续查询：从 Redis 缓存读取 → 返回
3. 数据变更：更新数据库 → 清除 Redis 缓存
4. 缓存 Key：dict:{code}，如 dict:sys_status

总结

数据字典模块具备以下特点：

1. 两级结构：字典类型（分组）+ 字典项（具体值），清晰管理
2. 前端集成：useDictStore 统一管理，el-select 直接绑定
3. 值为字符串：字典项 value 统一为字符串类型
4. 避免硬编码：枚举值统一走字典，修改无需改代码
5. Redis 缓存：减少数据库查询，提升性能
6. 批量导入导出：支持 Excel 批量导入字典项