⚡
MyBatis-Flex 치트시트

MyBatis-Flex 의존성 설정(Gradle/Maven), 엔티티 매핑, BaseMapper, QueryWrapper, Lambda 동적 쿼리, CTE 재귀 쿼리, 연관관계 및 실무 레퍼런스
#mybatis-flex#mybatis#database#sql#java#kotlin#orm#crud#cte#gradle#maven최종 업데이트: 2026-09-27
MyBatis-Flex 치트시트 핵심 명령어 및 실전 가이드

MyBatis-Flex 의존성 설정(Gradle/Maven), 엔티티 매핑, BaseMapper, QueryWrapper, Lambda 동적 쿼리, CTE 재귀 쿼리, 연관관계 및 실무 레퍼런스
## 1. 프로젝트 의존성 추가 (Gradle & Maven)

> [!NOTE]
> **Spring Boot 버전별 스타터 매핑**
> - **Spring Boot 4.x**: `mybatis-flex-spring-boot4-starter` (Java 17/21+, Spring Boot 4 대응)
> - **Spring Boot 3.x**: `mybatis-flex-spring-boot3-starter` (Java 17+, Jakarta 네임스페이스)
> - **Spring Boot 2.x**: `mybatis-flex-spring-boot-starter` (Java 8/11+, javax 네임스페이스)
> - **APT 프로세서**: `mybatis-flex-processor` (버전 공통, Q-Class 및 TableDef 생성)
> - *주의: 기존 `mybatis-spring-boot-starter`와 중복 선언 시 충돌이 발생할 수 있으므로 flex 스타터만 등록합니다.*

### Gradle (Groovy DSL - `build.gradle`)
```groovy
dependencies {
    // 1) Spring Boot 4.x 스타터 (Spring Boot 4.0 이상 환경)
    implementation 'com.mybatis-flex:mybatis-flex-spring-boot4-starter:1.11.8'

    // 2) Spring Boot 3.x 스타터 (Spring Boot 3.x 사용 시)
    // implementation 'com.mybatis-flex:mybatis-flex-spring-boot3-starter:1.10.6'

    // 3) Spring Boot 2.x 스타터 (Spring Boot 2.x 레거시 사용 시)
    // implementation 'com.mybatis-flex:mybatis-flex-spring-boot-starter:1.10.6'

    // APT 프로세서 (Q-Class 및 TableDef 클래스 자동 생성을 위해 필수)
    annotationProcessor 'com.mybatis-flex:mybatis-flex-processor:1.11.8'

    // Lombok과 함께 사용할 경우 순서: Lombok 선언 후 mybatis-flex-processor 선언
    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'
}
```

### Gradle (Kotlin DSL - `build.gradle.kts`)
```kotlin
dependencies {
    // 1) Spring Boot 4.x 스타터
    implementation("com.mybatis-flex:mybatis-flex-spring-boot4-starter:1.11.8")

    // 2) Spring Boot 3.x 스타터 사용 시
    // implementation("com.mybatis-flex:mybatis-flex-spring-boot3-starter:1.10.6")

    // 3) Spring Boot 2.x 스타터 사용 시
    // implementation("com.mybatis-flex:mybatis-flex-spring-boot-starter:1.10.6")

    // APT 프로세서 (TableDef 자동 생성)
    annotationProcessor("com.mybatis-flex:mybatis-flex-processor:1.11.8")

    // (선택 사항) Kotlin 확장 기능 및 DSL 지원 라이브러리
    implementation("com.mybatis-flex:mybatis-flex-kotlin:1.11.8")
}
```

### Maven (`pom.xml`)
```xml
<dependencies>
    <!-- 1) Spring Boot 4.x 스타터 -->
    <dependency>
        <groupId>com.mybatis-flex</groupId>
        <artifactId>mybatis-flex-spring-boot4-starter</artifactId>
        <version>1.11.8</version>
    </dependency>

    <!-- 2) Spring Boot 3.x 스타터 사용 시 -->
    <!--
    <dependency>
        <groupId>com.mybatis-flex</groupId>
        <artifactId>mybatis-flex-spring-boot3-starter</artifactId>
        <version>1.10.6</version>
    </dependency>
    -->

    <!-- 3) Spring Boot 2.x 스타터 사용 시 -->
    <!--
    <dependency>
        <groupId>com.mybatis-flex</groupId>
        <artifactId>mybatis-flex-spring-boot-starter</artifactId>
        <version>1.10.6</version>
    </dependency>
    -->
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.13.0</version>
            <configuration>
                <annotationProcessorPaths>
                    <!-- Lombok 사용 시 (순서 중요: lombok -> mybatis-flex) -->
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                        <version>${lombok.version}</version>
                    </path>
                    <!-- MyBatis-Flex APT 프로세서 (TableDef 자동 생성) -->
                    <path>
                        <groupId>com.mybatis-flex</groupId>
                        <artifactId>mybatis-flex-processor</artifactId>
                        <version>1.11.8</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>
```

## 2. 엔티티 매핑 & BaseMapper 기본 구조
```java
// 1. 엔티티 정의 (@Table, @Id, @Column)
@Table("tb_user")
@Getter
@Setter
public class User {
    @Id(keyType = KeyType.Auto) // MySQL AUTO_INCREMENT
    private Long id;

    @Column("user_name")
    private String name;

    private Integer age;

    @Column(isLogicDelete = true) // 논리 삭제 컬럼 (조회 시 자동 제외)
    private Boolean isDeleted;

    @Column(version = true) // 낙관적 락 버전 컬럼 (수정 시 자동 +1)
    private Long version;
}

// 2. Mapper 인터페이스 선언 (BaseMapper 상속만으로 기본 CRUD 자동 완성)
public interface UserMapper extends BaseMapper<User> {}
```
```java
// 기본 CRUD 메서드 호출 예시
userMapper.insert(user);             // 단건 등록
userMapper.insertBatch(userList);    // 대량 배치 등록
userMapper.selectOneById(1L);        // PK 단건 조회
userMapper.update(user);             // 단건 수정 (null 필드 제외)
userMapper.deleteById(1L);           // 논리 삭제 또는 물리 삭제
```

## 3. Lambda 기반 Type-Safe 동적 쿼리 (Q-Class 불필요)
```java
// Q-Class나 코드 생성 없이 Java 메서드 참조(Lambda)로 100% Type-Safe 쿼리 작성!
String searchName = "kim";
Integer minAge = 20;

QueryWrapper query = QueryWrapper.create()
    .select(User::getId, User::getName, User::getAge)
    .from(User.class)
    .where(User::getName).like(searchName, hasText(searchName)) // 조건이 true일 때만 WHERE 절 포함
    .and(User::getAge).ge(minAge, minAge != null)               // null-safe 동적 조건
    .orderBy(User::getId).desc();

List<User> users = userMapper.selectListByQuery(query);
```

## 4. APT 테이블 정의(Tables) 활용 (선택 사항)
```java
// APT(Annotation Processor) 설정 시 생성되는 정적 테이블 클래스(USER) 활용 가능
import static com.example.entity.table.UserTableDef.USER;

QueryWrapper query = QueryWrapper.create()
    .select(USER.ID, USER.NAME, USER.AGE)
    .from(USER)
    .where(USER.AGE.between(20, 30))
    .and(USER.NAME.like("Lee"));

List<User> list = userMapper.selectListByQuery(query);
```

## 5. CTE (Common Table Expressions) & 재귀 쿼리 (WITH)
```java
// MyBatis-Flex는 복잡한 계층형 조직도, 카테고리 트리 조회를 위한 재귀 CTE를 네이티브 지원!
QueryWrapper query = QueryWrapper.create()
    .withRecursive("DeptTree")
    .asSelect(
        // Anchor Member (시작 노드)
        select(DEPARTMENT.ALL_COLUMNS)
        .from(DEPARTMENT)
        .where(DEPARTMENT.ID.eq(1L))
        .unionAll(
            // Recursive Member (하위 노드 탐색)
            select(DEPARTMENT.ALL_COLUMNS)
            .from(DEPARTMENT)
            .join("DeptTree").on(DEPARTMENT.PARENT_ID.eq(column("DeptTree.id")))
        )
    )
    .select()
    .from("DeptTree");

List<Department> departments = deptMapper.selectListByQuery(query);
```

## 6. 연관관계 매핑 (@RelationOneToOne / ManyToOne / OneToMany)
```java
@Table("tb_order")
@Getter @Setter
public class Order {
    @Id(keyType = KeyType.Auto)
    private Long id;
    private Long userId;

    // N:1 관계 - 단일 쿼리로 매핑하여 N+1 문제 원천 차단
    @RelationManyToOne(selfField = "userId", targetField = "id")
    private User user;

    // 1:N 관계
    @RelationOneToMany(selfField = "id", targetField = "orderId")
    private List<OrderItem> items;
}
```
```java
// 연관 엔티티까지 함께 조회 (WithRelations 계열 메서드)
Order order = orderMapper.selectOneWithRelationsById(orderId);
List<Order> orders = orderMapper.selectAllWithRelations();
```

## 7. 페이징 & 정렬 (Pagination)
```java
// 1. Page 객체 생성 (페이지 번호는 1부터 시작)
Page<User> page = Page.of(1, 10); // 1페이지, 10건

// 2. 페이징 쿼리 실행 (자동 COUNT 쿼리 + LIMIT/OFFSET 생성)
QueryWrapper query = QueryWrapper.create()
    .where(User::getAge).gt(18)
    .orderBy(User::getId).desc();

Page<User> result = userMapper.paginate(page, query);

// 3. 결과 접근
long totalRow = result.getTotalRow();     // 전체 레코드 수
List<User> records = result.getRecords(); // 현재 페이지 데이터
long totalPage = result.getTotalPage();   // 전체 페이지 수
```

## 8. UpdateChain (안전하고 유연한 조건부 수정)
```java
// 엔티티를 통째로 생성하지 않고 원하는 필드만 즉시 업데이트
boolean success = UpdateChain.of(User.class)
    .set(User::getAge, 25)
    .set(User::getName, "UpdatedName")
    .where(User::getId).eq(100L)
    .update();

// IN 조건 대량 상태 변경
UpdateChain.of(Order.class)
    .set(Order::getStatus, "SHIPPED")
    .where(Order::getId).in(orderIds)
    .update();
```

## 9. 감사(Auditing) & 자동 컬럼 채우기
```java
@Table("tb_article")
@Getter @Setter
public class Article {
    @Id(keyType = KeyType.Auto)
    private Long id;
    private String title;

    // 1. SQL 함수로 인서트/업데이트 시 자동 채우기
    @Column(onInsertValue = "now()")
    private LocalDateTime createdAt;

    @Column(onInsertValue = "now()", onUpdateValue = "now()")
    private LocalDateTime updatedAt;

    // 2. 또는 리스너 등록을 통한 세션 사용자 ID 주입
    @Column(onInsertValue = "sessionUserId()", onUpdateValue = "sessionUserId()")
    private Long updatedBy;
}
```

## 10. Kotlin 지원 (Kotlin Extension & DSL)
```kotlin
// Kotlin에서는 프로퍼티 참조를 활용하여 더욱 직관적으로 작성
val query = query {
    select(User::id, User::name, User::age)
    from(User::class.java)
    where(User::name like "홍%")
    and(User::age ge 20)
    orderBy(User::id.desc())
}

val userList = userMapper.selectListByQuery(query)
```

## 11. Spring Boot 환경설정 (application.yml)
```yaml
mybatis-flex:
  # 1. SQL 실행 로그 출력 (개발 환경)
  configuration:
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
    map-underscore-to-camel-case: true

  # 2. 글로벌 논리 삭제 설정
  global-config:
    logic-delete-column: is_deleted
    logic-deleted-value: 1
    logic-normal-value: 0

  # 3. 콘솔 실행 SQL 포맷팅 및 실행 시간 출력
  logging:
    enable: true
```
💬
MyBatis-Flex 치트시트

의견 및 질문

댓글 수정

댓글 삭제
