Spring Boot 3.x 완전 가이드 2025: Virtual Threads, GraalVM Native, Spring AI

// Before (Spring Boot 2.x)
import javax.persistence.Entity;
import javax.servlet.http.HttpServletRequest;

// After (Spring Boot 3.x)
import jakarta.persistence.Entity;
import jakarta.servlet.http.HttpServletRequest;

// build.gradle — OpenRewrite 자동 마이그레이션
plugins {
    id 'org.openrewrite.rewrite' version '6.16.0'
}

rewrite {
    activeRecipe(
        'org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_3'
    )
}

dependencies {
    rewrite platform('org.openrewrite.recipe:rewrite-recipe-bom:2.13.0')
    rewrite 'org.openrewrite.recipe:rewrite-spring'
}

my-app/
  app-api/          # REST 컨트롤러, DTO
  app-domain/       # 엔티티, 서비스, 리포지토리 인터페이스
  app-infra/        # DB, 외부 API 구현체
  app-common/       # 공통 유틸, 예외
  app-batch/        # 배치 잡

// settings.gradle
rootProject.name = 'my-app'
include 'app-api', 'app-domain', 'app-infra', 'app-common', 'app-batch'

// 전통적 스레드 풀 (Spring Boot 2.x 기본)
// 최대 200개 스레드 = 200개 동시 요청
@Configuration
public class ThreadConfig {
    @Bean
    public TomcatProtocolHandlerCustomizer<?> protocolHandler() {
        return handler -> handler.setMaxThreads(200);
    }
}

// Virtual Threads (Spring Boot 3.2+)
// 수만 개의 동시 요청 처리 가능
// application.yml 한 줄이면 됨

# application.yml — Virtual Threads 활성화
spring:
  threads:
    virtual:
      enabled: true

@RestController
@RequestMapping("/api/benchmark")
public class BenchmarkController {

    @GetMapping("/blocking")
    public String blockingCall() throws InterruptedException {
        // DB 호출 시뮬레이션 (100ms 블로킹)
        Thread.sleep(100);
        return "response from " + Thread.currentThread();
    }
}

// WebFlux (리액티브 — 학습 곡선 높음)
@GetMapping("/reactive")
public Mono<User> getUser(@PathVariable Long id) {
    return userRepository.findById(id)
        .flatMap(user -> enrichmentService.enrich(user))
        .onErrorResume(e -> Mono.error(new UserNotFoundException(id)));
}

// Virtual Threads (동기 코드 그대로 — 학습 곡선 낮음)
@GetMapping("/virtual")
public User getUser(@PathVariable Long id) {
    User user = userRepository.findById(id)
        .orElseThrow(() -> new UserNotFoundException(id));
    return enrichmentService.enrich(user);
}

// 주의 1: synchronized 블록에서 carrier thread pinning 발생
// BAD — carrier thread가 고정되어 성능 저하
public synchronized void updateCache() {
    // 이 안에서 블로킹 I/O 하면 안 됨
    httpClient.send(request, bodyHandler);
}

// GOOD — ReentrantLock 사용
private final ReentrantLock lock = new ReentrantLock();
public void updateCache() {
    lock.lock();
    try {
        httpClient.send(request, bodyHandler);
    } finally {
        lock.unlock();
    }
}

// 주의 2: ThreadLocal 과도 사용 금지
// Virtual Thread는 수만 개 생성되므로 ThreadLocal 메모리 누수 위험
// ScopedValue(Preview) 사용 권장

// 주의 3: CPU 바운드 작업에는 부적합
// 피보나치 계산 같은 CPU 작업은 Virtual Thread가 이점 없음

# Virtual Thread 모니터링 JFR 이벤트 활성화
# application.yml
management:
  endpoints:
    web:
      exposure:
        include: health,metrics,threaddump

// build.gradle
plugins {
    id 'org.graalvm.buildtools.native' version '0.10.1'
    id 'org.springframework.boot' version '3.3.0'
}

graalvmNative {
    binaries {
        main {
            buildArgs.addAll(
                '--initialize-at-build-time=org.slf4j',
                '-H:+ReportExceptionStackTraces',
                '--verbose'
            )
            jvmArgs.add('-Xmx8g') // 빌드 시 메모리
        }
    }
}

# Native Image 빌드
./gradlew nativeCompile

# 실행 (0.08초 기동!)
./build/native/nativeCompile/my-app

# Docker로 빌드
./gradlew bootBuildImage

// RuntimeHintsRegistrar로 힌트 등록
@ImportRuntimeHints(MyRuntimeHints.class)
@SpringBootApplication
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

public class MyRuntimeHints implements RuntimeHintsRegistrar {
    @Override
    public void registerHints(RuntimeHints hints, ClassLoader classLoader) {
        // 리플렉션 힌트
        hints.reflection()
            .registerType(UserDto.class,
                MemberCategory.INVOKE_DECLARED_CONSTRUCTORS,
                MemberCategory.INVOKE_DECLARED_METHODS);

        // 리소스 힌트
        hints.resources()
            .registerPattern("templates/*.html")
            .registerPattern("static/**");

        // 직렬화 힌트
        hints.serialization()
            .registerType(UserDto.class);
    }
}

// DTO에 @RegisterReflectionForBinding 사용
@RegisterReflectionForBinding(UserDto.class)
@RestController
public class UserController {
    // UserDto가 Native Image에서 직렬화/역직렬화 가능
}

// build.gradle
dependencies {
    implementation 'org.springframework.ai:spring-ai-openai-spring-boot-starter:1.0.0'
    // 또는 Anthropic
    // implementation 'org.springframework.ai:spring-ai-anthropic-spring-boot-starter:1.0.0'
}

# application.yml
spring:
  ai:
    openai:
      api-key: your-api-key-here
      chat:
        options:
          model: gpt-4o
          temperature: 0.7

@Service
public class AiService {
    private final ChatClient chatClient;

    public AiService(ChatClient.Builder builder) {
        this.chatClient = builder
            .defaultSystem("당신은 친절한 Java 개발 도우미입니다.")
            .build();
    }

    // 간단한 텍스트 생성
    public String chat(String userMessage) {
        return chatClient.prompt()
            .user(userMessage)
            .call()
            .content();
    }

    // 구조화된 응답 (JSON -> Java 객체)
    public CodeReview reviewCode(String code) {
        return chatClient.prompt()
            .user(u -> u.text("다음 코드를 리뷰해주세요: {code}")
                .param("code", code))
            .call()
            .entity(CodeReview.class);
    }

    // 스트리밍 응답
    public Flux<String> streamChat(String userMessage) {
        return chatClient.prompt()
            .user(userMessage)
            .stream()
            .content();
    }
}

public record CodeReview(
    int score,
    List<String> issues,
    List<String> suggestions,
    String summary
) {}

@Configuration
public class RagConfig {

    @Bean
    public VectorStore vectorStore(EmbeddingModel embeddingModel) {
        return new PgVectorStore(
            jdbcTemplate, embeddingModel,
            PgVectorStore.PgVectorStoreConfig.builder()
                .withDimensions(1536)
                .withIndexType(PgVectorStore.PgIndexType.HNSW)
                .build()
        );
    }
}

@Service
public class RagService {
    private final ChatClient chatClient;
    private final VectorStore vectorStore;

    public RagService(ChatClient.Builder builder, VectorStore vectorStore) {
        this.vectorStore = vectorStore;
        this.chatClient = builder
            .defaultAdvisors(
                new QuestionAnswerAdvisor(vectorStore,
                    SearchRequest.defaults().withTopK(5))
            )
            .build();
    }

    // 문서 인덱싱
    public void indexDocuments(List<Document> documents) {
        // 텍스트 분할
        TokenTextSplitter splitter = new TokenTextSplitter(800, 200, 5, 10000, true);
        List<Document> chunks = splitter.apply(documents);

        // 벡터 저장소에 저장
        vectorStore.add(chunks);
    }

    // RAG 기반 질의
    public String queryWithContext(String question) {
        return chatClient.prompt()
            .user(question)
            .call()
            .content();
    }
}

@Service
public class WeatherService {

    @Tool("현재 날씨를 조회합니다")
    public WeatherInfo getCurrentWeather(
        @ToolParam("도시 이름") String city
    ) {
        // 실제 날씨 API 호출
        return weatherApiClient.getWeather(city);
    }
}

@RestController
public class AiController {
    private final ChatClient chatClient;
    private final WeatherService weatherService;

    @GetMapping("/ai/chat")
    public String chat(@RequestParam String message) {
        return chatClient.prompt()
            .user(message)
            .tools(weatherService)
            .call()
            .content();
    }
}
// "서울 날씨 어때?" -> AI가 자동으로 WeatherService.getCurrentWeather("서울") 호출

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        return http
            .csrf(csrf -> csrf
                .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())
                .csrfTokenRequestHandler(new CsrfTokenRequestAttributeHandler())
            )
            .cors(cors -> cors.configurationSource(corsConfigSource()))
            .sessionManagement(session -> session
                .sessionCreationPolicy(SessionCreationPolicy.STATELESS)
            )
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/public/**", "/actuator/health").permitAll()
                .requestMatchers("/api/admin/**").hasRole("ADMIN")
                .requestMatchers("/api/**").authenticated()
                .anyRequest().denyAll()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .jwt(jwt -> jwt.jwtAuthenticationConverter(jwtConverter()))
            )
            .exceptionHandling(ex -> ex
                .authenticationEntryPoint(new Http403ForbiddenEntryPoint())
            )
            .build();
    }

    @Bean
    public CorsConfigurationSource corsConfigSource() {
        CorsConfiguration config = new CorsConfiguration();
        config.setAllowedOrigins(List.of("https://myapp.com"));
        config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE"));
        config.setAllowedHeaders(List.of("*"));
        config.setAllowCredentials(true);

        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/api/**", config);
        return source;
    }
}

# application.yml
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://auth.example.com/realms/my-realm
          # 또는 jwk-set-uri

// JWT 클레임 -> Spring Security Authority 매핑
@Bean
public JwtAuthenticationConverter jwtConverter() {
    JwtGrantedAuthoritiesConverter grantedAuthorities =
        new JwtGrantedAuthoritiesConverter();
    grantedAuthorities.setAuthoritiesClaimName("roles");
    grantedAuthorities.setAuthorityPrefix("ROLE_");

    JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
    converter.setJwtGrantedAuthoritiesConverter(grantedAuthorities);
    return converter;
}

// Method Security
@Service
public class UserService {

    @PreAuthorize("hasRole('ADMIN') or #userId == authentication.name")
    public User getUser(String userId) {
        return userRepository.findById(userId).orElseThrow();
    }

    @PostAuthorize("returnObject.email == authentication.name")
    public UserProfile getProfile(String userId) {
        return profileRepository.findByUserId(userId);
    }
}

// SPA + REST API 환경에서의 보안 설정
@Bean
public SecurityFilterChain apiSecurity(HttpSecurity http) throws Exception {
    return http
        .securityMatcher("/api/**")
        .csrf(AbstractHttpConfigurer::disable) // JWT 사용 시 CSRF 불필요
        .cors(cors -> cors.configurationSource(corsConfigSource()))
        .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
        .oauth2ResourceServer(o -> o.jwt(Customizer.withDefaults()))
        .build();
}

@Entity
@Table(name = "users")
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

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

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

    @Enumerated(EnumType.STRING)
    private UserStatus status;

    @CreationTimestamp
    private LocalDateTime createdAt;

    @UpdateTimestamp
    private LocalDateTime updatedAt;
}

// Spring Data JPA Repository
public interface UserRepository extends JpaRepository<User, Long> {

    // 메서드 이름 기반 쿼리
    Optional<User> findByEmail(String email);

    // JPQL
    @Query("SELECT u FROM User u WHERE u.status = :status AND u.createdAt > :since")
    List<User> findActiveUsersSince(
        @Param("status") UserStatus status,
        @Param("since") LocalDateTime since
    );

    // Native Query
    @Query(value = "SELECT * FROM users WHERE email LIKE %:domain", nativeQuery = true)
    List<User> findByEmailDomain(@Param("domain") String domain);

    // Projection
    @Query("SELECT u.name as name, u.email as email FROM User u WHERE u.id = :id")
    Optional<UserSummary> findSummaryById(@Param("id") Long id);
}

interface UserSummary {
    String getName();
    String getEmail();
}

// build.gradle
dependencies {
    implementation 'com.querydsl:querydsl-jpa:5.1.0:jakarta'
    annotationProcessor 'com.querydsl:querydsl-apt:5.1.0:jakarta'
    annotationProcessor 'jakarta.persistence:jakarta.persistence-api:3.1.0'
}

@Repository
@RequiredArgsConstructor
public class UserQueryRepository {
    private final JPAQueryFactory queryFactory;

    public Page<User> searchUsers(UserSearchCond cond, Pageable pageable) {
        QUser user = QUser.user;

        BooleanBuilder where = new BooleanBuilder();

        if (cond.getName() != null) {
            where.and(user.name.containsIgnoreCase(cond.getName()));
        }
        if (cond.getStatus() != null) {
            where.and(user.status.eq(cond.getStatus()));
        }
        if (cond.getFromDate() != null) {
            where.and(user.createdAt.goe(cond.getFromDate()));
        }

        List<User> content = queryFactory
            .selectFrom(user)
            .where(where)
            .offset(pageable.getOffset())
            .limit(pageable.getPageSize())
            .orderBy(user.createdAt.desc())
            .fetch();

        long total = queryFactory
            .selectFrom(user)
            .where(where)
            .fetchCount();

        return new PageImpl<>(content, pageable, total);
    }
}

// R2DBC Repository (WebFlux 사용 시)
public interface ReactiveUserRepository extends ReactiveCrudRepository<User, Long> {
    Flux<User> findByStatus(UserStatus status);
    Mono<User> findByEmail(String email);
}

@Service
@RequiredArgsConstructor
public class ReactiveUserService {
    private final ReactiveUserRepository userRepository;

    public Flux<User> getActiveUsers() {
        return userRepository.findByStatus(UserStatus.ACTIVE)
            .delayElements(Duration.ofMillis(10)) // 백프레셔 시뮬레이션
            .onErrorResume(e -> Flux.empty());
    }
}

// build.gradle
dependencies {
    testImplementation 'org.springframework.boot:spring-boot-testcontainers'
    testImplementation 'org.testcontainers:junit-jupiter'
    testImplementation 'org.testcontainers:postgresql'
    testImplementation 'org.testcontainers:kafka'
}

@SpringBootTest
@Testcontainers
class UserServiceIntegrationTest {

    @Container
    @ServiceConnection
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine");

    @Container
    @ServiceConnection
    static KafkaContainer kafka = new KafkaContainer(
        DockerImageName.parse("confluentinc/cp-kafka:7.6.0")
    );

    @Autowired
    private UserService userService;

    @Autowired
    private UserRepository userRepository;

    @Test
    void shouldCreateUser() {
        // Given
        CreateUserRequest request = new CreateUserRequest("John", "john@test.com");

        // When
        User created = userService.createUser(request);

        // Then
        assertThat(created.getId()).isNotNull();
        assertThat(created.getName()).isEqualTo("John");

        User found = userRepository.findById(created.getId()).orElseThrow();
        assertThat(found.getEmail()).isEqualTo("john@test.com");
    }
}

// 공통 테스트 설정 — 모든 통합 테스트에서 재사용
@TestConfiguration(proxyBeanMethods = false)
public class TestContainersConfig {

    @Bean
    @ServiceConnection
    public PostgreSQLContainer<?> postgresContainer() {
        return new PostgreSQLContainer<>("postgres:16-alpine")
            .withReuse(true); // 컨테이너 재사용으로 테스트 속도 향상
    }

    @Bean
    @ServiceConnection
    public GenericContainer<?> redisContainer() {
        return new GenericContainer<>("redis:7-alpine")
            .withExposedPorts(6379)
            .withReuse(true);
    }
}

// CI/CD에서의 Testcontainers (GitHub Actions)

# .github/workflows/test.yml
name: Integration Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'
      - name: Run tests
        run: ./gradlew test
        env:
          TESTCONTAINERS_RYUK_DISABLED: false

// build.gradle
dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
    implementation 'io.micrometer:micrometer-registry-otlp'
    implementation 'io.micrometer:micrometer-tracing-bridge-otel'
    implementation 'io.opentelemetry:opentelemetry-exporter-otlp'
}

# application.yml
management:
  otlp:
    metrics:
      export:
        url: http://otel-collector:4318/v1/metrics
        step: 30s
    tracing:
      endpoint: http://otel-collector:4318/v1/traces
  tracing:
    sampling:
      probability: 1.0  # 프로덕션에서는 0.1 등으로 조절
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus,loggers
  metrics:
    tags:
      application: my-app
      environment: production

@Service
@RequiredArgsConstructor
public class OrderService {
    private final MeterRegistry meterRegistry;
    private final Counter orderCounter;
    private final Timer orderProcessingTimer;

    public OrderService(MeterRegistry meterRegistry) {
        this.meterRegistry = meterRegistry;
        this.orderCounter = Counter.builder("orders.created")
            .tag("type", "standard")
            .description("Number of orders created")
            .register(meterRegistry);
        this.orderProcessingTimer = Timer.builder("orders.processing.time")
            .description("Order processing time")
            .register(meterRegistry);
    }

    public Order createOrder(CreateOrderRequest request) {
        return orderProcessingTimer.record(() -> {
            Order order = processOrder(request);
            orderCounter.increment();

            // 게이지 — 현재 상태
            meterRegistry.gauge("orders.pending",
                orderRepository.countByStatus(OrderStatus.PENDING));

            return order;
        });
    }
}

@Service
@RequiredArgsConstructor
public class PaymentService {
    private final RestClient restClient;
    private final ObservationRegistry observationRegistry;

    // Spring Boot 3.x에서는 RestClient/WebClient가 자동으로 trace 전파
    public PaymentResult processPayment(PaymentRequest request) {
        Observation observation = Observation.createNotStarted(
            "payment.process", observationRegistry
        );

        return observation.observe(() -> {
            // 이 호출의 trace-id가 외부 서비스까지 전파됨
            return restClient.post()
                .uri("https://payment-gateway.com/api/charge")
                .body(request)
                .retrieve()
                .body(PaymentResult.class);
        });
    }
}

# docker-compose.yml (Observability Stack)
version: '3.8'
services:
  otel-collector:
    image: otel/opentelemetry-collector-contrib:0.96.0
    ports:
      - "4317:4317"   # gRPC
      - "4318:4318"   # HTTP
    volumes:
      - ./otel-config.yaml:/etc/otelcol/config.yaml

  prometheus:
    image: prom/prometheus:v2.51.0
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

  grafana:
    image: grafana/grafana:10.4.0
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin

  jaeger:
    image: jaegertracing/all-in-one:1.55
    ports:
      - "16686:16686"  # UI
      - "14250:14250"  # gRPC

# Stage 1: Build
FROM eclipse-temurin:21-jdk-alpine AS builder
WORKDIR /app
COPY gradle/ gradle/
COPY gradlew build.gradle settings.gradle ./
RUN ./gradlew dependencies --no-daemon
COPY src/ src/
RUN ./gradlew bootJar --no-daemon -x test

# Stage 2: Runtime
FROM eclipse-temurin:21-jre-alpine
RUN addgroup -S spring && adduser -S spring -G spring
USER spring:spring

COPY --from=builder /app/build/libs/*.jar app.jar

EXPOSE 8080
ENTRYPOINT ["java", \
  "-XX:+UseZGC", \
  "-XX:MaxRAMPercentage=75.0", \
  "-Djava.security.egd=file:/dev/./urandom", \
  "-jar", "app.jar"]

# Buildpacks로 이미지 빌드 (Dockerfile 불필요)
./gradlew bootBuildImage --imageName=myapp:latest

# Native Image로 빌드
./gradlew bootBuildImage --imageName=myapp:native \
  -Pnative=true

# k8s/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  labels:
    app: my-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: my-app
          image: myapp:latest
          ports:
            - containerPort: 8080
          env:
            - name: SPRING_PROFILES_ACTIVE
              value: "production"
            - name: JAVA_TOOL_OPTIONS
              value: "-XX:+UseZGC -XX:MaxRAMPercentage=75.0"
          resources:
            requests:
              memory: "256Mi"
              cpu: "250m"
            limits:
              memory: "512Mi"
              cpu: "1000m"
          readinessProbe:
            httpGet:
              path: /actuator/health/readiness
              port: 8080
            initialDelaySeconds: 10
            periodSeconds: 5
          livenessProbe:
            httpGet:
              path: /actuator/health/liveness
              port: 8080
            initialDelaySeconds: 30
            periodSeconds: 10
          startupProbe:
            httpGet:
              path: /actuator/health
              port: 8080
            failureThreshold: 30
            periodSeconds: 2
      terminationGracePeriodSeconds: 30
---
apiVersion: v1
kind: Service
metadata:
  name: my-app-service
spec:
  selector:
    app: my-app
  ports:
    - port: 80
      targetPort: 8080
  type: ClusterIP

# application.yml
server:
  shutdown: graceful

spring:
  lifecycle:
    timeout-per-shutdown-phase: 30s

// 커스텀 Graceful Shutdown 로직
@Component
public class GracefulShutdownHandler implements DisposableBean {

    private final ExecutorService executorService;

    @Override
    public void destroy() throws Exception {
        log.info("Graceful shutdown initiated...");
        executorService.shutdown();
        if (!executorService.awaitTermination(25, TimeUnit.SECONDS)) {
            executorService.shutdownNow();
        }
        log.info("Graceful shutdown completed");
    }
}

# 프로덕션 application-production.yml 예시
server:
  shutdown: graceful
  port: 8080

spring:
  datasource:
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
      connection-timeout: 3000
      idle-timeout: 600000
      max-lifetime: 1800000

  cache:
    type: redis
    redis:
      time-to-live: 600000

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus
  endpoint:
    health:
      show-details: when-authorized
      probes:
        enabled: true

logging:
  pattern:
    console: '{"timestamp":"%d","level":"%p","logger":"%c","message":"%m","trace":"%X{traceId}","span":"%X{spanId}"}%n'