🍃
Spring Boot 치트시트

Spring Boot 3.x 핵심 어노테이션, Gradle & Maven 빌드 설정, RESTful API 설계, 의존성 주입(DI), application.yml 설정, JPA 트랜잭션, 전역 예외 처리 및 실무 최적화 레퍼런스
#springboot#spring#java#gradle#maven#rest-api#backend#web#spring-security#jpa최종 업데이트: 2026-09-27
Spring Boot 치트시트 핵심 명령어 및 실전 가이드

## 1. 프로젝트 시작 & 구조 (Project Setup & Architecture)
```text
my-spring-app/
├── src/
│   ├── main/
│   │   ├── java/com/example/demo/
│   │   │   ├── DemoApplication.java      → @SpringBootApplication 진입점
│   │   │   ├── controller/               → HTTP 요청 수신 & 응답 반환
│   │   │   ├── service/                  → 비즈니스 로직 & 트랜잭션 관리
│   │   │   ├── repository/               → DB 접근 (Spring Data JPA)
│   │   │   ├── domain/ (또는 entity/)     → JPA 엔티티 객체
│   │   │   ├── dto/                      → 계층 간 데이터 전달 객체 (Request/Response)
│   │   │   ├── config/                   → 보안, 웹, 비동기 등 빈 설정 클래스
│   │   │   └── exception/                → 커스텀 예외 & @RestControllerAdvice
│   │   └── resources/
│   │       ├── application.yml           → 전역 환경 설정 파일
│   │       ├── application-local.yml     → 로컬 개발용 프로파일
│   │       └── static/ & templates/      → 정적 자원 (HTML/CSS)
│   └── test/java/com/example/demo/       → 단위/통합 테스트 코드
├── build.gradle (또는 pom.xml)            → 빌드 스크립트 및 의존성 라이브러리
└── gradlew / gradlew.bat (또는 mvnw)      → OS별 빌드 래퍼 스크립트
```
```java
// DemoApplication.java - 스프링 부트 애플리케이션 시작 지점
package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

// @SpringBootApplication = @SpringBootConfiguration + @EnableAutoConfiguration + @ComponentScan
@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}
```

## 2. Gradle 빌드 설정 (build.gradle - Groovy & Kotlin)
```groovy
// build.gradle (Groovy DSL) - Spring Boot 3.x 표준 실무 템플릿
plugins {
    id 'java'
    id 'org.springframework.boot' version '3.2.5'
    id 'io.spring.dependency-management' version '1.1.4'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17) // 또는 21
    }
}

configurations {
    compileOnly {
        extendsFrom annotationProcessor
    }
}

repositories {
    mavenCentral()
}

dependencies {
    // 1. 핵심 스타터 의존성
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-validation'
    implementation 'org.springframework.boot:spring-boot-starter-actuator'

    // 2. 개발 편의 & 핫 리로드
    developmentOnly 'org.springframework.boot:spring-boot-devtools'

    // 3. 롬복 (Lombok)
    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'
    testCompileOnly 'org.projectlombok:lombok'
    testAnnotationProcessor 'org.projectlombok:lombok'

    // 4. 데이터베이스 드라이버
    runtimeOnly 'com.mysql:mysql-connector-j'
    runtimeOnly 'com.h2database:h2' // 로컬/테스트 인메모리용

    // 5. 테스트 의존성 (JUnit 5, AssertJ, Mockito 내장)
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}

tasks.named('test') {
    useJUnitPlatform()
}

// 실무 배포 최적화: 실행 가능한 단일 fat-jar 생성 (plain jar 생성 방지)
bootJar {
    archiveFileName = 'app.jar'
}
jar {
    enabled = false // plain jar 비활성화
}
```
```bash
# 자주 사용하는 Gradle 빌드 명령어
./gradlew build                # 컴파일, 테스트 및 jar 빌드
./gradlew bootRun              # 로컬에서 스프링 부트 앱 즉시 실행
./gradlew clean build -x test  # 테스트를 건너뛰고 빠른 빌드
./gradlew dependencies         # 프로젝트 의존성 트리 확인
```

## 3. Maven 빌드 설정 (pom.xml)
```xml
<?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>

    <!-- [1] 스프링 부트 스타터 부모 POM 상속 (버전 관리 및 기본 플러그인 상속) -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.5</version>
        <relativePath/> <!-- 부모 POM을 저장소에서 조회 -->
    </parent>

    <groupId>com.example</groupId>
    <artifactId>demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>demo</name>
    <description>Spring Boot Project</description>

    <!-- [2] Java 버전 및 인코딩 속성 정의 -->
    <properties>
        <java.version>17</java.version>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <!-- [3] 의존성 목록 (부모 POM으로 인해 <version> 태그 생략 가능) -->
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>

        <!-- Lombok & 개발 툴 -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <scope>runtime</scope>
            <optional>true</optional>
        </dependency>

        <!-- DB 드라이버 -->
        <dependency>
            <groupId>com.mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
            <scope>runtime</scope>
        </dependency>

        <!-- 테스트 의존성 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <!-- [4] 빌드 및 플러그인 설정 -->
    <build>
        <plugins>
            <!-- 실행 가능한 Fat-JAR 패키징 플러그인 -->
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>
```
```bash
# 자주 사용하는 Maven 빌드 명령어
./mvnw clean package           # 컴파일, 테스트 및 jar 패키징
./mvnw spring-boot:run         # 스프링 부트 앱 로컬 실행
./mvnw clean package -DskipTests # 테스트를 제외하고 빠른 빌드
./mvnw dependency:tree         # 의존성 계층 구조 확인
```

## 4. 핵심 Starter 의존성 퀵 레퍼런스 (Starters Cheatsheet)
```groovy
// 목적별 필수 스타터 아티팩트 정리 (Gradle: implementation '...', Maven: <artifactId>...)

// 🌐 웹 & API
'org.springframework.boot:spring-boot-starter-web'        // Spring MVC, REST, 내장 톰캣(Tomcat)
'org.springframework.boot:spring-boot-starter-webflux'    // 논블로킹 리액티브 웹 (Netty 기반)

// 🗄️ 데이터 & ORM
'org.springframework.boot:spring-boot-starter-data-jpa'   // Spring Data JPA + Hibernate Core
'org.springframework.boot:spring-boot-starter-data-redis' // Redis 캐시, 세션, Lettuce 클라이언트
'org.mybatis.spring.boot:mybatis-spring-boot-starter:3.0.3' // MyBatis SQL 매퍼 연동

// 🔒 보안 & 검증
'org.springframework.boot:spring-boot-starter-security'   // 스프링 시큐리티 인증 & 인가
'org.springframework.boot:spring-boot-starter-validation' // Hibernate Validator (@Valid, @NotNull)

// 📨 메시징 & 배치
'org.springframework.boot:spring-boot-starter-mail'       // JavaMailSender 이메일 발송
'org.springframework.boot:spring-boot-starter-batch'      // 대용량 청크 단위 배치 작업

// 📊 운영 & 관측성
'org.springframework.boot:spring-boot-starter-actuator'   // 애플리케이션 상태(Health), 메트릭
'io.micrometer:micrometer-registry-prometheus'           // 프로메테우스(Prometheus) 모니터링 수집
```

## 5. 핵심 컴포넌트 & 어노테이션 (Core Annotations & IoC)
```java
// [1] 스테레오타입 어노테이션 (자동 컴포넌트 스캔 대상)
@Component    // 기본 스프링 관리 빈으로 등록
@Service      // 비즈니스 로직 계층 (명시적 역할 구분)
@Repository   // 데이터 접근 계층 (플랫폼 종속 예외를 DataAccessException으로 변환)
@Controller   // Spring MVC 컨트롤러 (뷰 템플릿 반환용)
@RestController // @Controller + @ResponseBody (JSON/REST API 전용)

// [2] 설정 클래스 및 수동 빈 등록
@Configuration // 스프링 설정 클래스로 선언 (싱글톤 CGLIB 프록시 적용)
public class AppConfig {

    @Bean // 메서드가 반환하는 객체를 스프링 컨테이너의 빈으로 수동 등록
    public RestTemplate restTemplate() {
        return new RestTemplate();
    }
}

// [3] 프로퍼티 값 주입
@Component
public class ApiClient {
    // 단일 프로퍼티 값 주입 (기본값 설정 가능)
    @Value("${external.api.timeout:5000}")
    private int timeout;

    @Value("${external.api.base-url}")
    private String baseUrl;
}

// [4] 타입 세이프 프로퍼티 바인딩 (@ConfigurationProperties)
@Component
@ConfigurationProperties(prefix = "app.mail")
@Getter @Setter
public class MailProperties {
    private String host;
    private int port;
    private List<String> defaultRecipients;
}
```

## 6. 의존성 주입 & 빈 생명주기 (DI & Bean Lifecycle)
```java
// 실무 권장 패턴: 생성자 주입 + Lombok @RequiredArgsConstructor
@Service
@RequiredArgsConstructor // final 필드 대상 생성자 자동 생성
public class UserService {

    // final 키워드로 불변성 보장 및 누락 방지
    private final UserRepository userRepository;
    private final EmailService emailService;

    // 빈 등록 직후 1회 초기화 작업 실행 (DB 기초 데이터 세팅 등)
    @PostConstruct
    public void init() {
        System.out.println("UserService 빈 초기화 완료");
    }

    // 스프링 컨테이너 종료 직전 리소스 반환/정리 작업 실행
    @PreDestroy
    public void cleanup() {
        System.out.println("UserService 빈 종료 리소스 정리");
    }
}

// 동일 타입 빈 충돌 시 해결 방법 (@Primary, @Qualifier)
@Component
@Primary // 기본 우선순위 빈으로 지정
public class KakaoPayService implements PaymentService { }

@Component("naverPay")
public class NaverPayService implements PaymentService { }

@Service
@RequiredArgsConstructor
public class OrderService {
    // 특정 빈을 명시적으로 주입받을 때
    @Qualifier("naverPay")
    private final PaymentService paymentService;
}
```

## 7. RESTful API 컨트롤러 (Spring MVC REST)
```java
@RestController
@RequestMapping("/api/v1/users")
@RequiredArgsConstructor
public class UserController {

    private final UserService userService;

    // 1. 단건 조회: GET /api/v1/users/{id}
    @GetMapping("/{id}")
    public ResponseEntity<UserResponse> getUser(@PathVariable Long id) {
        UserResponse response = userService.findById(id);
        return ResponseEntity.ok(response); // HTTP 200 OK
    }

    // 2. 목록 페이징 검색: GET /api/v1/users?role=ADMIN&page=0&size=10
    @GetMapping
    public ResponseEntity<Page<UserResponse>> getUsers(
            @RequestParam(required = false, defaultValue = "USER") String role,
            @PageableDefault(size = 10, sort = "id", direction = Sort.Direction.DESC) Pageable pageable) {
        return ResponseEntity.ok(userService.findAll(role, pageable));
    }

    // 3. 생성: POST /api/v1/users
    @PostMapping
    public ResponseEntity<UserResponse> createUser(@Valid @RequestBody UserCreateRequest request) {
        UserResponse created = userService.create(request);
        URI location = URI.create("/api/v1/users/" + created.getId());
        return ResponseEntity.created(location).body(created); // HTTP 201 Created
    }

    // 4. 수정: PUT /api/v1/users/{id}
    @PutMapping("/{id}")
    public ResponseEntity<UserResponse> updateUser(
            @PathVariable Long id,
            @Valid @RequestBody UserUpdateRequest request) {
        return ResponseEntity.ok(userService.update(id, request));
    }

    // 5. 삭제: DELETE /api/v1/users/{id}
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
        userService.delete(id);
        return ResponseEntity.noContent().build(); // HTTP 204 No Content
    }
}
```

## 8. DTO 유효성 검증 (Bean Validation)
```java
// 의존성: implementation 'org.springframework.boot:spring-boot-starter-validation'
@Getter
@NoArgsConstructor
public class UserCreateRequest {

    @NotBlank(message = "이름은 필수 입력 항목입니다.")
    @Size(min = 2, max = 30, message = "이름은 2~30자 이내여야 합니다.")
    private String name;

    @NotBlank(message = "이메일은 필수 입력 항목입니다.")
    @Email(message = "올바른 이메일 형식이 아닙니다.")
    private String email;

    @NotBlank(message = "비밀번호는 필수 입력 항목입니다.")
    @Pattern(
        regexp = "^(?=.*[A-Za-z])(?=.*\\d)(?=.*[@$!%*#?&])[A-Za-z\\d@$!%*#?&]{8,}$",
        message = "비밀번호는 8자 이상, 영문, 숫자, 특수문자를 각각 최소 1개 포함해야 합니다."
    )
    private String password;

    @Min(value = 14, message = "14세 이상만 가입 가능합니다.")
    @Max(value = 120, message = "유효한 나이를 입력해주세요.")
    private int age;
}
```

## 9. 전역 예외 처리 (Global Exception Handling)
```java
// [1] 통일된 에러 응답 DTO
@Getter
@Builder
public class ErrorResponse {
    private final LocalDateTime timestamp = LocalDateTime.now();
    private final int status;
    private final String error;
    private final String message;
    private final Map<String, String> validationErrors;
}

// [2] 전역 예외 처리기 (@RestControllerAdvice)
@RestControllerAdvice
@Slf4j
public class GlobalExceptionHandler {

    // 1. 유효성 검증 실패 예외 (@Valid 실패 시 자동 발생)
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleValidationException(MethodArgumentNotValidException ex) {
        Map<String, String> errors = new HashMap<>();
        ex.getBindingResult().getFieldErrors().forEach(err -> 
            errors.put(err.getField(), err.getDefaultMessage())
        );

        ErrorResponse response = ErrorResponse.builder()
                .status(HttpStatus.BAD_REQUEST.value())
                .error(HttpStatus.BAD_REQUEST.getReasonPhrase())
                .message("입력값 검증에 실패했습니다.")
                .validationErrors(errors)
                .build();
        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(response);
    }

    // 2. 비즈니스 커스텀 예외
    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleNotFoundException(ResourceNotFoundException ex) {
        ErrorResponse response = ErrorResponse.builder()
                .status(HttpStatus.NOT_FOUND.value())
                .error(HttpStatus.NOT_FOUND.getReasonPhrase())
                .message(ex.getMessage())
                .build();
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(response);
    }

    // 3. 기타 서버 내부 오류 (최후의 보루)
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleGeneralException(Exception ex) {
        log.error("Unhandled Exception occurred: ", ex);
        ErrorResponse response = ErrorResponse.builder()
                .status(HttpStatus.INTERNAL_SERVER_ERROR.value())
                .error(HttpStatus.INTERNAL_SERVER_ERROR.getReasonPhrase())
                .message("서버 내부 오류가 발생했습니다. 잠시 후 다시 시도해주세요.")
                .build();
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(response);
    }
}
```

## 10. application.yml 핵심 설정 (Configuration)
```yaml
# 기본 서버 및 프로파일 설정
server:
  port: 8080
  servlet:
    context-path: /
    encoding:
      charset: UTF-8
      force: true

spring:
  application:
    name: lucky-api-service
  profiles:
    active: local # 기본 활성화 프로파일

  # 데이터소스 & HikariCP 커넥션 풀 설정
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/lucky_db?useSSL=false&serverTimezone=UTC&characterEncoding=UTF-8
    username: root
    password: password123
    hikari:
      maximum-pool-size: 10
      minimum-idle: 5
      connection-timeout: 30000
      idle-timeout: 600000
      max-lifetime: 1800000

  # JPA & Hibernate 설정
  jpa:
    open-in-view: false # OSIV 비활성화 (커넥션 고갈 방지 및 실무 필수 권장)
    hibernate:
      ddl-auto: validate # local: update / dev, prod: validate or none
    show-sql: false # sysout 대신 logback으로 확인 권장
    properties:
      hibernate:
        format_sql: true
        default_batch_fetch_size: 100 # N+1 해결을 위한 In-query 배치 사이즈

# 로깅 레벨 설정
logging:
  level:
    root: INFO
    com.example.demo: DEBUG
    org.hibernate.SQL: DEBUG # SQL 쿼리 로깅
    org.hibernate.orm.jdbc.bind: TRACE # 바인딩 파라미터 값 표시 (Spring Boot 3.x)
```

## 11. Spring Data JPA & 트랜잭션 (Data & Transaction)
```java
// Repository 인터페이스 정의 (JpaRepository 기본 내장 메서드 활용)
public interface UserRepository extends JpaRepository<User, Long> {

    // 쿼리 메서드 패턴 (이름 기반 자동 쿼리 생성)
    Optional<User> findByEmail(String email);
    boolean existsByEmail(String email);
    List<User> findByStatusAndCreatedAtAfter(UserStatus status, LocalDateTime dateTime);

    // JPQL 직접 정의 (@Query)
    @Query("SELECT u FROM User u WHERE u.role = :role AND u.isActive = true")
    List<User> findActiveUsersByRole(@Param("role") Role role);

    // 벌크 업데이트/삭제 (@Modifying 필수, 영속성 컨텍스트 초기화 설정)
    @Modifying(clearAutomatically = true)
    @Query("UPDATE User u SET u.status = :newStatus WHERE u.lastLoginAt < :cutoff")
    int bulkUpdateStatus(@Param("newStatus") UserStatus newStatus, @Param("cutoff") LocalDateTime cutoff);
}

// 서비스 계층 트랜잭션 처리
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true) // 클래스 전체 읽기 전용 (성능 최적화 & 스냅샷 생략)
public class UserService {

    private final UserRepository userRepository;

    public UserResponse findById(Long id) {
        User user = userRepository.findById(id)
                .orElseThrow(() -> new ResourceNotFoundException("사용자를 찾을 수 없습니다: " + id));
        return UserResponse.from(user);
    }

    @Transactional // 쓰기/수정 작업에는 반드시 readOnly = false (기본값)
    public Long updateName(Long id, String newName) {
        User user = userRepository.findById(id)
                .orElseThrow(() -> new ResourceNotFoundException("사용자를 찾을 수 없습니다."));
        user.updateName(newName); // 더티 체킹(Dirty Checking)으로 save() 호출 없이 자동 UPDATE 쿼리 발생
        return user.getId();
    }
}
```

## 12. Spring Security 6.x 기본 구성 (Security FilterChain)
```java
// Spring Boot 3.x (Spring Security 6.x 최신 컴포넌트 스타일)
@Configuration
@EnableWebSecurity
@RequiredArgsConstructor
public class SecurityConfig {

    private final JwtAuthenticationFilter jwtAuthFilter;

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            // 1. CSRF & FormLogin 비활성화 (Stateless REST API 환경)
            .csrf(AbstractHttpConfigurer::disable)
            .formLogin(AbstractHttpConfigurer::disable)
            .httpBasic(AbstractHttpConfigurer::disable)

            // 2. 세션을 생성하지 않고 완전 무상태(Stateless)로 설정
            .sessionManagement(session -> 
                session.sessionCreationPolicy(SessionCreationPolicy.STATELESS)
            )

            // 3. URL 요청별 접근 권한 설정
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/v1/auth/**", "/public/**", "/swagger-ui/**", "/v3/api-docs/**").permitAll()
                .requestMatchers("/api/v1/admin/**").hasRole("ADMIN")
                .anyRequest().authenticated()
            )

            // 4. JWT 필터를 UsernamePasswordAuthenticationFilter 이전에 배치
            .addFilterBefore(jwtAuthFilter, UsernamePasswordAuthenticationFilter.class);

        return http.build();
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder(); // 비밀번호 단방향 암호화
    }
}
```

## 13. 비동기 처리 & 스케줄링 (Async & Scheduling)
```java
// [1] 비동기 처리 활성화 및 실행 (@EnableAsync)
@Configuration
@EnableAsync
public class AsyncConfig {

    @Bean(name = "mailTaskExecutor")
    public Executor mailTaskExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(5);
        executor.setMaxPoolSize(10);
        executor.setQueueCapacity(100);
        executor.setThreadNamePrefix("async-mail-");
        executor.initialize();
        return executor;
    }
}

@Service
public class EmailService {
    @Async("mailTaskExecutor") // 지정된 스레드풀에서 백그라운드 비동기 실행
    public CompletableFuture<Boolean> sendWelcomeEmail(String toEmail) {
        // 긴 시간이 소요되는 외부 SMTP 메일 발송 로직
        return CompletableFuture.completedFuture(true);
    }
}

// [2] 주기적 작업 스케줄링 (@EnableScheduling)
@Configuration
@EnableScheduling
public class SchedulerConfig { }

@Component
public class CacheEvictScheduler {
    // 매일 새벽 3시 실행 (초 분 시 일 월 요일)
    @Scheduled(cron = "0 0 3 * * ?")
    public void runDailyBatch() {
        System.out.println("일일 만료 캐시 정리 실행");
    }

    // 이전 작업 시작 기준 5초마다 실행
    @Scheduled(fixedRate = 5000)
    public void heartbeat() { }
}
```

## 14. 테스트 코드 작성 (Testing with MockMvc)
```java
// [1] 컨트롤러 슬라이스 테스트 (@WebMvcTest)
@WebMvcTest(UserController.class)
class UserControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private UserService userService;

    @Autowired
    private ObjectMapper objectMapper;

    @Test
    @DisplayName("회원 단건 조회 성공 시 200 OK와 사용자 정보를 반환한다")
    void getUserSuccess() throws Exception {
        // given
        UserResponse response = new UserResponse(1L, "lucky", "lucky@example.com");
        given(userService.findById(1L)).willReturn(response);

        // when & then
        mockMvc.perform(get("/api/v1/users/1")
                .contentType(MediaType.APPLICATION_JSON))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.id").value(1L))
                .andExpect(jsonPath("$.name").value("lucky"))
                .andExpect(jsonPath("$.email").value("lucky@example.com"));
    }
}

// [2] 서비스 단위 테스트 (Mockito)
@ExtendWith(MockitoExtension.class)
class UserServiceTest {

    @Mock
    private UserRepository userRepository;

    @InjectMocks
    private UserService userService;

    @Test
    @DisplayName("존재하지 않는 유저 조회 시 ResourceNotFoundException이 발생한다")
    void userNotFoundThrowsException() {
        // given
        given(userRepository.findById(999L)).willReturn(Optional.empty());

        // when & then
        org.junit.jupiter.api.Assertions.assertThrows(
            ResourceNotFoundException.class,
            () -> userService.findById(999L)
        );
    }
}
```

## 15. 운영 모니터링 & 최적화 (Actuator & Production)
```yaml
# Actuator 설정 (application.yml)
management:
  endpoints:
    web:
      exposure:
        # 실무 권장: 헬스체크, 지표 및 프로메테우스만 노출 (env, beans 등 민감 정보 숨김)
        include: health, info, metrics, prometheus
      base-path: /actuator
  endpoint:
    health:
      show-details: when_authorized # 상세 상태 정보는 권한 보유자에게만 노출
      probes:
        enabled: true # 쿠버네티스 Liveness, Readiness 프로브 지원

# 무중단 배포를 위한 Graceful Shutdown 설정
server:
  shutdown: graceful

spring:
  lifecycle:
    timeout-per-shutdown-phase: 20s # 종료 시 처리 중인 요청 대기 시간 (최대 20초)
```
💬
Spring Boot 치트시트

의견 및 질문

댓글 수정

댓글 삭제
