灰度发布的核心是流量路由，需在HTTP或RPC入口实时判定请求特征并导向不同版本实例，关键在于依据Header等字段轻量打标而非服务拆分或Nginx分流。
灰度发布的核心是流量路由，不是服务拆分
Golang 本身不内置灰度能力，关键在于在 HTTP 或 RPC 入口处对请求做实时判定，并将流量导向不同版本的服务实例。重点不在“用什么框架”，而在于“依据什么字段做决策”和“如何保证判定逻辑轻量、可配置、不拖慢主链路”。
常见误判是把灰度等同于“启动两套服务再配 Nginx 分流”——这无法支持用户 ID、设备号、Header、Query 参数等动态条件，也难做实时开关和比例调控。
-
Header（如X-User-Id、X-Device-Id）最常用，客户端可控且不侵入业务 URL -
Cookie适合 Web 场景，但需注意 SameSite 和跨域限制 -
Query（如?beta=1）调试方便，但不宜长期用于生产 - 避免用
IP做灰度依据：NAT、CDN、移动网络下 IP 复用率高，稳定性差
用 Gin + 中间件实现基于 Header 的灰度路由
Gin 是 Golang 最常用的 Web 框架，中间件机制天然适合插入灰度逻辑。核心是提前读取请求特征，设置一个可被下游使用的标记（如 ctx.Value），再由反向代理或服务发现层据此转发。
不建议在中间件里直接做转发（比如用 http.Redirect），那会破坏长连接、丢失原始 body、干扰 trace 上下文。灰度中间件只负责“打标”，转发交给统一网关或 sidecar。
立即学习“go语言免费学习笔记（深入）”；
func GrayMiddleware() gin.HandlerFunc {
return func(c *gin.Context) {
userID := c.GetHeader("X-User-Id")
version := "v1"
if userID != "" {
hash := fnv.New32a()
hash.Write([]byte(userID))
if hash.Sum32()%100 < 20 { // 20% 用户走 v2
version = "v2"
}
}
// 写入 context，供后续 handler 或 proxy 使用
c.Set("gray-version", version)
c.Header("X-Gray-Version", version) // 同时透传给下游
c.Next()
}
}
- 用
fnv哈希保证同一用户始终落在同一灰度组，避免来回跳变 - 比例控制用
%100 而非rand.Float64() ：后者每次请求都重算，无法保证用户一致性 -
c.Set只在当前请求生命周期有效；若需跨 goroutine（如异步日志、metric 上报），改用context.WithValue
gRPC 场景下用 UnaryServerInterceptor 控制灰度
gRPC 没有 Header 概念，但有 metadata.MD，它在传输层等价于 HTTP Header。灰度判断逻辑和 HTTP 类似，只是提取方式不同。
注意：gRPC 的 metadata 是字符串 map，所有值都是 []string，取值必须用 Get 并处理空切片。
func GrayUnaryInterceptor() grpc.UnaryServerInterceptor {
return func(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error) {
md, ok := metadata.FromIncomingContext(ctx)
if !ok {
return handler(ctx, req)
}
userIDs := md.Get("x-user-id")
if len(userIDs) == 0 {
return handler(ctx, req)
}
userID := userIDs[0]
hash := fnv.New32a()
hash.Write([]byte(userID))
version := "v1"
if hash.Sum32()%100 < 15 {
version = "v2"
}
// 注入到 outbound context，供下游服务读取
newCtx := context.WithValue(ctx, "gray-version", version)
return handler(newCtx, req)
}
}
- 不要在 interceptor 里修改
md后调用metadata.NewOutgoingContext再传给handler：这会覆盖原 metadata，导致认证 token 等关键字段丢失 - 下游服务读取
gray-version时，应统一从context.Value取，而非再次解析 metadata - 若使用 gRPC-Gateway，HTTP 请求的
X-User-Id会自动映射为 gRPC metadata 中的x-user-id，大小写自动转换
灰度开关必须支持运行时热更新，不能重启生效
硬编码比例或白名单在上线后就失去意义。真实场景中，灰度策略需要随时调整：比如 v2 版本出现 panic，要立刻切回 0%；或者运营活动期间临时提升到 80%。
推荐用本地文件 + fsnotify 监听，或对接 Consul/etcd。避免每次请求都查 Redis——QPS 高时会成为瓶颈，也增加故障面。
- 配置结构示例：
{"version": "v2", "percent": 10, "whitelist": ["u_1001", "u_2002"]} - 监听文件变化后，用
sync.RWMutex保护配置变量，读多写少场景下性能足够 - 首次加载失败不能 panic，应 fallback 到默认策略（如全走 v1），并记录 warn 日志
- 务必加指标：灰度命中数、v1/v2 调用量、配置加载失败次数——没监控的灰度等于裸奔
