kratos中metadata需显式注入context才能透传至grpc请求头：调用metadata.appendtooutgoingcontext包装ctx，否则服务端收不到；服务端须主动校验md.get("key")非空，避免panic；跨语言需统一小写横线命名并控制总大小在8kb内。
Metadata 在 Kratos 中如何被自动注入到 gRPC 请求头
Kratos 的 transport.GRPCClient 默认会将 metadata.MD 通过 grpc.Header() 和 grpc.Trailer() 自动透传，但前提是调用方显式构造并传入 context.Context，且该 context 已通过 metadata.AppendToOutgoingContext 注入数据。不手动包装 context，Metadata 就不会出现在请求头里。
常见错误是直接用 context.Background() 或未处理过的 context 调用 client 方法，导致服务端收不到任何 Metadata：
ctx := context.Background() // ❌ 这样调用，服务端 recv.Metadata() 是空的 resp, err := client.SayHello(ctx, req)
正确做法是先注入：
ctx := metadata.AppendToOutgoingContext(context.Background(), "trace-id", "123456", "span-id", "abc") resp, err := client.SayHello(ctx, req)
注意：AppendToOutgoingContext 是追加，不是覆盖；同一 key 多次调用会形成 slice 值（gRPC 允许重复 header），服务端需用 md.Get("key") 获取第一个值，或 md.Values("key") 获取全部。
服务端如何安全读取并验证 Metadata
Kratos 的 gRPC Server 默认接收所有传入的 Metadata，但不会自动校验或过滤。如果业务依赖 trace-id 等字段，必须在 handler 或 middleware 中主动提取并做非空/格式校验，否则可能引发 panic 或链路断裂。
典型风险点：
- 直接调用
md.Get("trace-id")[0]而不检查 slice 长度 → panic - 把 raw string 当结构体解析（如 JSON）却不捕获 error → 崩溃
- 未对敏感字段（如 auth-token）做白名单限制 → 泄露或越权
推荐写法：
func (s *UserService) SayHello(ctx context.Context, req *v1.HelloRequest) (*v1.HelloReply, error) {
md, ok := metadata.FromIncomingContext(ctx)
if !ok {
return nil, errors.BadRequest("metadata", "missing incoming metadata")
}
traceID := md.Get("trace-id")
if len(traceID) == 0 {
return nil, errors.BadRequest("trace-id", "required but empty")
}
// ✅ 安全取值
s.logger.WithField("trace-id", traceID[0]).Info("handling request")
// ...
}
如何与 OpenTracing / OpenTelemetry 集成传递 span 上下文
Kratos 本身不绑定任何 tracing 实现，但可通过 Metadata 手动桥接。关键在于：span context 必须序列化为字符串（如 W3C TraceContext 格式），再注入到 Metadata；服务端反序列化后，重新 attach 到 context 中供 tracer 使用。
常见误区是直接传 span.Context() 对象 —— 它不能跨进程，必须走文本载体：
- 客户端：用
otel.GetTextMapPropagator().Inject()写入metadata.MD - 服务端：用
otel.GetTextMapPropagator().Extract()从metadata.MD读出
示例（OpenTelemetry）：
// 客户端
ctx, span := tracer.Start(ctx, "client-call")
defer span.End()
// 将 span context 注入 metadata
md := metadata.MD{}
otel.GetTextMapPropagator().Inject(
context.TODO(), // 注意：这里不能用带 span 的 ctx，避免循环引用
propagation.MapCarrier(md),
)
ctx = metadata.NewOutgoingContext(ctx, md)
_, err := client.SayHello(ctx, req)
服务端对应 extract 即可。注意 propagation.MapCarrier 是适配器，不是原始 map，别手写键值赋值。
Metadata 传递时的性能与兼容性陷阱
Metadata 本质是 HTTP/2 headers，大小受限（默认 gRPC server limit 8KB）。单个 key-value 超过 4KB、或总 size 接近上限时，gRPC 会直接断连并返回 status.Code = ResourceExhausted 错误。
容易被忽略的兼容性问题：
- Go client 发送的
metadata.MD{"k": []string{"v1","v2"}}，Java/Python server 可能只取第一个值（取决于语言 SDK 实现） - key 名含大写字母或下划线（如
"X-Trace-ID"）会被 gRPC 规范自动转为小写加横线（"x-trace-id"），跨语言务必统一命名规范 - Kratos v2.4+ 默认启用
grpc.WithBlock()的连接模式，若 Metadata 携带非法字符（如控制字符、未编码空格），可能导致连接初始化失败，错误信息为rpc error: code = Unavailable desc = connection closed
建议上线前用 grpcurl -plaintext -proto xxx.proto -d '{}' localhost:9000 pkg.Service/Method 手动测试 header 透传是否正常，比纯代码验证更可靠。
Metadata 不是万能上下文容器，它只适合传轻量、结构化、低频变更的字段；大对象、二进制数据、频繁更新的状态，应该走 payload 或单独的元数据服务。
