Что такое gRPC reflection и когда он полезен?

Question

Accepted Answer

Что такое gRPC reflection

gRPC Server Reflection — стандартный протокол (grpc.reflection.v1), при котором сервер публикует метаданные своих сервисов прямо по gRPC-соединению. Клиент может запросить список сервисов, методов и полные дескрипторы Protobuf без доступа к исходным .proto-файлам.

Когда reflection необходим

Отладка через grpcurl/grpcui — инструменты автоматически получают схему и формируют запросы.
API-шлюзы и прокси — Envoy, grpc-gateway, Kong читают схему динамически.
Самодокументирующиеся сервисы — внутренние порталы могут строить UI без ручного импорта .proto.
Интеграционные тесты — тест-фреймворки проверяют наличие методов по reflection.

Подключение в Go

Пакет google.golang.org/grpc/reflection входит в основной модуль grpc-go. Достаточно одного вызова после создания сервера:

package main

import (
	"log"
	"net"

	"google.golang.org/grpc"
	"google.golang.org/grpc/reflection"

	pb "example.com/gen/helloworld"
)

type server struct{ pb.UnimplementedGreeterServer }

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

	s := grpc.NewServer()
	pb.RegisterGreeterServer(s, &server{})

	// включаем reflection — одна строка
	reflection.Register(s)

	log.Println("serving on :50051")
	if err := s.Serve(lis); err != nil {
		log.Fatalf("serve: %v", err)
	}
}

Проверка через grpcurl

# список сервисов
grpcurl -plaintext localhost:50051 list

# описание конкретного сервиса
grpcurl -plaintext localhost:50051 describe helloworld.Greeter

# вызов метода
grpcurl -plaintext -d '{"name":"World"}' localhost:50051 helloworld.Greeter/SayHello

Версии протокола reflection

Пакет reflection начиная с grpc-go v1.57 регистрирует одновременно grpc.reflection.v1 и grpc.reflection.v1alpha для совместимости со старыми клиентами. Явно выбрать версию можно через reflection.NewServer(reflection.ServerOptions{...}).

Отключение в продакшене

Reflection раскрывает всю схему API. Для production-сервисов рекомендуется включать его только в dev/staging-сборках через переменную окружения:

if os.Getenv("GRPC_REFLECTION") == "true" {
	reflection.Register(s)
}

Подводные камни

Reflection не защищён аутентификацией по умолчанию — любой клиент получает полную схему сервиса.
Пакет необходимо явно импортировать; компилятор Go удалит его при отсутствии использования (blank import _ "google.golang.org/grpc/reflection" не сработает — нужен reflection.Register(s)).
Если сервис зарегистрирован после reflection.Register(s), он всё равно попадёт в reflection — порядок регистрации не важен.
grpcurl по умолчанию ищет v1; старые клиенты ищут v1alpha — убедитесь, что сервер поддерживает оба.
При использовании TLS/mTLS grpcurl требует флагов -cert/-key/-cacert; без них соединение упадёт с handshake error.
Reflection возвращает дескрипторы только зарегистрированных сервисов, но не всех типов в .proto-файле — неиспользуемые message-типы не будут видны.
В микросервисной архитектуре API-шлюз кэширует схему; после обновления .proto нужно перезапустить шлюз или инвалидировать кэш.

Что такое gRPC reflection и когда он полезен?