MyBatis Spring Boot 4.0

Spring Boot 4.x의 정식 출시에 발맞춰, MyBatis 팀은 Spring Boot와의 완벽한 통합을 지원하는 MyBatis Spring Boot 4.0을 발표했습니다.
발표한 내용 기반으로 정리하였습니다.

---

1. 왜 버전 4.0인가?

Spring Boot 4.x 시대의 도래

2025년 11월, Spring Boot 4.x가 정식으로 릴리스되었습니다.
이번 메이저 업데이트는 기존 3.x 버전과의 하위 호환성을 담보하지 않는 과감한 변화를 포함하고 있습니다.
내부 API의 구조적 변경, 핵심 의존성 라이브러리의 업그레이드, 그리고 오랫동안 Deprecated 되었던 기능들의 제거가 이루어졌습니다.

이러한 변화로 인해, 기존 mybatis-spring-boot-starter 3.0.x는 Spring Boot 4.x 환경에서 더 이상 정상적인 동작을 보장할 수 없게 되었습니다.
따라서 MyBatis 팀은 Spring Boot 4.x 환경에 최적화된 새로운 스타터 패키지의 필요성을 인지하게 되었습니다.

버전 친화성 전략

MyBatis 팀은 차기 버전의 네이밍을 두고 3.1과 4.0 사이에서 고민했습니다.
결론적으로 4.0을 선택한 이유는 개발자 경험(DX)을 최우선으로 고려한 '버전 친화성' 전략 때문입니다.

• Spring Boot 3.x ↔ MyBatis Spring Boot 3.0.x
• Spring Boot 4.x ↔ MyBatis Spring Boot 4.0.x

이러한 버전 일치 전략은 개발자에게 매우 직관적인 가이드를 제공합니다.
만약 버전이 3.1이었다면, Spring Boot 4.x 사용자는 "과연 3.1 버전이 4.x 프레임워크와 호환되는가?"라는 불필요한 의문을 가질 수 있습니다.
메이저 버전을 통일함으로써 이러한 혼란을 사전에 방지하고, "Spring Boot 버전에 맞춰 MyBatis 버전도 올리면 된다"는 명확한 메시지를 전달합니다.

---

2. 프로젝트 적용 가이드

가장 먼저 수행해야 할 작업은 빌드 도구의 의존성 버전을 변경하는 것입니다.
Spring Boot 4.x로의 전환 시, MyBatis 스타터 역시 4.0.0으로 동기화해야 합니다.

Maven 설정

기존 Spring Boot 3.x 환경의 설정을 4.x 환경으로 변경합니다.

변경 전

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

<dependency>
    <groupId>org.mybatis.spring.boot</groupId>
    <artifactId>mybatis-spring-boot-starter</artifactId>
    <version>3.0.4</version>
</dependency>

변경 후

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

<dependency>
    <groupId>org.mybatis.spring.boot</groupId>
    <artifactId>mybatis-spring-boot-starter</artifactId>
    <version>4.0.0</version>
</dependency>

Gradle 설정

Gradle 사용자 역시 플러그인 버전과 의존성 버전을 동시에 상향 조정해야 합니다.

plugins {
    // Spring Boot 메이저 버전 업데이트
    id 'org.springframework.boot' version '4.0.0'
    id 'io.spring.dependency-management' version '1.2.0' // 호환되는 버전 확인 필요
}

dependencies {
    // MyBatis Starter 4.0.x 적용
    implementation 'org.mybatis.spring.boot:mybatis-spring-boot-starter:4.0.0'
}

---

3. 주요 변경 사항 및 권장 패턴

ConfigurationCustomizer를 활용한 설정

MyBatis 4.0.x는 Spring Boot 4.x의 강력한 Auto-Configuration 기능을 계승합니다. application.yml이나 application.properties를 통한 설정이 여전히 유효하지만, Java Config를 통해 동적으로 설정을 제어해야 할 경우 ConfigurationCustomizer 빈을 활용하는 것이 가장 안전하고 권장되는 방식입니다.

import org.mybatis.spring.boot.autoconfigure.ConfigurationCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class MyBatisConfig {

    /**
     * Spring Boot 4.x 환경에서 MyBatis 설정을 프로그래밍 방식으로 제어합니다.
     * 이 방식은 application.yml 설정보다 우선순위를 가지거나 보완할 수 있습니다.
     */
    @Bean
    public ConfigurationCustomizer mybatisConfigurationCustomizer() {
        return configuration -> {
            // 스네이크 케이스(DB) -> 카멜 케이스(Java) 자동 매핑 활성화
            configuration.setMapUnderscoreToCamelCase(true);
            
            // 전역 Fetch Size 설정 (성능 튜닝)
            configuration.setDefaultFetchSize(100);
            
            // null 값에 대한 처리 방식 지정
            configuration.setCallSettersOnNulls(true);
        };
    }
}

Spring Boot 4.x와 RestClient

MyBatis Spring Boot 4.0.x 샘플 프로젝트에는 주목할 만한 변화가 있습니다.
바로 spring-boot-restclient의 도입입니다.
Spring Framework 6.1부터 도입되고 Spring Boot 4.x에서 표준으로 자리 잡은 RestClient는 기존의 RestTemplate을 대체하는 모던하고 유창한 API를 제공합니다.

MyBatis 자체가 HTTP 통신을 직접 하지는 않지만, 서비스 레이어에서 외부 API와 연동할 때 이 패턴을 따르는 것이 권장됩니다.

@Configuration
public class ExternalApiConfig {
    
    // Spring Boot 4.x에서 권장되는 RestClient 구성 예시
    @Bean
    public RestClient todoRestClient(RestClient.Builder builder) {
        return builder
            .baseUrl("https://api.example.com")
            .defaultHeader("Authorization", "Bearer my-token")
            .build();
    }
}

// 서비스 레이어에서의 사용 예
@Service
public class TodoService {
    private final RestClient restClient;
    private final TodoMapper todoMapper; // MyBatis Mapper

    public TodoService(RestClient restClient, TodoMapper todoMapper) {
        this.restClient = restClient;
        this.todoMapper = todoMapper;
    }

    public void syncExternalTodos() {
        Todo[] externalTodos = restClient.get()
            .uri("/todos")
            .retrieve()
            .body(Todo[].class);
            
        // 가져온 데이터를 MyBatis를 통해 DB에 저장
        for (Todo todo : externalTodos) {
            todoMapper.insert(todo);
        }
    }
}

---

4. 로드맵 및 브랜치 관리 전략

개발 및 유지보수 효율성을 위해 Git 브랜치 전략도 재정비되었습니다.
특히, master 브랜치가 4.0.x 기반으로 전환된 점에 유의해야 합니다.

브랜치 명	대상 버전	용도 및 설명
master	4.0.x	최신 개발 브랜치
3.0.x	3.0.x	Spring Boot 3.x 사용자를 위한 유지보수 브랜치
4.0.x.dev	4.0.x (Pre)	GA 이전 개발 단계에서 사용되었던 임시 브랜치

릴리스 타임라인

• 2025년 8월: MyBatis Spring Boot 4.0.x 개발 착수
• 2025년 9월: Spring Boot 4.0.0-M3 릴리스와 함께 호환성 테스트 진행
• 2025년 11월 21일: Spring Boot 4.0.0 GA 발표
• 2025년 12월 1일: MyBatis Spring Boot 4.0.0 정식 릴리스 완료

---

5. 실무자를 위한 체크리스트

MyBatis Spring Boot 4.0으로의 업그레이드는 단순한 버전 숫자 변경 이상의 의미를 갖습니다. 성공적인 마이그레이션을 위해 다음 사항들을 반드시 점검해 주십시오.

1. Java 버전 확인: Spring Boot 4.x는 최소 Java 21을 요구할 가능성이 높습니다. JDK 버전 업그레이드를 선행하십시오.
2. Deprecated API 점검: mybatis-spring 코어 라이브러리 역시 4.0.0으로 업데이트되면서 제거된 API가 있을 수 있습니다. 컴파일 에러를 사전에 확인하세요.
3. 의존성 트랜지티브 확인: MyBatis 외에도 프로젝트 내의 다른 라이브러리가 Spring Boot 4.x와 호환되는지 mvn dependency:tree 또는 gradle dependencies를 통해 점검해야 합니다.

---

MyBatis Spring Boot 4.0 마이그레이션 체크리스트

카테고리	구분	체크 항목	세부 내용 및 조치 가이드	담당자	상태 (대기/진행/완료)	비고
1. 사전 준비	환경	JDK 버전 확인	Spring Boot 4.x 최소 요구 사항 확인 (예: JDK 21 이상 설치 및 환경변수 설정)
	IDE	IDE 호환성 점검	IntelliJ/Eclipse 최신 버전 업데이트 (Java 최신 문법 및 SB 4.x 지원)
	문서	릴리스 노트 정독	Spring Boot 4.0 & MyBatis Spring Boot 4.0 릴리스 노트 주요 변경점 팀 공유
2. 빌드 설정	Gradle / Maven	Spring Boot 버전 업그레이드	3.x.x → 4.0.0 (Parent POM 또는 Plugin 버전 변경)
	MyBatis	MyBatis Starter 버전 일치	mybatis-spring-boot-starter: 3.0.x → 4.0.0 변경
	의존성	타 라이브러리 호환성 체크	Spring Security, Lombok, DB Driver 등 타 의존성의 4.0 호환 버전 확인 및 동시 업데이트
3. 설정(Config)	YML/Properties	Deprecated 속성 제거	application.yml 내 사라진 설정이나 이름이 변경된 속성 확인 및 수정
	Java Config	MyBatis 커스텀 설정	ConfigurationCustomizer Bean을 활용하여 Java 코드로 설정 이관 (권장)
	DB 연결	DataSource 설정 확인	HikariCP 등 커넥션 풀 설정이 4.x 환경에서 유효한지 재점검
4. 코드 변경	MyBatis	Mapper 스캔 확인	@MapperScan 경로 및 동작 확인, @Mapper 어노테이션 인식 여부 점검
	MyBatis	동적 쿼리(XML) 점검	XML 내 문법 중 파싱 오류가 발생하는지 확인 (DTD 검증 등)
	Network	HTTP Client 교체 (선택)	RestTemplate 사용처 파악 → 신규 RestClient로 리팩토링 검토 (권장사항)
	API	Deprecated API 교체	컴파일 에러가 발생하는 구형 클래스/메서드 신규 API로 교체
5. 테스트	단위 테스트	JUnit 테스트 수행	전체 단위 테스트(@MybatisTest 포함) 수행 및 Pass 확인
	통합 테스트	애플리케이션 기동	로컬 환경에서 서버 정상 기동(BootRun) 여부 및 로그 에러 확인
	기능 검증	주요 비즈니스 로직 검증	CRUD 동작, 트랜잭션 롤백, 예외 처리 등 핵심 기능 수동 테스트

---

정리하며 느낀 점

이번 마이그레이션 가이드를 정리하며 가장 인상 깊었던 점은 MyBatis 팀의 '버전 친화성' 전략이었습니다.
보통 라이브러리들은 독자적인 버전 체계를 가져가기 마련인데, Spring Boot의 메이저 버전에 맞춰 숫자를 일치시킨 점은 개발자 경험을 깊이 고려한 현명한 선택이라고 느껴집니다.
덕분에 "Spring Boot 4니까 MyBatis도 4를 쓰면 된다"는 직관적인 공식이 성립되어, 기술 부채를 해결하는 과정이 한결 명확해졌습니다.
또한, 단순히 호환성만 맞추는 것이 아니라 RestClient 같은 최신 트렌드를 샘플에 반영하며 생태계 변화에 발맞추려는 노력도 엿볼 수 있었습니다.