架构与系统设计 / 系统课时
实现标准 gRPC Health Checking
实现标准 gRPC Health Checking
这一课把 gRPC 健康检查整理成可运行的标准实现:用官方 Health 服务同时支持一元 Check 与流式 Watch,区分进程存活、服务就绪和依赖健康,并让客户端实际观察健康状态如何影响后端是否参与请求分配。
学习目标
- 使用标准
grpc.health.v1.Health服务实现Check与Watch。 - 区分进程存活、服务就绪和依赖健康,避免把任意依赖抖动都升级成实例下线。
- 配置客户端健康检查,并验证
NOT_SERVING与SERVING对通道可用状态的影响。
先把存活、就绪和依赖分开
标准 Health 服务回答的是“这个服务现在能不能接流量”,不是“进程还在不在”。进程存活通常由进程管理器或编排系统使用独立、廉价的 liveness 机制判断;服务就绪才映射到 SERVING 或 NOT_SERVING。
| 信号 | 回答的问题 | 建议用途 |
|---|---|---|
| 进程存活 | 进程、事件循环是否还活着 | 决定是否重启进程 |
| 服务就绪 | 当前是否应该接收新 RPC | 更新 Health SERVING / NOT_SERVING |
| 依赖健康 | 数据库、缓存、下游是否可用 | 作为就绪判断输入,而不是直接等同于进程死亡 |
只有“缺少它就无法正确服务”的硬依赖才应该把对应服务切成 NOT_SERVING。可选依赖或局部功能异常更适合降级,并由业务方法返回精确错误,否则一次缓存抖动就可能把整个实例从负载均衡池中摘掉。

协议本身提供两种读取方式:Check 是一次性一元 RPC,适合探针或管理系统查询;Watch 是服务端流式 RPC,客户端侧健康检查会持续订阅状态变化。空字符串 "" 按标准约定表示整个 server 的整体状态,具体 service name 则允许同一进程里的不同 gRPC 服务维护不同状态。
用官方实现提供 Check 与 Watch
下面以 grpc-go v1.83.2 为例。示例依赖 google.golang.org/grpc;在已有 Go module 中先执行 go get google.golang.org/grpc@v1.83.2。官方 health.NewServer() 已实现标准 Check 与 Watch,应用只需要在真实就绪状态变化时调用 SetServingStatus。
示例用定时器模拟一个硬依赖“恢复后再次故障”。生产代码应把定时器替换成依赖探测或应用内部状态机。保存为 main.go 后执行 go run .。
package main
import (
"context"
"fmt"
"net"
"time"
"google.golang.org/grpc"
_ "google.golang.org/grpc/balancer/roundrobin"
"google.golang.org/grpc/credentials/insecure"
"google.golang.org/grpc/health"
healthpb "google.golang.org/grpc/health/grpc_health_v1"
)
const serviceName = "orders.v1.OrderService"
func main() {
lis, err := net.Listen("tcp", "127.0.0.1:50051")
must(err)
server := grpc.NewServer()
healthServer := health.NewServer()
healthpb.RegisterHealthServer(server, healthServer)
// 进程已经启动,但硬依赖尚未就绪,因此先拒绝新业务流量。
setStatus(healthServer, healthpb.HealthCheckResponse_NOT_SERVING)
go func() {
if err := server.Serve(lis); err != nil {
panic(err)
}
}()
defer server.Stop()
fmt.Println("server=NOT_SERVING")
// 这个连接只用于直接验证 Check/Watch,不启用负载均衡健康门控。
probeConn, err := grpc.NewClient(
"passthrough:///127.0.0.1:50051",
grpc.WithTransportCredentials(insecure.NewCredentials()),
)
must(err)
defer probeConn.Close()
healthClient := healthpb.NewHealthClient(probeConn)
checkCtx, cancelCheck := context.WithTimeout(context.Background(), time.Second)
check, err := healthClient.Check(
checkCtx,
&healthpb.HealthCheckRequest{Service: serviceName},
)
cancelCheck()
must(err)
fmt.Printf("Check=%s\n", check.Status.String())
watchCtx, cancelWatch := context.WithTimeout(context.Background(), 7*time.Second)
defer cancelWatch()
watch, err := healthClient.Watch(
watchCtx,
&healthpb.HealthCheckRequest{Service: serviceName},
)
must(err)
go printWatch(watch)
// round_robin 请求子通道健康检查;Health 包导入后会注册客户端检查实现。
serviceConfig := `{
"loadBalancingConfig": [{"round_robin": {}}],
"healthCheckConfig": {"serviceName": "orders.v1.OrderService"}
}`
appConn, err := grpc.NewClient(
"passthrough:///127.0.0.1:50051",
grpc.WithTransportCredentials(insecure.NewCredentials()),
grpc.WithDefaultServiceConfig(serviceConfig),
)
must(err)
defer appConn.Close()
appConn.Connect()
stateCtx, cancelState := context.WithTimeout(context.Background(), 7*time.Second)
defer cancelState()
go printChannelStates(stateCtx, appConn)
time.Sleep(2 * time.Second)
setStatus(healthServer, healthpb.HealthCheckResponse_SERVING)
fmt.Println("server=SERVING")
time.Sleep(2 * time.Second)
setStatus(healthServer, healthpb.HealthCheckResponse_NOT_SERVING)
fmt.Println("server=NOT_SERVING")
time.Sleep(2 * time.Second)
}
func setStatus(h *health.Server, status healthpb.HealthCheckResponse_ServingStatus) {
h.SetServingStatus("", status)
h.SetServingStatus(serviceName, status)
}
func printWatch(stream healthpb.Health_WatchClient) {
for {
resp, err := stream.Recv()
if err != nil {
return
}
fmt.Printf("Watch=%s\n", resp.Status.String())
}
}
func printChannelStates(ctx context.Context, conn *grpc.ClientConn) {
for {
state := conn.GetState()
fmt.Printf("channel=%s\n", state.String())
if !conn.WaitForStateChange(ctx, state) {
return
}
}
}
func must(err error) {
if err != nil {
panic(err)
}
}预期输出(并发日志顺序可能略有不同)
server=NOT_SERVING
Check=NOT_SERVING
Watch=NOT_SERVING
channel=IDLE
channel=CONNECTING
channel=TRANSIENT_FAILURE
server=SERVING
Watch=SERVING
channel=READY
server=NOT_SERVING
Watch=NOT_SERVING
channel=TRANSIENT_FAILUREWatch= 与 channel= 的相邻顺序可能因 goroutine 调度不同而变化,也可能省略某个短暂的中间连接状态。应验证的是状态关系:服务为 NOT_SERVING 时,启用健康检查的子通道不能作为可用后端;收到 SERVING 后才恢复为可选状态。
看懂客户端为什么用 Watch
客户端健康检查不是不断调用 Check。连接建立后,支持该能力的负载均衡策略会发起 Watch,让服务器在健康状态变化时主动推送更新,从而避免大量客户端以固定间隔轮询 Health 服务。
在 grpc-go 中,客户端健康门控需要同时满足几个条件:程序导入 google.golang.org/grpc/health 以注册客户端检查实现,Service Config 提供 healthCheckConfig,并且所用负载均衡策略请求对子通道启用健康检查。本示例使用 health.NewServer(),因此同一个 health 包已经被正常导入;round_robin 则负责请求这项检查。某些负载均衡策略会禁用或不请求健康检查,因此不能只看到 healthCheckConfig 就假设它一定生效。
如果 Watch 返回 UNIMPLEMENTED,客户端会把服务端视为“不支持标准客户端健康检查”并停用这一门控,而不是永久把后端判死。因此上线时要确认 Health 服务确实注册到了每个需要被客户端检查的 gRPC server。
让状态更新便宜且可信
不要在每次 Check 时同步执行一次数据库查询、Redis PING 和多个下游 RPC。更稳妥的做法是由后台探测或应用状态机维护就绪状态,Health 服务只读取已经计算好的结果;这样即使依赖本身变慢,健康接口也不会反过来放大故障。
启动阶段先保持 NOT_SERVING,等必要初始化和硬依赖准备完成后再切到 SERVING。优雅下线时先把状态改成不可服务,让客户端停止分配新请求;grpc-go 可在排空前调用 healthServer.Shutdown() 将已知服务统一切到 NOT_SERVING,再关闭连接和进程。进程 liveness 则保持独立,只有进程真正失去自愈能力时才触发重启。