اعتبارسنجی (Bean Validation) و MapStructBean Validation & MapStruct

This chapter is about two pains every developer meets in any serious backend, yet few people talk about correctly. The first pain: dirty input. A user fills out a signup form, leaves the email blank, types their age as -3, or sends a three-character password. If you let that broken data flow straight into your business logic and database, disaster starts right there. The second pain: glue code for conversion. You fetch an object from the database (an Entity), but you don't want to hand it out as-is; you want a different object (a DTO). So you sit down and write dozens of lines of dto.setName(entity.getName()) — code with no logic at all, just pouring data from one box into another, and full of chances to slip.

Java has a standard, mature cure for both pains: Jakarta Bean Validation for the first, and MapStruct for the second. In this chapter you won't memorize a list of annotations — you'll understand what each one does, where in the architecture it belongs, and most importantly, why MapStruct — which generates mappers at compile time — is both faster and safer than rivals that work at runtime with reflection.

Part 0 — a few words you must feel before we start

Before any code, a few terms recur throughout this chapter. Let me plant them now.

• Validation: checking whether data is "valid" — i.e. it obeys the rules we define. For example, "email must look like an email" or "age can't be negative."
• Constraint: a specific validation rule expressed as an annotation on a field or parameter, like @NotNull or @Size(min=8). Each constraint is a rule label.
• DTO: short for Data Transfer Object. An object built purely to move data between layers — say, between the controller and the client. It differs from an Entity (an object mapped directly to a database table).
• Mapper: code that converts one object (say an Entity) into another (say a DTO), field by field.
• Reflection: Java's ability to inspect and manipulate classes and fields at runtime, without knowing their names at compile time. Powerful, but slow and unsafe; you'll see why this word is central to the MapStruct discussion.

What is Bean Validation? Spec vs implementation

Here's the first thing that separates seniors from beginners. When we say "Bean Validation," we mean a standard, not a specific library. Java has an official specification called Jakarta Validation (formerly known under the javax.validation name as JSR 380, now renamed after Java EE moved to the Eclipse Foundation and became Jakarta). This standard only defines the contract: annotations like @NotNull, and interfaces like Validator. But it contains no executable code itself.

The actual code that implements that contract is an implementation, and the most famous and reference one is Hibernate Validator (which has nothing to do with the Hibernate ORM database — just the same family).

To wire it up in a plain Maven project (outside Spring Boot):

<!-- the standard itself (API) -->
<dependency>
    <groupId>jakarta.validation</groupId>
    <artifactId>jakarta.validation-api</artifactId>
    <version>3.1.1</version>
</dependency>

<!-- the reference implementation -->
<dependency>
    <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>9.1.2.Final</version>
</dependency>

<!-- an Expression Language implementation, so error messages work -->
<dependency>
    <groupId>org.glassfish.expressly</groupId>
    <artifactId>expressly</artifactId>
    <version>6.0.0</version>
</dependency>

The core annotations: stick rules onto fields

The heart of Bean Validation is that you attach rules right where the data is defined — on the field itself. Let's build a signup DTO:

import jakarta.validation.constraints.*;
import java.time.LocalDate;

public class RegistrationRequest {

    @NotBlank(message = "username is required")
    @Size(min = 3, max = 20, message = "username must be 3-20 characters")
    private String username;

    @NotBlank
    @Email(message = "invalid email format")
    private String email;

    @NotBlank
    @Size(min = 8, message = "password must be at least 8 characters")
    @Pattern(regexp = ".*\\d.*", message = "password must contain at least one digit")
    private String password;

    @NotNull
    @Min(value = 18, message = "age must be at least 18")
    @Max(150)
    private Integer age;

    @Past(message = "birth date must be in the past")
    private LocalDate birthDate;

    // getters/setters ...
}

Read each line: the rule sits next to the data, is readable, and there's nowhere else in the code where you can "forget" to check it. Now the most important distinction that many people get wrong:

The most commonly used built-in constraints:

But these annotations do nothing on their own — they're just labels. Someone has to read and enforce them. That someone is either the framework (Spring does it automatically) or you, with a Validator:

import jakarta.validation.*;

ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
Validator validator = factory.getValidator();

RegistrationRequest req = new RegistrationRequest();
req.setUsername("ab");          // too short
req.setEmail("not-an-email");   // wrong format

Set<ConstraintViolation<RegistrationRequest>> violations = validator.validate(req);
for (ConstraintViolation<RegistrationRequest> v : violations) {
    System.out.println(v.getPropertyPath() + " : " + v.getMessage());
    // username : username must be 3-20 characters
    // email : invalid email format
}

validator.validate(...) returns a Set of violations. If it's empty, everything is valid. Each violation tells you which field and why it was rejected.

@PostMapping("/register")
public ResponseEntity<?> register(@Valid @RequestBody RegistrationRequest req) {
    // if req is invalid, this method never runs;
    // Spring throws a MethodArgumentNotValidException, which by default
    // becomes a 400 Bad Request response.
    return ResponseEntity.ok(userService.register(req));
}

@Valid and cascading: validating nested objects

So far we've seen simple fields. But what if one object holds another object inside it? For example an Order that has an Address. By default, validation is not cascading — if you validate Order, Bean Validation won't peek inside Address and ignores its constraints. To make validation propagate into a nested object, you must put @Valid on that field:

public class Order {

    @NotNull
    private String orderId;

    @NotNull
    @Valid                          // ← this is the key
    private Address shippingAddress; // without @Valid, Address's constraints aren't checked

    @NotEmpty
    @Valid                          // works on collections too: each element is validated
    private List<OrderLine> lines;
}

public class Address {
    @NotBlank private String street;
    @NotBlank private String city;
    @Pattern(regexp = "\\d{10}") private String postalCode;
}

A subtle point: the error path becomes nested too. If postalCode inside shippingAddress is invalid, the path becomes shippingAddress.postalCode — which is great for building precise error messages for the user.

Validation groups: one object, different rules

Here's a real-world problem. Suppose you have a User. On create, the id should be null (it doesn't exist yet) and the password is required. On update, the id must be present and the password is optional. Same class, but two different sets of rules. If you apply all constraints unconditionally, you can't tell these two cases apart.

The solution: validation groups. A group is just an empty marker interface:

public interface OnCreate {}
public interface OnUpdate {}

Now you assign each constraint to a group (or groups):

public class UserDto {

    @Null(groups = OnCreate.class)       // must be null on create
    @NotNull(groups = OnUpdate.class)    // must be present on update
    private Long id;

    @NotBlank(groups = {OnCreate.class, OnUpdate.class})
    private String username;

    @NotBlank(groups = OnCreate.class)   // required only on create
    @Size(min = 8, groups = {OnCreate.class, OnUpdate.class})
    private String password;
}

And at validation time you choose which group to run:

// check only the OnCreate group's constraints
Set<ConstraintViolation<UserDto>> v = validator.validate(dto, OnCreate.class);

In Spring you use @Validated instead of @Valid, which can take a group:

@PostMapping("/users")
public User create(@Validated(OnCreate.class) @RequestBody UserDto dto) { ... }

@PutMapping("/users/{id}")
public User update(@Validated(OnUpdate.class) @RequestBody UserDto dto) { ... }

Groups can also be ordered: with @GroupSequence you say "check this group first; only if it passes, move on to the next." This is useful for staged validation — structure first, then expensive business rules.

Custom validation: write your own ConstraintValidator

The built-in annotations are great, but sooner or later you'll want a rule none of them covers: "username may contain only letters, digits, and underscores," "must be a valid national ID," "this email isn't already registered." That's when you build your own custom constraint. It has two pieces:

Piece 1 — the annotation itself. You define an annotation and, with @Constraint, tell it which class holds the checking logic:

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

@Documented
@Constraint(validatedBy = UsernameValidator.class)   // ← the logic class
@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
public @interface ValidUsername {
    String message() default "username may only contain letters, digits, and underscores";
    Class<?>[] groups() default {};              // to support groups — mandatory
    Class<? extends Payload>[] payload() default {}; // extra metadata — mandatory
}

Piece 2 — the validation logic. A class implementing ConstraintValidator<A, T>: A is the annotation type and T is the type of data being checked.

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

public class UsernameValidator implements ConstraintValidator<ValidUsername, String> {

    private static final java.util.regex.Pattern PATTERN =
        java.util.regex.Pattern.compile("^[a-zA-Z0-9_]+$");

    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        // important contract: treat null as "valid" and leave null-ness to @NotNull
        if (value == null) {
            return true;
        }
        return PATTERN.matcher(value).matches();
    }
}

Usage is now clean:

public class SignupForm {
    @NotBlank
    @ValidUsername          // our custom constraint, exactly like the built-in ones
    private String username;
}

If you need database access for validation (e.g. "email must be unique"), since a ConstraintValidator is a bean in Spring, you can inject dependencies:

@Component
public class UniqueEmailValidator implements ConstraintValidator<UniqueEmail, String> {

    private final UserRepository repository;

    public UniqueEmailValidator(UserRepository repository) { // constructor injection
        this.repository = repository;
    }

    @Override
    public boolean isValid(String email, ConstraintValidatorContext ctx) {
        if (email == null) return true;
        return !repository.existsByEmail(email);
    }
}

Method-level validation

So far we've validated an object's fields. But Bean Validation has another power: it can put constraints directly on method parameters and return values. This means you can declare a method's contract right in its signature:

import jakarta.validation.constraints.*;
import org.springframework.validation.annotation.Validated;

@Service
@Validated   // ← without this, method-level constraints are ignored in Spring
public class AccountService {

    public Account findById(@NotNull @Positive Long id) {
        // if id is null or <= 0, a ConstraintViolationException
        // is thrown before entering the method body.
        return repository.findById(id).orElseThrow();
    }

    public @NotNull Account create(@Valid AccountForm form) {
        // @Valid on the object parameter = cascade into form
        // @NotNull on the return value = guarantee a non-null output
        return repository.save(new Account(form));
    }
}

Which layer should validate?

This is a favorite interview question, and the shallow answer ("in the controller") is incomplete. The senior answer: validation isn't one layer, it's several kinds, and each kind has its place.

Now that the input is clean, we reach the second pain: converting these clean objects between layers.

The second pain: why DTOs and mapping at all?

A fair question: why not hand the Entity straight to the client and spare ourselves this conversion? Several serious reasons:

• Security. A user Entity might have a passwordHash or isAdmin field; you don't want to accidentally leak it in a JSON response. A DTO exposes only what it should.
• Layer decoupling. If the client is coupled directly to the Entity, every small database-structure change breaks your public API. A DTO is a shock absorber between the internal model and the external contract.
• Different shape. Sometimes the output must combine several entities or use different names and structure. For example firstName and lastName in the entity, but fullName in the DTO.
• Lazy-serialization problems. Handing an entity straight to JSON often leads to LazyInitializationException or unwanted queries (it pulls lazy relations mid-serialization).

So a DTO is needed. But manual conversion is tedious and error-prone:

// manual mapping — no logic, just moves data, full of chances to slip
public UserDto toDto(User user) {
    UserDto dto = new UserDto();
    dto.setId(user.getId());
    dto.setUsername(user.getUsername());
    dto.setEmail(user.getEmail());
    // ... and if a new field is added to User, "forgetting" to add it here → silent bug
    return dto;
}

MapStruct: a mapper at compile time

MapStruct is an annotation processor. You only define an interface saying "from this type to that type," and MapStruct generates a real Java implementation class for you at compile time — one that does exactly the same manual set/get — but you didn't write it, so you can't break it.

Wiring it in Maven:

<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct</artifactId>
    <version>1.6.3</version>
</dependency>

And, more importantly, you register the processor with the compiler:

<plugin>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <annotationProcessorPaths>
            <path>
                <groupId>org.mapstruct</groupId>
                <artifactId>mapstruct-processor</artifactId>
                <version>1.6.3</version>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>

Now let's write a mapper. Just an interface with the @Mapper annotation:

import org.mapstruct.*;

@Mapper(componentModel = "spring")   // so it can be injected as a Spring bean
public interface UserMapper {

    UserDto toDto(User user);        // MapStruct generates the implementation

    User toEntity(UserDto dto);      // the reverse direction likewise

    List<UserDto> toDtoList(List<User> users);  // collections too, automatically
}

That's it. For fields whose names match (username to username), MapStruct discovers the mapping itself. The generated code looks something like this — a perfectly ordinary class, readable and reflection-free:

// code generated by MapStruct (abbreviated) — you don't write this, but you can see it
@Component
public class UserMapperImpl implements UserMapper {
    @Override
    public UserDto toDto(User user) {
        if (user == null) return null;
        UserDto dto = new UserDto();
        dto.setId(user.getId());
        dto.setUsername(user.getUsername());
        dto.setEmail(user.getEmail());
        return dto;
    }
    // ...
}

Look at that code: it's exactly what you'd have written by hand, but flawless, automatic, and always in sync with the fields.

When names differ: @Mapping

If field names differ or you want to combine several fields, you guide it with @Mapping:

@Mapper(componentModel = "spring")
public interface UserMapper {

    @Mapping(source = "username", target = "login")            // different name
    @Mapping(target = "fullName", expression = "java(user.getFirstName() + \" \" + user.getLastName())")
    @Mapping(target = "password", ignore = true)               // don't map this at all
    @Mapping(source = "createdAt", target = "registeredOn", dateFormat = "yyyy-MM-dd")
    UserDto toDto(User user);
}

@Mapper(componentModel = "spring",
        unmappedTargetPolicy = ReportingPolicy.ERROR)
public interface UserMapper { ... }

Updating an existing object and nested mappers

// instead of creating a new object, update the fields of an existing one
@Mapping(target = "id", ignore = true)
void updateEntityFromDto(UserDto dto, @MappingTarget User entity);

// use other mappers for nested fields
@Mapper(componentModel = "spring", uses = { AddressMapper.class })
public interface OrderMapper {
    OrderDto toDto(Order order);   // AddressMapper is used automatically for the address field
}

@MappingTarget says "don't create a new object, fill this one" — perfect for update operations. And uses = {...} tells MapStruct to lean on other mappers for nested types, so you don't have to write everything in one place.

Why is compile-time better than reflection?

Here's the heart of the chapter. MapStruct's older rivals (libraries that work at runtime with reflection) inspect the source object at runtime: they find fields via reflection, match names, and copy values. That works, but has three serious costs that MapStruct eliminates by generating code at compile time.

Together: validation + mapping in one flow

Now let's put both tools side by side in a real request flow so you see where each sits in the chain:

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

    private final UserService userService;
    private final UserMapper userMapper;

    @PostMapping
    public UserDto register(@Valid @RequestBody RegistrationRequest req) {
        // 1) bouncer at the door: @Valid validates req right here.
        //    if invalid, the body never runs → 400.

        // 2) mapping: convert the clean DTO into an Entity.
        User entity = userMapper.toEntity(req);

        // 3) business logic in the service layer.
        User saved = userService.register(entity);

        // 4) return mapping: convert the Entity into a safe response DTO
        //    (without passwordHash and sensitive fields).
        return userMapper.toDto(saved);
    }
}

This flow shows the correct order: validate first (edge), then map to the internal model, then logic, then map back to the external model. Each tool in its place, with no hand-written glue code.

A few best practices to keep in mind

• Put constraints on input DTOs, not on entities; the app's edge is the place for format validation.
• Use @NotBlank for user strings, @NotEmpty for collections, and @NotNull for everything else — don't confuse their differences.
• Don't forget @Valid for nested objects; without it, cascading doesn't happen.
• In custom constraints, return true from isValid(null) so they stay composable.
• Database uniqueness validation doesn't replace a unique constraint; it's only for a better message.
• In MapStruct, use unmappedTargetPolicy = ReportingPolicy.ERROR so no field is accidentally left out.
• Set componentModel = "spring" so the mapper becomes an injectable bean.
• If you use Lombok and MapStruct together, add lombok-mapstruct-binding.
• Don't put business logic inside a mapper; a mapper only reshapes data, it doesn't decide.

Interview questions