Validation ve Hata Yönetimi — İstemci Ne Görüyor?

1
public record TransferRequest(
2
        @NotBlank @Iban String fromIban,
3
        @NotEmpty @Size(max = 100) List<@Valid Payee> payees,   // one debit, up to 100 credits
4
        @Size(max = 140) String description) {
5

6
    public record Payee(
7
            @NotBlank @Iban String iban,
8
            @NotBlank @Size(max = 70) String name,
9
            @NotNull @Positive @Digits(integer = 12, fraction = 2) BigDecimal amount) {
10
    }
11
}

1
@Target({ElementType.FIELD, ElementType.PARAMETER, ElementType.RECORD_COMPONENT, ElementType.TYPE_USE})
2
@Retention(RetentionPolicy.RUNTIME)
3
@Constraint(validatedBy = Iban.Validator.class)
4
public @interface Iban {
5

6
    String message() default "Geçerli bir IBAN değil";
7
    Class<?>[] groups() default {};
8
    Class<? extends Payload>[] payload() default {};
9

10
    // ISO 13616: move the first four characters to the end, turn letters into
11
    // numbers (A=10 … Z=35) and the whole number mod 97 must be 1.
12
    class Validator implements ConstraintValidator<Iban, String> {
13
        private static final Pattern SHAPE = Pattern.compile("[A-Z]{2}\\d{2}[A-Z0-9]{11,30}");
14

15
        @Override
16
        public boolean isValid(String value, ConstraintValidatorContext context) {
17
            if (value == null) return true;                     // null is @NotBlank's job
18
            String iban = value.replace(" ", "").toUpperCase(Locale.ROOT);
19
            if (!SHAPE.matcher(iban).matches()) return false;
20
            if (iban.startsWith("TR") && iban.length() != 26) return false;
21

22
            String rearranged = iban.substring(4) + iban.substring(0, 4);
23
            int remainder = 0;
24
            for (char c : rearranged.toCharArray()) {
25
                int digit = Character.getNumericValue(c);       // '7' -> 7, 'T' -> 29
26
                remainder = (digit > 9 ? remainder * 100 : remainder * 10) + digit;
27
                remainder %= 97;                                // stays small: no BigInteger needed
28
            }
29
            return remainder == 1;
30
        }
31
    }
32
}

1
@RestController
2
@RequestMapping("/transfers")
3
class TransferController {
4

5
    private final TransferService transfers;
6

7
    TransferController(TransferService transfers) {
8
        this.transfers = transfers;
9
    }
10

11
    @PostMapping
12
    ResponseEntity<TransferView> create(@Valid @RequestBody TransferRequest request) {
13
        TransferView created = transfers.create(request);
14
        return ResponseEntity.created(URI.create("/transfers/" + created.id())).body(created);
15
    }
16

17
    // Constraints on a plain parameter: Spring 6.1+ validates them without @Validated
18
    // and reports failures as HandlerMethodValidationException.
19
    @GetMapping("/{id}")
20
    TransferView get(@PathVariable @Min(1) long id) {
21
        return transfers.get(id);
22
    }
23
}

1
@RestControllerAdvice
2
class ApiExceptionHandler extends ResponseEntityExceptionHandler {
3

4
    private static final Logger log = LoggerFactory.getLogger(ApiExceptionHandler.class);
5

6
    // 400: which field, which rule. The body is already a ProblemDetail; we add the details.
7
    @Override
8
    protected ResponseEntity<Object> handleMethodArgumentNotValid(
9
            MethodArgumentNotValidException ex, HttpHeaders headers, HttpStatusCode status, WebRequest request) {
10
        ProblemDetail body = ex.getBody();
11
        body.setTitle("Geçersiz talimat");
12
        body.setProperty("errors", ex.getBindingResult().getFieldErrors().stream()
13
                .map(error -> Map.of("field", error.getField(), "message", String.valueOf(error.getDefaultMessage())))
14
                .toList());
15
        return handleExceptionInternal(ex, body, headers, status, request);
16
    }
17

18
    @ExceptionHandler(TransferNotFoundException.class)
19
    ProblemDetail notFound(TransferNotFoundException ex) {
20
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
21
        problem.setType(URI.create("https://docs.bank.example/problems/transfer-not-found"));
22
        return problem;
23
    }
24

25
    // A business rule, not a malformed request. Never echo the balance back:
26
    // the response may end up in a log or on a shared screen.
27
    @ExceptionHandler(InsufficientFundsException.class)
28
    ProblemDetail insufficientFunds(InsufficientFundsException ex) {
29
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT, "Bakiye bu işlem için yetersiz.");
30
        problem.setType(URI.create("https://docs.bank.example/problems/insufficient-funds"));
31
        return problem;
32
    }
33

34
    // 500: log everything, reveal nothing.
35
    @ExceptionHandler(Exception.class)
36
    ProblemDetail unexpected(Exception ex) {
37
        log.error("unhandled", ex);
38
        return ProblemDetail.forStatusAndDetail(HttpStatus.INTERNAL_SERVER_ERROR, "Beklenmeyen bir hata oluştu.");
39
    }
40
}

1
spring:
2
  mvc:
3
    problemdetails:
4
      enabled: true     # Spring's own errors (405, 415, …) also answer as application/problem+json

1
@WebMvcTest(TransferController.class)
2
@Import(ApiExceptionHandler.class)
3
class TransferControllerValidationTest {
4

5
    @Autowired MockMvc mvc;
6
    @MockitoBean TransferService transfers;
7

8
    @Test
9
    void rejectsATypoInTheIbanAndAThirdDecimalWithFieldErrors() throws Exception {
10
        // The last digit of a valid IBAN changed from 6 to 7: the check digits catch it.
11
        mvc.perform(post("/transfers").contentType(APPLICATION_JSON).content("""
12
                        {"fromIban": "TR330006100519786457841326",
13
                         "payees": [{"iban": "TR330006100519786457841327", "name": "Ayşe Yılmaz", "amount": 10.005}]}
14
                        """))
15
                .andExpect(status().isBadRequest())
16
                .andExpect(content().contentType(APPLICATION_PROBLEM_JSON))
17
                .andExpect(jsonPath("$.errors[*].field",
18
                        containsInAnyOrder("payees[0].iban", "payees[0].amount")));
19

20
        verifyNoInteractions(transfers);   // invalid input never reaches the service
21
    }
22
}