字典缓存工具

说明

src/common/utils/dict_util.py 提供业务字典的缓存读取能力，从 Redis 缓存中获取字典数据，缓存未命中时从数据库加载。字典维护时自动失效缓存。

核心接口

get_dict_data — 获取字典下拉数据

from common.utils.dict_util import get_dict_data

# 获取字典编码对应的下拉选项列表
options = get_dict_data("link_type")
# 返回: [{"label": "友情链接", "value": "1"}, {"label": "合作伙伴", "value": "2"}]

get_dict_label — 获取字典项标签

from common.utils.dict_util import get_dict_label

# 根据字典编码和值获取显示标签
label = get_dict_label("link_type", "1")
# 返回: "友情链接"

get_dict_map — 获取字典值→标签映射

from common.utils.dict_util import get_dict_map

# 获取字典编码的值→标签映射字典
mapping = get_dict_map("link_type")
# 返回: {"1": "友情链接", "2": "合作伙伴"}

缓存策略

1. 读取 Redis 缓存: dict:{code}
   ├─ 命中 → 直接返回
   └─ 未命中 → 从 DB 查询 → 写入 Redis → 返回
2. 字典维护（增删改）→ 删除 Redis 缓存 → 下次读取时自动重建

Redis Key 设计

Key	说明	TTL
dict:{code}	字典编码对应的选项列表	不过期（主动失效）
dict:version	字典版本号（缓存失效触发器）	不过期

缓存失效

字典数据变更时，通过递增版本号使所有缓存失效：

def invalidate_dict_cache():
    """字典数据变更时调用，递增版本号使缓存失效。"""
    redis = get_redis()
    redis.incr("dict:version")

在 BaseService 中使用

通过 serialize_maps 声明字段→字典编码映射，序列化时自动转换：

class LinkService(BaseService):
    serialize_maps = {
        "type": "link_type",    # type 字段按 link_type 字典解析
        "form": "link_form",    # form 字段按 link_form 字典解析
    }

序列化时自动将 type="1" 转换为 type_label="友情链接"。

与字典模块的关系

模块	职责
modules/dictionary/	字典数据的 CRUD 维护
common/utils/dict_util.py	字典数据的缓存读取

字典维护接口在增删改时自动调用 invalidate_dict_cache()，读取端无需关心缓存一致性。

使用场景

场景一：Service 序列化自动转换

通过 serialize_maps 声明字段→字典编码映射，列表/详情序列化时自动追加 xxxText 字段：

class LinkService(BaseService):
    serialize_maps = {
        "type": "link_type",    # type → typeText
        "form": "link_form",    # form → formText
    }

序列化结果：

{
    "id": 1,
    "name": "小蚂蚁云",
    "type": "1",
    "typeText": "友情链接",
    "form": "2",
    "formText": "后台添加"
}

场景二：Handler 下拉接口

class DictDataHandler(BaseHandler):
    async def get(self, code):
        """GET /api/v1/dict/data/{code}"""
        items = get_dict_data(code)
        return R.ok(self, data=items)

前端调用：

const res = await request({ url: '/api/v1/dict/data/link_type' });
// res.data: [{"label": "友情链接", "value": "1"}, {"label": "合作伙伴", "value": "2"}]

场景三：后端业务校验

def _before_add(self, handler, data):
    """新增前校验：字典值是否合法"""
    valid_types = get_dict_map("link_type")
    if str(data.get("type")) not in valid_types:
        raise ValidationError("链接类型不合法")

场景四：导出 Excel 翻译

def get_export_data(self, handler):
    items = self.repo.all()
    type_map = get_dict_map("link_type")
    result = []
    for item in items:
        result.append({
            "name": item.name,
            "type": type_map.get(str(item.type), "未知"),  # 数字→中文
        })
    return result

总结

字典缓存工具提供 get_dict_data、get_dict_label、get_dict_map 三个核心接口，基于 Redis 缓存实现高性能读取。字典维护时通过版本号机制自动失效缓存，保证数据一致性。广泛用于 Service 序列化、下拉接口、业务校验、导出翻译等场景。