Установка и настройка

Прежде чем что-то ставить, разложим по полочкам, что именно мы ставим — путаница здесь источник половины ошибок. Часть первая — runtime-модуль connectrpc.com/connect: обычная Go-зависимость, которую импортирует ваш main.go и сгенерированный код. В нём живут handler, клиент, коды ошибок, конверты запросов и ответов — всё то, что мы видели на примерах первого урока. Часть вторая — генератор: программа buf плюс два плагина кодогенерации. Важный момент, который многие пропускают: плагины protoc-gen-go и protoc-gen-connect-go — это не библиотеки, а самостоятельные исполняемые файлы, написанные на Go; их устанавливает go install, и они должны быть видны в PATH, потому что buf вызывает их по имени. Третья часть — конфигурация: два YAML-файла, buf.yaml (паспорт модуля схем: где лежат proto-файлы и какие правила применять) и buf.gen.yaml (рецепт генерации: какие плагины запускать и куда класть результат). Отдельно проговорю, что НЕ нужно: модуль google.golang.org/grpc. Урок первый показал, что Connect-сервер живёт на net/http, — и зависимости от grpc-go у него нет, protobuf-модуль и стандартная библиотека покрывают всё.

buf — это CLI от той же компании Buf, что написала Connect, и в англоязычных туториалах этап «поставить и настроить buf» часто так и называют: buf setup. Умеет он четыре вещи, важные для нашего курса: generate — запуск плагинов кодогенерации по декларативному конфигу; lint — проверка стиля схем по наборам правил; breaking — проверка, что новая версия схемы не ломает старую; format — автоформатирование proto-файлов. Установка занимает минуты. На macOS и Linux удобнее всего формула Homebrew: brew install bufbuild/buf/buf. Если Homebrew нет, официальный скрипт кладёт бинарник в ~/.local/bin: curl -sSL "https://buf.build/install.sh" | bash. Есть и путь через Go, если вы принципиально держите всё в одном менеджере: go install github.com/bufbuild/buf/cmd/buf@latest. Проверка одна и та же: buf --version должен ответить версией — если shell не нашёл команду, дело почти всегда в PATH. Для Windows есть установщик через Scoop и PowerShell-скрипт, но в курсе мы будем показывать POSIX-варианты.

Теперь плагины — те самые два исполнителя, которые превратят схему в код. Первый — protoc-gen-go: стандартный генератор message-типов от команды protobuf, тот же самый, что работал в gRPC-проектах. Второй — protoc-gen-connect-go: плагин проекта Connect, который создаёт handler-интерфейс, конструктор handler-а и типизированный клиент. Ставятся оба одинаково — go install по последнему тегу: go install google.golang.org/protobuf/cmd/protoc-gen-go@latest и go install connectrpc.com/connect/cmd/protoc-gen-connect-go@latest. Здесь прячется самая частая ловушка всей установки: go install кладёт бинарники в каталог GOBIN, а при пустом GOBIN — в GOPATH/bin (обычно ~/go/bin). Если этот каталог не прописан в PATH, buf потом не найдёт плагины, и вы получите загадочное «program not found or is not executable». Проверьте заранее: go env GOBIN GOPATH, затем which protoc-gen-go и which protoc-gen-connect-go — обе команды должны показывать путь к файлам. Имена бинарников — не украшение: buf ищет их буквально по строке из конфига, поэтому переименовывать или переносить их нельзя.

Окружение готово, время решить, где что лежит. Каноническая минимальная структура Connect-проекта держится на трёх каталогах с чёткими ролями. proto/ — единственное место, которое вы редактируете руками: схемы, и только схемы. gen/ — место сгенерированного кода: туда buf пишет файлы, и редактировать их нельзя категорически, потому что любая перегенерация затрёт правки. cmd/server/ — ваш код: реализация сервиса, монтирование handler-ов, запуск; в маленьких учебных проектах main.go можно держать и в корне модуля, но привычка cmd/server окупится сразу, как появится второй сервис или утилитный клиент. Рядом с ними — buf.yaml и buf.gen.yaml в корне, go.mod с модулем example.com/notes. Отдельный вечный спор — коммитить ли gen/ в git. Два лагеря: одни генерируют в CI и держат репозиторий чистым, другие коммитят — ради простых ревью и сборки без инструментов. Для учебного проекта коммитьте: меньше движущихся частей. Взрослую структуру — с несколькими модулями, линтерами и удалёнными плагинами — разберём отдельным уроком ближе к концу курса, а сейчас зафиксируйте три роли: схемы руками, генерат никогда, ваш код всегда.

Справедливости ради — buf не единственный вариант, и на существующих проектах вы встретите классический protoc. Компилятор ставится пакетом (brew install protobuf или apt install protobuf-compiler) и вызывается с двумя парами флагов: --go_out и --connect-go_out указывают, куда писать, а --go_opt=paths=source_relative и --connect-go_opt=paths=source_relative — как формировать пути. Поисковый запрос protoc connect почти всегда означает ровно эту пару флагов --connect-go_out: так ищут способ подключить connect-генерацию к существующему protoc-пайплайну, и это легитимный сценарий, если у вас уже настроен CI вокруг protoc и переписывать его ради buf-а никто не готов. Но для новых проектов аргументы за buf перевешивают: конфигурация лежит в файлах и версионируется, lint и breaking встроены в тот же тулчейн, а имена плагинов не растягиваются на три строки команды. Мой практический ориентир: protoc — когда вписываетесь в унаследованный пайплайн, buf — во всех остальных случаях, включая весь этот курс.

Финальный тест готовности — три команды. buf lint: если молчит (а buf молчалив при успехе, что поначалу сбивает с толку) — схема notes.v1 проходит правила STANDARD. buf generate: если ls gen/notes/v1 показывает notes.pb.go, а рядом каталог notesv1connect с notes.connect.go — кодогенерация работает end-to-end. И контрольный выстрел: grep NewNoteServiceHandler gen/notes/v1/notesv1connect/notes.connect.go должен найти конструктор — ту самую функцию, которую сервер из первого урока вызывал как данность. На этом окружение собрано полностью: runtime в go.mod, плагины в PATH, buf настроен двумя YAML-файлами, структура каталогов принята, notes.v1 превратилась в код. Если какая-то из трёх проверок не сошлась — вернитесь к order-заданию выше и сверьте порядок шагов; девяносто процентов проблем установки лечатся проверкой PATH и перечитыванием вывода buf, который пишет ошибки вполне внятно.

Окружение собрано, но в gen/ лежит пока мёртвый код — интерфейсы, которые никто не реализует, и конструкторы, которые никто не вызывает. Следующий урок — «Первый Connect-сервис» (03-pervyj-servis) — оживает в три действия: добавим к проекту схему ElizaService, официальный hello world мира Connect-а, реализуем handler с ответами болтуна, соберём main с двумя сервисами на одном mux и сделаем первую curl-проверку по-настоящему запущенного сервера. Заодно выполним обещание первого урока: полностью разберём notes-сервер построчно — вместе с клиентом NewNoteServiceClient и проверкой кодов ошибок. Дальше по курсу: четвёртый урок спустит нас на уровень проводов и покажет, чем на байтах отличаются три протокола, шестой — ошибки и connect.NewError, седьмой — interceptors, девятый — браузерных клиентов на TypeScript. Если прото-синтаксис пока читается с трудом — вернитесь к курсу gRPC: схема proto3 там разобрана с нуля.