Качество кода проверять нужно, чтобы потом плохой код не проверял вас на выносливость.
Продолжаем цикл статей по практике применения DevOps.
В первой части Павел Олейников рассказал про процессы DevOps, инструменты, используемые для каждого из них, и работу с Git.
А моя часть посвящена установке и настройке SonarQube для проверки качества кода.
Установка SonarQube и настройка wrapper.conf
SonarQube состоит из двух частей.
- серверная часть SonarQube;
- и sonar-scanner – это утилита, которая анализирует ваши проекты и отправляет данные на сервер SonarQube.
Для работы SonarQube требуется Java 11+
На компьютере, где вы собираетесь работать с SonarQube, обязательно нужно поставить Java, с версией больше 11-й. Мы используем у себя OpenJDK – его можно установить из https://jdk.java.net/archive/. Нужно просто скачать дистрибутив Java с сайта и распаковать его туда, откуда потом будет удобно вызывать.
Установка и настройка SonarQube
Следующим шагом нужно скачать сам SonarQube с официального сайта https://www.sonarqube.org/downloads/. Здесь есть возможность скачать бесплатную версию (Community Edition) и платную. Но нам для 1С пока возможностей бесплатной версии хватает. Тоже скачиваете архив и распаковываете его куда-нибудь.
Чтобы SonarQube заработал, его нужно будет немного настроить.
Все настройки SonarQube лежат в папке conf. Здесь есть:
- файл sonar.properties – это все настройки SonarQube;
- и файл wrapper.conf – это настройки исполняемого файла wrapper.exe.
Настроим wrapper.conf. Если Java у вас не прописана в PATH, вы можете здесь указать абсолютный путь к ней. Обратите внимание, в этом пути слэши должны быть обратные (/), потому что прямые слэши, которые используются в Windows (\), в этом файле могут работать некорректно – wrapper не стартанет и будет выдавать ошибку.
Больше ничего во wrapper.conf настраивать не нужно.
Настройка sonar.properties
Основные настройки находятся в sonar.properties. Здесь можно настроить очень много разных параметров, но нам среди них нужно буквально шесть мест – в файле они все подписаны. Это параметры:
- User credentials
- sonar.jdbc.username
- sonar.jdbc.password
- Microsoft SQLServer
- sonar.jdbc.url
- WEB SERVER
- sonar.web.javaOpts
- COMPUTE ENGINE
- sonar.ce.javaOpts
- ELASTICSEARCH
- sonar.search.javaOpts
Настройка доступа SonarQube к базе данных
Первое, что нужно сделать – это задать настройки доступа к используемой базе данных.
SonarQube для хранения может использовать различные базы данных:
- Embedded Database (внутреннюю базу SonarQube)
- Oracle
- PostgreSQL
- И Microsoft SQLServer – у нас в Инфостарте используется MS SQL.
По умолчанию используется внутренняя база SonarQube, но со временем SonarQube начинает «пухнуть», в нее может что-то не влезть, плюс эта база не поддерживает обновления версий SonarQube. Поэтому мы рекомендуем развернуть специальную базу – или PostgreSQL, или MS SQL, и использовать ее.
Поскольку мы используем аутентификацию самого MS SQL, нам нужно также задать имя пользователя и пароль для доступа к SQL. Если бы у нас была какая-то внутренняя аутентификация, можно было бы без них обойтись. Соответственно, в секции User credentials указываем имя пользователя (sonar.jdbc.username) и пароль (sonar.jdbc.password).
Потом мы указываем строку подключения к MS SQL (sonar.jdbc.url) – IP-адрес, где у нас развернута база и имя базы данных. Пусть вас не смущает, что он через точку с запятой – так оно и должно быть. Этого достаточно, чтобы sonar развернулся на SQL.
Единственный важный момент – когда вы создаете базу на MS SQL, ее порядок сортировки должен быть Case-sensitive, Accent-sensitive (_CS_AS), как на слайде – Cyrillic_General_CS_AS. Это должно быть обязательно, иначе, когда у вас будет запускаться SonarQube, он ругнется, что он не может сюда развернуться. Поэтому важно это не забывать.
Настройки выделения памяти
Теперь надо еще явным образом прописать, сколько выделять памяти Java-машине. У нас всего таких три места:
- sonar.web.javaOpts – память на веб-интерфейс SonarQube,
- sonar.ce.javaOpts – память на фоновые задания, которые там крутятся.
- sonar.search.javaOpts – память на ElasticSearch, который используется для поиска в этой базе данных.
Здесь нам нужно установить параметры Xmx и Xms – сколько мы готовы выделить оперативной памяти на сервере.
- Xms – это сколько он сразу выделяет.
- Xmx – сколько максимум.
Но мы их ставим одинаковыми – пусть сразу выделяет столько, сколько у него есть.
И тут логика такая – если у вас свободной оперативки 10 Гб, вы можете доступные 9 Гб раскидать на эти три строчки: допустим, на веб-интерфейс 2 Гб и по 3,5 Гб на фоновые задания и на Elastic Search.
Остальные параметры мы не используем. Тут очень много возможностей для настройки, но перечисленных параметров достаточно для того, чтобы SonarQube запустился.
Настройка SonarQube
После того как вы отредактировали файл sonar.properties, можно запустить сам SonarQube.
Для его запуска в каталоге bin у нас есть соответствующие папки под каждую из поддерживаемых операционных систем – для Linux, Mac и Windows. Допустим, у нас здесь стоит 64-битный Windows. Заходим сюда:
- здесь есть батник StartSonar, которым можно запустить SonarQube из командной строки;
- можно поставить SonarQube как сервис, чтобы он крутился на сервере как служба:
- файл InstallNTService.bat создает сервис SonarQube в списке сервисов;
- UninstallNTService.bat – удаляет;
- StartNTService.bat запускает сервис;
- а файл StopNTService.bat – останавливает.
Проще всего запускать эти батники из командной строки, потому что, если мы запустим батник двойным кликом в проводнике и будут какие-то ошибки, вы можете просто не успеть их увидеть.
После того как мы запустим сервис, в службах служба появится SonarQube – вы можете уже им пользоваться.
Чтобы проверить, что SonarQube запустился, нужно в браузере написать URL, на котором поднят SonarQube, указать порт (по умолчанию 9000), и в конце нужно написать maintetance. Это, по сути, проверка работоспособности – здесь он показывает, что SonarQube активен, все системы в норме. И дальше вы уже можете приступить к настройке внутри самого SonarQube, посмотреть, как оно работает.
Что здесь важно? Когда вы только устанавливаете SonarQube из коробки, тут есть только один пользователь admin и пароль тоже admin. Этот пароль лучше потом поменять, потому что очень много прав у админа, не стоит всем эти права раздавать.
SonarQube – это платформа, которая расширяется на разные языки программирования с помощью плагинов. Плагины есть бесплатные, а есть платные. Есть дорогие, а есть не очень дорогие.
Плагин можно поставить через магазин – Администрирование – Магазин. Здесь есть куча различных плагинов – часть из них уже установлены в коробочной версии SonarQube (например, самые распространенные – для Java, для C).
Первым делом мы поставим нужные нам плагины:
- 1C (BSL) Community Plugin – это бесплатный плагин, который использует диагностику кода с помощью BSL Language Server. Есть платные варианты, но они обычно стоят очень много денег, а для «попробовать» (понять, насколько это вообще нужно) нам вполне хватает бесплатного.
- Russian Pack – для перевода самого SonarQube на русский язык. Здесь еще не полностью все переведено, но большинство основных команд уже на русском.
Некоторые плагины поставляются разработчиками не через магазин, а отдельно в виде jar-файла. Если чего-то в магазине нет, в папке самого SonarQube есть папка extensions, где в папке plugins находятся исполняемые файлы с расширением jar – это все те плагины, которые у нас сейчас установлены. Поставляемый jar-файл плагина можно просто сюда скопировать, SonarQube это увидит, покажет, что появился новый плагин, его нужно будет перезапустить и потом можно будет этим пользоваться.
Настройка пользователей
Дальше нам обязательно нужно настроить безопасность (Администрирование – Конфигурация – Общие настройки – Безопасность). И мы рекомендуем здесь включать галочку Force user authentication, чтобы у вас анонимные пользователи не могли зайти в SonarQube, чтобы обязательно была авторизация под кем-то.
Через пункт Безопасность – Пользователи мы заводим пользователей.
Здесь заведены пользователи нашего отдела. В качестве почты лучше указывать ту почту, под которой у вас проходят коммиты, чтобы SonarQube сразу понимал, кто какое изменение сделал, кто ответственный.
Здесь просто создаете пользователя – имя для входа, пароль.
Токены доступа
Чтобы работал Sonar-scanner для пользователя, под которым он будет у вас запускаться, нужно обязательно задать токены – для этого здесь есть колонка Токены. Если для пользователя нажать кнопку в этой колонке, можно сгенерировать новый токен.
Сгенерированный токен нужно сохранить, потому что его отсюда просто так не выцепить. После его сохранения под этим токеном может авторизоваться sonar-scanner – тогда не нужно прописывать логин/пароль, достаточно просто токена.
Пороги качества
Дальше – после того как вы настроили пользователей и сделали токены, нам нужно немного кастомизировать SonarQube под себя. Для этого можно использовать так называемые «пороги качества» – это те критерии, по которым мы определяем, что текущую сборку можно выпускать.
По умолчанию в SonarQube есть порог качества Sonar way.
Вы здесь можете создать свой порог качества – мы свой порог назвали Infostart way. У нас сборочная линия настроена так, что если текущая сборка порог качества не проходит, то она валится с ошибкой – говорит, что пока не исправите, никакого релиза не будет.
Здесь можно добавлять различные метрики. Их очень много, можно очень сильно кастомизировать.
Мы для демонстрации пока добавили, что если нет новых блокирующих замечаний, значит, все хорошо, и можно выпускать.
Пороги качества можно ставить как в целом, допустим, по всему SonarQube, так и прописывать отдельно по проектам. Я сейчас поставил по умолчанию, чтобы ко всем новым проектам, которые будут попадать в SonarQube, сразу применялся этот порог качества.
Профили качества
После того как мы настроили пороги качества, посмотрим, какие возможности есть у профилей качества.
Когда мы устанавливаем 1C (BSL) Community Plugin, у нас автоматически появляется профиль для языка 1С (BSL).
Он встроенный. В нем сейчас есть 114 правил. Мы можем в них провалиться по гиперссылке.
Здесь будет выведен полный список этих правил.
Можно посмотреть, что каждое правило в себе содержит – какая у него критичность, какие пороговые значения. Но этот профиль качества – это как конфигурация на поддержке, мы его изменять не можем. Чтобы его изменить, его нужно скопировать.
Мы скопировали этот профиль, назвали его Infostart rules и сделали его для языка 1С (BSL) по умолчанию.
В таблице профилей качества видно, что он отнаследовался от встроенного профиля BSL Language Server rules.
Настройка правил
В этом профиле у нас уже появляется возможность отредактировать правила. Мы можем выбрать гиперссылку в таблице правил и детализировать активные правила, например.
Очень важный момент – здесь слева есть гибкая система фильтров, можно фильтровать по чему угодно.
Например, сейчас в профиле Infostart rules отобраны только активные правила этого профиля.
Допустим, мы здесь можем отредактировать какое-нибудь правило. Например, есть правило «Ограничение на длину строки», которое заключается в том, что строка не должна превышать 120 символов. Это незначительная ошибка, но SonarQube считает, что это ошибка.
А мы говорим, что у нас широкие мониторы, нам 120 символов мало, мы хотим видеть 500 символов. Соответственно, теперь мы поменяли пороговое значение, при котором срабатывает это правило, как ошибочное.
Кроме этого, мы можем поменять серьезность этого правила – указать, что оно у нас блокирующее. Длинные строки выше 500 символов мы в своей конфигурации видеть не хотим.
Тут все достаточно просто настраивается.
Мы всегда можем вернуть родительские настройки по соответствующей кнопке (у нас здесь указан родитель этого правила).
Кроме этого, тут есть неактивные правила. Это те, которые по умолчанию выключены. Но если мы, допустим, хотим, чтобы у нас было запрещено использование тернарного оператора, мы можем это правило активировать, и тогда оно тоже будет срабатывать в нашем коде.
Понятно, что неактивные правила при проверке не отрабатывают, а активные – отрабатывают.
Единственное, что когда у нас наследуется профиль качества от родителя, мы не можем сделать неактивным правилом то, которое было активным у родителя. Поэтому если мы точно не хотим какое-то правило использовать, мы можем отвязать профиль от родителя.
Тогда все правила автоматически станут неактивными, и мы можем выборочно что-то активировать, отредактировать их как хотим – под себя настроить.
Это – что касается самих настроек. Мы установили порог качества, профиль качества, пробежались по каким-то правилам. Это все можно было сделать и позже.
Sonar-scanner
Теперь нам нужно, чтобы у нас в SonarQube появились какие-то данные, содержащие показатели качества кода по нашим проектам – такая красивая картинка, которую можно вставлять во всякие презентации.
Для этого служит приложение sonar-scanner – утилита, которая анализирует ваш проект и проверяет его на соответствие действующим правилам.
Вы можете просто ввести в поисковике sonar-scanner, и первая же ссылка https://docs.sonarqube.org/latest/analysis/scan/sonarscanner/ ведет на сайт SonarQube. Здесь у нас есть возможность скачать sonar-scanner для различных операционных систем. Мы скачиваем sonar-scanner для Windows.
Структура у него стандартная:
- в папке bin находится батник sonar-scanner.bat;
- а в папке conf находится файл sonar-scanner.properties – это настройки.
По умолчанию SonarQube ставится на localhost, но у нас SonarQube крутится на специальном сервере, поэтому мы здесь прописываем свойство sonar.host.url (определенный IP-шник).
Больше здесь никаких особых настроек не нужно.
После всего этого мы заходим в какой-нибудь проект, например, у нас есть выгрузка EDT-шного проекта «Conference» – здесь находятся исходники всех наших подсистем, справочников и всего остального.
Чтобы просканировать проект вручную, надо положить в папку с исходниками батник check.bat и, опционально, еще файл sonar-project.properties.
Пример команды для батника check.bat вы можете получить из самого SonarQube, когда вы добавляете новый проект на закладке Проекты.
Здесь он потребует:
- токен доступа, потому что без токена он работать не хочет;
- далее выбираем язык;
- выбираем операционную систему;
- и здесь будет сгенерирован текст команды, которую можно скопировать в батник.
У нас получилась примерно следующая строка:
sonar-scanner.bat -D"sonar.projectKey=test" -D"sonar.sources=." -D"sonar.host.url=http://10.10.1.150:9000" -D"sonar.login=токен"
- Первым параметром указывается путь, куда мы установили sonar-scanner (путь к тому батнику в папке bin)
- sonar.projectKey – это ключ проекта (по этому ключу у нас будет собираться диагностика по проекту).
- sonar.sources – это какие файлы он должен анализировать этим батником. Для нашего проекта в качестве этого свойства указана папка EDT/src – папка, где лежат все выгруженные файлы конфигурации. Этой некий фильтр, который позволяет управлять тем, что будет сканировать sonar-scanner. Например, если мы хотим сканировать только общие модули, мы можем указать ему в параметре sonar.sources значение EDT/src/CommonModules, тогда он будет проверять только папку CommonModules и отправлять в SonarQube.
- sonar.host.url – мы указываем, где находится сам SonarQube, куда отправлять данные
- sonar.login – токен доступа, под которым мы должны в SonarQube авторизоваться.
Мы у себя в батнике check.bat, который лежит в корне нашего проекта, оставили только токен и ключ проекта, а остальные параметры вынесли в sonar-project.properties.
На Инфостарте есть статья Олега Тымко, где рассказано, как это все настраивается. Там есть ссылка на репозиторий, где можно скачать пример настройки проекта вместе с файлами sonar-project.properties и батником запуска check.bat.
Чтобы запустить анализ, мы снова запускаем командную строку и вызываем в ней батник.
Можно запустить сам батник двойным кликом, но, если будут какие-то ошибки, их будет просто не видно. А ошибки могут быть, например, если вы анализируете какой-то большой проект – Комплексную, ERP. Там вполне вероятно, что у вас памяти не хватит, нужно будет памяти вам побольше выделить, потому что это тяжелый процесс, он сильно нагружает систему.
Мы получили надпись EXECUTION SUCCESS – значит, все отправлено.
Теперь если мы вернемся в SonarQube, у нас порог качества у проекта Conference поменялся на «Пройдено» и обновилась дата последнего анализа.
Навигация по ошибкам и работа над ошибками
После того как мы запустили sonar-scanner и прогнали наш проект, у нас появились какие-то данные, с которыми можно работать дальше.
Провалимся в проект Conference. Здесь у нас построены различные графики, видно, как что менялось со временем. Это, кстати, очень полезно, чтобы видеть, растет ли у нас технический долг.
Допустим, у нас появилось три новых дефекта кода – можно все по гиперссылкам кликнуть. Он показывает, какие файлы с кодом были проанализированы и какие были найдены дефекты кода. Тут также можно сделать отбор по автору и другим параметрам.
И дальше мы работаем с теми замечаниями, которые он нашел. Что мы можем с ними сделать:
-
мы можем поменять тип этого замечания;
-
мы можем поменять важность этого замечания;
-
мы можем временно скрыть по каким-либо причинам замечание;
- мы можем явным образом назначить ответственного замечанию;
- и можем какие-то свои комментарии делать.
Все это можно сделать в ручном режиме или через массовое изменение – выделяем все или только некоторые, и массово меняем то, что нам нужно.
Допустим, удобно, когда у вас стартует новый проект, у вас уже есть какая-то наработанная база с кучей ошибок – непонятно, что с этим делать. Когда у вас первый раз прогонится sonar-scanner, у вас будет несколько тысяч ошибок. Естественно, никто сразу не сможет их исправить, удобно их массово учесть, как неактуальные – убрать их из текущих ошибок, а потом потихоньку рефакторить.
По фильтру можно всегда вернуться к неактуальным, переоткрыть их и исправить – назначать ответственных и потихоньку закрывать свой технический долг, приводить проект в какой-то читабельный, красивый вид.
Но правильнее использовать такой параметр, как «Версия проекта». И первое состояние проекта считать нулевой версией, а все проверки завязать на новый код, который отличается от последней версии.
Типы ошибок
Обратите внимание, что здесь есть несколько типов ошибок:
- просто явные ошибки;
- уязвимости (можно какое-то правило определить как уязвимость);
- дефекты кода;
- есть покрытие тестами – но пока для 1С нет какого штатного плагина или утилиты, как это покрытие высчитывать (я думаю, через какое-то время это тоже появится, мы тоже хотели, чтобы код был полностью покрыт).
- и процент дублирования кода – мы придерживаемся того, что у нас не должен один и тот же код кочевать из модуля в модуль, поэтому мы этот показатель тоже отслеживаем, он тоже важный.
Настройка оповещений
Теперь – еще один момент. Мы хотели бы еще, когда у нас прошла сборка, чтобы нам куда-то прилетало оповещение о том, что что-то произошло – появились какие-то новые ошибки. Это настраивается в несколько этапов.
В меню Администрирование, на закладке Общее у нас есть настройки почты для уведомлений. Мы говорим, от какого почтового ящика мы отправляем эти служебные email, указываем параметры подключения к этой почте.
Важный момент – в качестве Server base URL здесь нужно указать тот IP, на котором у вас находится SonarQube. Это нужно, чтобы гиперссылки в письме ссылались на правильный сервер (по умолчанию он всегда будет отправлять на localhost).
Например, вам придет сообщение, что прошел новый анализ, в новой версии появилось 55 ошибок – хотите их посмотреть? И чтобы к этим ошибкам перейти прямо из письма, вам нужно здесь указать, где у вас находится SonarQube.
После того как вы настроили почту, можно послать себе тестовое письмо и посмотреть, как оно будет выглядеть.
И дальше уже каждый пользователь сам себе настраивает те уведомления, которые он хочет получать. Для этого он заходит в Пользователь – Мой аккаунт – закладка Оповещения.
Здесь есть различные типы событий, о которых нужно оповещать – мы можем указать, что хотим получать все оповещения.
Также мы можем настроить оповещения в рамках каждого проекта.
Например, в рамках проекта Conference мы хотим видеть оповещения только по изменениям в замечаниях, назначенных мне. Тогда для проекта Conference будет своя настройка оповещений.
К сожалению, нет штатной возможности назначать эти оповещения другому пользователю – пока что приходится каждому самому для себя назначать. Возможно, позже какой-то плагин для этого появится. Пока что каждый настраивает сам для себя и, если при анализе были обнаружены проблемы, о которых вы хотите, чтобы вас уведомляли, вам придет напоминалка по почте.
Автоматический запуск анализа
Запускать анализ кода вручную через батник – это хорошо, но хотелось бы, чтобы это можно было делать автоматически. О том, как настроить автоматический запуск анализа кода, вам расскажет Валерий – он будет собирать сборочную линию. В сборочной линии на одном из шагов применяется sonar-scanner, он сканирует текущий проект, посылает результаты в SonarQube и получает данные о том, прошли мы порог качества или не прошли.
Анализ качества кода в EDT
Поскольку разработка конфигурации Conference у нас ведется в EDT, мы хотели непосредственно в процессе разработки видеть замечания по текущему модулю, чтобы не ждать, пока мы что-то закоммитим, scanner все просканирует и только тогда мы что-то увидим.
Мы искали какое-то решение и нашли специальный плагин для EDT https://github.com/DoublesunRUS/ru.capralow.dt.bslls.validator, который использует BSL Language Server – те диагностики, которые используются в 1C (BSL) Community Plugin. Этот плагин сделал Александр Капралов, исходники плагина опубликованы на GitHub.
Этот плагин наряду со стандартной проверкой для EDT показывает вам пул ошибок, которые потом всплывут в SonarQube.
Плагины в EDT ставятся через пункт меню Справка – Установить новое ПО.
Здесь мы должны выбрать сайт Александра Капралова http://capralow.ru/edt/bslls.validator/latest/. Выбираем этот адрес, и устанавливаем плагин. И теперь, если мы зайдем в EDT, мы можем в нем увидеть эти диагностики в режиме разработки модуля.
Давайте посмотрим в списке ошибок SonarQube какой-нибудь дефект. Например, дефект в общем модуле МенеджерОборудованияВызовСервера.
Заходим в это место кода в EDT и видим, что он пишет ровно то же самое, что потом напишет SonarQube. Это очень удобно – сразу такие ошибки исправлять в процессе разработки, не доводить до греха.
В следующих частях продолжим рассказывать:
- про тестирование;
- и про написание сборочной линии для проекта на Jenkins и в зависимости от результата – создания cf-файла релиза или отправки сообщения об ошибках на email.
*************
Данная статья написана по итогам доклада (видео), прочитанного на конференции Infostart Event 2019 Inception.
