Какую Java-аннотацию @NonNull/@NotNull лучше использовать? Сравнение и рекомендации

Краткий ответ: используйте org.jetbrains.annotations.NotNull (или @Nullable) для статического анализа, а для валидации в рантайме — jakarta.validation.constraints.NotNull

Вы совершенно правы: аннотации @NotNull сами по себе не генерируют код проверки. Это метаданные. Они нужны для:

• Статического анализа кода — чтобы IDE (IntelliJ IDEA, Eclipse) или инструменты вроде SpotBugs, Error Prone предупреждали вас о потенциальных NPE ещё до запуска программы.
• Документирования контракта — чтобы другой разработчик (или вы через месяц) сразу понимал, что параметр не должен быть null.
• Bean Validation (JSR 380) — для автоматической проверки на уровне фреймворка, например, в Spring MVC или JPA.

Почему ваш код не упал при компиляции?

Потому что аннотации @NotNull — это не встроенная фича языка Java. Это просто маркеры в байт-коде. Чтобы они работали как проверки, нужно:

1. Настроить IDE на их анализ (обычно включено по умолчанию в IntelliJ).
2. Использовать плагин для сборки, который проверяет аннотации на этапе компиляции (например, jsr305 + checkerframework).

В вашем примере IntelliJ IDEA подсветит вызов service.greet(null) жёлтым предупреждением, но не заблокирует компиляцию. Чтобы сделать это ошибкой, нужно включить инспекцию "Constant conditions & exceptions" на уровне "Error".

Сравнение популярных аннотаций

Рекомендация: комбинируйте подходы

Для нового проекта я рекомендую следующую стратегию:

• Для статического анализа — используйте org.jetbrains.annotations.NotNull (если у вас IntelliJ) или jakarta.annotation.Nonnull для универсальности. Подключите Checker Framework или SpotBugs в Maven/Gradle.
• Для рантайм-валидации — добавьте зависимость jakarta.validation (Hibernate Validator) и используйте jakarta.validation.constraints.NotNull на полях DTO и параметрах REST-контроллеров.
• Для явной проверки в коде — используйте Objects.requireNonNull(param, "param must not be null"); в начале методов. Это гарантирует ранний выброс NPE с понятным сообщением.

import org.jetbrains.annotations.NotNull;
import java.util.Objects;

public class UserService {

    public String greet(@NotNull String name) {
        // Явная проверка с понятным сообщением
        Objects.requireNonNull(name, "Имя не должно быть null");

        // Если name = null, упадёт здесь, а не при конкатенации строк
        return "Hello, " + name;
    }
}

Итог

• @NotNull — это не магия, а контракт.
• Для защиты от NPE на этапе компиляции — настройте статический анализатор.
• Для защиты в рантайме — используйте Objects.requireNonNull() или jakarta.validation.
• Не смешивайте аннотации из разных пакетов без необходимости — это запутывает.

import java.util.Objects;
import java.util.Optional;

public class UserService {

    // Вариант 1: requireNonNull с сообщением (бросает NPE)
    public String greet(String name) {
        Objects.requireNonNull(name, "name must not be null");
        return "Hello, " + name;
    }

    // Вариант 2: Optional как контракт (явно показывает, что null возможен)
    public String greetOptional(Optional<String> name) {
        return "Hello, " + name.orElse("Guest");
    }
}