Go map 如何从请求参数走到缓存：校验、键设计与过期清理

商品列表接口偶尔把不同筛选条件读成同一份结果，排查后常见的根因不是缓存服务挂了，而是请求参数进入 Go map 后，键的顺序和内容没有被稳定地表达出来。下面用一个小型筛选缓存把这条链路拆开：先收住输入，再生成确定性的键，最后验证过期清理真的发生。

缓存键要表达“业务上相同的查询”，不能直接依赖 map 的遍历顺序；参数校验、排序编码和过期回收要分别验证。

问题从哪里开始：同一个筛选条件出现两个键

接口接收的是品牌、价格区间和排序方式。最初的实现把参数放到 map[string]string，然后拼接成缓存键。测试数据量少时一切正常，上线后却出现同样的请求偶尔 miss。

func cacheKey(params map[string]string) string {
    var b strings.Builder
    for k, v := range params {
        b.WriteString(k)
        b.WriteByte('=')
        b.WriteString(v)
        b.WriteByte('&')
    }
    return "goods:" + b.String()
}

这里的问题不是 map 不能遍历，而是遍历顺序不应承担业务语义。两个内容相同、插入顺序不同的 map，可能得到不同的字符串。缓存就会把它们当成两次查询。

先收住输入：map 只是容器，不是校验器

进入缓存前先定义允许的字段和边界。以商品筛选为例，品牌最多 32 个字符，页码必须在 1 到 1000 之间，排序只接受白名单值。未知字段直接拒绝，避免调用方把无关参数带进键空间。

var allowedSort = map[string]bool{
    "price_asc":  true,
    "price_desc": true,
    "newest":     true,
}

func validateQuery(q map[string]string) error {
    for k, v := range q {
        switch k {
        case "brand":
            if utf8.RuneCountInString(v) > 32 { return errors.New("brand too long") }
        case "page":
            n, err := strconv.Atoi(v)
            if err != nil || n  1000 { return errors.New("invalid page") }
        case "sort":
            if !allowedSort[v] { return errors.New("invalid sort") }
        default:
            return fmt.Errorf("unknown query field: %s", k)
        }
    }
    return nil
}

校验通过只说明参数可以参与业务处理，不代表它已经适合拼进缓存键。空值是否等价于缺省值，也要在这里明确归一化，否则 brand= 和没有 brand 可能形成两份缓存。

存储模型要稳定：排序后再编码成键

键生成的目标是让业务等价的请求得到相同结果。做法很直接：提取键名、排序，再按固定顺序拼接；值使用 URL 编码或长度前缀，避免分隔符出现在用户输入里。

func stableKey(q map[string]string) (string, error) {
    if err := validateQuery(q); err != nil { return "", err }
    keys := make([]string, 0, len(q))
    for k := range q { keys = append(keys, k) }
    sort.Strings(keys)

    var b strings.Builder
    b.WriteString("goods:v1:")
    for _, k := range keys {
        b.WriteString(url.QueryEscape(k))
        b.WriteByte('=')
        b.WriteString(url.QueryEscape(strings.TrimSpace(q[k])))
        b.WriteByte('&')
    }
    return b.String(), nil
}

版本前缀值得保留。将来字段含义变化时，使用 goods:v2: 可以让旧键自然失效，不必先扫描全库删除。

查询路径里的三个检查点

缓存调用不要只记录“命中率”。一次请求至少能区分：键生成失败、缓存 miss 后回源、写入成功。日志里记录键版本和字段数量即可，不要把用户输入原样打进日志。

key, err := stableKey(query)
if err != nil {
    return nil, fmt.Errorf("build cache key: %w", err)
}
if value, ok := cache.Get(ctx, key); ok {
    metrics.CacheHit.Inc()
    return value, nil
}
metrics.CacheMiss.Inc()
value, err := loadGoods(ctx, query)
if err != nil { return nil, err }
if err := cache.Set(ctx, key, value, 10*time.Minute); err != nil {
    return value, fmt.Errorf("cache set: %w", err)
}
return value, nil

这里的策略是“回源成功才写缓存”。如果把空结果或半成品也写入缓存，短暂的上游故障就可能被放大成十分钟的错误命中。

过期不是删除按钮：如何确认旧键真的退出

TTL 到期通常由缓存服务惰性删除或后台清理完成，应用侧不能假设设置成功就立刻从存储中消失。验证时用一个很短的测试 TTL：先写入并读取一次，等待服务端报告过期，再读取一次确认 miss，同时检查回源是否只发生一次。

cache.Set(ctx, "test:goods:v1", []byte("ok"), 2*time.Second)
if _, ok := cache.Get(ctx, "test:goods:v1"); !ok {
    t.Fatal("value should exist before ttl")
}
// 在测试中使用可控时钟或等待 TTL 结束
if _, ok := cache.Get(ctx, "test:goods:v1"); ok {
    t.Fatal("expired value must miss")
}

生产环境更应该观察过期键数量、内存回收和 miss 后回源耗时。若键数量持续增长，优先检查是否把用户无意义的参数全量编码进键，而不是先把 TTL 调得更短。

常见问题：map 缓存实现容易踩哪些坑

为什么不能直接把 map 转成字符串做键？

map 没有业务顺序保证，直接遍历会让相同内容产生不同键。排序键名并固定编码后，键才具备可重复性。

缓存键需要把页码放进去吗？

如果分页结果不同，就必须放进去；也可以缓存不分页的稳定结果，再在应用侧分页。关键是先确定缓存对象的边界。

map 在多个 goroutine 间能直接读写吗？

不能把普通 map 当作并发容器。并发读写会触发运行时错误或数据竞争；构建好只读快照后再共享，或使用互斥保护、专用并发结构。

最后的验收清单

用两组字段顺序不同但业务含义相同的请求测试键是否一致；用一个未知字段测试校验是否拒绝；再用短 TTL 验证过期后的 miss 和回源次数。三项都通过后，map 才算完成了从请求容器到缓存键输入的职责，而不是把不确定性继续传给缓存层。