APIs REST Robustas: DTOs con Records y ProblemDetail RFC 7807

public record CrearTareaRequest(
        @NotBlank @Size(max = 120) String titulo,
        @Size(max = 2000) String descripcion,
        @Min(1) @Max(10) int prioridad) {}

public record TareaResponse(
        long id,
        String titulo,
        String descripcion,
        int prioridad,
        boolean completada,
        Instant creadaEn) {

    static TareaResponse desde(Tarea t) {
        return new TareaResponse(t.getId(), t.getTitulo(), t.getDescripcion(),
                t.getPrioridad(), t.isCompletada(), t.getCreadaEn());
    }
}

@RestController
@RequestMapping("/api/tareas")
class TareaController {
    private final TareaService servicio;
    TareaController(TareaService servicio) { this.servicio = servicio; }

    @GetMapping("/{id}")
    TareaResponse obtener(@PathVariable long id) {
        return TareaResponse.desde(servicio.obtener(id));
    }
}

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "https://api.acme.com/problemas/tarea-no-encontrada",
  "title": "Tarea no encontrada",
  "status": 404,
  "detail": "No existe ninguna tarea con id 42",
  "instance": "/api/tareas/42",
  "tareaId": 42,
  "timestamp": "2026-03-01T10:15:30Z"
}

@RestControllerAdvice
class ApiExceptionHandler extends ResponseEntityExceptionHandler {

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

    @ExceptionHandler(TareaNoEncontradaException.class)
    ProblemDetail noEncontrada(TareaNoEncontradaException ex) {
        var pd = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
        pd.setType(URI.create("https://api.acme.com/problemas/tarea-no-encontrada"));
        pd.setTitle("Tarea no encontrada");
        pd.setProperty("tareaId", ex.id());
        return pd;
    }

    @Override
    protected ResponseEntity<Object> handleMethodArgumentNotValid(
            MethodArgumentNotValidException ex, HttpHeaders headers,
            HttpStatusCode status, WebRequest request) {
        var pd = ProblemDetail.forStatusAndDetail(HttpStatus.BAD_REQUEST, "La petición tiene campos no válidos");
        pd.setProperty("errores", ex.getBindingResult().getFieldErrors().stream()
            .map(e -> Map.of("campo", e.getField(), "mensaje", e.getDefaultMessage()))
            .toList());
        return ResponseEntity.badRequest().body(pd);
    }

    @ExceptionHandler(Exception.class)
    ProblemDetail inesperada(Exception ex) {
        log.error("Error no controlado", ex);              // detalle solo en el log
        return ProblemDetail.forStatusAndDetail(HttpStatus.INTERNAL_SERVER_ERROR,
            "Error interno. Si persiste, contacta con soporte.");
    }
}

@RestController
@RequestMapping("/api/proyectos")
@Validated                                             // necesario para @PathVariable / @RequestParam
class ProyectoController {

    @PostMapping("/{proyectoId}/tareas")
    ResponseEntity<TareaResponse> crear(
            @PathVariable @Positive long proyectoId,
            @RequestBody @Valid CrearTareaRequest request) { /* ... */ return null; }
}

// Regla que afecta a dos campos
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = RangoFechasValidator.class)
@interface RangoFechasValido {
    String message() default "La fecha de fin debe ser posterior a la de inicio";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

class RangoFechasValidator implements ConstraintValidator<RangoFechasValido, SprintRequest> {
    @Override
    public boolean isValid(SprintRequest s, ConstraintValidatorContext ctx) {
        return s.inicio() == null || s.fin() == null || s.fin().isAfter(s.inicio());
    }
}

@RangoFechasValido
record SprintRequest(@NotBlank String nombre, @NotNull LocalDate inicio, @NotNull LocalDate fin) {}

@PostMapping
ResponseEntity<TareaResponse> crear(@RequestBody @Valid CrearTareaRequest req) {
    var creada = TareaResponse.desde(servicio.crear(req));
    URI ubicacion = ServletUriComponentsBuilder.fromCurrentRequest()
        .path("/{id}").buildAndExpand(creada.id()).toUri();
    return ResponseEntity.created(ubicacion).body(creada);          // 201 + Location
}

@PutMapping("/{id}")
TareaResponse reemplazar(@PathVariable long id, @RequestBody @Valid CrearTareaRequest req) {
    return TareaResponse.desde(servicio.reemplazar(id, req));       // 200
}

@DeleteMapping("/{id}")
@ResponseStatus(HttpStatus.NO_CONTENT)                              // 204
void borrar(@PathVariable long id) {
    servicio.borrar(id);                                             // idempotente: si no existe, también 204
}

@PostMapping("/{id}/completar")                                      // acción que no encaja en CRUD
TareaResponse completar(@PathVariable long id) {
    return TareaResponse.desde(servicio.completar(id));             // 409 si ya estaba completada
}