Spring Boot 2에서 3으로의 완벽한 마이그레이션 가이드: 새로운 변화와 적용 방법

 

Spring Boot 3 버전은 성능, 보안, 효율성 면에서 여러 중요한 개선 사항을 포함하고 있으며, Java 17과 Spring Framework 6을 기반으로 합니다. 이 블로그에서는 Spring Boot 2에서 3으로 마이그레이션 할 때 필요한 주요 변경 사항들을 설명하고, 각 단계에서 유의할 점과 해결 방법을 코드 예제와 함께 제시합니다.

1. 주요 변경 사항 소개

Spring Boot 3는 Jakarta EE 10, 새로운 의존성 관리, 보안 패치 등 많은 부분에서 변화가 있었습니다. 마이그레이션 전에 Spring Boot 2.7로 업그레이드하고 Java 17을 사용하는 것이 필수입니다.

---

2. 의존성 및 구성 변경

2.1. Jakarta EE 패키지로 전환

Spring Boot 3에서는 javax 패키지가 더 이상 사용되지 않으며, jakarta 패키지로 대체되었습니다. 이는 JPA, 서블릿 등 여러 라이브러리에서도 반영됩니다. 기존의 javax.persistence.*와 같은 import 문을 jakarta.persistence.*로 수정해야 합니다.

<dependency>
    <groupId>jakarta.persistence</groupId>
    <artifactId>jakarta.persistence-api</artifactId>
    <version>3.1.0</version>
</dependency>

2.2. 속성(Property) 변경 사항

기존 Spring Boot 2에서 사용되던 몇 가지 속성들이 Spring Boot 3에서 변경되었습니다. 예를 들어, spring.redis는 spring.data.redis로 이동했으며, spring.data.cassandra도 spring.cassandra로 변경되었습니다.

속성 이름 변경 사항을 쉽게 찾기 위해 spring-boot-properties-migrator를 사용하여 마이그레이션할 수 있습니다.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-properties-migrator</artifactId>
    <scope>runtime</scope>
</dependency>

반응형

---

3. 웹 애플리케이션 관련 변경 사항

3.1. Trailing Slash 매칭 비활성화

Spring Boot 3에서 기본적으로 URL의 trailing slash가 매칭되지 않게 변경되었습니다. 예를 들어, /api/v1/todos/name/과 같은 요청은 더 이상 기본적으로 매칭되지 않습니다.

이를 활성화하려면 WebMvcConfigurer를 구현하여 설정을 수정해야 합니다.

public class WebConfiguration implements WebMvcConfigurer {
    @Override
    public void configurePathMatch(PathMatchConfigurer configurer) {
        configurer.setUseTrailingSlashMatch(true);
    }
}

3.2. HTTP 헤더 크기 제한 변경

server.max.http.header.size 속성이 server.max-http-request-header-size로 변경되었으며, 요청 헤더와 응답 헤더에 대한 별도의 크기 제한을 설정할 수 있습니다.

@Configuration
public class ServerConfiguration implements WebServerFactoryCustomizer<TomcatServletWebServerFactory> {
    @Override
    public void customize(TomcatServletWebServerFactory factory) {
        factory.addConnectorCustomizers(connector -> 
            connector.setProperty("maxHttpResponseHeaderSize", "100000"));
    }
}

---

4. Spring Security 변경 사항

4.1. Spring Security 6로 업그레이드

Spring Boot 3는 Spring Security 6와만 호환됩니다. 따라서 먼저 Spring Boot 2.7에서 Spring Security 5.8로 업그레이드한 후, Spring Boot 3로 전환해야 합니다.

4.2. SAML2 의존성 변경

spring.security.saml2.relyingparty.registration.{id}.identity-provider 속성은 더 이상 지원되지 않으며, 새로운 속성인 spring.security.saml2.relyingparty.registration.{id}.asserting-party를 사용해야 합니다.

---

5. Spring Batch 변경 사항

5.1. @EnableBatchProcessing 사용 자제

Spring Boot 3에서는 @EnableBatchProcessing 애노테이션 사용을 권장하지 않습니다. 대신 자동 설정을 사용하여 배치 작업을 처리할 수 있으며, 다수의 배치 작업을 동시에 실행하려면 별도의 스케줄러를 사용하거나 spring.batch.job.name 속성을 통해 실행할 작업을 명시해야 합니다.

---

6. Actuator 변경 사항

6.1. Actuator Endpoint 보안 강화

Spring Boot 3에서는 /env 및 /configprops와 같은 Actuator 엔드포인트에서 모든 속성 값이 기본적으로 마스킹 처리됩니다. 이를 조정하려면 management.endpoint.env.show-values 속성을 설정해야 합니다.

• NEVER: 값을 숨김
• ALWAYS: 모든 값을 표시
• WHEN_AUTHORIZED: 인증된 사용자만 값을 볼 수 있음

management:
  endpoint:
    env:
      show-values: NEVER

728x90

---

Spring Boot 2에서 3으로의 마이그레이션은 구조적 변화와 성능 향상을 목표로 하지만, 여러 설정 변경과 의존성 수정이 필요합니다. 이 글에서 설명한 각 항목을 꼼꼼히 적용하여, Spring Boot 3의 최신 기능과 성능을 충분히 활용할 수 있기를 바랍니다.