Mapper 관리 전략 (XML vs 주석 기반)

1. XML 기반 Mapper 관리

개념

• SQL을 .xml 파일에 따로 작성
• Java 인터페이스와 매핑(namespace 일치)

예시

UserMapper.java

public interface UserMapper {
    User findById(int id);
}

 

UserMapper.xml

<mapper namespace="com.example.mapper.UserMapper">
  <select id="findById" resultType="User">
    SELECT * FROM users WHERE id = #{id}
  </select>
</mapper>

---

장점

• 복잡한 SQL (동적 조건, 조인, 페이징 등) 작성이 편함
• SQL 별도 관리 → 쿼리 수정 시 Java 코드 변경 불필요
• SQL 재사용 가능 (<sql>, <include>)
• DBA, SQL 최적화 담당자와 협업 용이

단점

• 파일 관리 필요 (xml 따로 관리해야 함)
• 간단한 CRUD에도 XML을 따로 만들어야 해서 번거로울 수 있음

---

2. 어노테이션(주석) 기반 Mapper 관리

개념

• SQL을 Java 인터페이스 안에 어노테이션으로 작성
• @Select, @Insert, @Update, @Delete 사용

예시

@Mapper
public interface UserMapper {

    @Select("SELECT * FROM users WHERE id = #{id}")
    User findById(int id);

    @Insert("INSERT INTO users (name, email) VALUES (#{name}, #{email})")
    void insert(User user);
}

---

장점

• 빠른 개발 (XML 파일 불필요)
• 소스코드와 SQL이 같이 있어 관리가 편리
• 간단한 CRUD 작업에 매우 적합
• 프로토타입, 소규모 서비스에서 유리

단점

• 복잡한 동적 SQL 작성이 매우 불편 (<if>, <where>, <choose> 같은 복잡한 조건을 지원하지 않음)
• SQL 길어지면 코드 가독성 급격히 하락
• SQL 재사용 어려움

---

XML vs 주석 기반 비교 정리

구분	XML 방식	어노테이션 방식
SQL 위치	외부 XML 파일	Java 인터페이스 내부
가독성	복잡한 쿼리에 강함	간단한 쿼리에 강함
유지보수성	SQL 수정이 쉽고 안정적	간단한 경우 빠름
대규모 프로젝트	추천 ✅	제한적
소규모/프로토타입	가능	추천 ✅
복잡한 동적 SQL	지원 잘 됨	비효율적

---

실전 추천 전략

상황	추천 방식
간단한 CRUD만 필요 (ex. 관리자 페이지)	주석 기반 (@Select 등)
다양한 조건 검색, 복잡한 동적 SQL 필요	XML 기반
팀 규모가 크고, SQL 담당자 따로 있음	XML 기반 (SQL 관리 분리)
스타트업, 빠른 MVP 제작	어노테이션 기반 (개발 속도 중시)

---

마무리

실제 프로젝트에서는 혼용도 가능합니다.

• 간단한 CRUD는 어노테이션
• 복잡한 검색 기능은 XML

이렇게 혼용하면 유지보수성과 생산성을 모두 챙길 수 있어요!