不能直接用 context.WithValue 存 IP 字符串，因 string 类型 key 全局可见易冲突，且 HTTP 真实 IP 需从 X-Real-IP/X-Forwarded-For 解析而非 RemoteAddr；应定义未导出类型如 clientIPKey{} 作 key，清洗后存字符串，并用 v, ok := ctx.Value(clientIPKey{}).(string) 安全读取。
为什么不能直接用 context.WithValue 存 IP 字符串
很多人第一反应是 ctx = context.WithValue(ctx, "clientIP", ip)，但这样既不类型安全，又容易被覆盖或误读。Go 官方文档明确建议：key 必须是自定义类型（非 string 或 int），否则不同包之间可能意外冲突。更关键的是，HTTP 层面的客户端 IP 并非总在 RemoteAddr 里——反向代理（如 Nginx、Cloudflare）会把真实 IP 放在 X-Forwarded-For 或 X-Real-IP 头中，直接取 req.RemoteAddr 往往拿到的是代理的内网地址。
怎么安全地定义和注入 IP key
定义一个未导出的私有类型作 key，避免外部篡改或误用：
type clientIPKey struct{}
在中间件中解析并写入 Context：
- 优先检查
X-Real-IP（Nginx 常用） - fallback 到
X-Forwarded-For的第一个非私有 IP（注意要校验格式和范围） - 最后才用
req.RemoteAddr（仅当无可信头时） - 务必做 IP 格式清洗，比如去掉端口（
127.0.0.1:54231→127.0.0.1）
示例中间件：
func WithClientIP(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
ip := r.Header.Get("X-Real-IP")
if ip == "" {
if xff := r.Header.Get("X-Forwarded-For"); xff != "" {
parts := strings.Split(xff, ",")
ip = strings.TrimSpace(parts[0])
}
}
if ip == "" {
ip, _, _ = net.SplitHostPort(r.RemoteAddr)
}
ctx := context.WithValue(r.Context(), clientIPKey{}, ip)
r = r.WithContext(ctx)
next.ServeHTTP(w, r)
})
}
怎么从 Context 中安全读取 IP
读取必须用相同 key 类型，并做类型断言判断是否成功：
ip, ok := r.Context().Value(clientIPKey{}).(string)
if !ok {
// key 不存在或类型不对，说明中间件没执行或被覆盖
log.Warn("client IP not found in context")
return
}
常见错误：
- 用
context.WithValue(ctx, "ip", ...)然后用ctx.Value("ip")—— key 类型不匹配，永远返回nil - 忽略
ok判断，直接解包.string导致 panic - 在中间件外（比如 handler 里）手动调用
WithValue覆盖了上游设置的值
为什么不要在 Context 里传结构体或 net.IP
net.IP 看似更“标准”，但实际带来额外负担：
- 每次都要调用
net.ParseIP，失败需处理错误 - 序列化/日志打印时仍得转成字符串，不如一开始就存规范格式字符串
- Context 是轻量传递机制，不是数据容器；IP 字符串已足够表达语义，无需强类型约束
真正需要强类型的场景（如权限校验依赖 IP 段），应在业务逻辑层解析，而非塞进 Context。
最常被忽略的一点：如果你的应用跑在 Kubernetes Ingress 或 ALB 后面，确认它们是否透传了 X-Real-IP；没配置的话，所有 X-* 头都会是空的，最终 fallback 到 RemoteAddr 就是集群内部地址（如 10.244.1.3），根本不是用户真实出口 IP。
