4. 缓存Key设计规范：命名空间、版本号、参数序列化、避免Key冲突与过长Key

缓存 Key 的设计是缓存系统的第一道防线。一个设计不良的 Key 可能导致数据污染、缓存穿透、内存浪费甚至系统雪崩。本节从命名空间、版本号、参数序列化、冲突避免与长度控制四个维度，给出 Go 项目中的落地规范。

4.1 命名空间：隔离业务与模块

命名空间是 Key 的第一级前缀，用于区分不同业务线、模块或租户。在微服务架构中，多个服务共享同一 Redis 集群时，命名空间可以避免 Key 冲突。

推荐格式：业务线:模块:子模块:具体标识

// Go 命名空间常量定义
const (
    NamespaceOrder   = "order"
    NamespaceUser    = "user"
    NamespaceProduct = "product"
)

// 构建 Key 函数
func BuildOrderDetailKey(orderID int64) string {
    return fmt.Sprintf("%s:detail:%d", NamespaceOrder, orderID)
}

4.2 版本号：平滑迁移与数据兼容

当缓存数据结构发生变化（如新增字段、修改序列化方式）时，旧缓存数据可能无法被新代码正确解析。版本号机制允许新旧 Key 共存，实现平滑迁移。

• 显式版本号：在 Key 中嵌入 v1、v2 等标识
• 隐式版本号：通过命名空间变更实现版本隔离
• 双写双读策略：迁移期间同时写入新旧 Key，逐步淘汰旧 Key

// 版本号常量
const (
    CacheVersionV1 = "v1"
    CacheVersionV2 = "v2"
)

// 带版本的 Key 构建
func BuildUserProfileKey(userID int64, version string) string {
    return fmt.Sprintf("user:profile:%s:%d", version, userID)
}

// 迁移期间同时读取新旧 Key
func GetUserProfile(ctx context.Context, userID int64) (*UserProfile, error) {
    // 优先读取新版本
    newKey := BuildUserProfileKey(userID, CacheVersionV2)
    if data, err := redis.Get(ctx, newKey).Bytes(); err == nil {
        return deserialize(data)
    }
    // 回退到旧版本
    oldKey := BuildUserProfileKey(userID, CacheVersionV1)
    if data, err := redis.Get(ctx, oldKey).Bytes(); err == nil {
        return deserialize(data)
    }
    return nil, ErrCacheMiss
}

4.3 参数序列化：保证 Key 的唯一性与可读性

当 Key 包含多个参数时，需要将参数序列化为字符串。序列化方式直接影响 Key 的唯一性、长度和可读性。

// 推荐：排序后拼接 + 哈希（适用于参数较多场景）
func BuildCacheKey(prefix string, params map[string]string) string {
    keys := make([]string, 0, len(params))
    for k := range params {
        keys = append(keys, k)
    }
    sort.Strings(keys)

    var sb strings.Builder
    sb.WriteString(prefix)
    sb.WriteString(":")
    for _, k := range keys {
        sb.WriteString(k)
        sb.WriteString("=")
        sb.WriteString(params[k])
        sb.WriteString("&")
    }
    key := sb.String()[:sb.Len()-1]

    // 如果 Key 过长，使用 MD5 缩短
    if len(key) > 128 {
        return fmt.Sprintf("%s:hash:%x", prefix, md5.Sum([]byte(key)))
    }
    return key
}

4.4 避免 Key 冲突与过长 Key

Key 冲突会导致数据覆盖或读取错误；Key 过长会浪费内存、降低查询性能。以下是常见问题与解决方案。

4.4.1 Key 冲突场景

• 不同业务使用相同 Key 前缀：通过命名空间隔离
• 参数顺序不同导致不同 Key：使用排序后拼接
• 不同数据类型使用相同 Key：在 Key 中标注数据类型

4.4.2 Key 过长问题

// 避免 Key 过长的实用函数
func SafeCacheKey(parts ...string) string {
    var sb strings.Builder
    for i, part := range parts {
        if i > 0 {
            sb.WriteByte(':')
        }
        // 对过长部分进行截断或哈希
        if len(part) > 64 {
            sb.WriteString(fmt.Sprintf("%x", md5.Sum([]byte(part))[:8]))
        } else {
            sb.WriteString(part)
        }
    }
    return sb.String()
}

4.5 缓存 Key 设计规范总览

以下 SVG 图展示了从参数输入到最终 Key 生成的完整流程，包含命名空间、版本号、序列化与长度控制四个关键环节。

4.6 常见错误与避坑指南