概览
通过上一讲，我们对gRPC的拦截器有了一定的认识，也能定制出很多通用的中间件。
但在大部分的业务系统中，我们面向的还是HTTP协议。那么，今天我们就从gRPC-Gateway的mux选项出发，一起来看看一些很实用的特性。
ServeMux
import "github.com/grpc-ecosystem/grpc-gateway/v2/runtime"
gwMux := runtime.NewServeMux()
// 函数签名
func NewServeMux(opts ...ServeMuxOption) *ServeMux {
}
我们将目标聚焦于这个ServeMux：
- 目前官方区分v1和v2版本，版本不一致会导致很多编译上的问题
- 入参包括多个
option选项函数，用于定制想要的mux内容
具体的内容可以参考ServeMux的数据结构，我这里挑选几个重点的能力：
type ServeMux struct {
// 这个是server的核心实现：即注册的handlerf
handlers map[string][]handler
// 1、转发正常响应
forwardResponseOptions []func(context.Context, http.ResponseWriter, proto.Message) error
// 2、序列化工具
marshalers marshalerRegistry
// 3、进入时（http->grpc）的header匹配规则
incomingHeaderMatcher HeaderMatcherFunc
// 4、返回时（grpc->http）的header匹配规则
outgoingHeaderMatcher HeaderMatcherFunc
// 5、metadata的转换（从http转成grpc的md）
metadataAnnotators []func(context.Context, *http.Request) metadata.MD
// 6、错误处理
errorHandler ErrorHandlerFunc
// 7、流式错误处理
streamErrorHandler StreamErrorHandlerFunc
// 8、路由错误
routingErrorHandler RoutingErrorHandlerFunc
}
综合一下，核心能力其实包括2块：
- Header数据的处理
- 返回消息的处理（包括正常情况和错误情况）
Header的数据处理
HTTP与gRPC协议头匹配
// HTTP -> gRPC
func WithIncomingHeaderMatcher(fn HeaderMatcherFunc) ServeMuxOption {
}
// gRPC -> HTTP
func WithOutgoingHeaderMatcher(fn HeaderMatcherFunc) ServeMuxOption {
}
type HeaderMatcherFunc func(string) (string, bool)
这个函数只做一个简单的映射，我们可以通过下面的例子开快速了解：
// 入参：header key
// 出参：返回header key，以及是否返回
func CustomMatcher(key string) (string, bool) {
switch key {
case "some-special-key":
return key, true
case "deprecated-key":
return "", false
default:
// 默认的匹配规则
return runtime.DefaultHeaderMatcher(key)
}
}
将HTTP头转成gRPC头
上面的matcher只是做一个key的映射，如果Header里包括更复杂的部分（例如Cookie），需要引入下面函数：
func WithMetadata(annotator func(context.Context, *http.Request) metadata.MD) ServeMuxOption {
return func(serveMux *ServeMux) {
serveMux.metadataAnnotators = append(serveMux.metadataAnnotators, annotator)
}
}
我们注意两个点：
- 只做协议转换，不做逻辑处理（逻辑处理交给gRPC层的中间件统一处理）
metadata.MD的底层数据结构为map[string][]string，与HTTP Header很类似
下面给出一个HTTP的Cookie处理示例：
// 示例
const (
HTTP_COOKIE_TOKEN = "http_cookie"
MD_TOKEN = "md_cookie"
)
func ExampleCookieMetadataAnnotator(ctx context.Context, r *http.Request) (md metadata.MD) {
// 从HTTP的cookie中读出对应的数据
c, err := r.Cookie(ODIN_JWT_TOKEN)
if err != nil {
return
}
// 将值放到md里，方便在后续提取
return metadata.Pairs(MD_TOKEN, c.Value)
}
返回数据处理
正确返回
func WithForwardResponseOption(forwardResponseOption func(context.Context, http.ResponseWriter, proto.Message) error) ServeMuxOption {
}
正确返回时，核心的数据结构为 protoMessage。我们不妨做一个封装：
type HTTPResponse struct {
Errno int `json:"errno"`
Msg string `json:"msg"`
Data interface{
} `json:"data"`
}
func GatewayResponseModifier(ctx context.Context, w http.ResponseWriter, resp proto.Message) error {
// 返回的数据，在外层同一封装了数据结构HTTPResponse，对一些历史项目兼容有很棒的效果
newResp := &HTTPResponse{
Data: resp,
}
pbData, _ := json.Marshal(newResp)
w.Write(pbData)
return nil
}
错误返回
func WithErrorHandler(fn ErrorHandlerFunc) ServeMuxOption {
}
错误处理在整个RPC框架中扮演了非常重要的角色，我们不妨通过如下例子来了解：
func GatewayErrModifier(ctx context.Context, mux *runtime.ServeMux, m runtime.Marshaler, w http.ResponseWriter, r *http.Request, err error) {
// 提取error
s, ok := status.FromError(err)
// 非标准错误
if !ok {
runtime.DefaultHTTPErrorHandler(ctx, mux, m, w, r, err)
return
}
// 对各类错误增加定制的逻辑
switch s.Code() {
case codes.Unauthenticated:
// 示例：认证失败，可以加入重定向的逻辑
default:
runtime.DefaultHTTPErrorHandler(ctx, mux, m, w, r, err)
}
return
}
分析一下重点：
error尽可能用gRPC标准的错误Status表示gRPC的标准错误，对错误码code有一套定义（参考google.golang.org/grpc/codes），类似于HTTP的状态码- 错误码code要尽量少，过多没有意义
- 标准错误码尽可能复用，如资源找不到、权限不足等
- 业务错误码可以独立，一般一个系统定义1个即可
小结
本文重点介绍了gRPC-Gateway中2类ServeMux，也演示了对应的示例，大家能理解其基本用法即可。
后续，随着整体项目的落地，我会增加一些日常项目中常见的定制需求，帮助大家更好地认识RPC框架的能力。
