Integrations
Supports running protolint in GitHub workflows through various actions including github/super-linter, plexsystems/protolint-action, and yoheimuta/action-protolint
Supports JetBrains GoLand through the intellij-protolint plugin for Protocol Buffer linting
Integrates with JetBrains IDEs through the intellij-protolint plugin for Protocol Buffer linting
протолинт
protolint — это подключаемая утилита для линтинга/исправления файлов Protocol Buffer (proto2+proto3):
- Работает быстро, так как не требует компилятора.
- Легко следовать официальному руководству по стилю. Правила и руководство по стилю точно соответствуют друг другу.
- Fixer автоматически исправляет все возможные нарушения официального руководства по стилю.
- Позволяет отключать правила с комментарием в файле буфера протокола.
- Это полезно для проектов, в которых необходимо поддерживать совместимость с API и при этом максимально строго соблюдать руководство по стилю.
- Некоторые правила можно автоматически отключить, добавив комментарии к обнаруженным нарушениям.
- Загружает плагины для хранения ваших пользовательских правил линтинга.
- Прошел проверку по всем правилам.
- Множество интеграционных поддержек.
- плагин протокола
- Интеграция редактора
- Действие GitHub
- Интеграция CI
Демо
После настройки сервера MCP вы можете попросить любые клиенты MCP, такие как Claude Desktop, выполнить линтинг и исправить ваши файлы буфера протокола следующим образом:
Кроме того, vim-protolint работает следующим образом.
MCP-сервер
protolint теперь поддерживает протокол контекста модели (MCP) , который позволяет моделям ИИ напрямую взаимодействовать с protolint.
Использование
Подробную документацию по использованию и интеграции функциональности сервера MCP Protolint см. в документации MCP .
Установка
Через Homebrew
protolint можно установить для Mac или Linux с помощью Homebrew через кран yoheimuta/protolint .
Поскольку homebrew-core включает protolint,
вы также можете установить его просто brew install protolint.
Это tap по умолчанию, который устанавливается по умолчанию. Он проще, но не поддерживается тем же автором. Чтобы поддерживать его в актуальном состоянии, я рекомендую вам сначала запустить brew tap yoheimuta/protolint
.
Через GitHub Releases
Вы также можете загрузить готовый двоичный файл с этой страницы релиза:
В разделе загрузок каждого релиза вы можете найти готовые двоичные файлы в пакетах .tar.gz.
Используйте поддерживаемый образ Docker
protolint поставляет образ Docker yoheimuta/protolint , который позволяет использовать protolint как часть рабочего процесса Docker.
Из источника
Бинарник можно установить из исходного кода, если доступен Go. Однако я рекомендую использовать один из готовых бинарных файлов, поскольку он не содержит информации о версии.
В JavaScript/TypeScript
Вы можете использовать protolint
с помощью менеджера пакетов nodejs, например npm
или yarn
.
Это добавит ссылку на зависимость разработки в ваш локальный package.json
.
Во время установки будет вызван скрипт install.mjs . Он загрузит соответствующий protolint
с github. Так же, как @electron/get , вы можете обойти загрузку, используя следующие переменные среды:
Переменная среды | Значение по умолчанию | Описание |
---|---|---|
PROTOLINT_MIRROR_HOST | https://github.com | Базовый URL-адрес HTTP/веб-сервера, на котором размещены двоичные файлы |
PROTOLINT_MIRROR_REMOTE_PATH | yoheimuta/protolint/загрузка/релизы | Путь к архивам на удаленном хосте |
PROTOLINT_MIRROR_USERNAME | Имя пользователя базовой аутентификации HTTP | |
PROTOLINT_MIRROR_PASSWORD | Пароль базовой аутентификации HTTP | |
ПРОТОЛИНТ_ПРОКСИ | HTTP(S)-прокси с дополнительными данными аутентификации |
В удаленном пути архивы со страницы релизов должны быть зеркальными.
После этого вы можете использовать npx protolint
(со всеми предоставленными аргументами protolint) в своих dev-скриптах.
Вы можете добавить узел protolint
в свой package.json
, который может содержать содержимое protolint.yml
под узлом lint
, т. е. корневым элементом конфигурации будет protolint
.
Если вы хотите получить вывод, соответствующий компилятору TSC, используйте reporter tsc
.
В проектах Python
Вы можете использовать protolint
как линтер в своих проектах python, wheel protolint-bin
на pypi содержит предварительно скомпилированные двоичные файлы для различных платформ. Просто добавьте нужную версию в свой pyproject.toml
или requirements.txt
.
Загруженные wheels будут содержать скомпилированные двоичные файлы go для protolint
и protoc-gen-protolint
. Ваша платформа должна быть совместима с поддерживаемыми бинарными платформами.
Конфигурацию linter можно добавить в пакет tools.protolint
в pyproject.toml
.
Использование
protolint не требует настройки по умолчанию, для большинства проектов он должен работать «из коробки».
Интеграция контроля версий
protolint доступен как pre-commit hook. Добавьте это в ваш .pre-commit-config.yaml
в вашем репозитории, чтобы запустить protolint с Go:
или альтернативно используйте это для запуска protolint с Docker:
Интеграция редактора
Код Visual Studio
JetBrains IntelliJ IDEA, GoLand, WebStorm, PHPStorm, PyCharm...
Vim ( движок ALE )
Vim ( синтаксис )
Действие GitHub
Действие GitHub для запуска protolint в ваших рабочих процессах
- github/super-linter
- плекссистемы/протолинт-действие
- yoheimuta/action-protolint - Интегрировано с reviewdog
Интеграция CI
Плагины Jenkins
- warnings-ng и любые, которые используют violatons-lib
Конкретный вывод для окружающей среды
Можно отформатировать линтинг в соответствии с форматированием среды CI/CD. Среда должна быть установлена с использованием формата вывода. В настоящее время реализован следующий вывод:
Среда | Значение командной строки | Описание | Пример |
---|---|---|---|
Действия Github | ci-gh | Помощь с Github | ::warning file=example.proto,line=10,col=20,title=ENUM_NAMES_UPPER_CAMEL_CASE::EnumField name \"SECOND.VALUE\" must be CAPITALS_WITH_UNDERSCORES |
AzureDevOps-решения | ci-az | Помощь Azure DevOps | ##vso[task.logissue type=warning;sourcepath=example.proto;linenumber=10;columnnumber=20;code=ENUM_NAMES_UPPER_CAMEL_CASE;]EnumField name \"SECOND.VALUE\" must be CAPITALS_WITH_UNDERSCORES |
Gitlab CI/CD | ci-глаб | Обратное проектирование на основе примеров | WARNING: ENUM_NAMES_UPPER_CAMEL_CASE example.proto(10,20) : EnumField name \"SECOND.VALUE\" must be CAPITALS_WITH_UNDERSCORES |
Вы также можете использовать универсальный форматтер ci
, который создаст универсальный сопоставитель проблем.
С помощью значения ci-env
вы можете указать шаблон из следующих переменных среды:
Переменная среды | Приоритет | Значение |
---|---|---|
PROTOLINT_CIREPORTER_TEMPLATE_STRING | 1 | Строка, содержащая Go-шаблон |
PROTOLINT_CIREPORTER_TEMPLATE_FILE | 2 | Путь к файлу, содержащему Go-шаблон |
Полученный перевод строки добавлять не нужно, так как он будет добавлен автоматически.
Доступны следующие поля:
Severity
: серьёзность в виде строки (примечание, предупреждение или ошибка)
File
: Путь к файлу, содержащему ошибку.
Line
: Строка в file
, содержащая ошибку (начальная позиция)
Column
: Столбец в file
, содержащий ошибку (начальная позиция)
Rule
: Название правила, которое является ошибочным.
Message
: Сообщение об ошибке, описывающее ошибку.
Создание выходного файла и потока ошибок CI/CD
Вы можете создать определенный вывод, соответствующий вашей среде CI/CD, а также создать выходной файл, например, для ваших инструментов статического анализа кода, таких как github CodeQL или SonarQube.
Это можно сделать, добавив флаг --add-reporter
. Обратите внимание, что значение должно быть отформатировано как <reporter-name>:<output-file-path>
(без <
и >
).
Использовать как плагин протокола
protolint также поддерживает бинарный protoc-gen-protolint , который выполняет функциональность lint как плагин protoc. Подробности см. в cmd/protoc-gen-protolint/README.md .
Это полезно в ситуациях, когда у вас уже есть рабочий процесс плагина protoc.
Звонок из Go кода
Вы также можете использовать protolint из кода Go. Подробности смотрите в документации Go и lib/lint_test.go .
Правила
Подробности смотрите в internal/addon/rules
.
Набор правил следующий:
- Официальное руководство по стилю . Это включено по умолчанию. По сути, эти правила могут исправить нарушения, добавив опцию
-fix
. - Неофициальное руководство по стилю. По умолчанию отключено. Вы можете включить каждое правило с помощью
.protolint.yaml
.
Опция -fix
в командной строке может автоматически исправить все проблемы, о которых сообщают правила fixable. См. столбцы Fixable ниже.
Параметр -auto_disable
в командной строке может автоматически отключить все проблемы, о которых сообщают правила автоматического отключения. Эта функция полезна, когда исправление существующих нарушений нарушает совместимость. См. столбцы AutoDisable ниже.
- *1: Эти правила не должны поддерживать AutoDisable, поскольку исправления не нарушают их совместимость. Вам следует запустить protolint с
-fix
.
Официально | Исправимо | Автоотключение | ИДЕНТИФИКАТОР | Цель |
---|---|---|---|---|
Да | ✅ | ✅ | ENUM_FIELD_NAMES_PREFIX | Проверяет, что имена полей перечисления имеют префикс ENUM_NAME_UPPER_SNAKE_CASE. |
Да | ✅ | ✅ | ENUM_FIELD_NAMES_UPPER_SNAKE_CASE | Проверяет, что все имена полей перечисления являются ЗАГЛАВНЫМИ_БУКВАМИ_С_ПОДЧЕРКАМИ. |
Да | ✅ | ✅ | ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH | Проверяет, что перечисление с нулевым значением должно иметь суффикс (например, "UNSPECIFIED", "INVALID"). Значение по умолчанию — "UNSPECIFIED". Вы можете настроить конкретный суффикс с помощью .protolint.yaml . |
Да | ✅ | ✅ | ENUM_NAMES_UPPER_CAMEL_CASE | Проверяет, что все имена перечислений имеют CamelCase (с заглавной буквы). |
Да | ✅ | *1 | FILE_NAMES_LOWER_SNAKE_CASE | Проверяет, что все имена файлов имеют вид lower_snake_case.proto. Вы можете настроить исключенные файлы с помощью .protolint.yaml . |
Да | ✅ | ✅ | FIELD_NAMES_LOWER_SNAKE_CASE | Проверяет, что все имена полей разделены символом подчеркивания. |
Да | ✅ | *1 | ИМПОРТ_СОРТИРОВКА | Проверяет, что все импорты отсортированы. |
Да | ✅ | ✅ | MESSAGE_NAMES_UPPER_CAMEL_CASE | Проверяет, что все имена сообщений написаны в стиле CamelCase (с заглавной буквы). |
Да | ✅ | *1 | ЗАКАЗ | Проверяет, что все файлы должны быть упорядочены определенным образом. |
Да | ✅ | *1 | PACKAGE_NAME_LOWER_CASE | Проверяет, что имя пакета должно содержать только строчные буквы. |
Да | ✅ | ✅ | RPC_NAMES_UPPER_CAMEL_CASE | Проверяет, что все имена rpc имеют формат CamelCase (с заглавной буквы). |
Да | ✅ | ✅ | SERVICE_NAMES_UPPER_CAMEL_CASE | Проверяет, что все названия служб написаны в стиле CamelCase (с заглавной буквы). |
Да | ✅ | ✅ | ПОВТОРЯЕМЫЕ_НАЗВАНИЯ_ПОЛЕЙ_МНОЖЕСТВЕННО | Проверяет, что повторяющиеся имена полей являются именами во множественном числе. |
Да | ✅ | *1 | ЦИТАТА_КОНСИСТЕНТНАЯ | Проверяет, что использование кавычек для строк является согласованным. По умолчанию используются двойные кавычки. Вы можете настроить конкретную кавычку с помощью .protolint.yaml . |
Да | ✅ | *1 | ОТСТУП | Обеспечивает последовательный стиль отступов. Стиль по умолчанию — 2 пробела. Вставка соответствующих новых строк также принудительно выполняется по умолчанию. Вы можете настроить детали с помощью .protolint.yaml . |
Да | ✅ | *1 | PROTO3_FIELDS_AVOID_REQUIRED | Проверяет, что все поля не являются обязательными для proto3. |
Да | _ | ✅ | PROTO3_GROUPS_AVOID | Проверяет, что для proto3 следует избегать всех групп. |
Да | _ | *1 | МАКСИМАЛЬНАЯ_ДЛИНА_ЛИНИИ | Устанавливает максимальную длину строки. Длина строки определяется как количество символов Unicode в строке. Значение по умолчанию — 80 символов. Вы можете настроить детали с помощью .protolint.yaml . |
Нет | _ | - | SERVICE_NAMES_END_WITH | Обеспечивает согласованный суффикс для имен служб. Вы можете настроить конкретный суффикс с помощью .protolint.yaml . |
Нет | _ | - | FIELD_NAMES_EXCLUDE_PREPOSITIONS | Проверяет, что все имена полей не содержат предлоги (например, "for", "during", "at"). Вы можете настроить определенные предлоги и исключенные ключевые слова с помощью .protolint.yaml . |
Нет | _ | - | MESSAGE_NAMES_EXCLUDE_PREPOSITIONS | Проверяет, что все имена сообщений не содержат предлоги (например, «С», «Для»). Вы можете настроить определенные предлоги и исключенные ключевые слова с помощью .protolint.yaml . |
Нет | _ | - | RPC_NAMES_CASE | Проверяет, что все имена rpc соответствуют указанному соглашению. Вам необходимо настроить конкретное соглашение с помощью .protolint.yaml . |
Нет | _ | - | СООБЩЕНИЯ_ИМЕЮТ_КОММЕНТАРИЙ | Проверяет, что все сообщения имеют комментарий. Вы можете настроить принудительное использование комментариев в стиле Golang с помощью .protolint.yaml . |
Нет | _ | - | SERVICES_HAVE_COMMENT | Проверяет, что все службы имеют комментарий. Вы можете настроить принудительное применение комментариев в стиле Golang с помощью .protolint.yaml . |
Нет | _ | - | RPCS_HAVE_COMMENT | Проверяет, что все rps имеют комментарий. Вы можете настроить принудительное применение комментариев в стиле Golang с помощью .protolint.yaml . |
Нет | _ | - | FIELDS_HAVE_COMMENT | Проверяет, что все поля имеют комментарий. Вы можете настроить принудительное использование комментариев в стиле Golang с помощью .protolint.yaml . |
Нет | _ | - | ENUMS_HAVE_COMMENT | Проверяет, что все перечисления имеют комментарий. Вы можете настроить принудительное использование комментариев в стиле Golang с помощью .protolint.yaml . |
Нет | _ | - | ENUM_FIELDS_HAVE_COMMENT | Проверяет, что все поля enum имеют комментарий. Вы можете настроить принудительное использование комментариев в стиле Golang с помощью .protolint.yaml . |
Нет | _ | - | ФАЙЛ_ИМЕЕТ_КОММЕНТАРИЙ | Проверяет, начинается ли файл с комментария документа. |
Нет | _ | - | СИНТАКСИС_ПОСЛЕДОВАТЕЛЬНЫЙ | Проверяет, что синтаксис — это указанная версия. По умолчанию — proto3. Вы можете настроить версию с помощью .protolint.yaml . |
Я рекомендую вам добавить all_default: true
в .protolint.yaml
, поскольку все указанные выше линтеры включаются автоматически, так что вы всегда можете пользоваться максимальными преимуществами при каждом обновлении protolint.
Вот несколько примеров, которые показывают, что хороший стиль включен по умолчанию. -
— плохой стиль, +
— хороший стиль:
ENUM_FIELD_NAMES_PREFIX
ENUM_FIELD_NAMES_UPPER_SNAKE_CASE
ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH
ENUM_NAMES_UPPER_CAMEL_CASE
FIELD_NAMES_LOWER_SNAKE_CASE
ИМПОРТ_СОРТИРОВКА
MESSAGE_NAMES_UPPER_CAMEL_CASE
ЗАКАЗ
PACKAGE_NAME_LOWER_CASE
RPC_NAMES_UPPER_CAMEL_CASE
RPC_NAMES_UPPER_CAMEL_CASE
ПОВТОРЯЕМЫЕ_НАЗВАНИЯ_ПОЛЕЙ_МНОЖЕСТВЕННО
ОТСТУП
ЦИТАТА_КОНСИСТЕНТНАЯ
Создание собственных правил
protolint — это подключаемый линтер, позволяющий свободно создавать собственные правила линтинга.
Полный пример проекта (он же плагин) включен в этот репозиторий в каталоге _example/plugin .
Репортеры
protolint поставляется с несколькими встроенными репортерами (они же форматировщиками) для управления внешним видом результатов линтинга.
Вы можете указать репортера, используя флаг -reporter в командной строке. Например, -reporter junit
использует репортер junit.
Встроенные параметры репортера:
- простой (по умолчанию)
- юнит
- json
- шариф
- сонар (формат общего выпуска SonarQube)
- юникс
- tsc (совместим с компилятором TypeScript)
Настройка
Отключить правила в файле буфера протокола
Правила можно отключить с помощью комментария внутри файла Protocol Buffer в следующем формате. Правила будут отключены до конца файла или пока линтер не увидит соответствующий разрешающий комментарий:
Также можно изменить команду отключения, добавив :next или :this, чтобы применить команду только к этой (текущей) или следующей строке соответственно.
Например:
Установите параметр командной строки -auto_disable
в next
, this
будут вставляться команды отключения при обнаружении проблем.
Вы можете указать опцию -fix
вместе. Правила, поддерживающие auto_disable, подавляют нарушения, а не исправляют их, вызывающие несовместимость схемы.
Файл конфигурации
protolint может работать с использованием файла конфигурации с именем .protolint.yaml
.
Спецификацию файла конфигурации см. в _example/config/.protolint.yaml .
protolint автоматически выполнит поиск текущего рабочего каталога для файла конфигурации по умолчанию и последующих родительских каталогов вплоть до корневого каталога файловой системы. И он может выполнять поиск в указанном каталоге с флагом -config_dir_path
. Он также может выполнять поиск в указанном файле с флагом --config_path
.
Коды выхода
При линтинге файлов protolint завершит работу с одним из следующих кодов завершения:
0
: Линтинг прошел успешно, ошибок линтинга нет.1
: Линтинг прошел успешно, и обнаружена как минимум одна ошибка линтинга.2
: Линтинг не удался из-за всех остальных ошибок, таких как ошибки синтаксического анализа, внутренние ошибки и ошибки времени выполнения.
Мотивация
По состоянию на 20.12.2018 существуют аналогичные линтеры protobuf.
Один из них — плагин для компилятора Protocol Buffers от Google.
- Если вы просто хотите линтинговать файлы, создание среды компиляции может оказаться утомительным.
- И обычно на компиляцию файлов уходит гораздо больше времени, чем на их анализ.
Other — это инструмент командной строки, который также анализирует файлы буфера протокола.
- Несмотря на то, что в нем есть много функций помимо линтера, он кажется громоздким для пользователей, которым нужен только линтер.
- Правило «линта» склоняется к тому, чтобы быть упрямым.
- Более того, набор правил и официальное руководство по стилю не соответствуют друг другу в точности. Требуется детально понять и правила, и руководство, а затем точно объединить правила.
Другие инструменты
17 декабря 2019 г. я написал статью, в которой сравнивал различные линтеры Protocol Buffer, включая protolint.
- https://qiita.com/yoheimuta/items/da7678fcd046b93a2637
- ПРИМЕЧАНИЕ: Этот текст написан на японском языке.
Зависимости
Разработка
Выпускать
Для упрощения процесса выпуска и уменьшения человеческих ошибок в репозиторий включен скрипт release.sh
. Этот скрипт автоматизирует шаги, необходимые для создания и отправки нового тега выпуска.
Как использовать
Чтобы создать новый релиз, выполните следующую команду:
Лицензия
Лицензия MIT (MIT)
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
protolint-mcp
Related MCP Servers
- GoMIT License
- PythonApache 2.0
- Rust
- TypeScriptMIT License