Qual @NotNull em Java escolher? Analisando por baixo dos panos

A Maldição do NullPointerException: escolhendo o @NotNull correto

Se você já programou em Java, certamente já encontrou um NullPointerException (NPE). Este é, provavelmente, o erro mais comum que derruba sistemas em produção. Os desenvolvedores criaram uma maneira elegante de combatê-lo — as anotações @NotNull e @Nullable. Mas aqui está o problema: no mundo Java existem pelo menos uma dezena de implementações diferentes desta anotação de diferentes fornecedores. Qual escolher? Por que existem tantas? E o que acontece "por baixo dos panos" quando você coloca @NotNull?

No Stack Overflow, a pergunta "Which @NotNull Java annotation should I use?" acumulou milhares de visualizações e centenas de votos. É uma verdadeira dor de cabeça para iniciantes e profissionais. Neste artigo, vamos detalhar todas as principais opções, mostrar código real e dar um plano de ação claro. Vamos lá!

Por que as anotações @NotNull são necessárias?

Java é uma linguagem com tipagem estática, mas não consegue distinguir referências null de não-null no nível de tipos (ao contrário de Kotlin ou Rust). As anotações são metadados que informam ao compilador, IDE ou analisador estático: "Ei, olhe, este campo nunca deve ser null!".

O uso de @NotNull oferece três benefícios principais:

\n
• Detecção precoce de erros — a IDE destacará um potencial NPE antes mesmo da execução.
\n
• Documentação do código — o desenvolvedor vê imediatamente o contrato do método.
\n
• Integração com ferramentas — Lombok, Checker Framework, FindBugs e outros usam essas anotações para geração de código e verificações.
\n

O problema é que cada grande ecossistema (JetBrains, Google, Eclipse, Oracle) criou sua própria versão. Vamos analisá-las em ordem.

Principais candidatos: quem é quem

1. javax.annotation.Nonnull (FindBugs / JSR-305)

Este foi o primeiro "padrão de facto". Anotação do pacote javax.annotation (JSR-305).

import javax.annotation.Nonnull;\n\npublic class UserService {\n    public String greet(@Nonnull String name) {\n        return "Hello, " + name;\n    }\n}

Prós: historicamente popular, suportada por ferramentas antigas (FindBugs, IntelliJ IDEA com plugin).
\nContras: JSR-305 ficou preso no status "rascunho" e nunca se tornou parte do Java SE. A biblioteca com.google.code.findbugs:jsr305 não é atualizada há muito tempo. Não recomendado para novos projetos.

2. jakarta.annotation.Nonnull (Jakarta EE)

Após a transição do Java EE para a Eclipse Foundation, o pacote javax.* foi renomeado para jakarta.*. A anotação jakarta.annotation.Nonnull é a herdeira moderna.

import jakarta.annotation.Nonnull;\n\npublic class RestController {\n    public void process(@Nonnull String data) {\n        // data garantidamente não é null\n    }\n}

Prós: suportada oficialmente, parte do Jakarta EE 9+, tem chance de padronização.
\nContras: requer adição da dependência jakarta.annotation-api. Nem todas as ferramentas de análise foram atualizadas.

3. org.jetbrains.annotations.NotNull (IntelliJ IDEA)

A anotação mais popular entre os usuários do IntelliJ. Distribuída na biblioteca org.jetbrains:annotations.

import org.jetbrains.annotations.NotNull;\n\npublic class DataValidator {\n    public boolean validate(@NotNull String input) {\n        return input.length() > 3;\n    }\n}

Prós: excelente integração com IntelliJ IDEA (destaque, inspeções, geração automática de verificações). Dependência leve (apenas 26 KB).
\nContras: vinculação à IDE JetBrains. Se a equipe usa Eclipse ou VS Code — o efeito é menor.

4.