4. gRPC 服务端实现：注册服务、启动监听、Graceful Shutdown、拦截器（Interceptor）基础

本章聚焦 gRPC-Go 服务端核心实现环节，涵盖服务注册、监听启动、优雅关闭（Graceful Shutdown）以及拦截器（Interceptor）的基础用法。这些是构建生产级 gRPC 服务的基础设施，也是契约审计中检查服务端实现合规性的关键点。

4.1 服务注册与启动监听

gRPC 服务端通过 grpc.NewServer() 创建实例，随后调用生成的 RegisterXxxServer 函数将服务实现注册到该实例上。启动监听则通过 Server.Serve() 方法完成，该方法会阻塞当前 goroutine 直到发生错误或服务停止。

// 示例：服务注册与启动
lis, err := net.Listen("tcp", ":50051")
if err != nil {
    log.Fatalf("failed to listen: %v", err)
}

s := grpc.NewServer()
pb.RegisterUserServiceServer(s, &userServer{})

// 在 goroutine 中启动服务
go func() {
    log.Printf("server listening at %v", lis.Addr())
    if err := s.Serve(lis); err != nil {
        log.Fatalf("failed to serve: %v", err)
    }
}()

4.2 Graceful Shutdown（优雅关闭）

优雅关闭确保服务在收到终止信号后，先停止接受新请求，等待正在处理的请求完成，再释放资源。gRPC 提供了 GracefulStop() 方法实现此功能。审计中需确认服务是否实现了信号监听与优雅关闭逻辑。

// 示例：优雅关闭实现
ch := make(chan os.Signal, 1)
signal.Notify(ch, syscall.SIGINT, syscall.SIGTERM)

<-ch // 等待信号
log.Println("shutting down gracefully...")

s.GracefulStop()
log.Println("server stopped")

4.3 拦截器（Interceptor）基础

拦截器是 gRPC 提供的中间件机制，允许在 RPC 调用前后注入通用逻辑（如日志、认证、监控、限流）。gRPC-Go 支持一元拦截器（Unary Interceptor）和流拦截器（Stream Interceptor），分别对应普通 RPC 和流式 RPC。

4.3.1 一元拦截器（Unary Interceptor）

一元拦截器通过 grpc.UnaryInterceptor 或 grpc.ChainUnaryInterceptor 注册。函数签名如下：

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

// 示例：日志拦截器
func loggingInterceptor(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error) {
    log.Printf("gRPC method: %s, request: %v", info.FullMethod, req)
    resp, err := handler(ctx, req)
    log.Printf("gRPC method: %s, response: %v, err: %v", info.FullMethod, resp, err)
    return resp, err
}

// 注册
s := grpc.NewServer(
    grpc.ChainUnaryInterceptor(loggingInterceptor, authInterceptor),
)

4.3.2 流拦截器（Stream Interceptor）

流拦截器用于拦截流式 RPC，通过 grpc.StreamInterceptor 或 grpc.ChainStreamInterceptor 注册。函数签名：

func(srv interface{}, ss grpc.ServerStream, info *grpc.StreamServerInfo, handler grpc.StreamHandler) error

4.4 拦截器注册方式对比

4.5 完整服务端启动模板

以下是一个集成了注册、优雅关闭和链式拦截器的完整启动模板：

func main() {
    lis, _ := net.Listen("tcp", ":50051")

    s := grpc.NewServer(
        grpc.ChainUnaryInterceptor(
            loggingInterceptor,
            recoveryInterceptor,
        ),
        grpc.ChainStreamInterceptor(
            streamLoggingInterceptor,
        ),
    )

    pb.RegisterUserServiceServer(s, &userServer{})

    // 优雅关闭
    ch := make(chan os.Signal, 1)
    signal.Notify(ch, syscall.SIGINT, syscall.SIGTERM)

    go func() {
        <-ch
        log.Println("shutting down...")
        s.GracefulStop()
    }()

    log.Println("server starting...")
    if err := s.Serve(lis); err != nil {
        log.Fatalf("serve error: %v", err)
    }
}

4.6 审计检查清单

• 服务注册： 是否使用 pb.RegisterXxxServer 注册了所有服务？
• 监听启动： Serve() 是否在 goroutine 中运行？是否处理了 Serve() 返回的错误？
• 优雅关闭： 是否监听了 SIGINT/SIGTERM？是否调用了 GracefulStop() 而非 Stop()？
• 拦截器： 是否使用了链式拦截器？拦截器是否按正确顺序注册？是否包含必要的日志、恢复、认证拦截器？
• 资源释放： 关闭后是否释放了监听器、数据库连接等资源？