gRPC Metadata 是什么，为什么不能直接当 context.Value 用
Metadata 本质是 HTTP/2 headers 的封装，只在 RPC 调用发起和响应时传输，不是进程内上下文。它不跨 goroutine 自动传播，也不随 context.WithValue 继承——你往 client context 里塞了东西，server 端收不到，除非显式写进 Metadata。
常见错误现象：context.WithValue(ctx, key, val) 后在 server 端用 ctx.Value(key) 取不到；或者误以为 metadata.Pairs("auth", "token") 能自动透传到下游服务（实际只传给直连的下一个服务）。
- Metadata 只在一次 RPC 调用生命周期内有效，不会“粘”在 context 上长期存活
- 必须用
metadata.MD类型构造，并通过grpc.Header()/grpc.Trailer()显式注入或提取 - 键名默认小写+中划线（如
"user-id"），大写或下划线会被 gRPC 自动标准化，导致取值失败
如何安全地在 client 端注入 Metadata 并确保 server 端能读到
关键不在“怎么塞”，而在“塞进哪个 context”——必须用 metadata.AppendToOutgoingContext，而不是自己 new 一个 context 或改原始 ctx。
使用场景：鉴权 token、请求 ID、灰度标签、租户 ID 等需要透传的轻量元数据。
立即学习“go语言免费学习笔记（深入）”；
// client 端正确写法
md := metadata.Pairs(
"x-request-id", reqID,
"tenant-id", tenant,
"env", "prod"
)
ctx = metadata.AppendToOutgoingContext(ctx, md...)
- 不要用
context.WithValue模拟 Metadata，server 端根本收不到 -
AppendToOutgoingContext内部会把 Metadata 绑定到 gRPC 的 transport 层，确保序列化进 header - 如果调用链涉及多个 gRPC 跳转（A→B→C），B 必须手动从入参 ctx 提取 Metadata，再重新 append 到发给 C 的 ctx 中，否则中断
- 敏感字段（如 token）建议加
"grpc-encoding"前缀规避日志明文打印，默认 gRPC 日志会 dump 所有 Metadata
server 端如何可靠提取 Metadata，为什么 metadata.FromIncomingContext 有时返回 nil
不是所有 incoming context 都带 Metadata——只有真正由 gRPC transport 解析过的 context 才有。常见于：中间件没传 ctx、handler 函数用了错误的 ctx 参数、或测试时直接 new context。
错误现象：metadata.FromIncomingContext(ctx) 返回 (nil, false)，但你知道 client 明明传了。
- 确认 handler 函数签名是否为
func(ctx context.Context, req *pb.Xxx) (*pb.Yyy, error)，且调用时传的是框架传入的ctx，不是自己context.Background()构造的 - 检查中间件是否无意中替换了 ctx（比如用了
context.WithValue但没保留原始 Metadata） - 提取后立即做
md.Get("key")，注意Get返回[]string，单值也得取[0]，空切片容易 panic - Metadata 键名区分大小写？不区分——gRPC 强制转小写，
md.Get("X-Request-ID")和md.Get("x-request-id")效果一样
Metadata 性能与边界：什么时候该换方案
Metadata 本质是 HTTP/2 header，受协议限制：单个 key-value 对最大约 8KB，整条请求 header 总大小通常不超过 64KB（取决于 server 配置）。超限会直接触发 StatusCode=ResourceExhausted。
性能影响：每次 RPC 都要序列化/反序列化 map[string][]string，大量小字段比少量大字段更耗 CPU；频繁修改 Metadata（如每毫秒更新 trace id）也会增加分配压力。
- 不要传结构体 JSON 字符串——用 proto message +
Any更稳妥，或走 payload 字段 - 高频变更字段（如计数器、时间戳）不适合放 Metadata，考虑用 streaming 的 header frame 或单独 metrics 接口
- 跨语言调用时，Java/Python 客户端对 Metadata 键名标准化行为略有差异，统一用小写+中划线最保险
- 调试时可用
grpc.EnableTracing = true+grpclog.SetLoggerV2查看实际收发的 header，比猜强
Metadata 不是万能的上下文总线，它只是 gRPC 协议层的一次性信封。用对地方省事，用错地方连 trace 都断掉。
