Клиенты: подключение из Go

Для каждого сервиса из .proto-схемы плагин создаёт три вещи. Первая — интерфейс NoteServiceClient с методами, зеркально повторяющими rpc-объявления: GetNote и CreateNote из схемы превращаются в методы с сигнатурой (запрос) — (ответ, error). Вторая — конструктор NewNoteServiceClient(httpClient, baseURL, options...), который собирает реализацию этого интерфейса. Обратите внимание на первый аргумент: это не строка и не специальный канал связи, а самый обыкновенный *http.Client из стандартной библиотеки — тот самый, которым вы ходите в REST-эндпоинты. Третья — интерфейсная проверка на этапе компиляции: если серверная реализация и клиентский интерфейс расходятся со схемой, сборка падает раньше, чем код доедет до прода. Это тот же proto-first контракт, который вы знаете по gRPC: типы генерируются из схемы, а не описываются руками. Конструктор также принимает переменный список опций ClientOption — именно через них чуть позже мы будем выбирать протокол, включать сжатие и подключать перехватчики. Если вы проходили курс по gRPC, сопоставьте это с grpc.NewClient и NewNoteServiceClient из пакета pb: связь с сервером, балансировка и переиспользование соединений там прячутся внутри ClientConn, здесь же роль транспорта играет честный http.Client со всеми его таймаутами, cookie jar-ом и прокси-настройками.

По умолчанию сгенерированный клиент разговаривает на собственном протоколе Connect — том самом, который едет по HTTP/1.1 или HTTP/2 без трейлеров и с осмысленными HTTP-статусами. Если сервер собран на Connect (или на чём-то, что понимает все три протокола, как наш handler из урока про протоколы), ничего настраивать не нужно. А вот чтобы заставить клиента говорить по-другому, есть две опции. connect.WithGRPC() переключает клиента на классический gRPC — полный паритет со спецификацией, включая трейлеры и требование HTTP/2. connect.WithGRPCWeb() включает gRPC-Web — протокол с закодированными в тело трейлерами, который исторически придумали для браузеров, но иногда используют и в Go. Зачем это нужно на практике? Первая причина — окружение: перед вашим сервисом стоит балансировщик или ingress, который понимает только gRPC, и клиент должен вписаться в эту цепочку. Вторая — совместимость: вы вызываете чужой сервис, собранный на чистом grpc-go, и он принимает только application/grpc. В обоих случаях сгенерированный клиент не меняется — меняется лишь опция в конструкторе. Схема, код вызова, обработка ошибок остаются прежними: это и есть обещание «один клиент — три протокола», зеркальное к серверному «один handler — три протокола».

Пункт про HTTP/2 стоит разобрать по-инженерному, потому что именно здесь новички спотыкаются чаще всего. Ситуация первая: сервер за TLS, адрес начинается с https. Стандартный http.Client умеет переговоры ALPN и поднимет HTTP/2 сам — ничего делать не нужно. Ситуация вторая: локальная разработка, сервер слушает открытый TCP без сертификатов, а клиенту нужен именно gRPC-протокол. Обычный http.Client по http:// пойдёт на HTTP/1.1, и gRPC-вызов развалится. Лечится это транспортом h2c — HTTP/2 без шифрования — из пакета golang.org/x/net/http2: создаёте http2.Transport с AllowHTTP: true и DialTLSContext, который вместо рукопожатия TLS просто открывает TCP-соединение, и оборачиваете его в http.Client. Код ниже — канонический рецепт из документации Connect. Третья ситуация: продакшен за ingress. Здесь правило простое — HTTP/2 должен дожить от клиента до сервера целиком; если посередине стоит терминирующий TLS-балансировщик, проверьте, что и следующий хоп тоже HTTP/2 или что он честно переводит запросы, иначе gRPC-протокол обломается посередине пути. Для Connect-протокола и gRPC-Web этих требований нет: они осознанно спроектированы жить и на HTTP/1.1 — ещё одна причина, почему дефолтный протокол такой удобный.

Редкий вызов живёт без метаданных: трассировочные заголовки, идентификатор запроса, токен доступа — всё это должно доехать от клиента до handler-а. В gRPC для этого существовали metadata.NewOutgoingContext и md.Pairs — мы подробно разбирали эту механику в уроке про метаданные и контекст курса gRPC. В Connect философия проще: метаданные — это обычные HTTP-заголовки, без промежуточного типа. Для сгенерированного клиента Unary-вызов принимает message напрямую, поэтому вкладывать заголовки в каждый вызов он не умеет — их добавляет перехватчик, о котором поговорим в седьмом уроке: клиентский interceptor навешивает Authorization на каждый исходящий запрос в одном месте. А вот у универсального generic-клиента, к которому мы сейчас переходим, запрос — это полноценный объект connect.NewRequest с методом Header(), и заголовки ставятся прямо на нём. Заметьте симметрию с сервером: handler читает их через req.Header().Get — один и тот же map, одна и та же семантика, никакого нового словаря. Именно поэтому между gRPC и Connect так просто переносятся трассировка и авторизация: стандартные заголовки остаются стандартными заголовками.

Контекст в Connect — не церемониальный параметр, а полноценный канал управления вызовом, точно так же, как и в gRPC и в обычном net/http. context.WithTimeout ограничивает время жизни вызова: если сервер не успел ответить до истечения дедлайна, клиент возвращает ошибку с кодом deadline_exceeded — и это не локальная имитация, а честный обрыв обеих сторон. Важно понимать, что дедлайн едет по проводу: gRPC передаёт его заголовком grpc-timeout, а у Connect-протокола для unary-вызовов есть собственный заголовок connect-timeout-ms — сервер видит дедлайн и старается уложиться, а если не успевает, возвращает соответствующий код. Отмена работает так же: context.WithCancel плюс cancel() по крестику в интерфейсе — и обе стороны получают уведомление, что продолжать смысла нет; серверный хендлер, который уважает ctx.Done(), перестанет гореть напрасно. Практические привычки из мира net/http здесь полностью переносимы: дедлайн ставьте на каждый вызов, а не только на «долгие»; значения таймаута наследуйте от SLA вышестоящего запроса, а не от потолка сервера; никогда не игнорируйте возвращённый cancel — иначе утечёте горутиной. Если вы привыкли к правилам курса net/http — здесь они без изменений, и это большой подарок по сравнению с собственным тайм-менеджментом gRPC-клиента.

Ещё одно следствие proto-first подхода, которое вы оцените ближе к проекту: сгенерированный клиент — это интерфейс, а не конкретный тип. Там, где ваш сервис зависит от NoteServiceClient, вы принимаете интерфейс и спокойно подставляете фейк в тестах — ровно та же дисциплина, которой учит любой зрелый Go-проект. Возьмите за правило: бизнес-логика не собирает http.Client и не знает адресов — конструктор клиента вызывается в main, а вниз по слоям передаётся уже интерфейс. Если хочется границу провести ещё жёстче, определите свой маленький интерфейс потребителя с одним-двумя методами — GetNote, CreateNote — и адаптируйте сгенерированный клиент к нему в композиционном корне; на этапе тестирования подмените его ручной заглушкой, которая возвращает фиксированную заметку. Полноценную механику мок-клиентов, httptest-серверы и приёмы интеграционных тестов мы отдельно разберём в шестнадцатом уроке про тестирование Connect-сервисов — там пригодится и generic-клиент из этого урока, потому что он позволяет строить лёгкие in-memory заглушки без сети. Пока запомните принцип: зависимость от клиента объявляет потребитель, реализация приходит снаружи. Это тот же шов, вокруг которого строились тесты в курсах Gin и Echo, только типы теперь генерируются из схемы.

Две настройки клиента, которые стоит знать до того, как заметки вырастут до больших сообщений. Первая — сжатие: по умолчанию клиент декларирует, что умеет читать gzip, а включить его на отправку можно опцией connect.WithGZIP() (в свежих версиях библиотеки она разделена на WithSendGzip и WithAcceptGzip). Библиотека сравнивает допустимое сжатие с тем, что объявил сервер, и выбирает рабочий вариант автоматически — в этом преимущество протокола, который договаривается по-HTTP-ному, через Accept-Encoding. Вторая — лимиты размера: опции WithSendMaxBytes и WithReadMaxBytes ограничивают, сколько клиент готов отправить и принять, и защищают от сюрпризов вида «один отчёт на двести мегабайт положил и клиент, и сервер». Симметричные настройки есть и у handler-а — там мы их подробно разберём в уроке про сжатие и производительность, вместе с HTTP/2-нюансами больших стримов. Здесь зафиксируйте принцип: лимиты ставят на обоих концах, клиент — чтобы не отправить лишнего и не принять внезапный поток, сервер — чтобы не принять его. Ошибки превышения приезжают клиенту тем же *connect.Error с кодом resource_exhausted — первое пересечение этой пары уроков, но далеко не последнее.

Мы научились вызывать Connect-сервисы из Go: конструктор клиента, три протокола, транспорт, метаданные, контекст. Но любой реальный вызов рано или поздно заканчивается не ответом, а ошибкой — и здесь у Connect есть свой словарь: шестнадцать кодов gRPC, их отображение в HTTP-статусы, *connect.Error с методами Code и Message и правила выбора кода, о которые спотыкаются даже опытные команды. Следующий урок — «Обработка ошибок» — целиком посвящён этой стороне жизни: от connect.NewError в хендлере до корректной обработки на клиенте. После ошибок возьмёмся за перехватчики — единое место для логирования, метрик и авторизации на обоих концах провода; затем стриминг, браузерные клиенты и buf-тулчейн. Программа всех двадцати пяти уроков живёт на странице курса. А если хочется сравнить клиентский опыт с классикой — загляните в урок про gRPC-клиент из курса по gRPC: как увидите, переход почти незаметен, и это лучший показатель качества API Connect.