Controllers

@RestController
@RequestMapping("/api/users")
public class UserController {
    // all handler methods return body, no @ResponseBody needed
}

@RestController
@RequestMapping("/api/products")
@RequiredArgsConstructor   // Lombok — generates constructor injection
public class ProductController {

    private final ProductService productService;

    @GetMapping
    public List<ProductDto> getAll() {
        return productService.findAll();
    }

    @GetMapping("/{id}")
    public ResponseEntity<ProductDto> getById(@PathVariable Long id) {
        return ResponseEntity.ok(productService.findById(id));
    }

    @PostMapping
    public ResponseEntity<ProductDto> create(@Valid @RequestBody CreateProductRequest req) {
        ProductDto created = productService.create(req);
        URI location = ServletUriComponentsBuilder.fromCurrentRequest()
            .path("/{id}").buildAndExpand(created.id()).toUri();
        return ResponseEntity.created(location).body(created);
    }

    @PutMapping("/{id}")
    public ProductDto update(@PathVariable Long id,
                             @Valid @RequestBody UpdateProductRequest req) {
        return productService.update(id, req);
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> delete(@PathVariable Long id) {
        productService.delete(id);
        return ResponseEntity.noContent().build();
    }
}

// Optional with default
@GetMapping
public Page<Item> list(
    @RequestParam(defaultValue = "0") int page,
    @RequestParam(defaultValue = "20") int size,
    @RequestParam(required = false) String search
) { ... }

// Multi-value: ?tag=java&tag=spring
@GetMapping("/search")
public List<Post> byTags(@RequestParam List<String> tag) { ... }

// Name must match {variable} or use name attribute
@GetMapping("/users/{userId}/orders/{orderId}")
public Order get(@PathVariable Long userId, @PathVariable Long orderId) { ... }

// Optional path variable
@GetMapping({"/items", "/items/{id}"})
public Object getOrList(@PathVariable(required = false) Long id) { ... }

ResponseEntity.ok(body)                          // 200
ResponseEntity.created(uri).body(body)           // 201 + Location header
ResponseEntity.accepted().build()                // 202, no body
ResponseEntity.noContent().build()               // 204
ResponseEntity.badRequest().body(errorDto)       // 400
ResponseEntity.notFound().build()                // 404
ResponseEntity.status(HttpStatus.CONFLICT).body(msg) // 409

// Custom headers
return ResponseEntity.ok()
    .header("X-Custom", "value")
    .contentType(MediaType.APPLICATION_JSON)
    .body(data);

@Controller
@RequestMapping("/")
public class PageController {

    @GetMapping("login")
    public String loginPage() {
        return "login";  // resolves to templates/login.html
    }

    @GetMapping("dashboard")
    public String dashboard(Model model) {
        model.addAttribute("user", currentUser());
        return "dashboard";
    }

    @PostMapping("register")
    public String register(@Valid @ModelAttribute RegisterForm form,
                           BindingResult result,
                           RedirectAttributes attrs) {
        if (result.hasErrors()) return "register";
        userService.register(form);
        attrs.addFlashAttribute("message", "Account created!");
        return "redirect:/login";
    }
}

// Return CompletableFuture for servlet-thread offloading
@GetMapping("/report")
public CompletableFuture<Report> generateReport() {
    return CompletableFuture.supplyAsync(() -> reportService.build());
}

// Reactive (WebFlux only)
@GetMapping("/stream")
public Flux<Event> streamEvents() {
    return eventService.stream();
}

// Upload
@PostMapping("/upload")
public ResponseEntity<String> upload(@RequestParam MultipartFile file) throws IOException {
    String url = storageService.store(file.getOriginalFilename(), file.getInputStream());
    return ResponseEntity.ok(url);
}

// Download
@GetMapping("/files/{name}")
public ResponseEntity<Resource> download(@PathVariable String name) throws IOException {
    Resource resource = storageService.load(name);
    return ResponseEntity.ok()
        .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"" + resource.getFilename() + "\"")
        .contentType(MediaType.APPLICATION_OCTET_STREAM)
        .body(resource);
}