因为context.WithValue写入的Go值仅存于当前进程内存，不会序列化到网络请求中，下游服务收到的是全新context，值必然为空；必须用metadata.MD透传，它是gRPC协议层定义的跨进程键值对容器。
gRPC Metadata 为什么不能用 context.WithValue 传
因为 context.WithValue 写进去的任意 Go 值（比如 *User、map[string]interface{}）只存在于当前进程内存，不会被序列化进网络请求。下游服务收到的是全新初始化的 context.Context，你“以为传过去”的值根本不存在。
常见错误是中间件里写 ctx = context.WithValue(ctx, userKey, u)，然后 handler 直接 ctx.Value(userKey) 取——这在单服务内能跑通，一跨 gRPC 就空指针或 panic。
- 鉴权、TraceID、租户 ID 等必须走
metadata.MD，它是 gRPC 协议层定义的、可跨进程透传的键值对容器 -
context.WithValue仅适合本进程内短链路传递（如日志打标、指标埋点），且务必做类型断言和空值判断 - 如果真要传结构化数据，拆成多个
metadata.Pairs("user-id", "123", "user-role", "admin")，服务端再组装
客户端怎么正确注入 metadata 到 outgoing context
别用 md.Set("key", "value") 直接写原始 map——它不校验 key 大小写、不防重复覆盖、也不支持多值，线上容易因大小写不一致（如 "Authorization" vs "authorization"）导致取不到值。
正确做法是始终用 metadata.Pairs() 构造初始 metadata.MD，再用 metadata.AppendToOutgoingContext() 注入：
立即学习“go语言免费学习笔记（深入）”；
md := metadata.Pairs(
"x-request-id", reqID,
"tenant-id", tenant,
"env", "prod",
)
ctx = metadata.AppendToOutgoingContext(ctx, md)
-
AppendToOutgoingContext内部会把metadata.MD绑定到 gRPC transport 层，确保序列化进 HTTP/2 headers - 不要用
metadata.NewOutgoingContext替代——它会丢弃原ctx中已有的 deadline/cancel 信号，破坏超时控制 - 敏感字段（如 token）建议加
"grpc-encoding"前缀，避免默认 gRPC 日志明文 dump
服务端为什么 metadata.FromIncomingContext 有时返回 nil
不是所有 incoming context.Context 都带 metadata——只有真正由 gRPC transport 解析过的请求才附带。常见于：中间件没把 ctx 传给 handler、handler 函数用了错误的 ctx 参数、或单元测试时直接 context.Background() 模拟。
提取前必须先判空，不能假设一定存在：
md, ok := metadata.FromIncomingContext(ctx)
if !ok {
return status.Error(codes.Unauthenticated, "missing metadata")
}
authHeader := md["authorization"] // 注意小写
if len(authHeader) == 0 {
return status.Error(codes.Unauthenticated, "empty authorization header")
}
- gRPC metadata key 默认转为小写，
"Authorization"发过去后服务端必须用"authorization"取 -
md["key"]返回[]string，取[0]前务必检查长度 - HTTP/1.1 + gRPC-Gateway 场景下，需显式配置
runtime.WithMetadata()回调，把http.Request.Header转成metadata.MD
跨多个 gRPC 跳转（A→B→C）时 metadata 怎么不中断
metadata.MD 只在单次 RPC 调用中有效，不会自动跨链路传播。A 发给 B 的 metadata，B 收到后如果不主动读取、修改、再透传，C 就完全收不到。
B 服务必须在 handler 或 interceptor 中完成三步操作：
- 从入参
ctx提取：md, ok := metadata.FromIncomingContext(ctx) - 必要时追加或改写：
md = metadata.Pairs("x-b-service", "true", "x-upstream-id", md["x-request-id"][0]) - 注入发往 C 的
ctx：ctx = metadata.AppendToOutgoingContext(ctx, md)
漏掉任何一步，链路就断了。实际项目里最容易忽略的是“B 不动 metadata 直接透传”这个动作——尤其当 B 只是简单转发、没做鉴权或日志时，开发者常误以为“没改就不需要处理”。
