[Spring Boot] MyBatis 게시판 구현 중 오류 해결

 

Spring Boot + MyBatis + JSP 기반 게시판 프로젝트를 만들면서 겪었던 오류들을 하나씩 해결했다.

단순히 오류만 수정한 게 아니라:

• Spring Boot와 Spring Framework 관계
• MyBatis가 동작하는 구조
• 버전 충돌 원인
• application.properties 역할
• SqlSession 동작 원리

까지 전체 흐름을 이해할 수 있었다.

특히 오늘 내용은 단순 CRUD보다:

"Spring Boot 내부가 어떻게 돌아가는지"

를 이해하는 데 의미가 컸다.

현재 프로젝트 구조

Controller
 ↓
Service
 ↓
DAO Interface
 ↓
Mapper XML(SQL)
 ↓
Database

사용 기술:

• Spring Boot 2.7.13
• MyBatis
• JSP
• MySQL
• Gradle

1. Spring Boot와 Spring Framework 차이

처음에는 Spring Boot와 Spring Framework를 거의 같은 개념으로 생각했는데 실제로는 다르다.

Spring Framework

실제 스프링 핵심 기능 담당.

예:

• DI
• IOC
• MVC
• Bean 관리
• Transaction

대표 기능:

@Controller
@Service
@Autowired

이런 기능들은 모두 Spring Framework 기능이다.

Spring Boot

Spring Framework를 쉽게 사용하게 만들어주는 플랫폼.

Boot가 하는 일:

• 자동설정(Auto Configuration)
• Starter Dependency 제공
• 버전 호환성 관리
• 내장 Tomcat 제공

예:

implementation 'org.springframework.boot:spring-boot-starter-web'

한 줄만 추가해도:

• Spring MVC
• Tomcat
• JSON 처리
• Logging

등이 자동 추가된다.

2. MyBatis 4.0.1 버전 충돌 오류

발생 오류

ClassNotFoundException:
org.springframework.boot.autoconfigure.service.connection.ConnectionDetails

처음에는 단순 라이브러리 오류인 줄 알았는데,
실제로는 Spring Boot 세대 충돌 문제였다.

원인 분석

현재 프로젝트:

id 'org.springframework.boot' version '2.7.13'

그런데 MyBatis는:

implementation 'org.mybatis.spring.boot:mybatis-spring-boot-starter:4.0.1'

을 사용 중이었다.

문제는:

• MyBatis 4.x → Spring Boot 3+/Framework 6+ 기반
• 현재 프로젝트 → Spring Boot 2.7 / Framework 5 기반

이었다.

즉 MyBatis 4.x가 내부적으로:

ConnectionDetails

라는 Spring Boot 3 계열 클래스를 찾으려 했는데,
Boot 2.7에는 존재하지 않았다.

그래서:

ClassNotFoundException

발생.

해결 방법

MyBatis 버전을 Spring Boot 2.x 세대와 맞게 변경.

수정 전:

implementation 'org.mybatis.spring.boot:mybatis-spring-boot-starter:4.0.1'

수정 후:

implementation 'org.mybatis.spring.boot:mybatis-spring-boot-starter:2.3.1'

그리고:

Gradle → Refresh Gradle Project

실행.

여기서 배운 점

Spring에서는:

ClassNotFoundException

오류가 나오면 대부분:

• 버전 충돌
• dependency 누락
• javax / jakarta 충돌

을 의심해야 한다.

특히:

"없는 클래스 이름"

이 핵심 단서가 된다.

3. MapperRegistry 오류

발생 오류

Type interface com.boot.dao.BbDAO
is not known to the MapperRegistry

원인 분석

MyBatis가 DAO 인터페이스를 Mapper로 등록하지 못한 상태였다.

즉:

BbDAO

를 MyBatis가 인식하지 못했다.

해결 방법

DAO 인터페이스에:

@Mapper
public interface BbDAO {
}

추가.

그리고 mapper XML namespace 확인:

<mapper namespace="com.boot.dao.BbDAO">

namespace와 DAO 전체 경로가 정확히 같아야 한다.

4. JDBC URL 오타 오류

발생 오류

Driver com.mysql.cj.jdbc.Driver claims to not accept jdbcUrl

원인 분석

DB URL 오타였다.

잘못된 코드:

jdbc.mysql://localhost:3306/atom

정상 코드:

jdbc:mysql://localhost:3306/atom

즉:

. → :

오타 문제였다.

5. application.properties 역할 이해

처음에는:

spring.datasource.url=...

이걸 어디서 사용하는지 궁금했다.

결론부터 말하면:

Spring Boot가 서버 시작 시 자동으로 읽는다.

실행 흐름:

SpringApplication.run()
 ↓
application.properties 읽기
 ↓
DataSource 자동 생성
 ↓
MyBatis SqlSession 생성
 ↓
Tomcat / MVC / DB 설정 적용

즉 개발자는 설정만 적고,
실제 객체 생성은 Spring Boot가 자동 처리한다.

6. SqlSession 이해

현재 코드:

@Autowired
private SqlSession sqlSession;

처음에는:

"서버에 있는 SqlSession을 가져오는 건가?"

라고 생각했다.

실제로는:

• Spring Boot + MyBatis가 SqlSession Bean 생성
• Spring Container에 등록
• @Autowired로 주입

하는 구조였다.

즉:

new SqlSession()

을 직접 한 적은 없다.

Spring이 생성해둔 객체를 가져다 쓰는 방식이다.

7. mybatis-config.xml 역할

<configuration>

    <mappers>
        <mapper resource="mybatis/mappers/board.xml"/>
    </mappers>

</configuration>

이 파일은:

"어떤 mapper XML을 사용할지 등록하는 파일"

역할이다.

즉:

board.xml 존재

만으로는 부족하고,
MyBatis에게:

이 mapper 사용할 거야

라고 등록해줘야 한다.

8. Mapper 경로 이해

현재 구조:

src/main/resources
 └─ mybatis
     └─ mappers
         └─ board.xml

Mapper 등록:

<mapper resource="mybatis/mappers/board.xml"/>

여기서:

mybatis/mappers/board.xml

은 Java package가 아니라:

resources 기준 resource path

였다.

즉:

src/main/resources

기준으로 찾는다.

9. 현재 프로젝트 특징

현재 프로젝트는:

Spring Boot + MyBatis + JSP

기반의 전통적인 MVC 구조이다.

특징:

• JSP 사용
• XML SQL 사용
• DAO 패턴 사용
• SqlSession 사용

요즘은:

• React
• JPA
• QueryDSL
• REST API

방식도 많이 사용하지만,

MyBatis 구조를 배우면:

• MVC 흐름
• DB 연결 구조
• Service / DAO 역할

을 이해하는 데 큰 도움이 된다.

특히:

• SI
• 공공 프로젝트
• 유지보수

에서는 아직도 많이 사용하는 방식이다.

오늘 느낀 점

오늘은 단순히 게시판을 만든 게 아니라,

• Spring Boot가 자동설정을 어떻게 하는지
• MyBatis가 어떻게 동작하는지
• 버전 충돌이 왜 나는지
• Spring Container가 객체를 어떻게 관리하는지

흐름 자체를 이해할 수 있었던 게 가장 큰 수확이었다.

특히:

오류 메시지를 읽고 원인을 추론하는 과정

이 생각보다 훨씬 중요하다는 걸 느꼈다.

이제는:

ClassNotFoundException

같은 오류가 나오면:

• 어떤 클래스가 없는지
• 어느 라이브러리 소속인지
• 현재 버전과 호환되는지

먼저 확인하는 습관을 가져야겠다.