MyBatis 기초 가이드 – 설정부터 첫 쿼리까지 완벽 정리
MyBatis는 SQL을 명확하게 제어할 수 있는 Java 기반의 데이터베이스 매퍼 프레임워크입니다. 복잡한 쿼리 작성이 필요한 실무 환경에서 널리 사용되며, JPA보다 더 많은 자유도와 유연성을 제공합니다. 이 글에서는 MyBatis의 설정 구조부터 첫 Select/Insert 쿼리 작성까지 기초적인 흐름을 정리합니다.
1. MyBatis란?
MyBatis는 Java 객체와 SQL 간의 매핑을 쉽게 해주는 프레임워크입니다. 기존 JDBC의 반복적인 코드 문제를 해결하면서도 SQL 작성의 자유로움을 유지합니다.
MyBatis 특징
- SQL 직접 제어 가능 → 복잡한 쿼리에 적합
- XML 또는 어노테이션 기반 매핑 지원
- SQL과 Java 객체 간 명시적 바인딩
- Spring과 쉽게 통합 가능
2. 기본 디렉토리 구조 (Spring Boot 기준)
src/
├─ main/
│ ├─ java/com/example/
│ │ ├─ mapper/UserMapper.java
│ │ └─ model/User.java
│ └─ resources/
│ ├─ mapper/UserMapper.xml
│ └─ application.yml
3. 의존성 설정 (Gradle)
dependencies {
implementation 'org.mybatis.spring.boot:mybatis-spring-boot-starter:2.3.1'
runtimeOnly 'mysql:mysql-connector-java'
}4. application.yml 설정
spring:
datasource:
url: jdbc:mysql://localhost:3306/testdb
username: root
password: 1234
mybatis:
mapper-locations: classpath:mapper/*.xml
type-aliases-package: com.example.model5. 도메인 객체 (User.java)
public class User {
private Long id;
private String name;
private int age;
// Getter, Setter
}6. Mapper 인터페이스 (UserMapper.java)
@Mapper
public interface UserMapper {
User selectUser(Long id);
void insertUser(User user);
}7. Mapper XML (UserMapper.xml)
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper
PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
"http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.example.mapper.UserMapper">
<select id="selectUser" parameterType="long" resultType="User">
SELECT * FROM users WHERE id = #{id}
</select>
<insert id="insertUser" parameterType="User" useGeneratedKeys="true" keyProperty="id">
INSERT INTO users(name, age) VALUES(#{name}, #{age})
</insert>
</mapper>8. 첫 쿼리 실행 예제 (Service or Controller)
@RestController
@RequiredArgsConstructor
public class UserController {
private final UserMapper userMapper;
@PostMapping("/users")
public String saveUser() {
User user = new User();
user.setName("홍길동");
user.setAge(30);
userMapper.insertUser(user);
return "User Saved: ID = " + user.getId();
}
}9. 자주 발생하는 오류
- Mapper XML 경로 오류 → mapper-locations 확인
- 타입 매핑 오류 → resultType 오타
- Mapper interface와 XML의 namespace 불일치
- keyProperty 설정 누락 → insert 후 ID 조회 안됨
10. 결론
MyBatis는 SQL을 명확히 제어하고 싶은 개발자에게 매우 유용한 프레임워크입니다. 이 글에서 다룬 구조를 바탕으로 설정과 쿼리를 구성하면 빠르게 실무에 적용할 수 있습니다. 이후에는 동적 SQL, resultMap, 페이징 처리 등으로 확장하며 숙련도를 높이세요.
