全局缓存键规范要求结构为{domain}:{resource}:{version}:{params_signature}，强制分段、语义清晰、长度≤39字节、仅含小写字母数字和冒号，租户与环境需显式嵌入，支持解析追溯。
构建一个标准化、高复用性的全局通用缓存键设计规范，核心在于让键具备唯一性、可读性、可追溯性与环境隔离能力，同时兼顾性能和运维友好性。它不是命名习惯的汇总，而是系统级契约——不同服务、不同团队、不同时间写入或读取缓存时，都能无歧义地生成和解析同一个键。
统一结构：强制分段 + 语义清晰
所有缓存键必须采用固定分段格式，推荐使用冒号（:）作为分隔符，结构为：
{domain}:{resource}:{version}:{params_signature}
-
domain：业务域标识，如
user、order、rag，避免模糊缩写（如u或ord） -
resource：资源类型，对应具体实体或操作，如
profile、search_result、embedding -
version：数据协议或逻辑版本，如
v1、schema_2026q2，用于灰度升级或格式变更后自动隔离旧缓存 -
params_signature：参数摘要，非原始拼接。对关键输入字段（如
tenant_id、query、top_k）做结构化排序后哈希（推荐SHA-256前8位或MD5前6位），确保相同语义输入总生成一致签名
示例：rag:chunk_retrieval:v2:9a3f7c 或 user:profile_summary:v1:4d8e2b
长度与字符：严控边界，规避底层陷阱
单个键长度严格限制在39字节以内（Redis嵌入式字符串优化阈值）。超长键不仅降低访问性能，还可能触发序列化异常或日志截断。
- 禁止空格、引号、换行、逗号、分号等特殊字符
- 仅允许小写字母、数字、英文冒号（
:） - 避免纯数字ID前置（如
12345:profile），易与整型键混淆；统一加前缀，如uid12345:profile - 哈希摘要建议截取6–8位十六进制字符，平衡唯一性与长度
租户与环境隔离：键内自带上下文
多租户或多环境系统中，不能依赖外部上下文推断归属。租户ID、环境标识（如prod、staging）必须显式纳入键结构，而非靠命名空间或连接池区分。
- 推荐将
tenant_id作为第一段，如：tenant_abc:rag:search:v1:7f2a1e - 若需跨环境共用缓存（如预热），则把环境作为
domain一部分：staging_user:profile:v1:5c9d3a - 禁止通过Redis库编号（DB 0/1/2）做逻辑隔离——库号是运维维度，不是数据语义维度
可追溯性：支持反向解析与问题定位
每个键应能直接映射回其生成逻辑、所属模块和关键参数，便于线上问题排查。
- 提供标准解析工具函数（如
parse_cache_key(key)），返回结构化字典：{"tenant": "abc", "resource": "search", "version": "v1", "hash": "7f2a1e"} - 在日志或监控中，对缓存未命中/击穿事件自动打点并记录完整键及解析结果
- 定期扫描缓存中高频键前缀，识别未按规范注册的“野键”，推动治理
