Что такое gRPC 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)
	}
}

Что такое gRPC reflection

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

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

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

Проверка через 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 нужно перезапустить шлюз или инвалидировать кэш.

• Давать ответ про reflection в gRPC-Go только на уровне определения, не показывая поведение в реальном приложении.
• Игнорировать границы ответственности вокруг темы «reflection в gRPC-Go»: кто отменяет работу, кто владеет ресурсом и где формируется ответ клиенту.
• Не связывать reflection в gRPC-Go с observability, тестированием или безопасностью, когда это влияет на продакшен-поведение.

• Точно объясняет, что именно делает reflection в gRPC-Go и где это используется в Go-коде.
• Связывает reflection в gRPC-Go с корректным lifecycle запроса, отменой, конкурентностью или конфигурацией сервера там, где это уместно.
• Не изобретает API и опирается на реальные контракты официальной документации.