当前位置：首页 > news >正文

gRPC-Go基础（4）metadata和超时设置

news 2026/2/10 22:37:55

文章目录

0. 简介
1. metadata
- 1.1 metadata结构
- 1.2 metadata创建
- 1.3 客户端处理metadata
- 1.4 服务端处理metadata
- 1.5 metadata的传输
2. 超时设置
- 2.1 客户端输出超时信息
- 2.2 服务端端接收超时信息
3. 小结

0. 简介

Go在多个go routine之间传递数据使用的是Go SDK提供的context包，而context的作用范围在进程内，而gRPC使用的是跨进程的网络传输，那如何实现跨进程的元数据传输呢？

1. metadata

1.1 metadata结构

metadata的简单理解，就是http 的 Header 中的 key-value 对

gRPC使用metadata在服务之间传输全局数据，metadata形式为键值对（k-v）列表，如下：

type MD map[string][]string

k一般为字符串，v可以是字符串，也可以是二进制数据，当v是二进制数据时，k必须以-bin结尾，二进制数据会被base64编码然后传输；
同时，k不能以grpc-开头，因为这是为gRPC所保留；
k中大写字符会被转化为小写；
如上，一个k可以对应多个v。

1.2 metadata创建

New方法

md := metadata.New(map[string]string{"k1":"v1","k2":"v2"})

Pair方法（相同的key自动合并）

md := metadata.Pairs("k1", "v1","k1", "v1.2","k2-bin", string([]byte{1, 2}),
)

k1对应的值会被自动合并为map[string][]string{k1: {v1, v1.2}}。k2-bin对应的值会被进行base64编码。

1.3 客户端处理metadata

1.3.1 发送metadata

NewOutgoingContext

md := metadata.Pairs("k1", "v1","k1", "v1.2","k2-bin", string([]byte{1, 2}),
)
ctx := metadata.NewOutgoingContext(context.Background(), md)

将新创建的 Metadata 添加到 context 中，这样会覆盖掉原来已有的 metadata。其实际上就是调用了context.WithValue 方法，生成了一个子context而已，这个子context中包含了传入的metadata。

// NewOutgoingContext creates a new context with outgoing md attached. If used
// in conjunction with AppendToOutgoingContext, NewOutgoingContext will
// overwrite any previously-appended metadata.
func NewOutgoingContext(ctx context.Context, md MD) context.Context {return context.WithValue(ctx, mdOutgoingKey{}, rawMD{md: md})
}

AppendToOutgoingContext

ctx = metadata.AppendToOutgoingContext(ctx, "k1", "v1", "k1", "v1.2", "k2-bin", string([]byte{1, 2}))

AppendToOutgoingContext方法将k-v对添加到已有的context中。如果对应的context没有metadata，那么就会创建一个；如果已有metadata了，那么就将数据添加到原来的metadata（推荐使用 AppendToOutgoingContext)。

1.3.2 接收metadata
目前，gRPC的客户端支持接收的metadata包括header和trailer。
一元RPC
header和trailer可以通过Header和Trailer方法，在调用gRPC方法的CallOption时传入，在函数调用结束后取出。

var header, trailer metadata.MD
res, err := grpcClient.SimpleRoute(ctx, &simplepb.SimpleRequest{Data: "I am iguochan"}, grpc.Header(&header), grpc.Trailer(&trailer))

值得注意的是，虽然流式RPC的方法调用中也有CallOption，但是这两个方法**明确仅用于一元RPC。

// Header returns a CallOptions that retrieves the header metadata
// for a unary RPC.
func Header(md *metadata.MD) CallOption {return HeaderCallOption{HeaderAddr: md}
}// Trailer returns a CallOptions that retrieves the trailer metadata
// for a unary RPC.
func Trailer(md *metadata.MD) CallOption {return TrailerCallOption{TrailerAddr: md}
}

流式RPC
所有的流式RPC都将使用以下形式接收服务端发送的header和trailer。通过接口ClientStream的Header() (metadata.MD, error)和Trailer() metadata.MD方法取出。

stream, err := grpcClient.RouteList(context.Background())// 从流中取header
header, err := stream.Header()// 从流中取出trailer
trailer := stream.Trailer()

1.4 服务端处理metadata

1.4.1 发送metadata
和客户端接收metadata一样，服务端只能发送header和trailer这两类metadata。

一元RPC
有关这些方法的具体用法可以参考go文档。

func (r *Server) SimpleRoute(ctx context.Context, request *simplepb.SimpleRequest) (*simplepb.SimpleResponse, error) {// ...md := metadata.Pairs(/* ... */)err := grpc.SendHeader(ctx, md)// ...md := metadata.Pairs(/* ... */)err = grpc.SetTrailer(ctx, md)
}

流式RPC

func (r *Server) RouteList(server simplepb.Route_RouteListServer) error {// ...md := metadata.Pairs(/* ... */)err := server.SendHeader(md)// ...md := metadata.Pairs(/* ... */)server.SetTrailer(md)// ...
}

1.4.2 接收metadata
要读取客户端发送的元数据，服务器需要从 RPC 上下文中检索它。如果是一元调用，则可以使用 RPC 处理程序的上下文。对于流式调用，服务器需要从流中获取上下文。

一元RPC

func (r *Server) SimpleRoute(ctx context.Context, request *simplepb.SimpleRequest) (*simplepb.SimpleResponse, error) {md, ok := metadata.FromIncomingContext(ctx)if ok {// do something with metadata}// ...
}

流式RPC

func (r *Server) ListValue(request *simplepb.SimpleRequest, server simplepb.Route_ListValueServer) error {md, ok := metadata.FromIncomingContext(server.Context())if ok {// do something with metadata}// ...
}

1.5 metadata的传输

以上介绍了metadata的用法，本节将介绍一下metadata在gRPC各端之间的传输机制。上面说过，在Go中，metadata就是实际上就是调用了context.WithValue 方法，生成了一个子context，那其实不管是在客户端还是服务端，都属于context的上下文传递。
1.5.1 客户端输出metadata
根据前面的文章，我们知道，用户定义好protobuf后通过protoc生成服务端的interface和客户端的桩代码（stub），在桩代码中，已经包含了客户端的实现：

func (c *routeClient) SimpleRoute(ctx context.Context, in *SimpleRequest, opts ...grpc.CallOption) (*SimpleResponse, error) {out := new(SimpleResponse)err := c.cc.Invoke(ctx, "/simplepb.Route/SimpleRoute", in, out, opts...)if err != nil {return nil, err}return out, nil
}

当发起gRPC请求后，会调用Invoke方法，最终会调用invoke方法：

func invoke(ctx context.Context, method string, req, reply interface{}, cc *ClientConn, opts ...CallOption) error {cs, err := newClientStream(ctx, unaryStreamDesc, cc, method, opts...)if err != nil {return err}if err := cs.SendMsg(req); err != nil {return err}return cs.RecvMsg(reply)
}

invoke方法会调用newClientStream，newClientStream方法比较长，在里面会生成一个函数newStream，并调用newClientStreamWithParams：

func newClientStream(ctx context.Context, desc *StreamDesc, cc *ClientConn, method string, opts ...CallOption) (_ ClientStream, err error) {// ...var newStream = func(ctx context.Context, done func()) (iresolver.ClientStream, error) {return newClientStreamWithParams(ctx, desc, cc, method, mc, onCommit, done, opts...)}// ...
}

newClientStreamWithParams最红会选择一个transport去传输：

func newClientStreamWithParams(ctx context.Context, desc *StreamDesc, cc *ClientConn, method string, mc serviceconfig.MethodConfig, onCommit, doneFunc func(), opts ...CallOption) (_ iresolver.ClientStream, err error) {// ...// Pick the transport to use and create a new stream on the transport.// Assign cs.attempt upon success.op := func(a *csAttempt) error {if err := a.getTransport(); err != nil {return err}if err := a.newStream(); err != nil {return err}// Because this operation is always called either here (while creating// the clientStream) or by the retry code while locked when replaying// the operation, it is safe to access cs.attempt directly.cs.attempt = areturn nil}// ...
}

而gRPC选择的是HTTP2作为传输协议，所以最终a.newStream()会最终调用到HTTP2的NewStream：

// NewStream creates a stream and registers it into the transport as "active"
// streams.  All non-nil errors returned will be *NewStreamError.
func (t *http2Client) NewStream(ctx context.Context, callHdr *CallHdr) (*Stream, error) {ctx = peer.NewContext(ctx, t.getPeer())headerFields, err := t.createHeaderFields(ctx, callHdr)if err != nil {return nil, &NewStreamError{Err: err, AllowTransparentRetry: false}}
}

createHeaderFields，顾名思义，就是构建HTTP请求时的头（HEADERS Frame），其有关metadata从context到HTTP Header的转换实现如下：

func (t *http2Client) createHeaderFields(ctx context.Context, callHdr *CallHdr) ([]hpack.HeaderField, error) {// ...if md, added, ok := metadata.FromOutgoingContextRaw(ctx); ok {var k stringfor k, vv := range md {// HTTP doesn't allow you to set pseudoheaders after non pseudoheaders were set.if isReservedHeader(k) {continue}for _, v := range vv {headerFields = append(headerFields, hpack.HeaderField{Name: k, Value: encodeMetadataHeader(k, v)})}}for _, vv := range added {for i, v := range vv {if i%2 == 0 {k = strings.ToLower(v)continue}// HTTP doesn't allow you to set pseudoheaders after non pseudoheaders were set.if isReservedHeader(k) {continue}headerFields = append(headerFields, hpack.HeaderField{Name: k, Value: encodeMetadataHeader(k, v)})}}}// ...
}

可以看到，所谓metadata，其实最终是通过HTTP2协议的头帧带入到网络的，主要存储在Binary-Header和ASCII-Header，感兴趣的同学可以参考gRPC over HTTP2。
1.5.2 服务端接收metadata
服务端通过Serve方法来启动，监听来自客户端的连接：

err = grpcServer.Serve(listener)
if err != nil {log.Fatalf("grpcServer.Serve err: %v", err)
}

Serve方法最终会调用到handleRawConn，handleRawConn会通过HTTP2去接收消息。

func (s *Server) handleRawConn(lisAddr string, rawConn net.Conn) {// ...st := s.newHTTP2Transport(rawConn)// ...go func() {s.serveStreams(st)s.removeConn(lisAddr, st)}()
}

接下来的调用流程涉及的方法是：serveStreams——>HandleStreams——>operateHeaders，最终在operateHeaders，会将所有的头文件中的传入的Header（除去默认的一些字段等）读入到mdata中，这就是服务端拿到的metadata。

func (t *http2Server) operateHeaders(frame *http2.MetaHeadersFrame, handle func(*Stream), traceCtx func(context.Context, string) context.Context) (fatal bool) {// ...for _, hf := range frame.Fields {switch hf.Name {// ...default:if isReservedHeader(hf.Name) && !isWhitelistedHeader(hf.Name) {break}v, err := decodeMetadataHeader(hf.Name, hf.Value)if err != nil {headerError = truelogger.Warningf("Failed to decode metadata header (%q, %q): %v", hf.Name, hf.Value, err)break}mdata[hf.Name] = append(mdata[hf.Name], v)}}// ...
}

2. 超时设置

除了一些元数据的传输，在gRPC中，我们还支持将context中的超时传递到接下来的每个服务中，甚至可以跨语言，而这是怎么做到的呢？首先我们想到是通过metadata传输，实际上并不是的。

2.1 客户端输出超时信息

其实从前面1.5.1 客户端输出metadata的最后一步，createHeaderFields方法中，就有如下处理，超时的数值会被作为key是grpc-timeout的值放在HTTP2的头中（正如备注中所言，其实在网络上的传输时间是没有被计入的，会有一定误差）。

func (t *http2Client) createHeaderFields(ctx context.Context, callHdr *CallHdr) ([]hpack.HeaderField, error) {// ...if dl, ok := ctx.Deadline(); ok {// Send out timeout regardless its value. The server can detect timeout context by itself.// TODO(mmukhi): Perhaps this field should be updated when actually writing out to the wire.timeout := time.Until(dl)headerFields = append(headerFields, hpack.HeaderField{Name: "grpc-timeout", Value: grpcutil.EncodeDuration(timeout)})}// ...
}

2.2 服务端端接收超时信息

同理，在HTTP2的server端的头处理函数operateHeaders中，也会对grpc-timeout对应的值进行处理，将其值读入到timeout中，并置上timeoutSet标志，用于后续处理。

func (t *http2Server) operateHeaders(frame *http2.MetaHeadersFrame, handle func(*Stream), traceCtx func(context.Context, string) context.Context) (fatal bool) {// ...var (// ...timeoutSet booltimeout    time.Duration)// ...for _, hf := range frame.Fields {switch hf.Name {// ...case "grpc-timeout":timeoutSet = truevar err errorif timeout, err = decodeTimeout(hf.Value); err != nil {headerError = true}}}// ...if timeoutSet {s.ctx, s.cancel = context.WithTimeout(t.ctx, timeout)} else {s.ctx, s.cancel = context.WithCancel(t.ctx)}// ...
}

3. 小结

根据以上分析，我们可以发现，不管是metadata还是超时，都是通过HTTP2的头帧传入到对侧的。