Construirea REST API-urilor de Producție cu Spring Boot

Un REST API Spring Boot care funcționează în dezvoltare și unul care rezistă în producție sunt lucruri diferite. Acest articol se concentrează pe deciziile structurale care contează: stratificare, validare, gestionarea erorilor, migrații Flyway și documentație.

Structura proiectului

src/main/java/com/example/api/
  ├── config/          # Security, CORS, Jackson, OpenAPI
  ├── controller/      # @RestController — subțiri, delegă la servicii
  ├── service/         # Logică de business
  ├── repository/      # Interfețe Spring Data JPA
  ├── domain/          # Clase @Entity
  ├── dto/             # Recorduri de request/response
  └── exception/       # Excepții custom + GlobalExceptionHandler

Menține controller-ele subțiri. O metodă de controller ar trebui să parseze input-ul, să apeleze un singur serviciu și să returneze un răspuns.

Validare și răspunsuri la erori

Folosește Bean Validation pe recordurile DTO și gestionează centralizat MethodArgumentNotValidException:

public record CreateOrderRequest(
    @NotBlank String packageId,
    @NotBlank @Email String email,
    @Positive Integer quantity
) {}

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleValidation(MethodArgumentNotValidException ex) {
        var errors = ex.getBindingResult().getFieldErrors()
            .stream()
            .map(e -> new FieldError(e.getField(), e.getDefaultMessage()))
            .toList();
        return ResponseEntity.badRequest().body(new ErrorResponse("VALIDATION_ERROR", errors));
    }
}

Migrații de baze de date cu Flyway

Flyway menține evoluția schemei versionată și auditabilă:

-- V1__init.sql
CREATE TABLE orders (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id),
    status VARCHAR(20) NOT NULL DEFAULT 'PENDING',
    amount_cents INTEGER NOT NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

Nu edita niciodată o migrație aplicată. Adaugă un nou fișier V2__ în schimb.

Documentație OpenAPI

Springdoc generează automat OpenAPI 3 din adnotările tale:

@Operation(summary = "Creează o comandă nouă")
@PostMapping("/orders")
public ResponseEntity<OrderResponse> createOrder(@Valid @RequestBody CreateOrderRequest request) { ... }

---

Ai nevoie de un backend Spring Boot — validare, migrații Flyway, autentificare JWT și un strat de servicii testat? Contactează-mă.