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

Краткий ответ: используйте jakarta.annotation.Nonnull (Jakarta EE) или org.jetbrains.annotations.NotNull (IntelliJ IDEA) — в зависимости от ваших приоритетов.

Давайте разберем все популярные варианты, чтобы вы могли сделать осознанный выбор. Проблема выбора аннотации для nullability — это классическая "война стандартов" в Java, которая длится уже много лет.

1. javax.annotation.Nonnull (JSR 305) — ❌ НЕ ИСПОЛЬЗУЙТЕ

Это была первая попытка стандартизации, но JSR 305 так и остался "спящим" (dormant). Он никогда не был принят как официальный стандарт. Библиотека com.google.code.findbugs:jsr305 заброшена. Многие современные инструменты (например, современные версии Checker Framework) перестали ее поддерживать.

2. org.jetbrains.annotations.NotNull — ✅ ОТЛИЧНЫЙ ВЫБОР (для IntelliJ IDEA)

Это аннотация от создателей IntelliJ IDEA. Она имеет несколько преимуществ:

• Глубокая интеграция с IDE: IntelliJ IDEA анализирует ваш код и предупреждает о возможных NPE еще до компиляции.
• Поддержка Type Use: можно писать List<@NotNull String>.
• Поддержка инференции: если вы пометили метод как @NotNull, IDE будет считать, что его возвращаемое значение не null.
• Работает с Lombok, Spring, и другими фреймворками.

Пример использования:

import org.jetbrains.annotations.NotNull;

public class UserService {
    public User createUser(@NotNull String name, @NotNull String email) {
        // Теперь IntelliJ IDEA предупредит, если кто-то вызовет createUser(null, "test@test.com")
        return new User(name, email);
    }
}

Недостаток: привязка к конкретной IDE (но на практике почти все используют IntelliJ IDEA).

3. jakarta.annotation.Nonnull — ✅ ЛУЧШИЙ СТАНДАРТ (Jakarta EE / Java EE)

Начиная с Java EE 8 / Jakarta EE 9+, это официальная аннотация из спецификации. Она:

• Является частью Jakarta Annotations (ранее Common Annotations).
• Поддерживается всеми серверами приложений (WildFly, TomEE, GlassFish).
• Работает с Checker Framework и другими инструментами статического анализа.

Пример:

import jakarta.annotation.Nonnull;

public class UserService {
    public User createUser(@Nonnull String name, @Nonnull String email) {
        // Эта аннотация также распознается IntelliJ IDEA (с плагином Jakarta EE)
        return new User(name, email);
    }
}

Недостаток: требует добавления зависимости jakarta.annotation-api (если вы не используете Jakarta EE сервер).

4. lombok.NonNull — ✅ ХОРОШО, НО С ОГРАНИЧЕНИЯМИ

Lombok — мощный инструмент, но его аннотация @NonNull работает только на этапе компиляции. Она генерирует проверку if (param == null) throw new NullPointerException(paramName) в конструкторах и методах. Однако:

• Она не распознается IDE как аннотация для статического анализа (в отличие от JetBrains).
• Работает только с Lombok.

Пример:

import lombok.NonNull;

public class UserService {
    public User createUser(@NonNull String name, @NonNull String email) {
        // Lombok сгенерирует проверку на null в байт-коде
        return new User(name, email);
    }
}

Лучше использовать Lombok @NonNull в сочетании с JetBrains @NotNull для полной защиты.

5. javax.validation.constraints.NotNull — ❌ НЕ ДЛЯ ЭТОГО

Эта аннотация из Bean Validation (JSR 380) предназначена для валидации данных на уровне бизнес-логики (например, в REST-контроллерах Spring). Она не предназначена для защиты от NPE в общем коде. Её использование для внутренних проверок — это злоупотребление.

Практическая рекомендация

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

1. Добавьте зависимость org.jetbrains:annotations (последняя версия — 24.0.0).
2. Используйте @NotNull и @Nullable из этого пакета везде, где это имеет смысл.
3. Настройте IntelliJ IDEA на проверку этих аннотаций (по умолчанию уже настроено).
4. Для runtime-проверок используйте Objects.requireNonNull() в начале методов:

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

public class UserService {
    public User createUser(@NotNull String name, @NotNull String email) {
        Objects.requireNonNull(name, "name must not be null");
        Objects.requireNonNull(email, "email must not be null");
        return new User(name, email);
    }
}

Такой подход даёт вам максимальную защиту: IDE предупредит на этапе написания кода, а Objects.requireNonNull() выбросит понятное исключение, если null всё-таки пробрался (например, при отражении или сериализации).

public class UserService {
    public User createUser(String name, String email) {
        this.name = Objects.requireNonNull(name, "Name is required");
        this.email = Objects.requireNonNull(email, "Email is required");
        return new User(name, email);
    }
}