Response Handling

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

    private final UserService userService;

    // Fixed outcome: return the object. 200 OK is implied.
    // userService.findById throws UserNotFoundException when missing (see the errors section).
    @GetMapping("/{id}")
    public UserResponse findById(@PathVariable Long id) {
        return userService.findById(id);
    }

    // Fixed non-200 status: annotate instead of wrapping.
    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public UserResponse create(@RequestBody @Valid CreateUserRequest request) {
        return userService.create(request);
    }

    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void delete(@PathVariable Long id) {
        userService.delete(id);
    }

    // Outcome varies: ResponseEntity makes the 200 or 404 explicit.
    @GetMapping("/by-email")
    public ResponseEntity<UserResponse> findByEmail(@RequestParam String email) {
        return userService.findOptionalByEmail(email)
            .map(ResponseEntity::ok)
            .orElseGet(() -> ResponseEntity.notFound().build());
    }

    // Gotcha: an empty Optional here is 200 with an empty body, NOT 404.
    @GetMapping("/optional/{id}")
    public Optional<UserResponse> findOptional(@PathVariable Long id) {
        return userService.findOptional(id);
    }
}

@RestController
@RequestMapping("/api/v1/orders")
@RequiredArgsConstructor
public class OrderController {

    private final OrderService orderService;

    // 201 Created + Location of the new resource
    @PostMapping
    public ResponseEntity<OrderResponse> create(
            @RequestBody @Valid CreateOrderRequest request,
            UriComponentsBuilder uriBuilder) {

        OrderResponse created = orderService.create(request);
        URI location = uriBuilder.path("/api/v1/orders/{id}")
            .buildAndExpand(created.id()).toUri();
        return ResponseEntity.created(location).body(created);
    }

    // 202 Accepted: the work continues in the background. Point the client at a status URL.
    @PostMapping("/{id}/ship")
    public ResponseEntity<Void> ship(@PathVariable Long id, UriComponentsBuilder uriBuilder) {
        orderService.scheduleShipment(id);
        URI status = uriBuilder.path("/api/v1/orders/{id}/shipment")
            .buildAndExpand(id).toUri();
        return ResponseEntity.accepted().location(status).build();
    }

    // 204 No Content: success with nothing to say
    @PatchMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void patch(@PathVariable Long id, @RequestBody @Valid PatchOrderRequest request) {
        orderService.patch(id, request);
    }

    // 404 from a one-off check
    @GetMapping("/{id}")
    public OrderResponse find(@PathVariable Long id) {
        return orderService.findOptional(id)
            .orElseThrow(() -> new ResponseStatusException(
                HttpStatus.NOT_FOUND, "Order " + id + " not found"));
    }

    // A batch endpoint: 207 Multi-Status comes from WebDAV and few clients understand it.
    // Returning 200 with a per-item result list is usually friendlier.
    @PostMapping("/batch-cancel")
    public List<BatchResult> batchCancel(@RequestBody List<Long> ids) {
        return orderService.cancelBatch(ids);
    }
}

@RestControllerAdvice
@Slf4j
public class ApiExceptionHandler extends ResponseEntityExceptionHandler {

    @ExceptionHandler(OrderNotFoundException.class)
    ProblemDetail handleNotFound(OrderNotFoundException ex) {
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
        problem.setTitle("Order not found");
        problem.setProperty("orderId", ex.getOrderId());   // extra fields are allowed
        return problem;
    }

    @ExceptionHandler(OptimisticLockingFailureException.class)
    ProblemDetail handleConflict(OptimisticLockingFailureException ex) {
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
            HttpStatus.CONFLICT, "The resource was modified by someone else. Reload and retry.");
        problem.setTitle("Conflict");
        return problem;
    }

    // Validation failures (@Valid on a request body): add the field errors to Spring's default body.
    @Override
    protected ResponseEntity<Object> handleMethodArgumentNotValid(
            MethodArgumentNotValidException ex, HttpHeaders headers,
            HttpStatusCode status, WebRequest request) {

        Map<String, String> errors = new LinkedHashMap<>();
        ex.getBindingResult().getFieldErrors()
            .forEach(e -> errors.putIfAbsent(e.getField(), e.getDefaultMessage()));

        ProblemDetail problem = ex.getBody();
        problem.setTitle("Validation failed");
        problem.setProperty("errors", errors);
        return handleExceptionInternal(ex, problem, headers, status, request);
    }

    // Last resort: log the details, tell the client nothing sensitive.
    @ExceptionHandler(Exception.class)
    ProblemDetail handleUnexpected(Exception ex) {
        log.error("Unhandled exception", ex);
        return ProblemDetail.forStatusAndDetail(
            HttpStatus.INTERNAL_SERVER_ERROR, "An unexpected error occurred.");
    }
}

// Example response:
// HTTP/1.1 404 Not Found
// Content-Type: application/problem+json
// { "type": "about:blank", "title": "Order not found", "status": 404,
//   "detail": "Order 42 not found", "instance": "/api/v1/orders/42", "orderId": 42 }

@RestController
@RequestMapping("/api/v1/files")
@RequiredArgsConstructor
public class FileController {

    private final FileService fileService;

    // Download. Because the body is a Resource, Range requests are answered with 206 automatically.
    @GetMapping("/{id}/download")
    public ResponseEntity<Resource> download(@PathVariable Long id) {
        StoredFile file = fileService.find(id);
        return ResponseEntity.ok()
            .header(HttpHeaders.CONTENT_DISPOSITION,
                ContentDisposition.attachment()
                    .filename(file.filename(), StandardCharsets.UTF_8)   // quotes and encodes safely
                    .build().toString())
            .contentType(MediaType.parseMediaType(file.contentType()))
            .contentLength(file.sizeBytes())
            .body(file.resource());
    }

    // Inline preview: still use ContentDisposition, never string concatenation.
    @GetMapping("/{id}/preview")
    public ResponseEntity<Resource> preview(@PathVariable Long id) {
        StoredFile file = fileService.find(id);
        return ResponseEntity.ok()
            .header(HttpHeaders.CONTENT_DISPOSITION,
                ContentDisposition.inline()
                    .filename(file.filename(), StandardCharsets.UTF_8).build().toString())
            .contentType(MediaType.parseMediaType(file.contentType()))
            .body(file.resource());
    }

    // Creation with Location and a few custom headers (header values must be Strings).
    @PostMapping
    public ResponseEntity<FileResponse> upload(@RequestParam MultipartFile file,
                                               UriComponentsBuilder uriBuilder) {
        FileResponse stored = fileService.store(file);
        URI location = uriBuilder.path("/api/v1/files/{id}").buildAndExpand(stored.id()).toUri();
        return ResponseEntity.created(location)
            .header("X-File-Id", String.valueOf(stored.id()))
            .header("X-Checksum", stored.checksum())
            .body(stored);
    }
}

// CORS: let browser code on another origin read your custom headers.
// registry.addMapping("/api/**").exposedHeaders("X-File-Id", "X-Checksum", "Location");

@RestController
@RequestMapping("/api/v1/catalogue")
@RequiredArgsConstructor
public class CatalogueController {

    private final ProductService productService;

    // Cheap revalidation: check the version first, load the body only if the client is out of date.
    @GetMapping("/products/{id}")
    public ResponseEntity<ProductResponse> product(@PathVariable Long id, WebRequest request) {
        long version = productService.currentVersion(id);   // one small query, not the whole object

        if (request.checkNotModified(String.valueOf(version))) {
            return null;   // 304 already written; Spring quotes the ETag for you
        }

        return ResponseEntity.ok()
            .cacheControl(CacheControl.maxAge(Duration.ofMinutes(10)).cachePublic())
            .eTag(String.valueOf(version))
            .body(productService.findById(id));
    }

    // Last-Modified variant
    @GetMapping("/categories")
    public ResponseEntity<List<CategoryResponse>> categories(WebRequest request) {
        Instant lastModified = productService.categoriesLastModified();

        if (request.checkNotModified(lastModified.toEpochMilli())) {
            return null;
        }

        return ResponseEntity.ok()
            .lastModified(lastModified)
            .cacheControl(CacheControl.maxAge(Duration.ofMinutes(30)).cachePublic())
            .body(productService.findAllCategories());
    }

    // Per-user data: only the user's own browser may keep it.
    @GetMapping("/me/recommendations")
    public ResponseEntity<List<ProductResponse>> recommendations(@AuthenticationPrincipal AppUser user) {
        return ResponseEntity.ok()
            .cacheControl(CacheControl.maxAge(Duration.ofMinutes(1)).cachePrivate())
            .body(productService.recommendationsFor(user.getId()));
    }

    // Sensitive: never stored anywhere.
    @GetMapping("/me/wishlist")
    public ResponseEntity<WishlistResponse> wishlist(@AuthenticationPrincipal AppUser user) {
        return ResponseEntity.ok()
            .cacheControl(CacheControl.noStore())
            .body(productService.wishlistFor(user.getId()));
    }
}

public record ProductResponse(
        Long id,
        String name,

        @JsonProperty("image_url")                  // rename one field
        String imageUrl,

        @JsonInclude(JsonInclude.Include.NON_NULL)  // omit when null
        String discountLabel,

        @JsonFormat(shape = JsonFormat.Shape.STRING) // "19.99" instead of 19.99, safe for JS clients
        BigDecimal price,

        Instant createdAt) {                         // written as ISO-8601, e.g. 2026-10-04T08:30:00Z
}

// Global defaults in application.yml instead of per-field annotations:
//
// spring:
//   jackson:
//     default-property-inclusion: non_null        # omit nulls everywhere
//     property-naming-strategy: SNAKE_CASE        # createdAt -> created_at
//
// Never serialise secrets by accident: keep password hashes, tokens and internal flags out of the
// response DTO entirely. @JsonIgnore on an entity is a safety net, not a design.

@RestController
@RequestMapping("/api/v1/reports")
@RequiredArgsConstructor
public class ReportController {

    private final ReportService reportService;

    // Simplest offload: Spring runs the Callable on its async executor.
    @GetMapping("/{id}")
    public Callable<ReportResponse> generate(@PathVariable Long id) {
        return () -> reportService.generate(id);
    }

    // DeferredResult: complete it on EVERY path, or the request hangs until the timeout.
    @GetMapping("/{id}/deferred")
    public DeferredResult<ReportResponse> deferred(@PathVariable Long id) {
        DeferredResult<ReportResponse> result = new DeferredResult<>(30_000L);

        result.onTimeout(() -> result.setErrorResult(
            new ResponseStatusException(HttpStatus.GATEWAY_TIMEOUT, "Report generation timed out")));

        reportService.generateAsync(id).whenComplete((report, error) -> {
            if (error != null) {
                result.setErrorResult(error);   // goes through your exception handlers
            } else {
                result.setResult(report);
            }
        });
        return result;
    }

    // Streaming export. The service opens its own read-only transaction and closes the stream.
    @GetMapping(value = "/export", produces = "text/csv")
    public ResponseEntity<StreamingResponseBody> export() {
        StreamingResponseBody body = out -> {
            try (Writer writer = new BufferedWriter(new OutputStreamWriter(out, StandardCharsets.UTF_8));
                 CSVPrinter csv = new CSVPrinter(writer, CSVFormat.DEFAULT.builder()
                     .setHeader("id", "name", "total", "createdAt").build())) {

                reportService.forEachRow(row -> {        // @Transactional(readOnly = true) inside
                    try {
                        csv.printRecord(row.id(), row.name(),
                            row.total().toPlainString(),   // locale-independent
                            row.createdAt());
                    } catch (IOException e) {
                        throw new UncheckedIOException(e);   // typically the client disconnecting
                    }
                });
            }
        };
        return ResponseEntity.ok()
            .header(HttpHeaders.CONTENT_DISPOSITION,
                ContentDisposition.attachment().filename("report.csv").build().toString())
            .body(body);
    }

    // Server-Sent Events: manage the emitter's whole lifecycle.
    @GetMapping(value = "/{id}/progress", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public SseEmitter progress(@PathVariable Long id) {
        SseEmitter emitter = new SseEmitter(120_000L);
        reportService.subscribe(id, emitter);   // events are sent from another thread

        Runnable cleanup = () -> reportService.unsubscribe(id, emitter);
        emitter.onCompletion(cleanup);
        emitter.onTimeout(emitter::complete);
        emitter.onError(ex -> cleanup.run());
        return emitter;
    }
}

// Behind nginx, stop it from buffering the event stream:
//   proxy_buffering off;        (or send the header  X-Accel-Buffering: no)