全局缓存键规范要求结构为{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"}
• 在日志或监控中，对缓存未命中/击穿事件自动打点并记录完整键及解析结果
• 定期扫描缓存中高频键前缀，识别未按规范注册的“野键”，推动治理