本章概要

数据字典的完整使用流程，从新增字典类型到在代码中使用字典数据的实操指南。

数据字典使用指南

数据字典是项目的基础配置功能，用于管理枚举类型的下拉选项。本章从「如何新增字典」到「如何在代码中使用」的完整实操流程。

数据字典结构

数据字典由两层组成：

字典类型（dict）          字典项（dict_item）
├── sys_user_status       ├── 1 → 正常
├── sys_user_gender       ├── 2 → 停用
├── article_type          └── 3 → 删除
└── ...

层级	表	说明
字典类型	fastapi_dict	字典分类（如「用户状态」「文章类型」）
字典项	fastapi_dict_item	字典的具体选项（如「1-正常」「2-停用」）

实操：新增一个字典类型

场景

需要为「培训方式」模块添加一个下拉选项：1-线上 2-线下 3-混合。

第 1 步：在后台添加字典类型

登录管理后台，进入「系统管理 → 数据字典」：

1. 点击「新增」按钮
2. 填写信息：

字段	值
字典名称	培训方式
字典编码	training_method
状态	正常

3. 保存

第 2 步：添加字典项

在字典类型列表中点击「培训方式」，进入字典项管理：

1. 添加字典项：

字典值	字典标签	排序
1	线上	1
2	线下	2
3	混合	3

2. 保存

第 3 步：在模型中关联字典

在模块的 service.py 中配置 serialize_maps：

class TrainingService(BaseService[Training]):
    # ... 其他配置 ...
    
    # 枚举显示名映射：字段名 → 字典编码
    serialize_maps = {
        'training_method': 'training_method',
        'status': 'training_status',
    }

配置后，列表和详情接口会自动将 training_method=1 转换为 training_method_name='线上'。

在后端代码中使用

方式 1：通过 serialize_maps 自动转换（推荐）

在 service.py 中配置 serialize_maps，基类自动处理：

class TrainingService(BaseService[Training]):
    serialize_maps = {'training_method': 'training_method'}

效果：列表/详情返回数据中自动添加 trainingMethod 和 trainingMethodName 字段。

方式 2：手动获取字典值

from modules.dictionary.dict_item.repository import dict_item_repo

# 获取字典项列表
items = dict_item_repo.get_all(dict_code='training_method', status=1)

# 转为 {value: label} 字典
options = {item.value: item.label for item in items}
# 结果：{'1': '线上', '2': '线下', '3': '混合'}

方式 3：通过参数模块获取（适合系统配置）

from modules.param.service import param_service

# 获取参数值
timeout = param_service.get_value_by_code('REQUEST_TIMEOUT', '30')

在前端代码中使用

方式 1：字典下拉组件

<template>
  <el-select v-model="form.trainingMethod" placeholder="请选择培训方式">
    <el-option
      v-for="item in dictOptions"
      :key="item.value"
      :label="item.label"
      :value="item.value"
    />
  </el-select>
</template>

<script setup>
import { ref, onMounted } from 'vue';
import { getDictItems } from '@/api/system/dictionary';

const dictOptions = ref([]);

onMounted(async () => {
    const { data } = await getDictItems('training_method');
    dictOptions.value = data;
});
</script>

方式 2：表格列显示字典文本

在 columns.ts 中使用 render 函数：

import { h } from 'vue';
import { ElTag } from 'element-plus';

export const columns = [
    {
        label: '培训方式',
        prop: 'trainingMethod',
        render(record) {
            const map = { 1: '线上', 2: '线下', 3: '混合' };
            const typeMap = { 1: 'success', 2: 'warning', 3: 'info' };
            return h(ElTag, { type: typeMap[record.row.trainingMethod] }, {
                default: () => map[record.row.trainingMethod] || '-'
            });
        },
    },
];

方式 3：搜索表单下拉

在 querySchemas.ts 中配置：

export const schemas: FormSchema[] = [
    {
        field: 'trainingMethod',
        component: 'Select',
        label: '培训方式',
        componentProps: {
            placeholder: '请选择培训方式',
            clearable: true,
            options: [
                { label: '线上', value: '1' },
                { label: '线下', value: '2' },
                { label: '混合', value: '3' },
            ],
        },
    },
];

代码生成器与字典

代码生成器会自动识别字段注释中的枚举格式（1-线上 2-线下 3-混合），并：

1. 自动解析 choices 列表
2. 自动生成 dict_code（格式：{table_name}_{field_name}）
3. 自动配置 serialize_maps
4. 前端自动生成下拉选择框

生成后需在后台手动创建对应的字典类型和字典项。

字典缓存

项目使用进程内缓存 + Redis 二级缓存存储字典数据：

层级	说明	失效策略
L1 进程内缓存	Python 字典，TTL 60 秒	自动过期
L2 Redis 缓存	Redis 字符串，TTL 120 秒	自动过期 + 主动失效

字典数据修改时自动清除相关缓存。

字典管理 API

方法	路径	说明
GET	/api/v1/dict/page	字典类型分页
POST	/api/v1/dict/add	新增字典类型
PUT	/api/v1/dict/update	更新字典类型
DELETE	/api/v1/dict/delete/{id}	删除字典类型
GET	/api/v1/dictItem/page	字典项分页
POST	/api/v1/dictItem/add	新增字典项
PUT	/api/v1/dictItem/update	更新字典项
DELETE	/api/v1/dictItem/delete/{id}	删除字典项

最佳实践

1. 字典编码命名：使用 模块_字段 格式，如 user_status、article_type
2. 字典值使用整数：便于排序和比较，避免使用字符串
3. 字典标签简洁：控制在 4 个字以内，适合表格列显示
4. 状态字段统一：1-正常 2-停用 全项目保持一致
5. 生成后补充字典：代码生成器创建的 dict_code 需在后台手动创建对应数据

总结

数据字典通过「字典类型 + 字典项」两层结构管理枚举选项。后端通过 serialize_maps 自动转换，前端通过 API 获取下拉数据。代码生成器会自动识别注释中的枚举格式并生成对应配置。