Artículo

@Nullable y @NonNull en Java: qué son y cómo usarlos

@Nullable indica que un valor puede ser null y @NonNull que nunca lo es. Qué significan, de qué librería importarlas y cómo usarlas en tu código Java.

@Nullable y @NonNull en Java: qué son y cómo usarlos

@Nullable indica que una variable, un parámetro o el valor de retorno de un método puede ser null. @NonNull indica que nunca debe serlo. Son anotaciones informativas: el IDE y las herramientas de análisis las leen para avisarte de un posible NullPointerException antes de ejecutar el programa.

Vídeo explicativo

¿Qué es @Nullable?

@Nullable marca un elemento que admite null. Quien lo use sabe que debe comprobarlo antes de llamar a sus métodos. No cambia el comportamiento del programa: es documentación que las herramientas entienden.

En parámetros

public class Usuario {
    private String nombre;
    private String email;

    public Usuario(@Nullable String nombre, @Nullable String email) {
        this.nombre = nombre;
        this.email = email;
    }

    public void setNombre(@Nullable String nombre) {
        this.nombre = nombre;
    }
}

En el valor de retorno

El método getUserById devuelve un User o null si no hay ningún usuario con ese identificador. La anotación obliga a quien lo llama a contemplar ese caso:

public class UserService {
    public @Nullable User getUserById(int id) {
        // busca el usuario en la base de datos
        // si no existe, devuelve null
    }
}

Para valores de retorno que pueden faltar, Optional expresa lo mismo en el propio tipo y suele ser mejor opción en código nuevo.

¿Qué es @NonNull?

@NonNull es lo contrario: declara que un parámetro no acepta null o que un método nunca lo devuelve.

En parámetros

public class Usuario {
    private String nombre;
    private String email;

    public Usuario(@NonNull String nombre, @NonNull String email) {
        this.nombre = nombre;
        this.email = email;
    }
}

En el valor de retorno

public class UserService {
    public @NonNull User getUserById(int id) {
        // busca el usuario en la base de datos
        // si no existe, lanza una excepción en lugar de devolver null
    }
}

¿De qué librería se importan?

Java no incluye estas anotaciones en el JDK. Varias librerías ofrecen las suyas, con el mismo significado y distinto paquete:

LibreríaAnotacionesComprueba en ejecución
JSpecifyorg.jspecify.annotations.Nullable y NonNullNo
Jakarta Annotationsjakarta.annotation.Nullable y NonnullNo
JetBrainsorg.jetbrains.annotations.Nullable y NotNullNo
Spring (hasta la versión 6)org.springframework.lang.Nullable y NonNullNo
Lomboklombok.NonNullSí

Dos detalles importantes:

  • JSpecify es el estándar hacia el que converge el ecosistema. Spring Framework 7 y Spring Boot 4 lo usan y dejan obsoletas las anotaciones de org.springframework.lang. Con @NullMarked en un paquete o una clase, todo se considera no nulo salvo lo que marques con @Nullable.
  • Lombok es la excepción: su @NonNull genera código que comprueba el parámetro y lanza NullPointerException si llega null.

¿Lanzan una excepción si llega un null?

No, salvo la de Lombok. Las demás no hacen nada en tiempo de ejecución: si pasas null a un parámetro @NonNull, el programa sigue hasta que algo falle más adelante. Su valor está en el aviso previo del IDE (IntelliJ IDEA las reconoce) y de analizadores como NullAway o Checker Framework.

Si necesitas rechazar un null en ejecución, tienes tres opciones:

  • Objects.requireNonNull(valor) al principio del método.
  • @NonNull de Lombok.
  • @NotNull de Bean Validation (jakarta.validation.constraints.NotNull) para validar datos de entrada, por ejemplo el cuerpo de una petición en Spring Boot. Es una validación, no una anotación de nulabilidad.

Preguntas frecuentes

¿Qué significa nullable?

Que un valor puede ser null, es decir, puede no apuntar a ningún objeto. En Java cualquier referencia es nullable por defecto; @Nullable lo hace explícito.

¿@Nullable evita el NullPointerException?

No por sí sola. Hace que el IDE y los analizadores te avisen cuando usas un valor que puede ser null sin comprobarlo. La comprobación la escribes tú.

¿Cuál es la diferencia entre @NonNull y @NotNull?

@NonNull (JSpecify, Spring, Lombok) describe el contrato del código. @NotNull de Bean Validation es una restricción que se valida en ejecución sobre datos de entrada. JetBrains también llama @NotNull a su anotación de nulabilidad.

¿Qué anotación uso en un proyecto nuevo?

JSpecify, con @NullMarked en package-info.java y @Nullable solo donde un valor pueda faltar. Es la que usa Spring Boot 4.

Artículos relacionados

Newsletter Semanal de Java

Cada viernes recibe lo más nuevo del ecosistema Java: frameworks, herramientas y mejores prácticas.

Sin spam. Cancela cuando quieras.

Compartir artículo