Управляй качеством кода 1С с помощью SonarQube

Оглавление

• Введение
• Управление техническим долгом
• Быстрый старт
  • Первый этап
  • Генерация token
  • Добавление новых пользователей
  • Интерфейс на Русском языке
  • Подготовка каталога проекта
    • Ручная выгрузка через конфигуратор
  • Второй этап
  • Последний этап
  • Проблемные ситуации
• Анализ проекта
• Расширенный пример
  • Подготовка каталога проекта
  • Выгрузка результата
• Подведем итоги
• Дальнейшее развитие темы
• Благодарности
• Ссылки

Введение

После разработки проектов и задач на 1С, собственно как и в других языках программирования, приходится сталкиваться с техническим долгом.

Что такое технический долг? Технический долг - это метафора программной инженерии, обозначающая накопленные в программном коде или архитектуре проблемы, связанные с пренебрежением к качеству при разработке программного обеспечения и вызывающие дополнительные затраты труда в будущем (Wikipedia).

Причины возникновения могут быть разными:

• Недостаточная компетентность кадров;

• Давление со стороны бизнеса;

• Плохо спроектированная архитектура и отсутствие документации;

• Отсутствие процессов review и refactoring;

• Отсутствует тестирование;

Основная причина, почему нужно управлять качеством кода - это увеличение стоимости сопровождения и разработки продукта в дальнейшем из-за технического долга.

Управление техническим долгом

Управлять техническим долгом можно следующим подходами:

• Внешний аудит - привлечение сторонней компании. Затратно, на результат может влиять человеческий фактор.

• Внутренний аудит - визуальная проверка кода (code review).  Опять же на результат влияет человеческий фактор и иногда необъективность.

• Автоматизированная проверка кода - применяются статические анализаторы. В мире 1С используется конфигурация 1С: АПК.

Существует еще один подход, который я считаю наиболее эффективным - непрерывная проверка кода (continuous code inspection). Более подробно можно изучить подход в статье Управление техническим долгом - Концепция Continuous Inspection. Мой выбор пал на SonarQube.

SonarQube - программное решение для непрерывного анализа и измерения качества кода. На текущий момент платформой поддерживается более 27 языков программирования. К сожалению, язык 1С не включен в официальный перечень поддерживаемых языков SonarQube. 

На рынке существует как минимум два плагина для поддержки языка 1С в SonarQube.

• SonarQube 1C (BSL) Community Plugin - open source решение (https://github.com/1c-syntax/sonar-bsl-plugin-community).

• SONARQUBE 1C (BSL) Plugin  - решение от SilverBulleters. (https://silverbulleters.org/sonarqube).

В статье используется плагин SonarQube 1C (BSL) Community Plugin, т.к. он бесплатен. Плагин основан на проекте BSL Language Server - реализации протокола language server protocol для языка 1С: Предприятие 8 и OneScript. 

Быстрый старт

В рамках базового примера мы развернем SonarQube, подготовим рабочий каталог проекта 1С, загрузим результаты проверки кода на сервис. В примере будет использоваться операционная система Windows. Повторить то же самое для unix / macos систем возможно, но с небольшими изменениями. Все скрипты будем выполнять в консоли CMD или Powershell (не имеет значения).

Мною заранее был заготовлен шаблон рабочего окружения. Скачиваем его по ссылке.

git clone https://github.com/otymko/article-sonar-for-infostart.git

Визуально проект выглядит:

В его состав входят:

• project1c - рабочий каталог с проектом для анализа.

  • src - каталог для исходных кодов 1С

  • check.bat - скрипт запуска проверки кода

  • sonar-project.properties - файл настроек проекта для SonarQube

Первый этап

Развернем сервис SonarQube версии 7.9. Будем рассматривать простую установку, с использованием внутренней базы данных. По умолчанию SonarQube использует базу данных H2. В дальнейшем, если вы хотите использовать сервис постоянно, обновлять его  - нужно использовать внешнюю базу данных, например PostgreSQL.

Для SonarQube требуется Java 11+. Скачиваем OpenJDK 11 https://jdk.java.net/archive/ и распаковываем в каталог C:\openjdk11.

Далее скачиваем архив с SonarQube по ссылке https://www.sonarqube.org/downloads/. Распаковываем в каталог C:\sonarqube.

Теперь нужно выставить базовые настройки. Для этого отредактируем файл конфигурации C:\sonarqube\conf\sonar.properties:

sonar.web.javaOpts=-server -Xmx2g -Xms1g -XX:+HeapDumpOnOutOfMemoryError
sonar.ce.javaOpts=-Xmx6g -Xms4g -XX:+HeapDumpOnOutOfMemoryError 
sonar.search.javaOpts=-Xmx6g -Xms6g -XX:+HeapDumpOnOutOfMemoryError

Указываем путь к java 11 (если ранее не было установлено и прописано в path). В файле C:\sonarqube\conf\wrapper.conf отредактируем строку:

wrapper.java.command=java

Меняем на:

wrapper.java.command=C:\openjdk\jdk-11.0.2\bin\java

Сервис можно запустить вручную из консоли или создать службу windows. Для ручного запуска в консоли запускаем скрипт:

C:\sonarqube\bin\windows-x86-64\StartSonar.bat

Дожидаемся завершение развертки сервиса. В консоли должно быть выведено:

Более подробно развертку SonarQube на Windows можно изучить здесь.

Скачиваем и копируем плагин для SonarQube в каталог C:\sonarqube\extensions\downloads\:

• https://github.com/1c-syntax/sonar-bsl-plugin-community/releases/tag/v0.6.0

docker-compose up -d

SonarQube будет доступен по адресу http://localhost:9000. По умолчанию в SonarQube создается пользователь admin / admin  - логин / пароль соответственно.

Теперь на сервисе SonarQube нужно:

• Если используется внешняя база данных для SonarQube, то нужно сгенерировать token доступа пользователя для запуска анализа проекта.

• Добавить пользователей с электронной почтой, соответствующей пользователям Git вашего проекта, на проверку. Если исходные коды выгружались вручную через конфигуратор, этот шаг нужно пропустить.

Генерация token (необязательно)

Переходим на настройки пользователя admin http://localhost:9000/account/security/, указываем название token и нажимаем Generate. Копируем полученный token, он вам понадобится в дальнейшем.

Добавление новых пользователей

Создаем новых пользователей. Для этого переходим на страницу http://localhost:9000/admin/users и нажимаем Create user. Обязательно заполняем все поля:

Если используется проект Git то создаем пользователей для каждого пользователя Git.

Интерфейс на Русском языке

Сменим язык интерфейса сервиса на Русский. Для этого переходим на страницу http://localhost:9000/admin/marketplace, находим плагин локализации Russian Pack и устанавливаем, используя кнопку Install.

Внимание: для смены языка интерфейса на русский нужно будет перезапустить сервис SonarQube. Для этого нажимаем на той же странице Restart Server:

Подготовка каталога проекта SonarQube

В каталоге project1c/src должны находиться исходные коды 1С конфигурации. Рассмотрим ручной вариант экспорта в этот каталог.

Ручная выгрузка через конфигуратор

Если Git проект не используется, делаем ручную выгрузку проекта через конфигуратор. Для этого в конфигураторе 1С нажимаем Конфигурация -> Выгрузить конфигурацию в файлы...

Указываем путь к каталогу project/src и нажимаем выполнить.

После завершения каталог исходных кодов должен выглядеть примерно так:

git clone url_your_project_1c /path/to/project1c/src

Второй этап

Для второго этапа потребуется консольное приложение для запуска анализа проекта sonar scanner. Скачиваем сканер со страницы https://docs.sonarqube.org/latest/analysis/scan/sonarscanner/. В нашем случае нужна версия для Windows x64:

Скачиваем по ссылке https://binaries.sonarsource.com/Distribution/sonar-scanner-cli/sonar-scanner-cli-4.0.0.1744-windows.zip. После распаковки архива копируем полный путь к скрипту sonar-scanner.bat. Скрипт расположен в каталог bin.

Теперь нужно изменить скрипт запуска анализа проекта. Редактируем файл project1c/check.bat.

Заменяем в нем путь к sonar-scanner и значение token (необязательно).

Без токена:

../sonar-scanner-cli-4.0.0.1744-windows/sonar-scanner-4.0.0.1744-windows/bin/sonar-scanner.bat

 С токеном:

../sonar-scanner-cli-4.0.0.1744-windows/sonar-scanner-4.0.0.1744-windows/bin/sonar-scanner.bat -D"sonar.login=1952877e4d61d69c766eb8d9ca1d39ac48a4254f"

Последнее, что потребуется  - это проверка настроек проекта SonarQube. Откроем файл настроек project1c/sonar-project.properties.

В этом конфигурационном файле меняем, если нужно:

• sonar.projectKey - ключ проекта

• sonar.projectName - имя проекта

• sonar.projectVersion - версию проекта

P.S. в конфигурационном файле sonar нельзя указывать значения параметров в кириллице.

Неправильно:

sonar.projectName=МойЛучшийПроект

Правильно:

sonar.projectName=\u041C\u043E\u0439\u041B\u0443\u0447\u0448\u0438\u0439\u041F\u0440\u043E\u0435\u043A\u0442

Для кодировки кириллицы используем сервис https://www.online-toolz.com/tools/text-unicode-entities-convertor.php. После кодировки нужно будет заменить символы % на \.

Последний этап

Запускаем анализ проекта через скрипт project1c/check.bat. Дожидаемся сообщения в консоли:

Проблемные ситуации

У вас может не хватить памяти, выделенной под JAVA во время запуска sonar-scanner. В логах появится ошибка

ERROR: Error during SonarQube Scanner execution
ERROR: null
ERROR: Caused by: GC overhead limit exceeded

Проблему можно решить с помощью Java Memory Settings. Нужно указать в переменной среды или в скрипте check.bat значение SONAR_SCANNER_OPTS. Например, для выделения 4 ГБ оперативной памяти указываем:

set SONAR_SCANNER_OPTS=-Xmx4g

Анализ проекта

Переходим на главную страницу сервиса sonarqube http://localhost:9000/projects. При первом анализе нужно дождаться его завершения на сервисе (выполняется фоновое задание загрузки результатов анализа).

Фоновое задание:

После завершения загрузки страница списка проектов будет выглядеть:

Переходим в проект MyConf. На странице метрик проекта видим:

• Количество ошибок

• Количество уязвимостей

• Время на исправление технического долга

• Количество дефектов кода (code smells)

• Процент и количество дублирующегося кода.

На закладке Замечания увидим ошибки и дефекты кода. Используя фильтры на панели слева, можно отфильтровать замечания, например, по правилам проверок:

Отфильтровываем замечания. Получаем:

Переходим в первое замечание:

Для тех, кто использует проект Git, будут доступны фильтры по авторам (если заведены пользователи на сервисе, то они будут отображаться сразу в замечании).

Возвращаемся на страницу метрик проекта. Переходим в дублирование кода и выбираем любое дублирование:

Список дублирования в коде:

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

Так как у нас сейчас нет истории изменения показателей проекта во времени, я покажу как это может выглядеть на примере другого проекта:

В области New code, выводится информация  о новых результатах проверок. На примере Дефектов кода можно увидеть динамику изменения показателей:

График изменений:

P.S. Хотите больше диагностик кода? Вы можете предложить, реализовать их в проекте https://github.com/1c-syntax/bsl-language-server.

Расширенный пример

Компания 1C-ИжТиСи разработала конфигурацию 1С: Автоматизированная проверка конфигураций (https://v8.1c.ru/acc/). 

Решение позволяет проверять конфигурации в автоматическом режиме на соответствие стандартам разработки 1С. Конфигурация имеет большое количество проверок кода 1С, но, к сожалению, отсутствует функционал анализа изменения качества кода. Используя проект acc-export из 1С: АПК, можно выгрузить результат анализа кода в SonarQube.

В рамках этой главы нужно установить:

• OneScript (http://oscript.io/)

• Конфигурацию 1С: АПК версии 1.2.3.16 (https://releases.1c.ru/project/ACC)

• acc-export (https://github.com/otymko/acc-export)

Конфигурацию 1С: АПК нужно развернуть на компьютере, создать новый проект и выполнить первоначальную проверку. Более подробно можно почитать в статье Автоматизированная проверка конфигураций… и пара слов о стандартах разработки.

После установки OneScript потребуется установить библиотеку vanessa-runner (https://github.com/oscript-library/vanessa-runner). Выполняем в консоли:

opm install vanessa-runner

Скачиваем обработку экспорта  https://github.com/otymko/acc-export/releases/download/1.1.0/acc-export.epf в каталог project1c.

Подготовка каталога проекта

В каталоге project1c создадим acc.properties - файл настроек экспорта из АПК.

• acc.projectKey - наименование конфигурации в АПК. 

• acc.catalog - каталог проекта (не к src) 

• acc.sources - путь / каталог исходных кодов, например, src. 

• acc.check - запуск проверки конфигурации. Настройки будут взяты с параметров запуска по расписанию. 

• acc.format - формат экспорта из АПК (reportjson или genericissue). По умолчанию reportjson. Можно не указывать. 

• acc.titleError - представление вывода ошибки при экспорте. Может принимать значения: code (только код ошибки), name (только наименование ошибки), codeName (код и наименование ошибки). По умолчанию codeName.

Отредактируем файл sonar-project.properties и добавим настройку:

sonar.bsl.languageserver.reportPaths=acc-json.json

Создадим скрипт acc.bat запуска экспорта проверок АПК.

@chcp 65001 
@set RUNNER_IBNAME=/FC:\Sonar\acc
@set RUNNER_DBUSER=Администратор
@call runner run --command "acc.propertiesPaths=./acc.properties;" --execute "./acc-export.epf" --ordinaryapp=1

Выгрузка результат

Запускаем скрипт acc.bat, затем check.bat и дожидаемся завершения:

Когда SonarQube обработает результат проверки, нам будут доступны новые данные для аналитики.

На закладке замечания список правил проверки расширился:

В итоге, мы имеем загруженные результаты проверки 1С: АПК в SonarQube для дальнейшей аналитики.

Подведем итоги

В результате проверки кода и загрузки результатов в SonarQube, мы получаем метрики, наглядно показывающие текущее состояние качества проекта.

Что теперь с этим делать?

• Исправлять критические ошибки, уязвимости.
• Исправлять дефекты, дублирование кода, если реализуются попутные задачи.
• Уменьшать количество дублирующего кода.
• Установить пороги качества.

Дальнейшее развитие темы

• Автоматический запуск проверки качества кода. Автоматизируем запуск проверки качества, используя, например, Jenkins или GitLabCI. 
• Исключение из проверки объектов конфигурации, которые находятся на поддержке.  В этом может помочь проект edt-export-bugs. Также с его помощью можно автоматизировать получение проверок из EDT. Более подробно можно почитать здесь (https://github.com/Stepa86/edt-export-bugs).
• Рассылка результатов проверки кода ответственным / виновникам замечаний.

Благодарности

Хочу выразить огромную благодарность за инструменты и помощь при создании статьи:

• Грызлову Никите https://github.com/nixel2007

• Сосновому Алексею https://github.com/asosnoviy

• Leon Chagelishvili https://github.com/lChagelishvili

• Степанову Антону https://github.com/Stepa86

Мой жене за чтение технической статьи. А так же читателям статьи, кто дотянул до конца =)

Ссылки

• SonarQube (https://www.sonarqube.org/)

• SonarQube 1C (BSL) Community Plugin (https://github.com/1c-syntax/sonar-bsl-plugin-community)

• BSL Language Server (http://1c-syntax.github.com/bsl-language-server)

• SONARQUBE 1C (BSL) Plugin (https://silverbulleters.org/sonarqube)

• SonarQube Russian Language Pack (https://github.com/silverbulleters/sonar-l10n-ru)

• OneScript (http://oscript.io/)

• Docker (https://www.docker.com/)

• Vanessa runner (https://github.com/silverbulleters/vanessa-runner)

• Шаблон проекта (https://github.com/otymko/article-sonar-for-infostart)

• acc-export (https://github.com/otymko/acc-export)

• edt-export-bugs (https://github.com/Stepa86/edt-export-bugs)

• 1С: Автоматическая проверка конфигураций (https://v8.1c.ru/acc/)

• Управление техническим долгом - Концепция Continuous Inspection