Buf с protoc_builtin PHP имеет другое поведение, чем фактический плагин protoc?

Содержание

Вопрос или проблема
Ответ или решение
Проблема с каталогами
Почему возникает проблема?
Решение проблемы
Завершение

Вопрос или проблема

Я мигрирую проект на PHP, используя protoc, к Buf CLI. Чтобы обеспечить обратную совместимость, я пытаюсь заставить Buf производить более-менее точно такой же вывод, как встроенный PHP плагин. Я настроил свой buf.gen.yaml, чтобы использовать protoc_builtin: php в качестве целевого плагина и не указал никаких опций, так как protoc тоже не принимал никаких аргументов раньше.

Когда я запускаю buf generate, бинарные файлы GPBMetadata теперь находятся в неправильной директории. Protoc помещает их в директорию на верхнем уровне вашего вывода, воспроизводя вашу структуру каталогов (даже не ваш путь пакета, просто каталоги).

Вот моя структура каталогов:

src
| users
    | user.proto
| items
    | user_item.proto

Вот моя конфигурация:

version: v2

managed:
  enabled: true

inputs:
  - directory: .
    paths:
      - src

plugins:
  - protoc_builtin: php
    out: buf_out

Запуск buf generate (с вышеуказанной конфигурацией)produces такой вывод:

buf_out
| Users
    | User.php
    | Metadata
        | User.php
| Items
    | UserItem.proto
        | Metadata
            | UserItem.php

Запуск protoc -I=. php_out=builtin_out $(find src -type f -name '*proto') дает следующее:

builtin_out
| Metadata
    | Users
        | User.php
    | Items
        | User_item.proto
| Users
    | User.php
| Items
    | User_item.proto

Обратите внимание также на различия в конвертации Snakecase. Очевидно, что Buf делает больше, чем говорит его документация.

Существуют ли какие-либо флаги для Buf, которые позволят мне вернуть поведение protoc? Или я каким-то образом использую неправильную версию? (использую 1.45.0, кстати)

Вам нужно отключить управляемый режим, чтобы получить такое же поведение, как с protoc и его встроенными плагинами.

В вашем buf.gen.yaml внутри блока managed установите enabled: false или совсем удалите блок.

Ответ или решение

При миграции проекта на PHP с использованием protoc к Buf CLI пользователи часто сталкиваются с несоответствием в выходных данных. Это связано с тем, что плагин protoc_builtin для PHP ведет себя иначе, чем стандартный протокол. В вашем случае проблема заключается в выходных файлах GPBMetadata и их структуре каталогов, которые Buf создает иначе, чем protoc.

Проблема с каталогами

Вы указали, что Buf генерирует выходные файлы в неправильных каталогах. Структура вашей директории, как указано, такова:

src
| users
    | user.proto
| items
    | user_item.proto

Когда вы выполняете команду buf generate, Buf создает следующие каталоги:

buf_out
| Users
    | User.php
    | Metadata
        | User.php
| Items
    | UserItem.proto
        | Metadata
            | UserItem.php

В то время как protoc выводит файлы в следующей структуре:

builtin_out
| Metadata
    | Users
        | User.php
    | Items
        | User_item.proto
| Users
    | User.php
| Items
    | User_item.proto

Как видно, структура каталогов и правила именования различаются.

Почему возникает проблема?

Основная причина — это режим управляемой сборки (managed mode) в Buf, который активирован по умолчанию. Этот режим построен для обеспечения совместимости и управления зависимостями, но он также изменяет способ генерации выходных файлов. В вашем случае это приводит к тому, что Buf не создает выходные файлы в том же формате и расположении, что и protoc.

Решение проблемы

Чтобы вернуть поведение Buf к стандартному protoc, вам необходимо отключить управляемый режим. Для этого в вашем файле конфигурации buf.gen.yaml нужно либо удалить блок managed, либо установить enabled: false. Пример изменения вашей конфигурации:

version: v2

managed:
  enabled: false  # Отключаем управляемый режим.

inputs:
  - directory: .
    paths:
      - src

plugins:
  - protoc_builtin: php
    out: buf_out

Завершение

После внесения изменений перезапустите команду buf generate. Это должно привести к тому, что Buf будет генерировать файлы в структуре каталогов, аналогичной той, что использует protoc. Обратите внимание на возможные другие конфигурации Buff, которые могут влиять на выходные данные. Всегда проверяйте документацию Buf для получения актуальных сведений об изменениях в последней версии.

Если проблема сохраняется даже после отключения управляемого режима, стоит проверить, используете ли вы последнюю версию Buf и обновить ее при необходимости.

Ваша задача заключается в том, чтобы тщательным образом протестировать полученные выходные файлы и убедиться, что ваше приложение корректно работает с новой структурой, прежде чем произойти полное переключение на Buf.