Spring Boot — Controllers (mappings, validation, organisation)

@RestController
@RequestMapping("/api/stocks")
class StockController {

    @GetMapping("/{id}")
    StockDto get(@PathVariable Long id) { ... }

    @PostMapping
    StockDto create(@Valid @RequestBody CreateStockRequest req) { ... }

    @PutMapping("/{id}")
    StockDto update(@PathVariable Long id,
                    @Valid @RequestBody UpdateStockRequest req) { ... }

    @DeleteMapping("/{id}")
    void delete(@PathVariable Long id) { ... }
}

// @PathVariable — segment d'URL
// GET /stocks/42
@GetMapping("/{id}")
StockDto get(@PathVariable Long id) { ... }

// @RequestParam — query string
// GET /stocks?status=FREE&zone=A1
@GetMapping
List<StockDto> search(
    @RequestParam String status,
    @RequestParam(required = false) String zone
) { ... }

// @RequestBody — payload JSON
// POST /stocks  { "productId": "P1", "quantity": 10 }
@PostMapping
StockDto create(@Valid @RequestBody CreateStockRequest req) { ... }

// @RequestHeader — header HTTP
@GetMapping
StockDto getWithCorrelation(
    @RequestHeader("X-Correlation-Id") String cid
) { ... }

// Combinaison libre
@PostMapping("/{id}/move")
void move(
    @PathVariable Long id,
    @RequestParam String target,
    @Valid @RequestBody MoveRequest body
) { ... }

// ✓ Records Java — immutables, compacts, intention claire
public record CreateStockRequest(
    @NotBlank String productId,
    @Positive BigDecimal quantity
) {}

public record StockDto(
    Long id,
    String productId,
    BigDecimal quantity,
    String status
) {}

public record CreateStockRequest(
    @NotBlank                          // non null, non vide, non whitespace
    String productId,

    @Positive                          // > 0
    BigDecimal quantity,

    @Size(min = 2, max = 50)
    String label,

    @Email
    String contactEmail
) {}

// ✓ @Valid OBLIGATOIRE — sans ça, toutes les annotations ci-dessus sont ignorées
@PostMapping
StockDto create(@Valid @RequestBody CreateStockRequest req) { ... }

@RestControllerAdvice
class ApiErrors {

    // Validation Jakarta
    @ExceptionHandler(MethodArgumentNotValidException.class)
    ResponseEntity<?> handleValidation(MethodArgumentNotValidException ex) {
        var errors = ex.getBindingResult()
            .getFieldErrors()
            .stream()
            .map(e -> e.getField() + ": " + e.getDefaultMessage())
            .toList();
        return ResponseEntity.badRequest().body(Map.of("errors", errors));
    }

    // Business exception
    @ExceptionHandler(StockNotFoundException.class)
    ResponseEntity<?> handleNotFound(StockNotFoundException ex) {
        return ResponseEntity
            .status(HttpStatus.NOT_FOUND)
            .body(Map.of("error", ex.getMessage()));
    }

    // Catch-all
    @ExceptionHandler(Exception.class)
    ResponseEntity<?> handleGeneric(Exception ex) {
        log.error("Unhandled exception", ex);
        return ResponseEntity.internalServerError()
            .body(Map.of("error", "Internal server error"));
    }
}

<!-- pom.xml -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.x</version>
</dependency>

@Operation(summary = "Get stock by ID")
@GetMapping("/{id}")
StockDto get(
    @Parameter(description = "Stock ID") @PathVariable Long id
) { ... }

public record StockDto(
    Long id,
    @Schema(description = "Product identifier") String productId,
    @Schema(description = "Available quantity") BigDecimal quantity
) {}

StockController   // tout ce qui concerne /stocks
OrderController   // tout ce qui concerne /orders

StockQueryController    // GET /stocks/**
StockCommandController  // POST/PUT/DELETE /stocks/**