Spring Boot 4 Complete Guide · درس

إنشاء تعليقات القيود المخصصة

إنشاء أدوات تحقق مخصصة قابلة لإعادة الاستخدام باستخدام ConstraintValidator لمنطق تحقق خاص بالنطاق.

الدرس 2 من 413 خطوة

إنشاء تعليقات القيود المخصصة درس مجاني في Spring Boot 4 Complete Guide على CoddyKit. هذا هو الدرس 2 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Spring Boot 4 Complete Guide، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Spring Boot 4 Complete Guide 4 دروس في المجموع.

بعض أجزاء هذا الدرس لم تُترجم بعد وتظهر باللغة الإنجليزية.

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?

أجب عليها في الدرس التفاعلي

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.

البدء مجانًا

تعلم Java مع معلم ذكاء اصطناعي — مجانًا

اكتب وقم بتشغيل أكوادك الفعلية في المتصفح، واحصل على مساعدة فورية من معلم ذكاء اصطناعي متاح 24/7، واستمر من حيث توقفت على الويب أو في التطبيق.

الدورات: 21
الدروس: 84

ابدأ التعلم مجانًا عرض الدورة الكاملة

الأسئلة الشائعة

هل درس «إنشاء تعليقات القيود المخصصة» مجاني؟

نعم — نص درس «إنشاء تعليقات القيود المخصصة» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Spring Boot 4 Complete Guide، انتقل إلى CoddyKit PRO. تتضمن دورة Spring Boot 4 Complete Guide 4 دروس في المجموع.

ماذا ستتعلم في «إنشاء تعليقات القيود المخصصة»؟

إنشاء أدوات تحقق مخصصة قابلة لإعادة الاستخدام باستخدام ConstraintValidator لمنطق تحقق خاص بالنطاق. تتمرن على Spring Boot 4 Complete Guide مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Spring Boot 4 Complete Guide؟

لا تُشترط خبرة سابقة. Spring Boot 4 Complete Guide على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 2 من أصل 4.

كم من الوقت يستغرق درس «إنشاء تعليقات القيود المخصصة»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Spring Boot 4 Complete Guide هذا؟

نعم. كل درس في Spring Boot 4 Complete Guide يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

قيود Bean Validation ومجموعات القيود
إنشاء تعليقات القيود المخصصة
معالجة الاستثناءات العامة باستخدام @ControllerAdvice
استجابات تفاصيل المشكلة وفق RFC 7807

← العودة إلى Spring Boot 4 Complete Guide