Mybatis 파라미터 전달 방법 정리(parameterType, @Param)

MyBatis로 SQL을 작성할 때 가장 기본이 되는 개념 중 하나가 파라미터(parameter) 전달 방식입니다.
파라미터를 어떻게 매핑하느냐에 따라 SQL 실행 결과가 달라질 수 있기 때문에, parameterType과 @Param을 올바르게 이해하는 것이 중요합니다.

이번 글에서는 MyBatis에서 파라미터를 전달하는 주요 방법을 정리하겠습니다.

1. MyBatis에서 파라미터 전달 개요

MyBatis에서 SQL에 값을 전달하는 방식은 크게 두 가지로 나눌 수 있습니다.

parameterType을 XML 매퍼에서 선언하는 방법
@Param 어노테이션을 통해 매개변수 이름을 지정하는 방법

두 방식 모두 장단점이 있으며, 상황에 따라 적절히 선택하는 것이 중요합니다.

2. parameterType 속성 활용 방법

매퍼 XML의 <select>, <insert>, <update>, <delete> 태그에서 parameterType 속성을 정의할 수 있습니다.
이때 전달할 객체의 타입을 지정하면, SQL에서 해당 객체의 필드를 사용할 수 있습니다.

예시:

<select id="selectUser" parameterType="User" resultType="User">
  SELECT id, name, email
  FROM users
  WHERE id = #{id}
</select>

자바 코드:

User user = sqlSession.selectOne("selectUser", new User(1));

👉 객체의 프로퍼티명이 XML에서 사용되는 #{id}와 매핑됩니다.

3. @Param 어노테이션 사용법

메서드에 여러 개의 파라미터를 전달할 경우, 기본적으로 MyBatis는 param1, param2와 같은 이름으로 자동 매핑합니다.
이 경우 가독성이 떨어질 수 있는데, @Param을 활용하면 명시적으로 이름을 지정할 수 있습니다.

예시:

@Select("SELECT * FROM users WHERE id = #{id} AND status = #{status}")
User selectUser(@Param("id") int id, @Param("status") String status);

👉 SQL 내에서 #{id}, #{status}와 같이 명확하게 사용할 수 있습니다.

4. 여러 개의 파라미터 처리 방식

여러 개의 파라미터를 전달하는 방법은 크게 3가지입니다.

1. Map 활용

Map<String, Object> params = new HashMap<>();
params.put("id", 1);
params.put("status", "ACTIVE");

sqlSession.selectOne("selectUser", params);

2. DTO/VO 객체 활용

UserSearchCondition condition = new UserSearchCondition(1, "ACTIVE");
sqlSession.selectList("selectUser", condition);

3. @Param 활용 (가장 직관적)

User selectUser(@Param("id") int id, @Param("status") String status);

👉 실무에서는 파라미터 개수와 성격에 따라 DTO 객체나 @Param 방식을 많이 사용합니다.

5. 실무에서 자주 쓰이는 예제

(1) 단일 파라미터 전달

<select id="getUserById" parameterType="int" resultType="User">
  SELECT * FROM users WHERE id = #{id}
</select>

(2) 다중 파라미터 전달(@Param 사용)

@Select("SELECT * FROM users WHERE id = #{id} AND email = #{email}")
User getUser(@Param("id") int id, @Param("email") String email);

(3) Map 활용 예시

<select id="getUserByMap" parameterType="map" resultType="User">
  SELECT * FROM users WHERE id = #{id} AND status = #{status}
</select>

✅ 마무리

MyBatis에서 파라미터를 전달하는 방법은 parameterType 속성, @Param 어노테이션, Map/DTO 객체 활용 등 다양합니다.

단일 파라미터라면 parameterType만으로 충분
다중 파라미터라면 @Param을 통한 명시적 매핑 추천
복잡한 조건은 DTO/VO 객체 활용이 가장 안정적

상황에 따라 유연하게 선택하는 것이 SQL 관리와 유지보수에 큰 도움이 됩니다.

기록기록