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

【gRPC-gateway】是否有拦截器的情况添加健康检查的细节，与多路复用runtime.NewServeMux和gRPC区别讲解，与跨域功能，go案例

news 来源：原创 2025/5/9 16:13:24

健康检查详解

什么是健康检查？

健康检查（Health Checking）是一种机制，用于监控服务的状态，确保服务在运行时是健康的、可用的。通过健康检查，系统可以自动检测服务是否正常工作，并在出现问题时采取相应的措施，如重新启动服务或将其从负载均衡器中移除。

在gRPC中的应用

在gRPC中，健康检查通常用于以下几个方面：

服务发现：负载均衡器或其他服务发现工具可以通过健康检查来判断某个服务实例是否可用。
故障转移：当某个服务实例不可用时，客户端可以自动切换到其他健康的实例。
维护模式：管理员可以手动将服务标记为“不健康”，以便进行维护或更新。

具体实现

grpc_health_v1.RegisterHealthServer(s, health.NewServer())

health.NewServer() 创建了一个新的健康检查服务器实例。
grpc_health_v1.RegisterHealthServer(s, ...) 将这个健康检查服务器注册到 gRPC 服务器 s 中。

这意味着，一旦有客户端请求健康检查，gRPC 服务器会通过这个健康检查服务器来响应请求，告知客户端当前服务的状态。

控制流图

接下来建立与gRPC服务器的连接，注册健康检查grpc服务器

建立gRPC连接：

   conn, err := grpc.Dial(*grpcServerEndpoint, grpc.WithTransportCredentials(insecure.NewCredentials()))if err != nil {return err}

使用 grpc.Dial 方法连接到指定的 gRPC 服务器地址 *grpcServerEndpoint。
grpc.WithTransportCredentials(insecure.NewCredentials()) 表示使用不安全的传输凭证（即不启用TLS）。
如果连接失败，返回错误。

创建HTTP处理多路复用器：

   mux := runtime.NewServeMux(inComingOpt, runtime.WithHealthzEndpoint(grpc_health_v1.NewHealthClient(conn)))

runtime.NewServeMux 创建一个新的 HTTP 处理多路复用器。
inComingOpt 是传入的自定义选项，用于配置 ServeMux。
runtime.WithHealthzEndpoint(grpc_health_v1.NewHealthClient(conn)) 指定健康检查的 gRPC 客户端。通过 NewHealthClient(conn) 创建一个健康检查客户端，并将其绑定到默认路径 /healthz。
可以使用 WithHealthEndpointAt() 来指定自定义的健康检查路径。

扩展： `多路复用器`与`.yaml`配置的`http.rules`的区别

区别与使用场景

mux.HandlePath("POST", "/upload", uploadHandler) 和通过 .yaml 文件配置 http.rules 的作用并不完全相同，它们适用于不同的场景和需求。下面详细解释两者的区别以及各自的适用场景。

1. `mux.HandlePath`

功能

mux.HandlePath("POST", "/upload", uploadHandler)

手动注册HTTP路由：直接在代码中为特定的HTTP路径和方法（如 /upload 和 POST）注册一个处理函数 uploadHandler。
灵活性高：可以在代码中动态添加或修改路由规则，适合需要灵活控制路由逻辑的场景。
独立于gRPC服务定义：不依赖于gRPC服务定义文件（如 .proto 或 .yaml），可以用于处理非gRPC相关的HTTP请求。

使用场景

自定义HTTP API：当你需要实现一些与gRPC服务无关的HTTP接口时，例如上传文件、处理静态资源等。
动态路由：需要根据运行时条件动态注册路由的情况。

2. `http.rules` in `.yaml` 文件

功能

http:rules:- selector: user.User.Getget: "/user/{id}"- selector: user.User.AddOrUpdatepost: "/user"body: "*"additional_bindings:- put: "/user"body: "*"- patch: "/user"body: "addr"- selector: user.User.Deletedelete: "/user/{id}"

映射gRPC到HTTP：将gRPC服务的方法映射为HTTP端点，并指定HTTP方法和路径。
基于服务定义：这些规则是基于gRPC服务定义文件（.proto）生成的，确保HTTP接口与gRPC服务保持一致。
自动处理：通过 grpc-gateway 自动生成HTTP处理逻辑，减少手动编写代码的工作量。

区别总结

特性	`mux.HandlePath`	`http.rules` in `.yaml` 文件
注册方式	手动在代码中注册	在配置文件中定义
依赖关系	独立于gRPC服务定义	基于gRPC服务定义
灵活性	高，适合动态路由	较低，但更稳定
适用场景	自定义HTTP API、动态路由	gRPC网关、HTTP与gRPC接口一致性维护

示例对比

mux.HandlePath：
```
mux.HandlePath("POST", "/upload", uploadHandler)
```
这段代码仅注册了一个特定的HTTP路由，处理上传文件的请求，与gRPC服务无关。
http.rules：
```
http:rules:- selector: user.User.Getget: "/user/{id}"
```
这段配置将 user.User.Get 方法映射为HTTP GET请求 /user/{id}，并由 grpc-gateway 自动生成相应的处理逻辑。

控制流图

值得一提的是如果之前写了一元请求拦截器，那么，需要设置规则跳过健康检查的验证

在这里插入图片描述

为什么不将 `upload` 放到 `.yaml` 里，反而使用多路复用器注册？

1. 功能差异

`upload` 的特殊性

文件上传：upload 通常涉及文件上传操作，这种操作可能需要处理较大的二进制数据流、分块上传、进度跟踪等复杂逻辑。
自定义处理：文件上传可能需要额外的中间件来处理文件存储、验证、转换等操作，这些逻辑不适合直接映射到 gRPC 方法上。

`.yaml` 中的 HTTP 规则

RESTful API 映射：.yaml 文件主要用于将 gRPC 方法映射为标准的 RESTful API，适用于结构化数据（如 JSON）的传输。
简单路由：它更适合处理简单的 CRUD 操作和其他基于 JSON 的请求，不擅长处理复杂的文件上传场景。

2. 灵活性与控制

多路复用器的灵活性

动态注册：通过 mux.HandlePath 可以在代码中动态注册路由，适合需要根据运行时条件调整路由逻辑的场景。
独立于 gRPC：upload 路由可以完全独立于 gRPC 服务定义，不会影响现有的 gRPC 接口设计。
自定义中间件：可以方便地添加自定义中间件（如认证、日志、限流等），更好地控制文件上传的整个流程。

`.yaml` 文件的限制

静态配置：.yaml 文件是静态配置，修改后需要重新生成代码或重启服务，不如代码中的动态注册灵活。
依赖 gRPC：必须有对应的 gRPC 方法才能映射，而文件上传通常不需要一个专门的 gRPC 方法。

3. 维护与扩展

维护成本

集中管理：如果所有路由都放在 .yaml 文件中，可能会导致文件变得庞大且难以维护。特别是当涉及到复杂的业务逻辑时，代码中的路由注册更易于管理和调试。
分离关注点：将文件上传逻辑与常规的 gRPC 网关路由分开，有助于分离关注点，使代码结构更加清晰。

扩展性

未来扩展：如果你将来需要为 upload 添加更多功能（如支持多种文件类型、版本控制等），代码中的实现会更容易扩展和维护。

如何抉择grpc与多路复用

功能需求	适用技术	理由	企业常用的功能对应
高性能微服务通信	gRPC	高效、低延迟、强类型检查	内部微服务之间的实时数据同步、高频交易系统、实时消息推送
结构化数据传输	gRPC	固定且复杂的数据格式	用户信息管理、商品信息查询、订单处理等业务逻辑
支持多种语言客户端	gRPC	多语言支持，跨平台通信	移动应用与后端服务的通信（iOS 和 Android 应用）、多语言微服务架构
文件上传/下载	ServeMux	二进制数据传输，自定义中间件	文件存储服务、图片和视频上传下载、文档管理系统
自定义HTTP API	ServeMux	独立于 gRPC，灵活扩展	`健康检查接口`、管理后台API（如用户权限管理、配置管理）、监控和日志接口
动态路由	ServeMux	运行时动态调整路由	动态生成的API路由（如基于用户角色的访问控制）、A/B测试和实验性功能的快速迭代
传统HTTP客户端对接	ServeMux	向后兼容，第三方集成	Web 前端的 AJAX 请求、第三方支付网关、社交媒体API集成

所以健康检查应该放到多路复用里

mux := runtime.NewServeMux(inComingOpt, runtime.WithHealthzEndpoint(grpc_health_v1.NewHealthClient(conn)))

跨域

在gateway.go中添加handler := middleware.Cors(mux)
Cors示例：func Cors(handler http.Handler) http.Handler {

为什么mux可以传进Cors？

Cors接收一个http.Handler

在这里插入图片描述

Handler接口只有一个 ServeHTTP方法需要实现

在这里插入图片描述

而mux对应的serveMux 实现了ServeHTTP方法。因此它可以作为 http.Handler 使用

在这里插入图片描述

完整跨域代码

middleware.go

package middlewareimport "net/http"// Cors 是一个中间件函数，用于为HTTP处理器添加跨域资源共享(CORS)支持。
// 它接受一个 http.Handler 类型的参数，并返回一个新的 http.Handler。
// 这个新的处理器会在每个响应中添加CORS相关的HTTP头部，以允许跨域请求。
func Cors(handler http.Handler) http.Handler {// 创建一个新的http.HandlerFunc，它实现了http.Handler接口。// 这个匿名函数将原始处理器和CORS逻辑结合在一起。return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {// 获取请求的方法。method := r.Method// 获取请求的Origin头部，用于判断是否需要添加CORS支持。origin := r.Header.Get("Origin")// 如果Origin头部不为空，则添加CORS相关的HTTP头部。if origin != "" {// 允许所有来源的跨域请求（* 表示通配符）。// 也可以根据需要替换为指定的域名，以提高安全性。w.Header().Set("Access-Control-Allow-Origin", "*")// 指定允许的HTTP方法，以支持跨域请求。w.Header().Set("Access-Control-Allow-Methods", "POST, GET, OPTIONS, PUT, DELETE, UPDATE, PATCH")// 指定允许的HTTP头部，以支持跨域请求。w.Header().Set("Access-Control-Allow-Headers", "Origin, X-Requested-With, Content-Type, Accept, Authorization")// 指定允许暴露的HTTP头部，以支持跨域请求。w.Header().Set("Access-Control-Expose-Headers", "Content-Length, Access-Control-Allow-Origin, Access-Control-Allow-Headers, Cache-Control, Content-Language, Content-Type")// 允许跨域请求带上用户凭证（如Cookies）。w.Header().Set("Access-Control-Allow-Credentials", "true")}// 如果请求的方法是OPTIONS，且设置了Origin头部，则返回204状态码，// 表示预检请求成功，实际请求可以继续进行。if method == "OPTIONS" {w.WriteHeader(http.StatusNoContent)return}// 调用原始的处理器函数，继续处理请求。handler.ServeHTTP(w, r)})
}

gateway.go

package gatewayimport ("context""flag""github.com/grpc-ecosystem/grpc-gateway/v2/runtime"gw "golang19-grpc-gateway/user/proto""golang19-grpc-gateway/user/user-server/gateway/middleware""google.golang.org/grpc""google.golang.org/grpc/credentials/insecure""google.golang.org/grpc/health/grpc_health_v1""net/http"
)var (// grpc服务器端点grpcServerEndpoint = flag.String("grpc-server-endpoint", "localhost:50051", "gRPC server endpoint")
)// Run 启动一个 HTTP 服务器，用于将 HTTP 请求转发到 gRPC 服务器。
// 该函数配置了一个 HTTP 多路复用器以处理不同的 HTTP 路径，并将这些路径与 gRPC 方法关联起来。
// 它还设置了一个不安全的 gRPC 连接选项，仅适用于开发环境。
// 返回值: 如果 HTTP 服务器启动失败或在处理请求时遇到错误，则返回错误。
func Run() error {// 初始化一个上下文对象，用于取消操作和传递请求范围的值。ctx := context.Background()// 创建一个可取消的上下文，以便在函数退出时取消可能的挂起操作。ctx, cancel := context.WithCancel(ctx)// 确保在函数退出时取消上下文。defer cancel()// inComingOpt 配置了一个处理传入的http请求头的选项// 该选项使用一个函数来检查和转换请求头的键// 该匹配器函数决定哪些传入的HTTP头应该被传递给gRPC上下文，以及是否应该修改这些头的键。inComingOpt := runtime.WithIncomingHeaderMatcher(func(s string) (string, bool) {// 如果matcher返回true，则该标头将传递给gRPC上下文。要在传递给gRPC上下文之前转换标头，匹配器应返回修改后的标头。switch s {// 对于"Service-Authorization"头，将其转换为"service-authorization"并传递给gRPC上下文。case "Service-Authorization":return "authorization", true// 不修改请求头的键，不传递给上下文default:return "", false}})// 使用 gRPC 拨号函数连接到 gRPC 服务器端点。// 参数 grpcServerEndpoint 是服务器地址，WithTransportCredentials 指定使用不安全的凭据进行传输。// 如果连接失败，返回错误。conn, err := grpc.Dial(*grpcServerEndpoint, grpc.WithTransportCredentials(insecure.NewCredentials()))if err != nil {return err}// 创建一个 HTTP 处理多路复用器，用于将 HTTP 请求分发到不同的处理程序。// inComingOpt 是传入的自定义选项，用于配置 ServeMux。// WithHealthzEndpoint 选项用于指定健康检查的 gRPC 客户端，通过 NewHealthClient 创建。// WithHealthzEndpoint默认路径"/healthz"  WithHealthEndpointAt()可以自己指定路径mux := runtime.NewServeMux(inComingOpt, runtime.WithHealthzEndpoint(grpc_health_v1.NewHealthClient(conn)))// 为 "/upload" 路径添加一个处理程序，处理 POST 请求。mux.HandlePath("POST", "/upload", uploadHandler)// handler变量用于处理跨域请求，通过将mux传递给middleware.Cors来实现。// 这里使用了中间件Cors来处理跨域问题，以确保应用程序的安全性和功能性。handler := middleware.Cors(mux)// 配置一个不安全的 gRPC 连接选项，这仅适用于开发环境。opts := []grpc.DialOption{grpc.WithTransportCredentials(insecure.NewCredentials())}// 将 gRPC 方法映射为 HTTP 请求，使 HTTP 客户端可以与 gRPC 服务器通信。err = gw.RegisterUserHandlerFromEndpoint(ctx, mux, *grpcServerEndpoint, opts)// 如果注册处理程序时发生错误，返回该错误。if err != nil {return err}// 启动 HTTP 服务器，监听端口 8081，使用配置好的多路复用器处理请求。return http.ListenAndServe(":8081", handler)
}

https://github.com/0voice

健康检查详解

什么是健康检查？

在gRPC中的应用

具体实现

控制流图

接下来建立与gRPC服务器的连接，注册健康检查grpc服务器

扩展： 多路复用器与.yaml配置的http.rules的区别

区别与使用场景

1. mux.HandlePath

功能

使用场景

2. http.rules in .yaml 文件

功能

区别总结

示例对比

控制流图

值得一提的是如果之前写了一元请求拦截器，那么，需要设置规则跳过健康检查的验证

为什么不将 upload 放到 .yaml 里，反而使用多路复用器注册？

1. 功能差异

upload 的特殊性

.yaml 中的 HTTP 规则

2. 灵活性与控制

多路复用器的灵活性

.yaml 文件的限制

3. 维护与扩展

维护成本

扩展性

如何抉择grpc与多路复用

跨域

为什么mux可以传进Cors？

相关文章：

扩展： `多路复用器`与`.yaml`配置的`http.rules`的区别

1. `mux.HandlePath`

2. `http.rules` in `.yaml` 文件

为什么不将 `upload` 放到 `.yaml` 里，反而使用多路复用器注册？

`upload` 的特殊性

`.yaml` 中的 HTTP 规则

`.yaml` 文件的限制