Привет всем! Недавно я решил поэкспериментировать с SonarQube и создать свой собственный кастомный плагин для проверки кода на соответствие моим правилам разработки. В этой статье я поделюсь с вами своим опытом и покажу, как вы тоже можете создать такой плагин своими руками.

Небольшие вводные

Disclaimer: Данная статья повторяет многое из официального гайда.

Давайте начнем с выдуманного use-case'a:

Нам нужен инструмент для проверки кода во время MR, который сможет определять не соответствия установленному код-стайлу команды.

Тут на самом деле у нас есть 2 варианта.

Использование готовых Lint-инструментов

Примером таких инструментов могут служить ESLint (для JavaScript/TypeScript) или Checkstyle (для Java). Этот вариант, на мой взгляд, является самым простым и удобным. В случаях, когда требуется кастомная проверка, процесс также несложен: разработайте свой чек и добавьте его в директорию plugins или extensions.

Плюсы:

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

Минусы:

Сложно разделять правила проверки кода по разным командам с различными стандартами разработки. В таких случаях правила одной команды могут конфликтовать с правилами другой.

Использование SonarQube с кастомным плагином

Этот вариант привлекает меня тем, что все проверки, связанные с код-стайлингом и безопасностью кода, находятся в одном месте и объединены в красивом интерфейсе. SonarQube отлично подходит для компаний с большим количеством команд разработки, так как позволяет создавать кастомные профили.

Плюсы:

Все проверки кода в одном месте.
Удобный и красивый интерфейс.
Подходит для крупных компаний с множеством команд разработки благодаря возможности создания кастомных профилей.

Минусы:

Требования к инфраструктуре: SonarQube требует отдельного сервера и ресурсов для своей работы, что может быть проблематично для небольших команд или проектов.

Подготавливаем локальную среду

Давайте начнем разработку нашего первого кастомного чека спулив проект с гитхаба: ссылка.

Я немного почистил и изменил проект, чтобы облегчить процесс разработки и избавить вас от необходимости заниматься конфигурацией Maven.

По рекомендации разработчиков SonarQube, мы должны придерживаться подхода TDD (разработка через тестирование) при написании наших кастомных чеков. Лично я не являюсь большим поклонником этого подхода, но в данном случае он показывает себя очень эффективно.

Чтобы наш кастомный чек правильно работал после интеграции в SonarQube, его необходимо протестировать. Для этого мы будем использовать инструмент CheckVerifier. С его помощью можно прогонять наши проверки на реальных кейсах, что, на мой взгляд, гораздо удобнее, чем написание моков в Mockito.

Давайте напишем тесты для чека, который будет проверять, написаны ли URL эндпойнтов в kebab-case.

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.DeleteMapping;

public class MyController {

    @GetMapping("/kebab-case-url") // Compliant
    public String getCompliant() {
        return "compliant";
    }

    @GetMapping("/camelCaseUrl") // Noncompliant
    public String getNonCompliant() {
        return "noncompliant";
    }

    @PostMapping("/another-kebab-case-url") // Compliant
    public void postCompliant() {
    }

    @PostMapping("/AnotherCamelCaseUrl") // Noncompliant
    public void postNonCompliant() {
    }

    @PutMapping("/yet-another-kebab-case-url") // Compliant
    public void putCompliant() {
    }

    @PutMapping("/YetAnotherCamelCaseUrl") // Noncompliant
    public void putNonCompliant() {
    }

    @DeleteMapping("/final-kebab-case-url") // Compliant
    public void deleteCompliant() {
    }

    @DeleteMapping("/FinalCamelCaseUrl") // Noncompliant
    public void deleteNonCompliant() {
    }
}

Важные аспекты тест-кейсов

Расположение тестов:
- Все ваши тесты должны находиться в следующей директории: src/test/files/.
Сценарии тестирования:
- Обязательно расписывайте как негативные, так и позитивные сценарии.
- Негативные сценарии помечайте как // Noncompliant, а позитивные как // Compliant.
Импорты:
- Не забывайте добавлять необходимые импорты. Без них тесты не пройдут успешно.

Теперь давайте напишем непосредственно саму проверку на kebab-case.

@Rule(key = "KebabCaseUrlCheck")
public class KebabCaseUrlCheck extends BaseTreeVisitor implements JavaFileScanner {

    private static final Pattern KEBAB_CASE_PATTERN = Pattern.compile("^(/[a-z0-9]+(-[a-z0-9]+)*)*$");

    private JavaFileScannerContext context;

    @Override
    public void scanFile(JavaFileScannerContext context) {
        this.context = context;
        scan(context.getTree());
    }

    @Override
    public void visitMethod(MethodTree tree) {
        List<AnnotationTree> annotations = tree.modifiers().annotations();
        for (AnnotationTree annotationTree : annotations) {
            TypeTree annotationType = annotationTree.annotationType();
            if (annotationType.is(Tree.Kind.IDENTIFIER)) {
                IdentifierTree identifier = (IdentifierTree) annotationType;
                String annotationName = identifier.name();
                if (annotationName.equals("GetMapping") || annotationName.equals("PostMapping") ||
                        annotationName.equals("PutMapping") || annotationName.equals("DeleteMapping")) {
                    checkUrl(annotationTree);
                }
            }
        }
        super.visitMethod(tree);
    }

    private void checkUrl(AnnotationTree annotationTree) {
        if (annotationTree.arguments().isEmpty()) {
            return;
        }

        Tree argument = annotationTree.arguments().get(0);
        if (argument.is(Tree.Kind.ASSIGNMENT)) {
            argument = ((org.sonar.plugins.java.api.tree.AssignmentExpressionTree) argument).expression();
        }

        if (argument.is(Tree.Kind.STRING_LITERAL)) {
            LiteralTree literal = (LiteralTree) argument;
            String url = literal.value().substring(1, literal.value().length() - 1);

            if (!KEBAB_CASE_PATTERN.matcher(url).matches()) {
                context.reportIssue(this, literal, "The URL should be in kebab-case.");
            }
        }
    }
}

Начнем с аннотации @Rule(key = "KebabCaseUrlCheck"), которая определяет ключ правила, используемого в SonarQube для идентификации этого чека. Класс KebabCaseUrlCheck наследуется от BaseTreeVisitor и реализует интерфейс JavaFileScanner, что позволяет ему сканировать Java-файлы.

Шаблон для проверки соответствия URL формату kebab-case определяется с помощью регулярного выражения:

private static final Pattern KEBAB_CASE_PATTERN = Pattern.compile("^(/[a-z0-9]+(-[a-z0-9]+))$");.

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

private JavaFileScannerContext context;

Основной метод для сканирования файла scanFile сохраняет контекст и начинает процесс сканирования дерева синтаксиса файла:

@Override
public void scanFile(JavaFileScannerContext context);

Сканирование начинается вызовом

scan(context.getTree());

Метод visitMethod переопределяется для обработки каждого метода в файле:

 public void visitMethod(MethodTree tree);

Он получает все аннотации метода:

List<AnnotationTree> annotations = tree.modifiers().annotations();

В цикле for каждая аннотация проверяется, и если она является одной из @GetMapping, @PostMapping, @PutMapping или @DeleteMapping, вызывается метод checkUrl.

Метод checkUrl проверяет URL в аннотации. Он начинается с проверки наличия аргументов у аннотации. Если аргументов нет, метод завершается. Затем извлекается первый аргумент аннотации и проверяется, является ли он строковым литералом. Если это так, значение строки извлекается без кавычек:

String url = literal.value().substring(1, literal.value().length() - 1);

Далее, с помощью регулярного выражения проверяется, соответствует ли URL шаблону kebab-case: if (!KEBAB_CASE_PATTERN.matcher(url).matches()). Если URL не соответствует шаблону, создается отчет об ошибке с сообщением "The URL should be in kebab-case."

Запускаем наш первый тест

После того как мы настроили тест-кейсы и сам класс проверки, нам нужно непосредственно данный тест запустить.
Для этого в директории src/test/java/org/sonar/samples/java/checks создаем новый класс KebabCaseUrlTest и пишим простую конструкцию для теста:

package org.sonar.samples.java.checks;

import org.junit.jupiter.api.Test;
import org.sonar.java.checks.verifier.CheckVerifier;

public class KebabCaseUrlCheckTest {

    @Test
    void test() {
        CheckVerifier.newVerifier()
                .onFile("src/test/files/KebabCaseUrlCheck.java")
                .withCheck(new KebabCaseUrlCheck())
                .verifyIssues();
    }
}

Далее, запускаем тест и радуемся, что наш метод проверки url работает!

Финальные штрихи

Начнем с конфигурации нейминга нашего плагина. Переходим к этому файлу:

src/main/java/org/sonar/samples/java/MyJavaRulesDefinition.java и меняем поля REPOSITORY_KEY и REPOSITORY_NAME на нужные вам.

public static final String REPOSITORY_KEY = "sonar-plugin-habr";
public static final String REPOSITORY_NAME = "Habr Guide Plugin";

Далее, Перед тем, как компилить наш .jar файл, нам нужно зарегистрировать наш кастомный плагин. Для этого переходим к этому файлу: src/main/java/org/sonar/samples/java/RulesList.java

и в метод getJavaChecks добавляем наш KebabCaseUrlCheck.

public static List<Class<? extends JavaCheck>> getJavaChecks() {
    return Collections.unmodifiableList(Arrays.asList(
            SpringControllerRequestMappingEntityRule.class,
            AvoidAnnotationRule.class,
            AvoidBrandInMethodNamesRule.class,
            AvoidMethodDeclarationRule.class,
            AvoidSuperClassRule.class,
            AvoidTreeListRule.class,
            MyCustomSubscriptionRule.class,
            KebabCaseUrlCheck.class,
            SecurityAnnotationMandatoryRule.class));
  }

Далее, нам нужно добавить наш файл с проверкой в тест, проверяющий регистрацию правил. По умолчанию, он использует метод containsExactly() что как по мне делает реализацию проверок более комплексной и не нужной, для этого, по желанию вы можете поменять метод на containsExactlyInAnyOrder() что в итоге не будет выкидать ошибку, если вы будете регистрировать ваши правила не по порядку.

class MyJavaFileCheckRegistrarTest {

  @Test
  void checkRegisteredRulesKeysAndClasses() {
    TestCheckRegistrarContext context = new TestCheckRegistrarContext();

    MyJavaFileCheckRegistrar registrar = new MyJavaFileCheckRegistrar();
    registrar.register(context);

    assertThat(context.mainRuleKeys).extracting(RuleKey::toString).containsExactlyInAnyOrder(
            "omni-sonar:SpringControllerRequestMappingEntity",
            "omni-sonar:AvoidAnnotation",
            "omni-sonar:AvoidBrandInMethodNames",
            "omni-sonar:AvoidMethodDeclaration",
            "omni-sonar:AvoidSuperClass",
            "omni-sonar:AvoidTreeList",
            "omni-sonar:AvoidMethodWithSameTypeInArgument",
            "omni-sonar:KebabCaseUrlCheck",
            "omni-sonar:SecurityAnnotationMandatory");

    assertThat(context.mainCheckClasses).extracting(Class::getSimpleName).containsExactlyInAnyOrder(
            "SpringControllerRequestMappingEntityRule",
            "AvoidAnnotationRule",
            "AvoidBrandInMethodNamesRule",
            "AvoidMethodDeclarationRule",
            "AvoidSuperClassRule",
            "AvoidTreeListRule",
            "MyCustomSubscriptionRule",
            "KebabCaseUrlCheck",
            "SecurityAnnotationMandatoryRule");

    assertThat(context.testRuleKeys).extracting(RuleKey::toString).containsExactly(
            "omni-sonar:NoIfStatementInTests");

    assertThat(context.testCheckClasses).extracting(Class::getSimpleName).containsExactly(
            "NoIfStatementInTestsRule");
  }

}

Как последний пункт, нам нужно добавить документацию к нашему кастомному плагину. Это делается довольно легко, мы создаем 2 файла(html и json) в директории src/main/resources/org/sonar/l10n/java/rules/java с идентичным названием нашей проверки. В нашем случае, файлы будут называться: KebabCaseUrlCheck.html и KebabCaseUrlCheck.json.

В HTML файле, нам нужно описать нашу проверку и как она работает, код помещайте в тэг <pre>.

<h1>Kebab-Case URL Check</h1>
<p>This rule ensures that the URLs in <code>@GetMapping</code>, <code>@PostMapping</code>, <code>@PutMapping</code>, and <code>@DeleteMapping</code> annotations are in kebab-case format.</p>

<h2>Noncompliant Code Example</h2>
<pre>
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.DeleteMapping;

public class MyController {

    @GetMapping("/camelCaseUrl") // Noncompliant
    public String getNonCompliant() {
        return "noncompliant";
    }

    @PostMapping("/AnotherCamelCaseUrl") // Noncompliant
    public void postNonCompliant() {
    }

    @PutMapping("/YetAnotherCamelCaseUrl") // Noncompliant
    public void putNonCompliant() {
    }

    @DeleteMapping("/FinalCamelCaseUrl") // Noncompliant
    public void deleteNonCompliant() {
    }

    @GetMapping("/nested/camelCaseUrl") // Noncompliant
    public String getNestedNonCompliant() {
        return "noncompliant";
    }
}
    </pre>

<h2>Compliant Solution</h2>
<pre>
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.DeleteMapping;

public class MyController {

    @GetMapping("/kebab-case-url") // Compliant
    public String getCompliant() {
        return "compliant";
    }

    @PostMapping("/another-kebab-case-url") // Compliant
    public void postCompliant() {
    }

    @PutMapping("/yet-another-kebab-case-url") // Compliant
    public void putCompliant() {
    }

    @DeleteMapping("/final-kebab-case-url") // Compliant
    public void deleteCompliant() {
    }

    @GetMapping("/nested/kebab-case-url") // Compliant
    public String getNestedCompliant() {
        return "compliant";
    }
}
</pre>

В Json вам нужно предоставить метаданные вашей проверки:

{
  "title": "URLs in @GetMapping, @PostMapping, @PutMapping, @DeleteMapping should be in kebab-case",
  "type": "code_smell",
  "status": "ready",
  "tags": [
    "convention",
    "style",
    "rest"
  ],
  "defaultSeverity": "Minor"
}

Тут интуитивно все понятно, с type можете ознакомиться по ссылке.

Как последний штрих, давайте запустим mvn clean install и получим .jar файл в директории /target

Интеграция в SonarQube

Для начала, давайте мы sonar развернем локально и добавим наш .jar файл.
Для этого используйте данный Dockerfile:

# Use the official SonarQube image as the base image
FROM sonarqube:latest

# Set the SonarQube home directory as an environment variable
ENV SONAR_HOME=/opt/sonarqube

# Copy the custom rules JAR file to the SonarQube plugins directory
COPY target/java-custom-rules-example-1.0.0-SNAPSHOT.jar $SONAR_HOME/extensions/plugins/

и запустите его следующей командой:

docker build . -t sonar-habr
docker run -d -p 9000:9000 sonar-habr

Активируем Плагин

Заходите в Quality Profiles и делаете фильтр на язык Java.
Зайдите в профиль SonarWay и скопируйте его назовите habr.
В профиле habr нажмите activate more и во вкладке Repository вы увидите наш плагин "Habr Guide Plugin".
Найдите нашу проверку и активируйте ее, она будет называться URLs in @GetMapping, @PostMapping, @PutMapping, @DeleteMapping should be in kebab-case.

Весь наш код можете найти по данной ссылке.

Пишем кастомный Plugin SonarQube