Почему не protobuf.js: контроль над кодогенерацией и бинарным контрактом без сюрпризов
Текст написан с позиции марта 2024 года: так, как тема выглядела тогда, без технологий и событий, появившихся позже.
Когда в JavaScript-проекте возникает тема Protocol Buffers, очень быстро всплывает почти автоматический ответ: взять готовую экосистему, подключить protobuf.js и закрыть вопрос. На первый взгляд это выглядит рационально. Библиотека известная, задача распространенная, сериализация и десериализация уже решены, значит нет смысла изобретать собственный путь. Но чем ближе подходишь не к демо-сценарию, а к реальной архитектуре, тем заметнее становится одна важная проблема: далеко не всегда хочется просто “уметь читать protobuf”. Иногда нужно контролировать сам контракт, процесс кодогенерации, форму бинарного протокола и способ, которым этот протокол встраивается в транспорт и типовую систему приложения.
Именно в этот момент вопрос перестает звучать как “какую библиотеку взять для protobuf”, и начинает звучать иначе: “насколько я контролирую цепочку от .proto до runtime-сообщения”. Для одних команд protobuf.js действительно остается хорошим готовым ответом. Но для других он оказывается слишком общим, слишком высокоуровневым или слишком непрозрачным в тех местах, где нужен не просто runtime, а управляемый contract-first pipeline. И тогда логика меняется: вместо того чтобы подстраивать архитектуру под чужую библиотеку, хочется собрать свой слой из более контролируемых деталей.
Именно так раскрывается история с @veksa/protobuf-parser и @veksa/protobuf-codec. Первая библиотека парсит .proto-файлы в структурированное представление JavaScript/TypeScript, поддерживает syntax 3 и возвращает схему с messages, enums, services, options, imports и другими элементами. Вторая реализует protobuf codec для @veksa/transport, поддерживает type-safe message handling, binary encoding/decoding и задает поля сообщений через явные массивы FieldItem. В связке это уже не “еще одна protobuf-библиотека”, а попытка взять под контроль полный путь от контракта до бинарного сообщения без лишних скрытых слоев.
Проблема не в protobuf.js как таковом
Сразу важно зафиксировать: разговор “почему не protobuf.js” не обязан быть нападением на саму библиотеку. Проблема обычно не в том, что готовое решение плохое. Проблема в том, что у готового решения уже есть собственная модель мира. Оно предполагает определенный стиль работы с .proto, свой runtime, свою степень абстракции, свою форму codegen- или reflection-подхода и свой способ связывания схемы с приложением. Если этот мир совпадает с вашей архитектурой, все отлично. Если нет, начинаются компромиссы.
Именно на зрелом этапе проекта это становится критично. Пока система маленькая, любая рабочая сериализация кажется достаточной. Но как только protobuf начинает играть роль не просто формата, а центрального контракта между клиентом и сервером, между несколькими транспортами или между несколькими runtime-контекстами, уже хочется не просто удобной библиотеки, а максимально предсказуемого пайплайна. Хочется понимать, откуда берется тип, как генерируется поле, где задается tag, как кодируется payload, кто контролирует oneof, как отражаются services и каким образом все это вплетается в transport.
Вот здесь и появляется главный архитектурный мотив: не минимизировать количество собственного кода любой ценой, а минимизировать количество сюрпризов в контракте.
Почему контроль над кодогенерацией вообще важен
Во многих командах code generation по-прежнему воспринимают как техническое удобство. Мол, хорошо, когда типы появляются автоматически, но это не ядро архитектуры. На практике все наоборот. Если protobuf объявлен источником правды, кодогенерация становится не бонусом, а главным способом удержать клиент, сервер и transport в одном договоре.
Проблема любой непрозрачной генерации в том, что она быстро превращается в отдельную экосистему со своей логикой. Разработчик видит уже сгенерированный результат, но хуже контролирует промежуточные этапы. Когда в проекте нужно не просто получить классы из .proto, а встроить контракт в свою внутреннюю messaging-модель, в свой runtime, в свои transport adapters и в свои правила типизации, хочется иметь схему, доступную как данные. Не как черный ящик, а как объект, по которому можно построить свой pipeline.
@veksa/protobuf-parser как раз интересен тем, что работает на этом уровне. В документации библиотека описана как легковесный парсер для JavaScript и TypeScript, который превращает protobuf definition files в структурированное JavaScript-представление. Среди заявленных возможностей — поддержка Protocol Buffers syntax 3, обработка messages, enums, services, options и аккуратная обработка ошибок с указанием строки и столбца. А возвращаемая Schema включает syntax, package, imports, enums, messages, options, extends, services и comment.
Именно такой слой особенно ценен, когда хочется контролировать генерацию самому. Парсер не навязывает итоговую форму клиентского кода. Он не говорит, как именно вы обязаны строить runtime. Он сначала дает схему как структуру. А дальше уже вы решаете, какие типы генерировать, как маппить messages на payload types, как связывать services с transport API и где проводить границу между compile-time и runtime.
Когда готовый runtime становится лишним посредником
Одна из типичных причин отказаться от универсальной библиотеки — желание не иметь лишнего промежуточного слоя между контрактом и сообщением. Чем больше в цепочке скрытых механизмов, тем труднее объяснить себе, почему бинарный пакет получился именно таким, как эволюционирует схема и как гарантировать совместимость в нестандартных сценариях.
Если команда строит собственный messaging transport, собственный протокол событий или двунаправленный обмен между несколькими контекстами, ей часто важно, чтобы бинарный codec не жил полностью отдельной жизнью. Хочется, чтобы он был встроен в transport language приложения, а не просто “где-то рядом сериализовал payload”. В таком режиме избыточный runtime может начать мешать, потому что он решает задачу слишком широко и не учитывает ваши архитектурные правила.
@veksa/protobuf-codec интересен как раз более прямым подходом. В описании библиотеки она представлена как реализация Protocol Buffers codec для messaging-слоя @veksa/transport. Среди его возможностей перечислены protobuf encoding/decoding для транспорта, эффективная бинарная сериализация и десериализация, поддержка всех типов данных Protocol Buffers, type-safe обработка сообщений на TypeScript, настройка полей через простые массивы, легковесная реализация с минимумом зависимостей и полная интеграция с @veksa/transport.
Это уже совсем другой архитектурный акцент. Не “универсальный protobuf runtime сам по себе”, а codec, завязанный на ваш транспортный слой и вашу модель сообщений. То есть бинарный контракт становится не внешней подсистемой, а частью общей transport-архитектуры.
Явные FieldItem вместо магии вокруг схемы
Очень показательно, что @veksa/protobuf-codec задает поля сообщений через массивы FieldItem. В документации приводится формат [tag, name, type, required, oneof?, anyof?], а также перечисляется поддержка простых типов, maps, repeated fields, wrapped fields и nested messages. Это может показаться менее “красивым”, чем полностью автоматическая генерация классов, но именно в этом и заключается ценность подхода.
Когда структура поля выражена явно, контракт становится ближе к данным, а не к магии runtime. Вы в буквальном смысле видите номер тега, имя, тип, обязательность, принадлежность к oneof и другие параметры. Это очень важное свойство для систем, где совместимость и предсказуемость важнее, чем ощущение “все произошло автоматически”.
Такой подход особенно хорош, когда генерация идет в две стадии. Сначала parser читает .proto и превращает его в схему. Потом поверх схемы ваш codegen выводит ровно те FieldItem-структуры и TypeScript-типы, которые нужны transport-слою. В результате бинарный codec не зависит от opaque runtime-представления. Он зависит от тех структур, которые вы сами же и сгенерировали из контракта.
Именно здесь заголовок “без сюрпризов” перестает быть лозунгом. Если поле поменялось, это видно в схеме. Если codegen поменял FieldItem, это видно в результатах генерации. Если бинарный пакет изменился, у изменения есть прозрачный путь от .proto к codec map.
Parser как фундамент, а не как вспомогательная утилита
Во многих системах парсер .proto воспринимается как промежуточный технический шаг. Но в contract-first архитектуре это гораздо более важный элемент. Если у вас есть собственный parser layer, вы перестаете зависеть от того, какую именно форму сгенерированного кода кто-то другой считает правильной. Вы работаете не с чужим мнением о вашей схеме, а с самой схемой.
У @veksa/protobuf-parser здесь хорошо читаемая роль. Он не обещает “полный экосистемный фреймворк”. Он решает конкретную задачу: дать структурированный доступ к .proto. Поддержка messages, enums, services, imports и options делает его достаточной основой для своей генерации, а zero runtime dependencies, кроме @veksa/protobuf-tokenizer, подчеркивает легковесность слоя. В документации также указано требование TypeScript 5.4 или новее.
С архитектурной точки зрения это очень здоровый баланс. Чем проще и честнее фундамент, тем меньше вероятность, что он внезапно начнет диктовать поведение верхним слоям. Парсер должен разбирать контракт, а не решать за вас, какой должна быть вся среда вокруг него.
Контроль над бинарным контрактом важнее, чем “удобный API”
Готовые библиотеки часто продают себя через удобство использования. И это понятный аргумент. Но в системах, где protobuf является межсистемным договором, удобный API не всегда главный критерий. Гораздо важнее знать, что wire contract стабилен, предсказуем и контролируем. То есть что вы не обнаружите внезапно в рантайме неочевидное преобразование, скрытую нормализацию схемы или несовпадение между тем, как вы интерпретируете контракт, и тем, как его интерпретирует библиотека.
Поэтому идея “почему не protobuf.js” в таком контексте звучит вполне практично. Не потому что хочется меньше абстракций вообще, а потому что хочется только те абстракции, которые находятся под вашим наблюдением. Чем меньше слой скрытой логики между контрактом и бинарным пакетом, тем легче сопровождать протокол много лет.
Если у проекта длинный жизненный цикл, это преимущество становится очень ощутимым. Сегодня вам нужно просто сериализовать пару сообщений. Завтра вы добавляете transport adapters. Послезавтра строите shared contract между браузером, сервером и embedded client. Еще через полгода внедряете строгую типогенерацию и сервисные маппинги. В такой эволюции прозрачный pipeline выигрывает у готовой коробки намного чаще, чем кажется в начале.
Почему transport-интеграция меняет всю картину
Обычно protobuf обсуждают в отрыве от transport. Но в реальном приложении сообщение почти никогда не существует в вакууме. Оно проходит через сокет, канал событий, host-client bridge, iframe messaging или другой messaging layer. И если protobuf остается изолированной технологией, а transport живет своей жизнью, система быстро начинает дробиться на несколько несовместимых уровней.
Здесь особенно интересен тот факт, что @veksa/protobuf-codec изначально позиционируется не как абстрактная библиотека кодирования, а как codec для @veksa/transport. То есть сериализация встроена в messaging-модель. Более того, в документации демонстрируется API createProtobufCodec(apiMap), которое возвращает объект, реализующий ITransportCodec с методами encode(message: IMessage) и decode(buffer).
Это очень важное архитектурное решение. Оно означает, что типы сообщений, бинарный формат и транспортный runtime разговаривают на одном языке. Когда контракт меняется, вы не просто обновляете классы protobuf, а перестраиваете целый communication contract. Для message-driven систем это намного сильнее, чем просто иметь где-то поддержку protobuf.
Codegen под свою модель, а не под чужую
Самая сильная причина идти по пути parser + codec обычно именно в этом: хочется генерировать не “как положено библиотеке”, а как нужно вашей системе. Один проект хочет получить чистые TS-типы и transport maps. Другой — таблицы сервисов, payload type registries и message contracts. Третий — общий слой для клиента и сервера с минимальным runtime и строгим контролем бинарных полей. Универсальная библиотека редко угадывает все эти сценарии одновременно.
Когда у вас есть parser, вы можете строить собственный codegen поверх реальной схемы. Хотите разделить compile-time types и runtime field maps — пожалуйста. Хотите генерировать тонкие transport wrappers вместо классов — пожалуйста. Хотите на клиенте иметь только типы и codec tables, а на сервере отдельный binding — тоже возможно. В этом и состоит реальная свобода.
Именно поэтому вопрос “почему не protobuf.js” в 2024 году все чаще упирается не в производительность и не в количество звезд на GitHub, а в ownership над архитектурой. Кто контролирует кодогенерацию, тот контролирует не только DX, но и совместимость протокола.
Меньше зависимостей — меньше скрытой политики
Легковесность здесь важна не только ради размера пакета. Когда в фундаменте у вас меньше зависимостей и меньше чужой runtime-политики, проще понять, что именно происходит в системе. В описании @veksa/protobuf-parser отдельно подчеркивается отсутствие runtime-зависимостей, кроме токенизатора. В документации @veksa/protobuf-codec заявлена легковесная реализация с минимумом зависимостей. Это выглядит как небольшая деталь, но на архитектурном уровне это очень важный сигнал: слой должен делать свое дело, а не приносить с собой слишком много дополнительного поведения.
Для библиотек, через которые проходит контракт между системами, это особенно ценно. Любая избыточная магия в такой точке потом дорого стоит при отладке, миграции или анализе несовместимости. Чем прозрачнее фундамент, тем устойчивее весь протокол.
Где такой подход особенно выигрывает
Подход parser + custom codegen + codec особенно силен в нескольких типах систем. Во-первых, в тех, где protobuf — это не разовая интеграция, а долгоживущий межсервисный контракт. Во-вторых, в приложениях с собственным transport layer, где сообщение должно жить внутри единой messaging-модели. В-третьих, там, где клиент и сервер должны делить один источник правды, но при этом иметь разные runtime-представления. В-четвертых, в проектах, где важно понимать бинарный контракт буквально на уровне поля и тега, а не доверять этот слой внешней экосистеме целиком.
Еще один важный сценарий — постепенная эволюция. Можно начать с parser как инструмента чтения .proto, затем добавить генерацию TS-типов, потом вывести FieldItem-массивы для codec, затем связать это с transport. Такой путь гораздо спокойнее, чем большой и мгновенный переход на чужую полную экосистему, от которой потом трудно отделаться.
Это не путь “сделаем все сами”, а путь “сделаем только критическое сами”
Со стороны такой подход иногда выглядит как попытка написать собственный protobuf-мир с нуля. Но на деле это не обязательно так. Здесь важна не максимальная самостоятельность, а правильный уровень самостоятельности. Не нужно переписывать все подряд. Нужно взять под контроль только те слои, которые формируют долгоживущий контракт и правила его эволюции.
Парсер решает задачу понимания схемы. Кодогенерация решает задачу проекции схемы в типы и runtime tables. Codec решает задачу бинарной сериализации внутри транспортного слоя. Все. Это не “все свое”, это “свое ровно там, где нельзя жить на чужих предположениях”.
Именно поэтому такой стек выглядит особенно разумно в 2024 году. Современные TypeScript-проекты уже достаточно зрелые, чтобы не путать удобство старта с управляемостью архитектуры на дистанции.
За контроль над контрактом вы расплачиваетесь glue-кодом и дисциплиной
Разумеется, такой путь не бесплатный. Если вы отказываетесь от готовой экосистемы в пользу parser + собственного codegen + своего codec layer, вы берете на себя ответственность за glue-код, эволюцию генерации, тесты совместимости и дисциплину вокруг контракта. Это не нужно скрывать. Подход оправдан только тогда, когда выигрыш от контроля действительно важнее, чем стоимость поддержки своей цепочки.
Но именно здесь и проходит взрослая инженерная граница. Для небольшого проекта может быть разумнее жить на готовом решении. Для системы, где бинарный контракт — это одна из опор архитектуры, цена контроля вполне может быть дешевле, чем цена постоянных компромиссов с чужой моделью.
Почему в 2024 году это уже не экзотика
К марту 2024 года фронтенд и full-stack TypeScript уже давно вышли за пределы модели “клиент просто получает JSON”. У многих систем есть shared schema, persistent transports, message-driven communication, embedded contexts, multi-runtime архитектура и все более строгая типизация. На этом фоне желание иметь собственный contract pipeline выглядит не прихотью, а естественной реакцией на сложность продукта.
Когда protobuf становится частью такого pipeline, контроль над кодогенерацией и бинарным контрактом перестает быть узкой низкоуровневой задачей. Он становится способом удержать систему от медленного расползания между слоями. И в этом смысле parser + codec — это не альтернатива “из любви к своим велосипедам”, а способ держать договор между системами в максимально прозрачной форме.
Заключение
Вопрос “почему не protobuf.js” на самом деле почти никогда не про вкусы. Он про архитектурный ownership. Если вам нужен просто рабочий protobuf runtime, готовая библиотека может быть полностью достаточной. Но если вам нужен контроль над тем, как .proto превращается в типы, как контракт отражается в transport, как задаются поля, как выглядит wire format и как вся эта цепочка живет без скрытых сюрпризов, тогда готовый универсальный слой уже не всегда лучший выбор.
@veksa/protobuf-parser и @veksa/protobuf-codec хорошо показывают именно такую логику. Parser дает доступ к схеме как к данным: syntax 3, messages, enums, services, imports, options и структурированный Schema. Codec дает бинарный слой, интегрированный с transport, с type-safe message handling и явными FieldItem-массивами для описания структуры сообщений. Вместе это создает не просто поддержку protobuf, а контролируемый contract-first pipeline.
Именно поэтому аргумент звучит так: не “protobuf.js плох”, а “в некоторых системах слишком дорог каждый слой, который ты не контролируешь”. Когда контракт важнее convenience, а бинарная совместимость важнее красивой магии, путь через собственный parser, свою генерацию и свой codec оказывается не усложнением, а самым прямым способом построить протокол без сюрпризов.