📌”MyBatis 설정도 결국 아키텍처다 – SqlSessionFactory 유틸 설계기”

🗓 2025년 4월 29일

✍️ by 박찬희

---

🧭 배경: MyBatis는 쉽게 쓸 수 있지만, 아무렇게나 써도 된다는 뜻은 아니다

팀 프로젝트에서 JDBC 코드의 반복과 복잡도가 점점 늘어갔다.

그래서 도입한 게 바로 MyBatis였다. XML 기반 매핑이 다소 번거로울 수는 있어도,

SQL 주도 개발, 명확한 트랜잭션 흐름, Mapper 구조의 단순함은 여전히 매력적이다.

하지만 실제로 적용할 때는 단순한 설정 이상의 고려가 필요했다:

고려 포인트	이유
❌ 매번 SqlSessionFactoryBuilder 생성	성능 낭비 + 메모리 누수 가능성
❌ 설정 파일 중복 로딩	테스트와 운영 간 설정 경로 불일치 발생 가능
❌ 스레드 간 세션 충돌	안전하지 않은 인스턴스 사용은 다중 요청 시 치명적
✅ 필요한 건 단 하나	전역에서 공유 가능한 Thread-safe한 SqlSessionFactory 인스턴스

그래서 나는 Singleton 기반의 MyBatis 유틸리티 클래스를 만들기로 했다.

---

🔧 구현: MyBatisUtil 클래스

public class MyBatisUtil {

    private static SqlSessionFactory sqlSessionFactory;

    static {
        try {
            String resource = "model/mapper/mybatis-config.xml";
            InputStream inputStream = Resources.getResourceAsStream(resource);

            sqlSessionFactory = new SqlSessionFactoryBuilder().build(inputStream);  // ⛏ 1회 생성
        } catch (Exception e) {
            e.printStackTrace();
            throw new RuntimeException("SqlSessionFactory 생성 실패: " + e.getMessage());
        }
    }

    public static SqlSessionFactory getSqlSessionFactory() {
        return sqlSessionFactory;  // ✅ 전역 접근 메서드
    }
}

---

🧠 설계 철학 & 기술 고찰

설계 요소	의도
static {} 블록 초기화	클래스 최초 로딩 시 1회 실행 → Lazy Singleton 보장
Resources.getResourceAsStream()	자원 로딩 실패 시 확실한 예외 발생 유도
RuntimeException throw	설정 실패 시 시스템 중단 → 조기 오류 인식 가능
SqlSessionFactory를 캐시	Factory는 Thread-safe → 재사용이 성능상 유리
경로 하드코딩 → 상수화 고려	유지보수성을 위해 추후 외부 config 전환 가능

---

🧪 DAO와의 통합 흐름

try (SqlSession session = MyBatisUtil.getSqlSessionFactory().openSession()) {
    LectureMapper mapper = session.getMapper(LectureMapper.class);
    List<LectureDTO> lectures = mapper.findAll();
}

• 불필요한 팩토리 생성 없이 openSession()만 호출
• Spring 없이도 동작 가능 → 순수 Java MVC 환경에서도 완전 호환
• try-with-resources 구조로 세션 자동 close 처리

---

🧱 설정 파일 구조

<configuration>
  <settings>
    <setting name="mapUnderscoreToCamelCase" value="true"/>
  </settings>
</configuration>

• XML은 src/main/resources 기준으로 위치
• typeAliases, mapper 경로는 내부적으로 확장 가능
• mapUnderscoreToCamelCase: DB 컬럼명이 user_id일 때, DTO 필드를 userId로 매핑

---

🚧 실무 이슈 & 장애 대응

🧨 오류: mybatis-config.xml not found

• 원인: config 파일이 resources가 아닌 다른 경로에 있었음
• 해결: Maven 기준 resources/에 배치하고, 경로는 classpath 기준으로 작성

🧨 오류: SqlSessionFactory is null

• 원인: 정적 초기화가 트리거되지 않음 (JVM이 클래스 로딩을 아직 하지 않음)
• 해결: DAO 첫 호출 전에 강제적으로 MyBatisUtil.getSqlSessionFactory() 호출

---

🔐 확장 가능성과 리팩토링 방향

기능	방향
Spring 전환	SqlSessionFactoryBean을 사용하되, 구조는 동일
다중 DB 구성	getFactory(String dbName) 방식으로 팩토리 인스턴스 분기
로그 최적화	SLF4J + log4jdbc.log4j2.properties 연동 시 쿼리 출력 가능
Mapper 자동 등록	설정 파일에서 <mappers> 노드로 모듈별 XML 자동 인식

---

💬 시니어 개발자가 주목할 키워드

키워드	핵심 메시지
SqlSessionFactory	MyBatis에서 세션을 생성하는 핵심 객체, Thread-safe
Singleton 패턴	Java의 static block으로 구현한 Lazy Initialization
Resources.getResourceAsStream	안전한 설정 파일 로딩 방식
설정 단일화	mybatis-config.xml 위치 변경 시 단 1곳만 수정
Spring 없는 구조	프레임워크 독립적으로도 ORM 적용 가능

---

🧾 실제 DAO 예시

public class LectureDAO {
  public List<LectureDTO> getAllLectures() {
    try (SqlSession session = MyBatisUtil.getSqlSessionFactory().openSession()) {
      return session.selectList("LectureMapper.findAll");
    }
  }
}

• 의존성 없음
• 단위 테스트 가능
• 트랜잭션 명시적으로 관리 가능

---

✅ 결과 & 회고

“ORM은 단순히 라이브러리 쓰는 문제가 아니라, 아키텍처 수준의 결정이다.”

이번 MyBatisUtil 유틸은 단순한 설정 코드 이상의 가치를 지닌다.

• 전역 팩토리 접근 → 성능/자원 절약
• 명확한 로딩 지점 → 오류 발생 시점 고립
• Spring 미사용 환경에서도 테스트/운영 모두 커버 가능