Spring Boot REST API: Complete Production Guide (2026)

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
             https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.3.2</version>
  </parent>

  <groupId>io.thecodeforge</groupId>
  <artifactId>user-service</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <name>user-service</name>

  <properties>
    <java.version>21</java.version>
    <mapstruct.version>1.5.5.Final</mapstruct.version>
  </properties>

  <dependencies>
    <!-- Core web stack: Spring MVC + embedded Tomcat + Jackson -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- JPA / Hibernate -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>

    <!-- Jakarta Bean Validation (@NotBlank, @Email, @Size...) -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>

    <!-- Security (JWT-based auth) -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-security</artifactId>
    </dependency>

    <!-- Actuator: /health, /metrics, /info endpoints -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>

    <!-- Springdoc: auto-generated Swagger UI -->
    <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>2.5.0</version>
    </dependency>

    <!-- H2 in-memory DB for development -->
    <dependency>
      <groupId>com.h2database</groupId>
      <artifactId>h2</artifactId>
      <scope>runtime</scope>
    </dependency>

    <!-- PostgreSQL for production -->
    <dependency>
      <groupId>org.postgresql</groupId>
      <artifactId>postgresql</artifactId>
      <scope>runtime</scope>
    </dependency>

    <!-- Lombok: removes boilerplate -->
    <dependency>
      <groupId>org.projectlombok</groupId>
      <artifactId>lombok</artifactId>
      <optional>true</optional>
    </dependency>

    <!-- MapStruct: compile-time DTO mapper -->
    <dependency>
      <groupId>org.mapstruct</groupId>
      <artifactId>mapstruct</artifactId>
      <version>${mapstruct.version}</version>
    </dependency>

    <!-- Testing -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-test</artifactId>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.springframework.security</groupId>
      <artifactId>spring-security-test</artifactId>
      <scope>test</scope>
    </dependency>
    <!-- Testcontainers for real PostgreSQL in tests -->
    <dependency>
      <groupId>org.testcontainers</groupId>
      <artifactId>postgresql</artifactId>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.testcontainers</groupId>
      <artifactId>junit-jupiter</artifactId>
      <scope>test</scope>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
        <configuration>
          <!-- Exclude Lombok from the final JAR -->
          <excludes>
            <exclude>
              <groupId>org.projectlombok</groupId>
              <artifactId>lombok</artifactId>
            </exclude>
          </excludes>
        </configuration>
      </plugin>
      <!-- MapStruct annotation processor: Lombok MUST come before MapStruct -->
      <!-- Wrong order = MapStruct cannot see Lombok-generated getters/setters -->
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
          <annotationProcessorPaths>
            <path>
              <groupId>org.projectlombok</groupId>
              <artifactId>lombok</artifactId>
            </path>
            <path>
              <groupId>org.mapstruct</groupId>
              <artifactId>mapstruct-processor</artifactId>
              <version>${mapstruct.version}</version>
            </path>
          </annotationProcessorPaths>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

package io.thecodeforge.userservice.model;

import jakarta.persistence.*;
import lombok.Getter;
import lombok.Setter;
import lombok.NoArgsConstructor;
import org.springframework.data.annotation.CreatedDate;
import org.springframework.data.annotation.LastModifiedDate;
import org.springframework.data.jpa.domain.support.AuditingEntityListener;
import java.time.Instant;

@Entity
@Table(
    name = "users",
    uniqueConstraints = @UniqueConstraint(columnNames = "email")
)
@EntityListeners(AuditingEntityListener.class) // enables @CreatedDate / @LastModifiedDate
@Getter @Setter @NoArgsConstructor
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    // IDENTITY = database auto_increment / SERIAL
    // Never use AUTO in production — behaviour differs across databases
    private Long id;

    @Column(name = "full_name", nullable = false, length = 100)
    private String name;

    @Column(nullable = false, unique = true, length = 255)
    private String email;

    @Column(nullable = false)
    private Integer age;

    @Enumerated(EnumType.STRING)  // store 'ACTIVE' not '0' — readable, refactor-safe
    @Column(nullable = false, length = 20)
    private UserStatus status = UserStatus.ACTIVE;

    @CreatedDate
    @Column(nullable = false, updatable = false)
    private Instant createdAt;

    @LastModifiedDate
    @Column(nullable = false)
    private Instant updatedAt;

    public enum UserStatus {
        ACTIVE, INACTIVE, SUSPENDED
    }
}

# ── application.properties (shared defaults) ─────────────────────────────────
spring.application.name=user-service

# Virtual threads — enables Project Loom for I/O-heavy REST APIs on Java 21+
# Eliminates manual thread pool tuning for blocking JDBC workloads
spring.threads.virtual.enabled=true

# Actuator: expose health and info by default; production overrides this
management.endpoints.web.exposure.include=health,info
management.endpoint.health.show-details=when_authorized

# ── application-dev.properties (development) ──────────────────────────────────
# H2 in-memory: zero setup, resets on restart — fine for dev, dangerous to mistake for prod
spring.datasource.url=jdbc:h2:mem:userdb;DB_CLOSE_DELAY=-1
spring.datasource.driver-class-name=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=

# H2 console at /h2-console for inspecting the in-memory database
spring.h2.console.enabled=true

# Hibernate creates schema on startup, drops on shutdown — fine for dev, catastrophic in prod
spring.jpa.hibernate.ddl-auto=create-drop

# Show generated SQL — essential for catching N+1 queries during development
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true

logging.level.io.thecodeforge=DEBUG

# More actuator exposure during development
management.endpoints.web.exposure.include=*
management.endpoint.health.show-details=always

# ── application-prod.properties (production) ──────────────────────────────────
# Read connection details from environment variables — never hardcode secrets in files
spring.datasource.url=${DB_URL}
spring.datasource.username=${DB_USERNAME}
spring.datasource.password=${DB_PASSWORD}
spring.datasource.driver-class-name=org.postgresql.Driver

# Connection pool tuning — HikariCP defaults are sensible; adjust based on your DB's max_connections
spring.datasource.hikari.maximum-pool-size=20
spring.datasource.hikari.minimum-idle=5
spring.datasource.hikari.connection-timeout=30000

# validate: Hibernate checks schema matches entity model but makes NO changes
# Schema changes are Flyway's job — not Hibernate's
spring.jpa.hibernate.ddl-auto=validate

# No SQL logging in production — it fills logs and exposes query structure
spring.jpa.show-sql=false

logging.level.root=WARN
logging.level.io.thecodeforge=INFO

# Actuator: expose only what's needed, on a separate internal port
management.endpoints.web.exposure.include=health,info,metrics
management.server.port=8081

// ── UserDto.java — the response body for all User endpoints ──────────────────
package io.thecodeforge.userservice.dto;

import com.fasterxml.jackson.annotation.JsonFormat;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import java.time.Instant;

@Data
@NoArgsConstructor
@AllArgsConstructor
@Schema(description = "User response body")
public class UserDto {

    @Schema(description = "User ID", example = "42")
    private Long id;

    @Schema(description = "Full name", example = "Alice Chen")
    private String name;

    @Schema(description = "Email address", example = "alice@thecodeforge.io")
    private String email;

    private Integer age;

    @Schema(description = "Account status", example = "ACTIVE",
            allowableValues = {"ACTIVE", "INACTIVE", "SUSPENDED"})
    private String status;

    @JsonFormat(shape = JsonFormat.Shape.STRING)
    private Instant createdAt;

    @JsonFormat(shape = JsonFormat.Shape.STRING)
    private Instant updatedAt;
}

// ── CreateUserRequest.java ─────────────────────────────────────────────────────
package io.thecodeforge.userservice.dto;

import jakarta.validation.constraints.*;
import lombok.Data;

@Data
public class CreateUserRequest {

    @NotBlank(message = "Name is required")
    @Size(min = 2, max = 100, message = "Name must be between 2 and 100 characters")
    private String name;

    @NotBlank(message = "Email is required")
    @Email(message = "Must be a valid email address")
    private String email;

    @NotNull(message = "Age is required")
    @Min(value = 18, message = "User must be at least 18")
    @Max(value = 120, message = "Age is not realistic")
    private Integer age;
}

// ── UpdateUserRequest.java ─────────────────────────────────────────────────────
package io.thecodeforge.userservice.dto;

import jakarta.validation.constraints.*;
import lombok.Data;

@Data
public class UpdateUserRequest {

    @Size(min = 2, max = 100)
    private String name;   // null = not updating this field

    @Min(18) @Max(120)
    private Integer age;   // null = not updating this field

    // Email intentionally excluded — treat email changes as a separate
    // verified flow, not a plain field update
}

// ── PagedResponse.java ─────────────────────────────────────────────────────────
// Wraps Spring's Page<T> into a clean JSON response.
// Spring's raw Page serialisation includes internal implementation fields
// that clients should not depend on. This wrapper exposes only what matters.
package io.thecodeforge.userservice.dto;

import org.springframework.data.domain.Page;
import java.util.List;

public record PagedResponse<T>(
    List<T> content,
    int page,
    int size,
    long totalElements,
    int totalPages,
    boolean last
) {
    public static <T> PagedResponse<T> from(Page<T> page) {
        return new PagedResponse<>(
            page.getContent(),
            page.getNumber(),
            page.getSize(),
            page.getTotalElements(),
            page.getTotalPages(),
            page.isLast()
        );
    }
}

package io.thecodeforge.userservice.controller;

import io.thecodeforge.userservice.dto.CreateUserRequest;
import io.thecodeforge.userservice.dto.UpdateUserRequest;
import io.thecodeforge.userservice.dto.UserDto;
import io.thecodeforge.userservice.service.UserService;
import jakarta.validation.Valid;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.*;

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

    private final UserService userService;

    // Constructor injection — explicit, immutable, testable
    // No @Autowired needed: Spring injects the single constructor automatically
    public UserController(UserService userService) {
        this.userService = userService;
    }

    // GET /api/v1/users?page=0&size=20&sortBy=createdAt&sortDir=desc
    @GetMapping
    public PagedResponse<UserDto> getAllUsers(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") int size,
            @RequestParam(defaultValue = "createdAt") String sortBy,
            @RequestParam(defaultValue = "desc") String sortDir) {
        return userService.findAll(page, size, sortBy, sortDir);
    }

    // GET /api/v1/users/42
    @GetMapping("/{id}")
    public UserDto getUserById(@PathVariable Long id) {
        return userService.findById(id);
    }

    // POST /api/v1/users -> 201 Created
    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public UserDto createUser(@RequestBody @Valid CreateUserRequest request) {
        return userService.create(request);
    }

    // PUT /api/v1/users/42 — full replacement
    @PutMapping("/{id}")
    public UserDto updateUser(@PathVariable Long id,
                              @RequestBody @Valid UpdateUserRequest request) {
        return userService.update(id, request);
    }

    // DELETE /api/v1/users/42 -> 204 No Content
    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void deleteUser(@PathVariable Long id) {
        userService.delete(id);
    }
}

// CreateUserRequest.java is defined in the DTOs section above.
// The @Valid annotation on @RequestBody triggers these constraints.

// ── GlobalExceptionHandler.java (validation portion) ──────────────────────────
@RestControllerAdvice
public class GlobalExceptionHandler {

    // Returns ALL field errors at once — not just the first
    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public Map<String, String> handleValidationErrors(
            MethodArgumentNotValidException ex) {
        Map<String, String> errors = new LinkedHashMap<>();
        ex.getBindingResult().getFieldErrors().forEach(
            err -> errors.put(err.getField(), err.getDefaultMessage())
        );
        return errors;
    }
}

package io.thecodeforge.userservice.exception;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.*;
import java.time.Instant;
import java.util.LinkedHashMap;
import java.util.Map;

// Typed exceptions — define these in the exception package
public class ResourceNotFoundException extends RuntimeException {
    public ResourceNotFoundException(String resource, Long id) {
        super(resource + " with id " + id + " not found");
    }
}

public class BusinessRuleException extends RuntimeException {
    public BusinessRuleException(String message) {
        super(message);
    }
}

// Standardised error body — used for every error response
public record ApiError(int status, String message, Instant timestamp) {}

// ── GlobalExceptionHandler.java ───────────────────────────────────────────────
@RestControllerAdvice
public class GlobalExceptionHandler {

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

    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public Map<String, String> handleValidationErrors(MethodArgumentNotValidException ex) {
        Map<String, String> errors = new LinkedHashMap<>();
        ex.getBindingResult().getFieldErrors().forEach(
            err -> errors.put(err.getField(), err.getDefaultMessage())
        );
        return errors;
    }

    @ExceptionHandler(ResourceNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ApiError handleNotFound(ResourceNotFoundException ex) {
        return new ApiError(404, ex.getMessage(), Instant.now());
    }

    @ExceptionHandler(BusinessRuleException.class)
    @ResponseStatus(HttpStatus.UNPROCESSABLE_ENTITY)
    public ApiError handleBusinessRule(BusinessRuleException ex) {
        return new ApiError(422, ex.getMessage(), Instant.now());
    }

    // Catch-all: log the real cause server-side; return a safe message to the client
    // Never expose stack traces, class names, or internal paths to the client
    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public ApiError handleGeneric(Exception ex) {
        log.error("Unhandled exception", ex);
        return new ApiError(500, "An unexpected error occurred", Instant.now());
    }
}

// POST returning 201 + Location header (correct REST practice)
@PostMapping
public ResponseEntity<UserDto> createUser(@RequestBody @Valid CreateUserRequest req) {
    UserDto created = userService.create(req);
    URI location = ServletUriComponentsBuilder
            .fromCurrentRequest()
            .path("/{id}")
            .buildAndExpand(created.getId())
            .toUri();
    return ResponseEntity.created(location).body(created);
}

// GET with conditional 200/404 — Optional.map makes this clean
@GetMapping("/{id}")
public ResponseEntity<UserDto> getUser(@PathVariable Long id) {
    return userService.findOptional(id)
            .map(ResponseEntity::ok)
            .orElse(ResponseEntity.notFound().build());
}

// File download — Content-Disposition and content type set explicitly
@GetMapping("/export")
public ResponseEntity<byte[]> exportCsv() {
    byte[] csv = reportService.generateCsv();
    return ResponseEntity.ok()
            .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=users.csv")
            .contentType(MediaType.parseMediaType("text/csv"))
            .body(csv);
}

package io.thecodeforge.userservice.service;

import io.thecodeforge.userservice.dto.*;
import io.thecodeforge.userservice.exception.BusinessRuleException;
import io.thecodeforge.userservice.exception.ResourceNotFoundException;
import io.thecodeforge.userservice.mapper.UserMapper;
import io.thecodeforge.userservice.repository.UserRepository;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.PageRequest;
import org.springframework.data.domain.Sort;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
@Transactional(readOnly = true) // default: read-only; write methods override below
public class UserService {

    private final UserRepository repo;
    private final UserMapper mapper;

    public UserService(UserRepository repo, UserMapper mapper) {
        this.repo = repo;
        this.mapper = mapper;
    }

    public UserDto findById(Long id) {
        return repo.findById(id)
                .map(mapper::toDto)
                .orElseThrow(() -> new ResourceNotFoundException("User", id));
    }

    public java.util.Optional<UserDto> findOptional(Long id) {
        return repo.findById(id).map(mapper::toDto);
    }

    public PagedResponse<UserDto> findAll(int page, int size, String sortBy, String sortDir) {
        int cappedSize = Math.min(size, 100);
        Sort sort = sortDir.equalsIgnoreCase("asc")
                ? Sort.by(sortBy).ascending()
                : Sort.by(sortBy).descending();
        Page<UserDto> result = repo.findAll(PageRequest.of(page, cappedSize, sort))
                .map(mapper::toDto);
        return PagedResponse.from(result);
    }

    @Transactional // overrides class-level readOnly — this method writes
    public UserDto create(CreateUserRequest req) {
        if (repo.existsByEmail(req.getEmail())) {
            throw new BusinessRuleException("Email already registered");
        }
        return mapper.toDto(repo.save(mapper.toEntity(req)));
    }

    @Transactional
    public UserDto update(Long id, UpdateUserRequest req) {
        var user = repo.findById(id)
                .orElseThrow(() -> new ResourceNotFoundException("User", id));
        mapper.updateEntityFromRequest(req, user);
        return mapper.toDto(repo.save(user));
    }

    @Transactional
    public void delete(Long id) {
        if (!repo.existsById(id)) {
            throw new ResourceNotFoundException("User", id);
        }
        repo.deleteById(id);
    }
}

// ── UserRepository.java ───────────────────────────────────────────────────────
package io.thecodeforge.userservice.repository;

import io.thecodeforge.userservice.model.User;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;
import java.util.List;

public interface UserRepository extends JpaRepository<User, Long> {

    boolean existsByEmail(String email);

    // Derived query — Spring Data generates the SQL from the method name
    boolean existsById(Long id);

    // JPQL for anything the method name syntax can't express cleanly
    @Query("SELECT u FROM User u WHERE u.status = :status ORDER BY u.createdAt DESC")
    List<User> findByStatus(@Param("status") User.UserStatus status);
}

package io.thecodeforge.userservice.mapper;

import io.thecodeforge.userservice.dto.CreateUserRequest;
import io.thecodeforge.userservice.dto.UpdateUserRequest;
import io.thecodeforge.userservice.dto.UserDto;
import io.thecodeforge.userservice.model.User;
import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
import org.mapstruct.MappingTarget;
import org.mapstruct.NullValuePropertyMappingStrategy;

// componentModel = "spring" → MapStruct generates a @Component;
// Spring injects it wherever you @Autowire UserMapper
@Mapper(
    componentModel = "spring",
    // For partial updates: skip null fields — don't overwrite with null
    nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE
)
public interface UserMapper {

    // Entity → DTO
    // User.UserStatus enum → String: MapStruct calls .name() automatically
    // Instant fields: serialisation handled by @JsonFormat on the DTO
    UserDto toDto(User user);

    // CreateUserRequest → Entity
    @Mapping(target = "id",        ignore = true) // DB generates this
    @Mapping(target = "createdAt", ignore = true) // @CreatedDate generates this
    @Mapping(target = "updatedAt", ignore = true) // @LastModifiedDate generates this
    @Mapping(target = "status",    constant = "ACTIVE") // new users always start ACTIVE
    User toEntity(CreateUserRequest request);

    // Partial update: apply non-null fields from request onto the existing entity in-place
    // @MappingTarget tells MapStruct to mutate the existing object, not create a new one
    // NullValuePropertyMappingStrategy.IGNORE (class-level) skips null source fields
    @Mapping(target = "id",        ignore = true)
    @Mapping(target = "email",     ignore = true) // email changes require a separate verified flow
    @Mapping(target = "status",    ignore = true) // status changes require explicit business logic
    @Mapping(target = "createdAt", ignore = true)
    @Mapping(target = "updatedAt", ignore = true)
    void updateEntityFromRequest(UpdateUserRequest request, @MappingTarget User user);
}

package io.thecodeforge.userservice.controller;

import io.thecodeforge.userservice.dto.PagedResponse;
import io.thecodeforge.userservice.dto.UserDto;
import io.thecodeforge.userservice.service.UserService;
import org.springframework.web.bind.annotation.*;

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

    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    // GET /api/v1/users?page=0&size=20&sortBy=createdAt&sortDir=desc
    @GetMapping
    public PagedResponse<UserDto> getUsers(
            @RequestParam(defaultValue = "0")         int page,
            @RequestParam(defaultValue = "20")        int size,
            @RequestParam(defaultValue = "createdAt") String sortBy,
            @RequestParam(defaultValue = "desc")      String sortDir) {

        // Service handles the cap — Math.min(size, 100)
        // Never trust the client's requested size
        return userService.findAll(page, size, sortBy, sortDir);
    }
}

package io.thecodeforge.userservice.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import io.thecodeforge.userservice.dto.CreateUserRequest;
import io.thecodeforge.userservice.dto.UserDto;
import jakarta.validation.Valid;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/v1/users")
@Tag(name = "Users", description = "User management operations")
public class UserController {

    @Operation(
        summary = "Get user by ID",
        description = "Returns a single user. Returns 404 if the user does not exist.",
        responses = {
            @ApiResponse(responseCode = "200", description = "User found",
                content = @Content(schema = @Schema(implementation = UserDto.class))),
            @ApiResponse(responseCode = "404", description = "User not found")
        }
    )
    @GetMapping("/{id}")
    public ResponseEntity<UserDto> getUserById(
            @Parameter(description = "User ID", example = "42")
            @PathVariable Long id) {
        return ResponseEntity.ok(userService.findById(id));
    }

    @Operation(
        summary = "Create a new user",
        description = "Creates a user. Returns 409 Conflict if the email already exists."
    )
    @PostMapping
    public ResponseEntity<UserDto> createUser(
            @RequestBody @Valid CreateUserRequest request) {
        UserDto created = userService.create(request);
        URI location = ServletUriComponentsBuilder
                .fromCurrentRequest()
                .path("/{id}")
                .buildAndExpand(created.getId())
                .toUri();
        return ResponseEntity.created(location).body(created);
    }
}

// ── OpenApiConfig.java — API-level metadata ───────────────────────────────────
package io.thecodeforge.userservice.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI userServiceOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("User Service API")
                        .description("REST API for user management")
                        .version("v1.0")
                        .contact(new Contact()
                                .name("TheCodeForge")
                                .url("https://thecodeforge.io")));
    }
}

package io.thecodeforge.userservice.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;

@Configuration
@EnableWebSecurity
@EnableMethodSecurity // enables @PreAuthorize on service/controller methods
public class SecurityConfig {

    private final JwtAuthenticationFilter jwtFilter;

    public SecurityConfig(JwtAuthenticationFilter jwtFilter) {
        this.jwtFilter = jwtFilter;
    }

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            // STATELESS: no HttpSession created or used — required for JWT
            .sessionManagement(sm ->
                sm.sessionCreationPolicy(SessionCreationPolicy.STATELESS))

            // CSRF: disable for stateless JWT APIs
            // CSRF protection is for browser cookie auth.
            // When the client sends a Bearer token in the Authorization header,
            // CSRF attacks are not possible — the browser does not auto-send that header.
            .csrf(csrf -> csrf.disable())

            // CORS: configured via CorsConfig WebMvcConfigurer
            .cors(cors -> cors.configure(http))

            .authorizeHttpRequests(auth -> auth
                // Public endpoints: docs, health check, and auth
                .requestMatchers("/swagger-ui/**", "/api-docs/**").permitAll()
                .requestMatchers("/actuator/health").permitAll()
                .requestMatchers(HttpMethod.POST, "/api/v1/auth/**").permitAll()
                // Everything else requires a valid JWT
                .anyRequest().authenticated()
            )

            // JWT filter runs before Spring's username/password filter
            .addFilterBefore(jwtFilter, UsernamePasswordAuthenticationFilter.class);

        return http.build();
    }
}

// ── JwtAuthenticationFilter.java (skeleton) ────────────────────────────────────
// Full JWT implementation (token generation, validation, refresh rotation)
// is covered in the dedicated JWT guide. This skeleton shows where it plugs in.
package io.thecodeforge.userservice.config;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;
import java.io.IOException;

@Component
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain chain)
            throws ServletException, IOException {

        String authHeader = request.getHeader("Authorization");

        // If no Bearer token is present, continue — the authorization rules
        // in SecurityConfig will reject the request if authentication is required
        if (authHeader == null || !authHeader.startsWith("Bearer ")) {
            chain.doFilter(request, response);
            return;
        }

        String token = authHeader.substring(7);
        // TODO: validate token signature, check expiry, extract claims,
        // build UsernamePasswordAuthenticationToken, set in SecurityContextHolder
        // See: thecodeforge.io/spring-boot-jwt for the full implementation

        chain.doFilter(request, response);
    }
}

package io.thecodeforge.userservice.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class CorsConfig implements WebMvcConfigurer {

    // Drive allowed origins from config — not hardcoded in source
    // application-dev.properties:  cors.allowed-origins=http://localhost:3000
    // application-prod.properties: cors.allowed-origins=https://app.thecodeforge.io
    @Value("${cors.allowed-origins}")
    private String[] allowedOrigins;

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")
                .allowedOrigins(allowedOrigins)
                .allowedMethods("GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS")
                .allowedHeaders("Authorization", "Content-Type", "Accept")
                .exposedHeaders("Location") // clients need Location header from POST 201
                .allowCredentials(true)     // required if frontend sends cookies alongside JWT
                .maxAge(3600);              // cache preflight response for 1 hour
    }
}

# ── application-prod.properties: Actuator exposure ───────────────────────────
# Expose only what orchestrators need — health and metrics
management.endpoints.web.exposure.include=health,info,metrics

# show-details=when_authorized: full health detail visible only to authenticated admin
# show-details=always: exposes DB status, disk space, connection pool to anyone — don't do this
management.endpoint.health.show-details=when_authorized

# Separate actuator port — not routed through the public load balancer
management.server.port=8081

# ── CustomHealthIndicator.java ────────────────────────────────────────────────
package io.thecodeforge.userservice.health;

import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;

// Example: check a downstream dependency your API relies on
// Spring Boot auto-registers this and includes it in /actuator/health
@Component
public class DownstreamServiceHealthIndicator implements HealthIndicator {

    private final DownstreamServiceClient client;

    public DownstreamServiceHealthIndicator(DownstreamServiceClient client) {
        this.client = client;
    }

    @Override
    public Health health() {
        try {
            client.ping(); // throws if service is unreachable
            return Health.up()
                    .withDetail("service", "downstream-api")
                    .withDetail("status", "reachable")
                    .build();
        } catch (Exception e) {
            return Health.down()
                    .withDetail("service", "downstream-api")
                    .withDetail("error", e.getMessage())
                    .build();
        }
    }
}

package io.thecodeforge.userservice.controller;

import io.thecodeforge.userservice.dto.CreateUserRequest;
import io.thecodeforge.userservice.dto.UserDto;
import io.thecodeforge.userservice.exception.ResourceNotFoundException;
import io.thecodeforge.userservice.service.UserService;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import org.springframework.http.MediaType;
import org.springframework.security.test.context.support.WithMockUser;
import org.springframework.test.web.servlet.MockMvc;
import java.time.Instant;

import static org.mockito.Mockito.when;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
import static org.springframework.test.web.servlet.result.MockMvcResultHandlers.print;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

@WebMvcTest(UserController.class)
class UserControllerTest {

    @Autowired MockMvc mockMvc;
    @MockBean  UserService userService;
    @Autowired ObjectMapper objectMapper; // same instance Spring uses — consistent serialisation

    @Test
    @WithMockUser // satisfies Spring Security's authentication requirement in the web layer
    void getUser_found_returns200() throws Exception {
        UserDto dto = new UserDto(1L, "Alice", "alice@thecodeforge.io",
                                  28, "ACTIVE", Instant.now(), Instant.now());
        when(userService.findById(1L)).thenReturn(dto);

        mockMvc.perform(get("/api/v1/users/1"))
               .andDo(print()) // useful during development; remove in CI
               .andExpect(status().isOk())
               .andExpect(content().contentType(MediaType.APPLICATION_JSON))
               .andExpect(jsonPath("$.name").value("Alice"))
               .andExpect(jsonPath("$.email").value("alice@thecodeforge.io"));
    }

    @Test
    @WithMockUser
    void getUser_notFound_returns404() throws Exception {
        when(userService.findById(99L))
                .thenThrow(new ResourceNotFoundException("User", 99L));

        mockMvc.perform(get("/api/v1/users/99"))
               .andExpect(status().isNotFound())
               .andExpect(jsonPath("$.message").value("User with id 99 not found"));
    }

    @Test
    @WithMockUser
    void createUser_invalidEmail_returns400() throws Exception {
        CreateUserRequest req = new CreateUserRequest();
        req.setName("Bob");
        req.setEmail("not-an-email"); // will fail @Email
        req.setAge(25);

        mockMvc.perform(post("/api/v1/users")
                       .contentType(MediaType.APPLICATION_JSON)
                       .content(objectMapper.writeValueAsString(req)))
               .andExpect(status().isBadRequest())
               .andExpect(jsonPath("$.email").value("Must be a valid email address"));
    }

    @Test
    @WithMockUser
    void createUser_underageUser_returns400() throws Exception {
        CreateUserRequest req = new CreateUserRequest();
        req.setName("Charlie");
        req.setEmail("charlie@thecodeforge.io");
        req.setAge(16); // will fail @Min(18)

        mockMvc.perform(post("/api/v1/users")
                       .contentType(MediaType.APPLICATION_JSON)
                       .content(objectMapper.writeValueAsString(req)))
               .andExpect(status().isBadRequest())
               .andExpect(jsonPath("$.age").value("User must be at least 18"));
    }
}

package io.thecodeforge.userservice.integration;

import io.thecodeforge.userservice.dto.CreateUserRequest;
import io.thecodeforge.userservice.repository.UserRepository;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.MediaType;
import org.springframework.security.test.context.support.WithMockUser;
import org.springframework.test.context.DynamicPropertyRegistry;
import org.springframework.test.context.DynamicPropertySource;
import org.springframework.test.web.servlet.MockMvc;
import org.testcontainers.containers.PostgreSQLContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

import static org.assertj.core.api.Assertions.assertThat;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

@SpringBootTest              // full application context
@AutoConfigureMockMvc       // MockMvc wired against the real context
@Testcontainers             // Testcontainers lifecycle management
class UserControllerIntegrationTest {

    // Shared across all tests in this class — started once
    // Each test cleans up via @BeforeEach, not by restarting the container
    @Container
    static PostgreSQLContainer<?> postgres =
            new PostgreSQLContainer<>("postgres:16")
                    .withDatabaseName("userdb_test")
                    .withUsername("test")
                    .withPassword("test");

    // Wire the random-port container to Spring's datasource config
    @DynamicPropertySource
    static void configureProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url",      postgres::getJdbcUrl);
        registry.add("spring.datasource.username", postgres::getUsername);
        registry.add("spring.datasource.password", postgres::getPassword);
    }

    @Autowired MockMvc         mockMvc;
    @Autowired ObjectMapper    objectMapper;
    @Autowired UserRepository  userRepository;

    @BeforeEach
    void cleanDatabase() {
        userRepository.deleteAll();
    }

    @Test
    @WithMockUser
    void createUser_validRequest_returns201WithLocation() throws Exception {
        CreateUserRequest req = new CreateUserRequest();
        req.setName("Alice Chen");
        req.setEmail("alice@thecodeforge.io");
        req.setAge(28);

        mockMvc.perform(post("/api/v1/users")
                       .contentType(MediaType.APPLICATION_JSON)
                       .content(objectMapper.writeValueAsString(req)))
               .andExpect(status().isCreated())
               .andExpect(header().exists("Location"))
               .andExpect(jsonPath("$.id").isNumber())
               .andExpect(jsonPath("$.email").value("alice@thecodeforge.io"))
               .andExpect(jsonPath("$.status").value("ACTIVE"));

        // Verify the record actually persisted to PostgreSQL
        assertThat(userRepository.count()).isEqualTo(1);
    }

    @Test
    @WithMockUser
    void createUser_duplicateEmail_returns422() throws Exception {
        CreateUserRequest req = new CreateUserRequest();
        req.setName("Alice");
        req.setEmail("alice@thecodeforge.io");
        req.setAge(28);

        // First creation — must succeed
        mockMvc.perform(post("/api/v1/users")
                       .contentType(MediaType.APPLICATION_JSON)
                       .content(objectMapper.writeValueAsString(req)))
               .andExpect(status().isCreated());

        // Second creation with same email — BusinessRuleException → 422
        mockMvc.perform(post("/api/v1/users")
                       .contentType(MediaType.APPLICATION_JSON)
                       .content(objectMapper.writeValueAsString(req)))
               .andExpect(status().isUnprocessableEntity())
               .andExpect(jsonPath("$.message").value("Email already registered"));
    }

    @Test
    @WithMockUser
    void getUser_nonExistent_returns404() throws Exception {
        mockMvc.perform(get("/api/v1/users/9999"))
               .andExpect(status().isNotFound())
               .andExpect(jsonPath("$.message").value("User with id 9999 not found"));
    }
}