Отражение и документация API

Комментарии в proto-файле — обычные C-стилевые строки: двойной слэш перед объявлением. Правило простое, как в Go: комментарий над объявлением service, rpc, message или поля становится документацией этого элемента во всех генератах. protoc-gen-go переносит его doc-комментарием на соответствующий тип и метод — комментарий над rpc попадает на интерфейс вашего хендлера и на клиентский метод, и IDE показывает его при каждом наведении. Комментарий над полем доезжает до struct-поля сгенерированного сообщения. Никакой магии: это текст, который protoc хранит в дескрипторах рядом с именами методов и полей, а плагины решают, что с ним делать. Отсюда первый рабочий вывод — комментарии пишутся для потребителя API, а не для автора: «GetNote возвращает заметку по идентификатору» бесполезно, когда имя метода и так это говорит; полезно объяснить семантику — что вернётся, если заметки нет, чьи заметки видны, какие идентификаторы валидны. Второй вывод — linter может держать планку: в buf есть отдельная категория правил COMMENTS (COMMENT_SERVICE, COMMENT_RPC, COMMENT_FIELD и соседние), которые требуют комментария у каждого сервиса, метода и поля; в дефолтный набор они не входят, их включают в buf.yaml вручную — и с тех пор PR без комментариев не проходит проверку. Третий вывод: формат комментариев стоит стандартизировать в команде — например, первая строка как краткое summary, дальше абзацы деталей, а пометки об экспериментальности и сроках удаления — отдельным тегом. Всё это обычный текст, но дисциплина в комментариях — это то, что отличает схему, по которой можно работать, от схемы, которую приходится раскапывать в исходниках хендлера.

Самый известный генератор документации protobuf — protoc-gen-doc: он читает дескрипторы схемы и её комментарии и выдаёт markdown, HTML, docbook или JSON. Настраивается как обычный плагин в buf.gen.yaml из одиннадцатого урока — либо локально установленным бинарником, либо удалённым плагином BSR buf.build/community/pseudomuto-doc, которому не нужен ничего в вашем окружении. Порядок работы не отличается от кодогенерации: buf generate читает схему, гоняет список плагинов, каждый пишет свои файлы в свой out-каталог. Доки едут в репозиторий рядом с кодом, и это не компромисс, а выигрыш: изменения документации ревьюятся в том же PR, что и изменения схемы, история — в git, а CI из одиннадцатого урока, который гоняет buf generate и проверяет git diff --exit-code, заодно не даёт докам отстать от схемы — забыл перегенерировать, тест не пройдёт. Дальше с артефактом можно делать что угодно: коммитить markdown в папку docs, публиковать HTML на внутренней странице, собирать из JSON собственный портал. Тот же проток документа помогает BSR-модулям из двенадцатого урока: в веб-интерфейсе Buf README модуля и описания элементов видны потребителям, а источник у них всё тот же — комментарии схемы. Единственная ловушка плагина — шаблоны: дефолтный markdown-шаблон выводит всё подряд, и на больших схемах документ превращается в простыню; protoc-gen-doc поддерживает кастомные шаблоны, где вы решаете, что попадёт в короткую справку, а что в полный справочник. Но это уже тюнинг — базовая связка buf generate плюс protoc-gen-doc закрывает потребность в доков для внутреннего API целиком.

Под всеми генераторами лежит одна структура — FileDescriptorSet: компилированное представление proto-файлов, где описаны сообщения, поля, сервисы, методы и — важно для этой темы — комментарии с координатами строк. Получить её можно двумя командами, которые вы уже знаете: buf build -o image.binpb пишет буф-образ, который и есть тот же дескриптор-набор, а классический protoc --descriptor_set_out=out.binpb --include_imports собирает то же самое с импортами. Флаг --include_imports существен: без него в наборе не будет зависимостей вроде well-known-типов, и инструменты, которым нужен полный граф, споткнутся. Дальше начинается самое интересное: сгенерированный Go-код несёт дескриптор в себе. В каждом сгенерированном пакете лежит переменная вида File_notes_v1_note_service_proto — скомпилированный дескриптор файла, из которого всё сгенерировано. Через пакет google.golang.org/protobuf/reflect/protoreflect по этому дескриптору можно пройтись как по данным: перечислить сервисы, у сервиса методы, у метода вход и выход, у файла — комментарии. Именно поэтому рефлексия, генераторы и валидаторы работают без исходных proto-файлов: схема уже внутри вашего бинарника. Практические применения этого факта шире доков: динамический маршрутизатор, который регистрирует хендлеры по списку методов из дескриптора; служебный эндпоинт, отдающий JSON со списком версий API; проверка, что собранный сервис содержит те методы, о которых заявляет деплой. Buf breaking из десятого урока сравнивает дескрипторы старой и новой схемы — тот же механизм, поднятый на уровень CI. Так что когда слышите «схема — это данные», это не лозунг: FileDescriptorSet — обычный protobuf, который можно хранить, сравнивать, публиковать и читать из кода.

Service-рефлексия — протокольная возможность, унаследованная у gRPC: клиент спрашивает сервер «какие у тебя сервисы и методы», и сервер отвечает дескрипторами. Для классического gRPC за это отвечает пакет google.golang.org/grpc/reflection, а grpcurl без флагов -proto сначала стучится в рефлексию. В мире Connect ту же возможность даёт пакет connectrpc.com/grpcreflect: его рефлектор раздаёт дескрипторы ваших сервисов через обычные хендлеры, которые монтируются на тот же mux, что и бизнес-API, — и grpcurl, и buf curl начинают работать против вашего сервера без локальных proto-файлов. Пакет свежий, точное API сверяйте с README, но форма устойчивая: рефлектор конструируется со списком файлов, которые он готов отдавать, и монтируется двумя хендлерами — стабильной версией протокола и ранней alpha, которую слушают текущие grpcurl и buf curl. Список файлов — это те самые сгенерированные переменные File_..._proto из прошлого раздела: вы явно перечисляете, о чём сервер готов рассказывать. Зачем это нужно на практике. Первое — исследовать API: grpcurl list, grpcurl describe — и у новичка в команде вместо просьбы «скинь proto» есть живой источник с актуальным состоянием. Второе — отладка: buf curl против рефлексии отвечает на вопрос «а что сервер реально отдаёт в проде», включая версии методов, которые могли измениться после последнего деплоя. Третье — инструменты: универсальные клиенты и генераторы прокси могут строить запросы по ответу рефлексии. Цена вопроса — поверхность атаки: рефлексия раскрывает всё, что вы ей скормили, включая сервисы, которые вы считали внутренними. Поэтому правило тринадцатого урока продолжается и здесь: на публичном граничном сервере рефлексия либо выключена, либо закрыта авторизацией, либо отдаёт урезанный список файлов.

Proto-схема и рефлексия покрывают внутренний мир, где все понимают RPC. Но у внешнего мира свой язык: Swagger UI, шлюзы, генераторы SDK для языков, в которых proto-инструментария нет, и люди, которым «контракт — это открытый yaml, а не бинарник». Ответ на это — OpenAPI, и для proto-схем он тоже генерируется: главный генератор — protoc-gen-openapiv2 из grpc-gateway, который выдаёт OpenAPI 2.0 (Swagger) прямо из дескрипторов; есть и protoc-gen-openapi из gnostic с OpenAPI 3. Описания в контракте берутся из тех же комментариев схемы — у вас уже всё написано, генератор только разложит текст по полям summary и description. HTTP-маршруты описываются аннотациями google/api/annotations — это те самые googleapis-зависимости из двенадцатого урока: вы объявляете, что GetNote живёт на GET /notes/v1/{id}, и OpenAPI получает настоящий путь с параметрами, а не абстрактный rpc. Для Connect-проекта связка openapi с connect-сервисом — это мост к браузерным клиентам из девятого урока: фронтенд, который ходит через HTTP-шлюз или читает контракты в Swagger UI, получает привычный артефакт; а дружелюбие Connect-протокола к curl из четвёртого урока означает, что примеры из OpenAPI можно исполнять curl-ом буквально. Честная оговорка: protoc-gen-openapiv2 исторически описывает grpc-gateway-маршруты, а не connect-эндпоинты — для чисто connect-трафика путь выглядит как /notes.v1.NoteService/GetNote, и его в контракт дописывают шаблоном плагина или вручную. Поэтому практический порядок такой: OpenAPI — для потребителей за границей вашего RPC-мира (шлюзы, фронтенд-команды, публичный API), а proto и рефлексия — для тех, кто работает с API напрямую. Два артефакта из одного источника, и расхождение между ними физически невозможно.

Документация замкнулась на buf-конвейер: схема описывает контракт словами, генераторы разносят его по потребителям, рефлексия отвечает на вопросы живого сервера. Дальше по курсу: шестнадцатый урок — тестирование, где эта же схема станет предметом тестов полного стека на httptest — шестнадцатый; метрики семнадцатого покажут, как документированный API ведёт себя под нагрузкой. Для повторения: конвейер генерации — в одиннадцатом уроке, lint и breaking changes — в десятом, зависимость googleapis — в двенадцатом. Программа всех двадцати пяти уроков — на странице курса.