4. gRPC 服务端实现：Server创建、拦截器注册、优雅启停、健康检查

本章聚焦于 gRPC 服务端的完整实现流程，涵盖 Server 的创建与配置、拦截器（Interceptor）的注册机制、基于系统信号的优雅启停（Graceful Shutdown）以及标准健康检查（Health Check）协议的集成。这是构建生产级 gRPC 微服务的核心基础环节。

4.1 gRPC Server 创建与核心配置

gRPC 服务端的创建通过 grpc.NewServer() 函数完成，该函数接受可变数量的 ServerOption 参数。以下表格列出了生产环境中常用的配置选项：

4.2 拦截器注册机制与链式调用

gRPC 拦截器分为一元拦截器（UnaryInterceptor）和流拦截器（StreamInterceptor）。在 Go 1.17+ 版本中，推荐使用 grpc.ChainUnaryInterceptor 和 grpc.ChainStreamInterceptor 实现链式注册，避免手动嵌套。

以下是一元拦截器的标准签名：

type UnaryServerInterceptor func(
    ctx context.Context,
    req interface{},
    info *grpc.UnaryServerInfo,
    handler grpc.UnaryHandler,
) (resp interface{}, err error)

链式注册的执行顺序遵循“先进先出”原则：第一个注册的拦截器最先处理请求上下文，最后一个注册的拦截器最接近实际业务 handler。

以下是一个包含日志、鉴权、链路追踪三个拦截器的链式注册示例：

import (
    "google.golang.org/grpc"
    "google.golang.org/grpc/keepalive"
)

func NewGRPCServer() *grpc.Server {
    // 1. 定义拦截器
    loggingInterceptor := func(ctx context.Context, req interface{},
        info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error) {
        // 前置日志
        resp, err := handler(ctx, req)
        // 后置日志
        return resp, err
    }

    authInterceptor := func(ctx context.Context, req interface{},
        info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error) {
        // 鉴权逻辑
        return handler(ctx, req)
    }

    tracingInterceptor := func(ctx context.Context, req interface{},
        info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error) {
        // 链路追踪上下文注入
        return handler(ctx, req)
    }

    // 2. 创建 Server 并链式注册
    srv := grpc.NewServer(
        grpc.KeepaliveParams(keepalive.ServerParameters{
            MaxConnectionIdle: 5 * time.Minute,
            Time:              2 * time.Hour,
            Timeout:           20 * time.Second,
        }),
        grpc.KeepaliveEnforcementPolicy(keepalive.EnforcementPolicy{
            MinTime:             5 * time.Second,
            PermitWithoutStream: false,
        }),
        grpc.ChainUnaryInterceptor(
            loggingInterceptor,
            authInterceptor,
            tracingInterceptor,
        ),
        grpc.MaxRecvMsgSize(10 * 1024 * 1024), // 10MB
    )
    return srv
}

4.3 优雅启停（Graceful Shutdown）实现

优雅启停的核心目标是：在进程收到终止信号（SIGINT/SIGTERM）时，停止接受新连接，等待正在处理的 RPC 请求完成，然后释放资源并退出。Go 标准库 os/signal 配合 grpc.Server.GracefulStop() 方法实现此模式。

标准优雅启停流程如下：

1. 创建 net.Listener 监听指定端口。
2. 启动 gRPC Server 的 Serve() 方法（阻塞）。
3. 在另一个 goroutine 中监听系统信号（SIGINT, SIGTERM）。
4. 收到信号后，调用 srv.GracefulStop() 等待现有请求完成。
5. 关闭其他资源（数据库连接、消息队列等）。
6. 调用 os.Exit(0) 退出。

func main() {
    lis, err := net.Listen("tcp", ":50051")
    if err != nil {
        log.Fatalf("failed to listen: %v", err)
    }

    srv := NewGRPCServer()
    // 注册业务服务
    pb.RegisterUserServiceServer(srv, &UserServiceImpl{})

    // 启动健康检查服务
    healthcheck.RegisterHealthServer(srv, healthcheck.NewHealthChecker())

    // 优雅启停
    go func() {
        sigCh := make(chan os.Signal, 1)
        signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
        sig := <-sigCh
        log.Printf("received signal %v, starting graceful shutdown", sig)
        srv.GracefulStop()
        log.Println("gRPC server stopped gracefully")
    }()

    log.Println("gRPC server listening on :50051")
    if err := srv.Serve(lis); err != nil {
        log.Fatalf("failed to serve: %v", err)
    }
}

4.4 健康检查（Health Check）集成

gRPC 提供了标准的健康检查协议（grpc.health.v1.Health），服务端需要注册 HealthServer 并实现 Check 和 Watch 方法。客户端（如 Kubernetes liveness/readiness probe、Envoy 代理）可以通过该协议探测服务状态。

健康检查状态枚举：

以下是一个自定义健康检查实现，支持按服务名称设置状态：

import (
    "google.golang.org/grpc/health"
    "google.golang.org/grpc/health/grpc_health_v1"
)

type HealthChecker struct {
    *health.Server
}

func NewHealthChecker() *HealthChecker {
    h := &HealthChecker{
        Server: health.NewServer(),
    }
    // 初始设置所有服务为 SERVING
    h.SetServingStatus("", grpc_health_v1.HealthCheckResponse_SERVING)
    h.SetServingStatus("user.UserService", grpc_health_v1.HealthCheckResponse_SERVING)
    return h
}

// 在服务依赖（如数据库）就绪后调用
func (h *HealthChecker) MarkReady(service string) {
    h.SetServingStatus(service, grpc_health_v1.HealthCheckResponse_SERVING)
}

// 在服务依赖故障时调用
func (h *HealthChecker) MarkUnready(service string) {
    h.SetServingStatus(service, grpc_health_v1.HealthCheckResponse_NOT_SERVING)
}

4.5 整体架构流程

下图展示了 gRPC 服务端从启动到优雅关闭的完整生命周期，以及拦截器链与健康检查的协作关系：

4.6 完整服务端启动模板

综合以上所有要素，以下是一个可直接用于生产环境的 gRPC 服务端启动模板：

package main

import (
    "log"
    "net"
    "os"
    "os/signal"
    "syscall"
    "time"

    "google.golang.org/grpc"
    "google.golang.org/grpc/health"
    "google.golang.org/grpc/health/grpc_health_v1"
    "google.golang.org/grpc/keepalive"
)

func main() {
    lis, err := net.Listen("tcp", ":50051")
    if err != nil {
        log.Fatalf("failed to listen: %v", err)
    }

    srv := grpc.NewServer(
        grpc.KeepaliveParams(keepalive.ServerParameters{
            MaxConnectionIdle: 5 * time.Minute,
            Time:              2 * time.Hour,
            Timeout:           20 * time.Second,
        }),
        grpc.KeepaliveEnforcementPolicy(keepalive.EnforcementPolicy{
            MinTime:             5 * time.Second,
            PermitWithoutStream: false,
        }),
        grpc.ChainUnaryInterceptor(
            loggingInterceptor,
            authInterceptor,
            tracingInterceptor,
        ),
        grpc.MaxRecvMsgSize(10 * 1024 * 1024),
    )

    // 注册业务服务
    pb.RegisterUserServiceServer(srv, &UserServiceImpl{})

    // 注册健康检查
    healthSrv := health.NewServer()
    healthSrv.SetServingStatus("", grpc_health_v1.HealthCheckResponse_SERVING)
    healthSrv.SetServingStatus("user.UserService", grpc_health_v1.HealthCheckResponse_SERVING)
    grpc_health_v1.RegisterHealthServer(srv, healthSrv)

    // 优雅启停
    go func() {
        sigCh := make(chan os.Signal, 1)
        signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
        sig := <-sigCh
        log.Printf("received signal %v, starting graceful shutdown", sig)

        // 先标记健康检查为 NOT_SERVING，通知负载均衡器
        healthSrv.SetServingStatus("", grpc_health_v1.HealthCheckResponse_NOT_SERVING)
        healthSrv.SetServingStatus("user.UserService", grpc_health_v1.HealthCheckResponse_NOT_SERVING)

        srv.GracefulStop()
        log.Println("gRPC server stopped gracefully")
    }()

    log.Println("gRPC server listening on :50051")
    if err := srv.Serve(lis); err != nil {
        log.Fatalf("failed to serve: %v", err)
    }
}