直接用 github.com/bradfitz/gomemcache，它是事实标准、维护活跃、api 稳定且轻量；其他客户端存在接口不兼容或连接复用缺陷，易引发 timeout 和 connection refused 错误。
Memcached 客户端选哪个：bradfitz/gomemcache 还是其他？
直接用 github.com/bradfitz/gomemcache，别换。它是事实标准，维护活跃（最新提交在 2026 年 4 月），API 稳定且轻量，没有多余抽象层。其他 fork 或新库要么接口不兼容，要么连接复用逻辑有 bug，线上踩过坑。
常见错误现象：memcache: server error: timeout 或大量 connection refused，多数是因为误用了非官方客户端导致连接池未正确复用，或未设置 Timeout 和 MaxIdleConns。
- 初始化时必须显式配置超时：
mc := memcache.New("10.0.1.10:11211")后立即调mc.Timeout = 500 * time.Millisecond - 高并发场景下，建议用
memcache.NewSelector()+ 多个节点，避免单点故障；不要依赖 DNS 轮询或手动拼接 host 字符串 - 它不支持自动重试，业务层需对
memcache.ErrServer做简单兜底（比如降级为直查 DB）
如何让 Memcached 支持结构体缓存？
Memcached 只认 []byte，所有结构体都得序列化。别自己写 json.Marshal + json.Unmarshal 散落在各处，统一封装成两个方法：SetJSON 和 GetJSON。
容易踩的坑：json 序列化私有字段会丢数据；结构体字段没加 json: tag 导致 key 名不一致；空指针解引用 panic。
- 务必确保结构体字段可导出（首字母大写），并显式声明 tag，例如
UserName string `json:"user_name"` -
GetJSON必须传入指针，否则反序列化失败不报错但值为空；示例：err := mc.GetJSON("user:123", &u) - 避免缓存
nil结构体——先判空再塞进Item.Value，否则json.Marshal(nil)得到null字节数组，取出来再Unmarshal会静默失败
集群扩容时 key 分布不均？检查一致性哈希配置
gomemcache 默认用的是简单哈希（hash(key) % len(servers)），不是一致性哈希。节点增减会导致几乎所有 key 重映射，缓存雪崩。
必须手动启用一致性哈希：用 memcache.NewSelector() 替代 memcache.New()，并调用 selector.AddServers("a:11211", "b:11211", "c:11211")。它底层使用 golang.org/x/exp/maps（Go 1.21+）或自研环形哈希，能保证 90%+ 的 key 在增减一个节点后仍命中原机器。
- 不要混用
New和NewSelector初始化的客户端实例，它们哈希逻辑不互通 - 节点地址必须完全一致（包括端口、域名 or IP），
"localhost:11211"和"127.0.0.1:11211"被视为两个不同节点 - 如果用 Kubernetes Service 做入口，确保 selector 的 endpoints 是真实 Pod IP + Port，而非 ClusterIP —— 否则哈希计算和实际路由脱节
为什么 Get 返回 “memcache: not found” 却没走 DB 回源？
这是最隐蔽的问题：你写了缓存回源逻辑，但 mc.Get 返回 memcache.ErrNotFound 时，业务代码却没触发加载，而是直接返回了空响应。根本原因常是错误地把 ErrNotFound 当成了连接错误处理。
gomemcache 对“key 不存在”和“网络失败”返回的是两个完全不同的 error 类型：memcache.ErrNotFound vs memcache.ErrServer。前者可安全回源，后者应熔断或降级。
- 永远用
errors.Is(err, memcache.ErrNotFound)判断缺失，而不是err == nil或strings.Contains(err.Error(), "not found") - 别在
Get后立刻return，先做 error 分支判断；尤其注意 defer 里有没有提前 return 掉回源路径 - 如果用了 groupcache 封装层，它的
GetterFunc内部对ErrNotFound是透明的，但你要确保底层mc.Get真的返回了这个 error —— 有些代理层（如 twemproxy）会把 not found 转成 generic error
实际部署时，Memcached 集群本身无状态，但客户端的一致性哈希配置、序列化方式、错误分类这三处一旦写错，问题往往延迟暴露，等流量上来才集中爆发。宁可多写两行判断，也不要靠“应该没问题”跳过校验。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
