gRPC -- Guides -- Metadata

Metadata（元数据）

解释元数据的定义、传输方式与用途

概述（Overview）

元数据是一条旁路通道，用于让客户端与服务端传递与 RPC 关联的附加信息。

gRPC 元数据是一组键值对，随 gRPC 初始请求 / 最终请求或响应一同发送，用于提供调用相关附加信息，如认证凭证、追踪信息或自定义请求头。

gRPC 元数据基于HTTP/2 头部实现：

• 键为 ASCII 字符串
• 值可为 ASCII 字符串或二进制数据
• 键不区分大小写
• 键不能以grpc-前缀开头（该前缀为 gRPC 内部保留）

客户端与服务端均可收发元数据：

• Headers（请求头）：客户端在初始请求前发送给服务端；服务端在初始响应前发送给客户端。
• Trailers（响应尾）：服务端在关闭 RPC 时发送。

gRPC 元数据适用于多种场景：

• 认证（Authentication）：用于向服务端传递认证凭证，可基于标准 HTTP Authorization 请求头实现 OAuth2、JWT 等认证方案。
• 追踪（Tracing）：用于向服务端传递追踪信息，可在分布式系统中追踪请求流转过程。
• 自定义请求头（Custom headers）：用于客户端 / 服务端传递自定义请求头，实现负载均衡、限流、服务端详细错误信息透传等应用专属功能。
• 内部用途（Internal usages）：gRPC 内部使用 HTTP/2 头部与响应尾，并与应用层指定的元数据集成。

注意事项（Be Aware）

警告：服务端可能限制请求头大小，建议默认上限为8 KiB。

自定义元数据必须遵循 PROTOCOL-HTTP2 中定义的 “Custom-Metadata” 格式，二进制头部无需进行 Base64 编码。

Headers（请求头）

Headers 在客户端发送初始请求数据前、服务端发送初始响应数据前传输，包含认证凭证、RPC 处理策略等信息。部分请求头（如授权请求头）由 gRPC 自动生成。

自定义请求头处理逻辑与编程语言相关，一般通过拦截器实现。

Trailers（响应尾）

Trailers 是在消息数据之后发送的特殊请求头，用于内部传递 RPC 调用结果。在应用层，自定义响应尾可用于传递非数据直接相关信息，如服务端利用率、查询开销等。Trailers 仅由服务端发送。

更多细节，请参考以下文档：

• proposal: G1 true binary metadata
• proposal: L7 go metadata api
• proposal: L48 node metadata options
• proposal: L42 python metadata flags
• proposal: L11 ruby interceptors

语言支持（Language Support）