Spring Boot 4 Complete Guide · Lección

Creación de anotaciones de restricciones personalizadas

Cree validadores personalizados reutilizables con ConstraintValidator para lógica de validación específica del dominio.

Lección 2 de 413 pasos

Creación de anotaciones de restricciones personalizadas es una lección gratuita de Spring Boot 4 Complete Guide en CoddyKit. Esta es la lección 2 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de Spring Boot 4 Complete Guide, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de Spring Boot 4 Complete Guide incluye 4 lecciones en total.

Partes de esta lección aún no han sido traducidas y se muestran en inglés.

Why Custom Constraints?

Bean Validation ships with annotations like @NotNull, @Size, and @Email. But real applications have domain-specific rules that no built-in annotation covers.

A username must be lowercase and 3-20 chars
A phone number must match your country's format
A status field must be one of an allowed enum set

Instead of writing manual checks in every controller or service, you can build a reusable custom constraint annotation that plugs into the same validation pipeline as the built-in ones.

The Two Pieces of a Custom Constraint

Every custom constraint in Spring Boot 4 (which uses Jakarta Bean Validation) has exactly two parts:

The annotation — what you write on a field, e.g. @ValidUsername. It declares metadata and points to a validator.
The ConstraintValidator — a class containing the actual isValid() logic.

The @Constraint meta-annotation links the two together. When validation runs, the framework instantiates your validator and calls isValid() for each annotated field.

Defining the Annotation

A custom constraint annotation must declare three standard attributes: message, groups, and payload. The @Constraint(validatedBy = ...) wires it to a validator class.

Note the imports come from jakarta.validation, not the old javax.validation.

import jakarta.validation.Constraint;
import jakarta.validation.Payload;
import java.lang.annotation.*;

@Documented
@Constraint(validatedBy = UsernameValidator.class)
@Target({ ElementType.FIELD, ElementType.PARAMETER })
@Retention(RetentionPolicy.RUNTIME)
public @interface ValidUsername {
    String message() default "invalid username";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

Understanding @Target and @Retention

Two meta-annotations control where and when your constraint applies:

@Target — where the annotation can be placed. FIELD for entity fields, PARAMETER for method args, METHOD for getters, TYPE_USE for generics like List<@ValidUsername String>.
@Retention(RUNTIME) — the annotation must survive into runtime so the validation engine can read it via reflection. This is mandatory; SOURCE or CLASS retention would make the constraint invisible.

Writing the ConstraintValidator

The validator implements ConstraintValidator<A, T>, where A is your annotation type and T is the type of the value being validated (e.g. String).

The isValid() method returns true if valid. A key rule: treat null as valid and let @NotNull handle nullness separately. This keeps each constraint focused on one concern.

import jakarta.validation.ConstraintValidator;
import jakarta.validation.ConstraintValidatorContext;

public class UsernameValidator
        implements ConstraintValidator<ValidUsername, String> {

    @Override
    public boolean isValid(String value, ConstraintValidatorContext ctx) {
        if (value == null) {
            return true; // let @NotNull handle null
        }
        return value.matches("^[a-z0-9_]{3,20}$");
    }
}

Applying the Constraint

Once defined, your constraint is used exactly like a built-in one. Place it on a DTO field and combine it with other constraints. Spring evaluates all of them when the object is validated.

Use @NotNull alongside @ValidUsername since the validator deliberately allows null.

import jakarta.validation.constraints.NotNull;

public record RegisterRequest(
        @NotNull
        @ValidUsername(message = "username must be 3-20 lowercase chars")
        String username,

        @NotNull
        String password
) {}

Triggering Validation in a Controller

To run validation on incoming request bodies, annotate the parameter with @Valid. If any constraint fails, Spring throws a MethodArgumentNotValidException before your method body runs.

The message you set on the annotation becomes the error message reported back to the client.

import jakarta.validation.Valid;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/users")
public class UserController {

    @PostMapping("/register")
    public String register(@Valid @RequestBody RegisterRequest req) {
        return "registered: " + req.username();
    }
}

Customizing the Error Message Dynamically

Sometimes a static message isn't enough — you want the message to reflect why validation failed. Use the ConstraintValidatorContext to disable the default message and build a custom one.

You must call disableDefaultConstraintViolation() first, then add your own violation, otherwise both messages appear.

@Override
public boolean isValid(String value, ConstraintValidatorContext ctx) {
    if (value == null) return true;
    if (value.length() < 3 || value.length() > 20) {
        ctx.disableDefaultConstraintViolation();
        ctx.buildConstraintViolationWithTemplate(
                "username length must be between 3 and 20")
           .addConstraintViolation();
        return false;
    }
    return value.matches("^[a-z0-9_]+$");
}

Passing Parameters to Your Constraint

Make constraints configurable by adding attributes to the annotation. For example, a @ValidUsername that accepts min and max length.

The validator reads these in initialize(), which runs once before isValid() calls.

public @interface ValidUsername {
    String message() default "invalid username";
    int min() default 3;
    int max() default 20;
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

Reading Parameters in initialize()

Override initialize() to capture the annotation's attribute values into fields. The framework calls it once per validator instance, before any isValid() invocation.

This lets one validator class serve many different configurations.

public class UsernameValidator
        implements ConstraintValidator<ValidUsername, String> {

    private int min;
    private int max;

    @Override
    public void initialize(ValidUsername ann) {
        this.min = ann.min();
        this.max = ann.max();
    }

    @Override
    public boolean isValid(String value, ConstraintValidatorContext ctx) {
        if (value == null) return true;
        return value.length() >= min && value.length() <= max
                && value.matches("^[a-z0-9_]+$");
    }
}

Pure-Java: The Validation Logic Standalone

The core regex and length logic is plain Java you can test without any framework. Here is the same rule expressed as a runnable program to prove the logic before wiring it into Spring.

This isolation makes your validators easy to unit test.

public class Main {
    static boolean isValidUsername(String value, int min, int max) {
        if (value == null) return true;
        return value.length() >= min && value.length() <= max
                && value.matches("^[a-z0-9_]+$");
    }

    public static void main(String[] args) {
        System.out.println(isValidUsername("alice_99", 3, 20)); // true
        System.out.println(isValidUsername("Al", 3, 20));       // false
        System.out.println(isValidUsername("Bad Name", 3, 20)); // false
        System.out.println(isValidUsername(null, 3, 20));       // true
    }
}

Quick Check

You implement a custom ConstraintValidator for a String field. The field is optional, and a separate @NotNull already guards nullness. What should isValid() return when the value is null?

Responde en la lección interactiva

Recap

You learned how to build reusable custom constraint annotations in Spring Boot 4:

A constraint has two parts: the annotation (with message, groups, payload) and a ConstraintValidator.
@Constraint(validatedBy = ...) links them; @Retention(RUNTIME) and @Target control visibility and placement.
isValid() holds the logic and should treat null as valid, deferring to @NotNull.
Use initialize() to read annotation parameters, and ConstraintValidatorContext to craft dynamic messages.
Apply the constraint on DTO fields and trigger it with @Valid in controllers.

With these patterns, domain rules live in one tested place and plug seamlessly into Spring's validation pipeline.

Gratis para empezar

Aprende Java con un tutor de IA — gratis

Escribe y ejecuta código real en tu navegador, obtén ayuda instantánea de un tutor de IA disponible 24/7 y continúa donde lo dejaste en la web o en la aplicación.

Cursos: 21
Lecciones: 84

Empezar a aprender gratis Ver el curso completo

Preguntas frecuentes

¿La lección «Creación de anotaciones de restricciones personalizadas» es gratis?

Sí — el texto completo de «Creación de anotaciones de restricciones personalizadas» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de Spring Boot 4 Complete Guide, actualiza a CoddyKit PRO. El curso de Spring Boot 4 Complete Guide incluye 4 lecciones en total.

¿Qué aprenderé en «Creación de anotaciones de restricciones personalizadas»?

Cree validadores personalizados reutilizables con ConstraintValidator para lógica de validación específica del dominio. Practicas Spring Boot 4 Complete Guide con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar Spring Boot 4 Complete Guide?

No se requiere experiencia previa. Spring Boot 4 Complete Guide en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 2 de 4.

¿Cuánto tiempo toma la lección «Creación de anotaciones de restricciones personalizadas»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de Spring Boot 4 Complete Guide?

Sí. Cada lección de Spring Boot 4 Complete Guide incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

Restricciones de Bean Validation y grupos de restricciones
Creación de anotaciones de restricciones personalizadas
Gestión global de excepciones con @ControllerAdvice
Respuestas Problem Detail según RFC 7807

← Volver a Spring Boot 4 Complete Guide