읽기는 유연하게, 쓰기는 안전하게 다룹니다
게시글 목록 화면에는 검색 조건이 여럿 있습니다. 제목 키워드, 작성자, 상태를 고를 수 있고, 아무것도 고르지 않으면 전체가 나와야 합니다. 조건이 세 개면 조합이 여덟 가지입니다. SQL을 여덟 개 쓸 수는 없으니 값이 있는 조건만 WHERE에 붙는 SQL이 필요합니다. 이것이 동적 SQL입니다.
Chapter의 후반은 다른 문제를 다룹니다. 계좌 이체처럼 SQL 두 개가 하나의 업무를 이룰 때, 중간에 실패해도 데이터가 어긋나지 않게 묶는 트랜잭션입니다.
이 Chapter에서 만드는 것
| 만드는 것 | 설명 |
|---|---|
| 게시글 검색 API | 키워드, 작성자, 상태(복수), 정렬을 조합하는 동적 SQL |
| JOIN 결과 매핑 | 글과 작성자를 중첩 객체로, 사용자와 글 목록을 1:N 목록으로 |
| 페이징 응답 | items, page, size, totalElements, totalPages |
| 이체 서비스 | 두 UPDATE를 하나의 트랜잭션으로 묶고 여러 설정을 비교 |
| 감사 기록 서비스 | 실패해도 남는 REQUIRES_NEW 기록 |
| 테스트 36건 | 동적 SQL 22건(ch10), 트랜잭션 14건(ch11) |
이 Chapter의 구조와 파일 지도
이 Chapter는 두 예제 모듈을 씁니다.
| 절 | 예제 모듈 | 핵심 파일 |
|---|---|---|
| “값이 있는 조건만 이어 붙이기”부터 “동적 SQL 오류와 해결 방법”까지 (동적 SQL, JOIN, 페이징) | examples/ch10-dynamic-sql |
PostMapper(+XML), PostSearch, PostSummary, UserWithPosts, PageResponse, PostService, PostController |
| “이체는 두 UPDATE가 한 덩어리여야 합니다”부터 “이체 API 확인과 트랜잭션 오류 진단”까지 (트랜잭션) | examples/ch11-transaction |
AccountMapper, AuditMapper, TransferService, AuditService, TransferController, TransactionTests |
전반부는 “읽기 SQL을 유연하게”, 후반부는 “쓰기를 안전하게”가 주제입니다. 후반부의 @Transactional 프록시 함정은 Chapter 18의 AOP로 이어집니다.
사전 지식과 준비물
- Chapter 08의 Mapper, XML,
resultMap,#{}. - Chapter 06의 검증, 오류 응답.
- 코드는
examples/ch10-dynamic-sql과examples/ch11-transaction입니다.
확인 환경
실행 결과는 컨테이너에서 JAR로 직접 실행해 얻었고, 트랜잭션 시나리오는 테스트 14건으로 확인했습니다. H2 기준이며 Windows 실행은 검증하지 못했습니다.
예제 코드
| 대상 | 링크 |
|---|---|
| 동적 SQL 모듈 | ch10-dynamic-sql/ |
| 트랜잭션 모듈 | ch11-transaction/ |
| Mapper XML | PostMapper.xml |
| 검색 조건 | PostSearch.java |
| 시드 데이터 | data.sql |
| Mapper 테스트 | PostMapperTests.java |
| 결과 타입 | PostSummary.java |
| 결과 타입 | UserWithPosts.java |
| 서비스 | PostService.java |
| 페이지 응답 | PageResponse.java |
| 컨트롤러 | PostController.java |
| API 테스트 | PostApiTests.java |
| 이체 서비스 | TransferService.java |
| Mapper | AccountMapper.java |
| 스키마 | schema.sql |
| 트랜잭션 테스트 | TransactionTests.java |
| 감사 서비스 | AuditService.java |
| 감사 Mapper | AuditMapper.java |
| 컨트롤러 | TransferController.java |
| API 테스트 | TransferApiTests.java |
값이 있는 조건만 이어 붙이기
검색 조건이 여러 개이고 모두 선택 사항일 때 SQL을 조건 조합마다 따로 쓰면 끝이 없습니다. MyBatis의 동적 SQL은 값이 있는 조건만 WHERE에 붙이는 SQL을 XML 태그로 만들게 해 줍니다.
검색 조건 객체
검색 조건은 record 하나로 모았습니다.
public record PostSearch(String keyword, Long authorId, List<String> statuses, String sort) { }
keyword: 제목에 포함된 글자(선택)authorId: 작성자 id(선택)statuses: 상태 목록. 공개(PUBLISHED), 임시저장(DRAFT), 보관(ARCHIVED) 중 여러 개(선택)sort: 정렬 기준(선택, 아래 “안전한 정렬: choose와 허용 목록” 절)
XML
<sql id="searchConditions">
<where>
<if test="cond.keyword != null and cond.keyword != ''">
AND p.title LIKE CONCAT('%', #{cond.keyword}, '%')
</if>
<if test="cond.authorId != null">
AND p.author_id = #{cond.authorId}
</if>
<if test="cond.statuses != null and !cond.statuses.isEmpty()">
AND p.status IN
<foreach collection="cond.statuses" item="status" open="(" separator="," close=")">
#{status}
</foreach>
</if>
</where>
</sql>
주요 코드 설명
<if test="...">: 조건식이 참일 때만 안의 SQL을 붙입니다.cond.keyword는 Mapper 메서드의cond파라미터(@Param("cond"))의keyword속성입니다. 빈 문자열도 “조건 없음”으로 취급하려고!= ''를 함께 검사했습니다. 화면에서 입력 칸을 비우면 빈 문자열이 오기 때문입니다.<where>: 안쪽에 내용이 하나라도 있을 때만WHERE를 붙이고, 맨 앞의AND를 알아서 지웁니다. 그래서 첫 조건에도AND를 적어도 됩니다. 조건이 하나도 없으면WHERE자체가 생략됩니다.LIKE CONCAT('%', #{cond.keyword}, '%'): 부분 일치 검색입니다. 값은#{}로 바인딩합니다.LIKE에 들어가는%와_문자의 이스케이프는 이 Chapter에서 처리하지 않았습니다.<foreach collection="cond.statuses" item="status" open="(" separator="," close=")">: 목록을('PUBLISHED','DRAFT')꼴로 펼칩니다.open과close는 앞뒤 괄호,separator는 구분자입니다.
조건 조각을 공유한다
목록 조회와 전체 건수 조회는 같은 조건을 써야 합니다. 그래서 조건을 <sql>로 만들고 두 쿼리에서 <include>로 가져옵니다.
조건을 한 곳에만 두면 목록과 건수가 어긋나는 일을 막을 수 있습니다. 조건을 고칠 때도 한 곳만 고치면 됩니다.
조합을 바꿔 보니 의도대로 걸러졌다
시드 데이터는 사용자 3명, 글 12건입니다. 테스트로 여러 조합을 확인했습니다.
| 조건 | 결과 |
|---|---|
| 조건 없음 | 12건, 최신 id 순 |
| 빈 키워드, 빈 상태 목록 | 조건 없음과 같은 12건 |
키워드 Spring |
id 12, 8, 4, 1 |
| 작성자 1 | id 5, 4, 3, 2, 1 |
상태 PUBLISHED |
7건 |
상태 PUBLISHED, DRAFT |
10건 |
키워드 Spring + 상태 PUBLISHED |
id 8, 4, 1 |
키워드 없는제목 |
0건, 빈 목록 |
조건이 하나도 없을 때, 조건 둘이 AND로 합쳐질 때, 아무것도 안 맞을 때가 모두 한 XML 조각으로 처리됩니다. 빈 문자열과 빈 목록을 “조건 없음”으로 취급하는 동작도 확인했습니다.
만들어진 SQL을 로그로 확인하기
동적 SQL은 최종 SQL이 코드에 보이지 않습니다. 이 절의 서버(examples/ch10-dynamic-sql)를 Mapper 로그 수준을 낮춰 실행하면 MyBatis가 만든 SQL이 그대로 출력됩니다.
./gradlew :examples:ch10-dynamic-sql:bootRun --args='--logging.level.com.jqdom.curriculum.ch10.PostMapper=DEBUG'
curl "http://localhost:8080/posts?keyword=Spring&status=PUBLISHED&status=DRAFT&size=2"
실제로 출력된 로그입니다.
PostMapper.count : ==> Preparing: SELECT COUNT(*) FROM posts p WHERE p.title LIKE CONCAT('%', ?, '%') AND p.status IN ( ? , ? )
PostMapper.count : ==> Parameters: Spring(String), PUBLISHED(String), DRAFT(String)
PostMapper.search: ==> Preparing: SELECT p.id, p.title, p.status, u.id AS author_id, u.name AS author_name FROM posts p JOIN users u ON u.id = p.author_id WHERE p.title LIKE CONCAT('%', ?, '%') AND p.status IN ( ? , ? ) ORDER BY p.id DESC OFFSET ? ROWS FETCH NEXT ? ROWS ONLY
PostMapper.search: ==> Parameters: Spring(String), PUBLISHED(String), DRAFT(String), 0(Integer), 2(Integer)
읽는 법:
WHERE ... AND ...:<where>가 첫 조건 앞의AND를 지우고WHERE를 붙인 결과입니다.IN ( ? , ? ):<foreach>가statuses두 개를?두 개로 펼친 결과입니다.count와search의WHERE부분이 똑같습니다.<sql>조각을 두 쿼리가 공유하기 때문입니다.- 값은 모두
?로 바인딩되고Parameters:줄에 따로 나옵니다.
조건 없이 GET /posts를 호출하면 count는 SELECT COUNT(*) FROM posts p처럼 WHERE 없이 실행됩니다. 로그는 동적 SQL이 의도대로 조립되는지 확인하는 가장 확실한 방법이고, 이 방법은 아래 “동적 SQL 오류와 해결 방법” 절의 오류 확인에도 쓰입니다.
확인 문제
- 조건이 하나도 없을 때
<where>는 무엇을 하나요? - 목록 쿼리와 건수 쿼리가 같은 조건을 쓰게 하는 방법은 무엇인가요?
답: 1) WHERE 자체를 생략합니다. 2) 조건을 <sql>로 정의하고 두 쿼리에서 <include>로 가져옵니다.
직접 해 보기
PostMapperTests에서 키워드Spring과 작성자 1을 함께 줘서 결과가 어떻게 되는지 예측하고 확인하세요.<where>를 지우고<if>만 남기면 어떤 SQL이 만들어질지 적어 보세요(“동적 SQL 오류와 해결 방법” 절의 오류 1에서 실제 결과를 확인합니다).- 상태 목록에 하나만 넣었을 때
IN ('PUBLISHED')가 되는지 로그로 확인하세요(logging.level설정이 필요할 수 있습니다).
안전한 정렬: choose와 허용 목록
검색 화면에는 정렬 선택도 있습니다. “제목순”, “최신순”처럼 사용자가 고르면 SQL의 ORDER BY가 바뀌어야 합니다. 그런데 ORDER BY 뒤는 값이 아니라 컬럼 이름이라 #{}를 쓸 수 없습니다. 이 절에서는 ${}의 유혹을 피하고 허용 목록으로 처리하는 방법을 봅니다.
왜 #{}를 못 쓰나
Chapter 08에서 #{}는 ?로 바뀐다고 했습니다. ORDER BY ?로 바인딩하면 컬럼 이름이 아니라 상수 문자열로 취급되어 정렬이 되지 않습니다. 이름 자체를 바꿔야 하는 자리는 문자열로 이어 붙이는 ${}만 가능하지만, 사용자 입력을 그대로 ${sort}에 넣으면 SQL 주입 통로가 됩니다.
허용 목록으로 고른다
<choose>
<when test="cond.sort == 'title'">ORDER BY p.title ASC, p.id DESC</when>
<otherwise>ORDER BY p.id DESC</otherwise>
</choose>
주요 코드 설명
<choose>: 여러 조건 중 하나만 선택하는 태그입니다. 자바의if / else if / else와 비슷합니다.<when test="cond.sort == 'title'">: 입력이 정확히'title'일 때만 제목순입니다.<otherwise>: 나머지 모든 경우(모르는 값, 빈 값 포함)는 기본인 최신 id 순입니다.- SQL 문장은 XML에 고정되어 있고 입력은 어느 분기로 갈지만 정합니다. 입력이 SQL의 일부가 되지 않습니다.
주입 시도도 확인했다
@Test
void unknownSortFallsBackToDefaultInsteadOfBeingInjected() {
PostSearch hostile = cond(null, null, null, "id; DROP TABLE posts");
assertEquals(12L, ids(hostile).get(0)); // 기본 정렬(최신 id 순)
assertEquals(12, mapper.count(cond(null, null, null, null))); // 테이블이 남아 있다
}
id; DROP TABLE posts 같은 값을 sort로 보내도 <otherwise>로 가서 기본 정렬이 적용되고, 테이블은 그대로 남아 있습니다. 허용 목록 방식에서는 입력이 SQL로 해석될 경로 자체가 없기 때문입니다. cond(...)와 ids(...)는 테스트 안의 작은 도우미 메서드입니다. 정렬 동작(sortByTitleUsesWhitelist)과 주입 시도(unknownSortFallsBackToDefaultInsteadOfBeingInjected) 두 가지를 테스트가 모두 확인합니다.
정렬 방식 비교
| 방식 | 안전한가 | 비고 |
|---|---|---|
ORDER BY ${sort} |
위험 | 입력이 SQL이 됨 |
ORDER BY #{sort} |
동작하지 않음 | 상수 문자열로 취급 |
<choose> 허용 목록 |
안전 | 새 정렬은 <when>을 추가 |
자바에서 허용 목록 검사 후 ${} |
가능하나 실수 위험 | 검사를 빠뜨리면 위험 |
정렬 키는 하나만 두지 말고 마지막에 고유 키를 덧붙입니다. 정렬 기준이 같은 행들의 순서가 보장되지 않으면 요청마다 순서가 달라져 페이지 경계에서 중복이나 누락이 생길 수 있어서, 이 예제는 제목순에도 p.id DESC를 붙였습니다.
왜 이름 자리에는 바인딩이 안 될까
데이터베이스는 SQL을 실행하기 전에 문장 구조를 먼저 해석합니다. 어떤 테이블에서 어떤 컬럼을 어떻게 정렬할지는 이 단계에서 정해지고, ?에 들어갈 값은 그 뒤에 따로 전달됩니다.
그래서 ORDER BY ?에 'title'을 바인딩하면 컬럼 title로 정렬되는 것이 아니라 모든 행에 같은 상수가 붙은 것처럼 되어 정렬이 의미를 잃습니다. 컬럼 이름은 문장 구조의 일부이므로 ${}로 이어 붙이거나 <choose>로 구조 자체를 고르는 수밖에 없고, 이 절은 후자를 택했습니다.
악성 입력이 어떻게 처리되는지 로그로 확인
curl "http://localhost:8080/posts?sort=id%3B%20DROP%20TABLE%20posts&size=1"
sort에 id; DROP TABLE posts를 보낸 요청을 Mapper 로그로 보면 이렇게 실행됩니다.
PostMapper.search: ==> Preparing: SELECT p.id, p.title, p.status, u.id AS author_id, u.name AS author_name FROM posts p JOIN users u ON u.id = p.author_id ORDER BY p.id DESC OFFSET ? ROWS FETCH NEXT ? ROWS ONLY
입력은 SQL에 전혀 들어가지 않고 <otherwise>의 기본 정렬 ORDER BY p.id DESC로 처리되었습니다. 응답도 200입니다. 알 수 없는 정렬 값을 오류(400)로 돌려줄지 기본값으로 처리할지는 설계 선택이고, 이 Chapter는 기본값을 택했습니다.
확인 문제
<choose>방식이 안전한 이유를 한 문장으로 설명해 보세요.- 새 정렬 기준(작성자순)을 추가하려면 XML의 어디를 고쳐야 하나요?
답: 1) 입력은 어느 분기로 갈지만 정하고, 실행되는 SQL 문장은 XML에 고정되어 있기 때문입니다. 2) <choose>에 <when test="cond.sort == 'author'">ORDER BY u.name ASC, p.id DESC</when>를 추가합니다.
직접 해 보기
<when>을 하나 더 추가해sort=author로 작성자 이름순 정렬을 지원해 보세요.- 컨트롤러에서
sort파라미터를 열거형(enum)으로 받으면 어떤 점이 더 안전해지는지 적어 보세요. 이 Chapter는 문자열로 받았습니다. - 공격 문자열 대신
sort=TITLE(대문자)을 보냈을 때 기본 정렬로 가는지 확인하세요.
JOIN 결과를 중첩 객체로 묶기
게시글 목록 한 행에는 글 정보와 함께 작성자의 id와 이름이 필요합니다. 글 테이블과 사용자 테이블을 JOIN해 한 번에 읽고, 작성자 컬럼은 중첩 객체로 묶습니다. 이 절에서는 record를 결과 타입으로 쓰는 <constructor> 매핑과, 처음 빌드에서 만난 타입 오류를 봅니다.
결과 타입
public record PostSummary(long id, String title, String status, Author author) {
public record Author(long id, String name) { }
}
한 행의 컬럼이 두 객체로 나뉘어 담기고, 안쪽 객체(Author)가 바깥 객체(PostSummary)의 인자로 들어갑니다.
글 정보와 작성자(중첩 record)입니다. Chapter 08에서는 setter 클래스를 썼는데, 여기서는 값을 바꿀 일이 없는 조회 전용 결과라서 record를 씁니다.
resultMap
<resultMap id="postSummaryMap" type="PostSummary">
<constructor>
<idArg column="id" javaType="_long"/>
<arg column="title" javaType="string"/>
<arg column="status" javaType="string"/>
<arg resultMap="authorMap" javaType="com.jqdom.curriculum.ch10.PostSummary$Author"/>
</constructor>
</resultMap>
작성자 중첩 객체를 만드는 authorMap과 JOIN SQL은 이렇습니다.
<resultMap id="authorMap" type="com.jqdom.curriculum.ch10.PostSummary$Author">
<constructor>
<idArg column="author_id" javaType="_long"/>
<arg column="author_name" javaType="string"/>
</constructor>
</resultMap>
<select id="search" resultMap="postSummaryMap">
SELECT p.id, p.title, p.status, u.id AS author_id, u.name AS author_name
FROM posts p
JOIN users u ON u.id = p.author_id
<include refid="searchConditions"/>
...
</select>
u.id AS author_id,u.name AS author_name: 글의id와 사용자의id가 컬럼 이름이 겹치므로 별칭으로 구분합니다.authorMap은 이 별칭을 읽습니다.JOIN users u ON u.id = p.author_id: 글의 작성자 id로 사용자 테이블을 이어 붙입니다. 이 JOIN은 INNER JOIN이라 작성자가 없는 글은 결과에서 빠집니다.
주요 코드 설명
<constructor>: record는 setter가 없으므로 생성자 인자로 값을 넘깁니다. 인자의 순서와 타입이 record의 생성자와 맞아야 합니다.<idArg>,<arg>: 생성자 인자입니다.idArg는 행을 구분하는 키 인자입니다.<arg resultMap="authorMap" ...>: 이 인자는 다른resultMap(authorMap)의 결과, 즉 작성자 중첩 객체입니다. 이 방식으로 JOIN한 컬럼들이Author하나로 묶입니다.- 중첩 record의 클래스 이름은
PostSummary$Author처럼$로 바깥 클래스와 이어 씁니다.
처음 빌드가 실패했다
처음 만든 XML에서 javaType="long"이라고 썼더니 빌드가 실패했습니다.
ReflectionException: Error instantiating class com.jqdom.curriculum.ch10.PostSummary$Author with invalid types (Long,String) or values (3,park).
Cause: java.lang.NoSuchMethodException: com.jqdom.curriculum.ch10.PostSummary$Author.<init>(java.lang.Long,java.lang.String)
생성자는 (long, String)인데 MyBatis는 (Long, String)을 찾았습니다. XML에서 javaType="long"이라고 쓰면 MyBatis가 이 별칭을 래퍼 타입 Long으로 해석하기 때문입니다. 기본형 long을 가리키려면 javaType="_long"을 써야 합니다.
| XML 표기 | 의미 |
|---|---|
long |
java.lang.Long (래퍼) |
_long |
기본형 long |
int |
java.lang.Integer (래퍼) |
_int |
기본형 int |
string |
java.lang.String |
메시지에 찾으려 한 생성자의 인자 타입 (java.lang.Long,java.lang.String)이 적혀 있어서 원인을 곧바로 알 수 있었습니다. 바꾸자 JOIN 결과가 그대로 매핑되었습니다.
PostSummary first = mapper.search(cond, 0, 1).get(0);
assertEquals(new PostSummary(12, "Spring 배포", "ARCHIVED", new PostSummary.Author(3, "park")), first);
record는 equals를 자동으로 만들어 주기 때문에 객체 전체를 한 번에 비교할 수 있습니다. 한 줄로 글, 상태, 작성자 중첩 객체까지 검증합니다.
따라 하기
curl "http://localhost:8080/posts?size=1"
응답의 첫 항목에 글 정보와 함께 author 중첩 객체({"id":3,"name":"park"})가 있으면 성공입니다. 시드 데이터에서 최신 글(id 12)의 작성자가 park입니다.
확인 문제
- record 결과에
<constructor>를 쓰는 이유는 무엇인가요? long과_long은 XML에서 어떻게 다르게 해석되나요?
답: 1) record에는 setter가 없어 값을 생성자 인자로만 넘길 수 있기 때문입니다. 2) long은 래퍼 java.lang.Long, _long은 기본형 long입니다.
직접 해 보기
javaType="_long"을"long"으로 바꿔 위 오류를 재현해 보세요. 확인 후 되돌립니다.Author에email필드를 추가하면authorMap과 SQL의 어디를 고쳐야 할지 적어 보세요.- 이 JOIN이 INNER인지 LEFT인지 XML에서 확인하고, 작성자가 없는 글이 있다면 어떻게 될지 예측해 보세요.
1:N을 목록으로 묶기
앞의 “JOIN 결과를 중첩 객체로 묶기” 절은 글 하나에 작성자 하나(N:1)였습니다. 반대로 사용자 한 명에 글 여러 건이 붙는 1:N 관계도 많습니다. JOIN하면 사용자 정보가 글 수만큼 반복되는데, 이를 하나의 사용자 객체와 글 목록으로 묶는 것이 collection입니다.
결과 타입
public class UserWithPosts {
private long id;
private String name;
private List<PostTitle> posts = new ArrayList<>();
public record PostTitle(long id, String title) { }
// getter, setter ...
}
UserWithPosts는 setter가 있는 클래스입니다. 목록(posts)에 글을 하나씩 채워 넣어야 하는데, record는 만든 뒤에 값을 바꿀 수 없기 때문입니다. 목록의 원소(PostTitle)는 조회 전용이라 record입니다.
resultMap
<resultMap id="userWithPostsMap" type="UserWithPosts">
<id property="id" column="user_id"/>
<result property="name" column="user_name"/>
<collection property="posts" ofType="com.jqdom.curriculum.ch10.UserWithPosts$PostTitle">
<constructor>
<idArg column="post_id" javaType="_long"/>
<arg column="post_title" javaType="string"/>
</constructor>
</collection>
</resultMap>
주요 코드 설명
<id property="id" column="user_id"/>: 사용자를 구분하는 키입니다. 같은user_id를 가진 여러 행이 하나의UserWithPosts로 합쳐집니다.<collection property="posts" ofType="...">: 합쳐진 객체의posts목록에 행마다 글 하나씩을 채웁니다.ofType은 목록 원소의 타입입니다.- 목록의 원소 안에서
<constructor>로 record를 만듭니다. 컬럼 이름(user_id,post_id등)은 SQL에서AS로 구분해 둔 별칭입니다.
JOIN SQL은 사용자에서 시작해 글을 LEFT JOIN합니다.
<select id="findUserWithPosts" resultMap="userWithPostsMap">
SELECT u.id AS user_id, u.name AS user_name, p.id AS post_id, p.title AS post_title
FROM users u
LEFT JOIN posts p ON p.author_id = u.id
WHERE u.id = #{userId}
ORDER BY p.id
</select>
LEFT JOIN이라 글이 없는 사용자도 결과에 남습니다. ORDER BY p.id로 글이 id 순서로 목록에 담깁니다.
실행 결과
GET /users/3/posts
-> 200 {"id":3,"name":"park","posts":[{"id":10,"title":"Docker 입문"},{"id":11,"title":"CI 정리"},{"id":12,"title":"Spring 배포"}]}
한 사용자와 글 세 건이 하나의 JSON으로 묶여 나옵니다. 없는 사용자는 null을 돌려주고 컨트롤러가 404로 바꿉니다.
@Test
void missingUserIsNull() {
assertNull(mapper.findUserWithPosts(999));
}
JOIN 결과가 객체가 되는 과정
사용자 3번에게 글이 세 개라면 JOIN은 사용자 정보가 반복된 세 행을 돌려줍니다. MyBatis는 <id>로 지정한 컬럼 값이 같은 행을 한 객체로 합치고, 나머지 컬럼은 <collection>에 하나씩 채웁니다.
| user_id | user_name | post_id | post_title |
|---|---|---|---|
| 3 | park | 10 | Docker 입문 |
| 3 | park | 11 | CI 정리 |
| 3 | park | 12 | Spring 배포 |
<id>는 “이 컬럼이 같으면 같은 객체”라는 기준입니다. 이 표시가 없으면 MyBatis는 매핑된 모든 컬럼으로 행을 구분하므로 행마다 다른 객체로 취급될 수 있어, 합치기가 기대와 다르게 동작할 수 있습니다.
N+1이란
GET /users/3/posts처럼 한 사용자만 읽을 때는 JOIN 한 번이면 충분합니다. 그런데 사용자 목록을 읽고 각 사용자의 글을 따로 조회하면, 예를 들어 사용자 100명을 쿼리 1번으로 읽은 뒤 사용자마다 글 조회 쿼리를 1번씩 더 보내 모두 101번(1 + N)의 쿼리가 나갑니다.
이것이 N+1 문제입니다. 사용자 수만큼 쿼리가 늘어 사용자가 많아질수록 느려집니다. 쿼리 한 번으로 사용자와 모든 글을 읽는 이 절의 JOIN 방식이 이를 피하는 한 가지 방법입니다. 대신 JOIN은 데이터가 반복되고 페이징이 까다로워진다는 단점이 있어, 용도에 맞게 고릅니다. 사용자와 글을 두 쿼리로 나눠 읽는 방식과의 비교는 이 Chapter에서 다루지 않았습니다.
따라 하기
curl http://localhost:8080/users/3/posts # 사용자 1명 + 글 3건
curl -i http://localhost:8080/users/999/posts # 404
확인 문제
- 1:N JOIN에서 부모 컬럼이 반복되는 이유는 무엇인가요?
- 사용자가 글이 없을 때
posts는 어떻게 나올까요?
답: 1) 자식 행마다 한 행이 만들어지고 부모 컬럼은 각 행에 복사되기 때문입니다. 2) LEFT JOIN이므로 사용자는 남고, 글 컬럼이 null인 행 하나가 만들어집니다. 목록 매핑에서 이 행이 어떻게 처리되는지는 실제로 호출해 보고 확인해 보세요.
직접 해 보기
GET /users/1/posts를 호출해 글 5건이 id 순서로 모두 나오는지 확인하세요. 작성자 1의 글은 5건이고, 테스트(collectionGroupsPostsUnderOneUser)는 첫 글이Spring Boot 시작인 것까지 검증합니다.- 글이 하나도 없는 사용자가 있다면
posts가 빈 배열인지null인지 관찰하세요(시드 데이터에는 없으므로 직접 추가해 봅니다). <id>를 지우면 같은 사용자가 글 수만큼 중복되는지 관찰해 보세요. 확인 후 되돌립니다.
페이징과 전체 건수
글이 수천 건이면 한 번에 모두 내려 줄 수 없습니다. 화면에는 한 페이지 분량만 보여 주고, “전체 몇 건, 몇 페이지”를 함께 알려 줘야 합니다. 이 절에서는 OFFSET 페이징과 전체 건수를 한 응답으로 묶는 방법을 봅니다.
OFFSET과 FETCH
OFFSET #{offset} ROWS FETCH NEXT #{limit} ROWS ONLY
요청이 오면 PostService.search가 먼저 count 쿼리로 총 건수를 셉니다. 0이면 search를 건너뛰고 빈 목록을, 1 이상이면 search 쿼리로 해당 페이지(예: page=1&size=5면 OFFSET 5 ROWS FETCH NEXT 5 ROWS)를 가져와 PageResponse로 묶습니다. 건수를 먼저 세는 이유는 전체 페이지 수를 응답에 담기 위해서이고, 0건이면 목록 쿼리를 아낄 수 있기 때문입니다.
OFFSET n ROWS는 앞의 n건을 건너뛰고, FETCH NEXT m ROWS ONLY는 그다음 m건만 가져옵니다. 표준 SQL이어서 H2와 Oracle 12c 이상에서 같은 문장으로 동작합니다. #{offset}, #{limit}은 값이므로 #{}로 바인딩합니다.
| 페이지(0부터) | 크기 | offset | 가져오는 범위 |
|---|---|---|---|
| 0 | 5 | 0 | 1~5번째 |
| 1 | 5 | 5 | 6~10번째 |
| 2 | 5 | 10 | 11~15번째 |
offset = page * size입니다. 12건을 5건씩 자르는 테스트가 이 계산을 확인합니다.
@Test
void offsetAndLimitSlicePages() {
PostSearch all = cond(null, null, null, null);
assertEquals(List.of(12L, 11L, 10L, 9L, 8L), mapper.search(all, 0, 5).stream().map(PostSummary::id).toList());
assertEquals(List.of(7L, 6L, 5L, 4L, 3L), mapper.search(all, 5, 5).stream().map(PostSummary::id).toList());
assertEquals(List.of(2L, 1L), mapper.search(all, 10, 5).stream().map(PostSummary::id).toList());
}
마지막 페이지에는 나머지 2건만 있습니다.
서비스와 응답 객체
public PageResponse<PostSummary> search(PostSearch cond, int page, int size) {
long total = mapper.count(cond);
// 총 건수가 0이면 목록 조회를 건너뛴다.
var items = total == 0 ? List.<PostSummary>of() : mapper.search(cond, page * size, size);
return PageResponse.of(items, page, size, total);
}
/** 페이지 번호는 0부터 시작한다. */
public record PageResponse<T>(List<T> items, int page, int size, long totalElements, int totalPages) {
public static <T> PageResponse<T> of(List<T> items, int page, int size, long totalElements) {
int totalPages = (int) ((totalElements + size - 1) / size);
return new PageResponse<>(items, page, size, totalElements, totalPages);
}
}
주요 코드 설명
- 쿼리가 둘입니다. 먼저
count로 조건에 맞는 전체 건수를 세고, 그다음search로 해당 페이지만 가져옵니다. 두 쿼리는 “값이 있는 조건만 이어 붙이기” 절의<sql>조각으로 같은 조건을 공유합니다. - 전체 건수가 0이면 목록 쿼리를 건너뜁니다. 불필요한 쿼리를 피합니다.
totalPages = (totalElements + size - 1) / size: 올림 나눗셈입니다. 12건을 3건씩이면 4페이지, 12건을 5건씩이면 3페이지입니다. 0건이면 0페이지입니다.PageResponse<T>: 제네릭이라 어떤 목록에도 쓸 수 있습니다. Chapter 06의ApiResponse<T>와 같은 아이디어입니다.
컨트롤러와 입력 제한
@GetMapping("/posts")
public PageResponse<PostSummary> search(
@RequestParam(required = false) String keyword,
@RequestParam(required = false) Long authorId,
@RequestParam(name = "status", required = false) List<String> statuses,
@RequestParam(required = false) String sort,
@RequestParam(defaultValue = "0") @Min(0) int page,
@RequestParam(defaultValue = "5") @Min(1) @Max(50) int size) {
return service.search(new PostSearch(keyword, authorId, statuses, sort), page, size);
}
@RequestParam(name = "status") List<String> statuses:status=PUBLISHED&status=DRAFT처럼 같은 이름을 반복하면 목록으로 받습니다.@Min(0) int page,@Min(1) @Max(50) int size: Chapter 06의 인자 제약입니다.size가 0이거나 51이면 400입니다. 한 번에 너무 많은 건수를 요청하는 것을 막는 안전장치입니다.
경계 확인
GET /posts?size=3
-> 200 {"items":[{"id":12,...},{"id":11,...},{"id":10,...}],"page":0,"size":3,"totalElements":12,"totalPages":4}
GET /posts?keyword=none
-> 200 {"items":[],"page":0,"size":5,"totalElements":0,"totalPages":0}
GET /posts?size=0
-> 400 {"timestamp":"2026-10-17T04:38:16.752Z","status":400,"error":"Bad Request","path":"/posts"}
끝을 넘어선 페이지는 빈 목록에 전체 건수를 그대로 돌려줍니다(pageBeyondEndIsEmptyButKeepsTotals 테스트). 이 Chapter는 이를 오류가 아니라 정상 응답으로 정했습니다.
OFFSET 방식의 한계
OFFSET은 앞의 건수를 건너뛰기 위해 데이터베이스가 그만큼 읽어야 하므로, 큰 오프셋(수만 번째 페이지)에서는 느려질 수 있습니다. 이 한계와 대안(마지막으로 본 키를 기준으로 이어 읽는 keyset 방식)은 이 Chapter에서 다루지 않았고, Chapter 18의 배치에서 keyset 페이징을 다시 만납니다.
따라 하기
curl "http://localhost:8080/posts?size=5&page=0" # 5건, totalPages 3
curl "http://localhost:8080/posts?size=5&page=2" # 마지막 페이지 2건
curl "http://localhost:8080/posts?size=5&page=9" # 끝을 넘음: items 빈 배열, totalElements 12 유지
curl -i "http://localhost:8080/posts?size=0" # 400
curl -i "http://localhost:8080/posts?size=51" # 400
확인 문제
- 12건을 5건씩 나누면 총 몇 페이지이고, 마지막 페이지에는 몇 건이 있나요?
- 끝을 넘은 페이지를 오류로 하지 않고 빈 목록으로 돌려주는 선택의 장점은 무엇인가요?
답: 1) 3페이지이고 마지막 페이지(2)에는 2건이 있습니다. 2) 클라이언트가 마지막 페이지를 넘겨 호출해도 총 건수를 알 수 있어 화면 처리가 단순해집니다.
직접 해 보기
GET /posts?size=5&page=2로 마지막 페이지의 2건과totalPages를 확인하세요.GET /posts?page=10을 호출해 빈 목록과totalElements가 함께 오는지 확인하세요.- 총 건수 계산식
(total + size - 1) / size를total / size로 바꾸면 12건, size 5에서totalPages가 어떻게 되는지 예측하세요(바꾸지 말고 계산만).
검색 API 실행과 테스트 22건
동적 SQL, JOIN 매핑, 페이징을 각각 봤으니 서버를 실행해 전체 응답을 확인하고, 테스트 22건이 무엇을 고정하는지 정리합니다.
실행
| OS | 실행 | 이 모듈만 빌드 |
|---|---|---|
| Linux / macOS | ./gradlew :examples:ch10-dynamic-sql:bootRun |
./gradlew :examples:ch10-dynamic-sql:build |
| Windows | gradlew.bat :examples:ch10-dynamic-sql:bootRun |
gradlew.bat :examples:ch10-dynamic-sql:build |
GET /posts?keyword=Spring&status=PUBLISHED
-> 200 {"items":[{"id":8,"title":"Spring Security 노트",...},{"id":4,...},{"id":1,...}],"page":0,"size":5,"totalElements":3,"totalPages":1}
GET /posts?status=PUBLISHED&status=DRAFT&sort=title&size=3&page=1
-> 200 {"items":[{"id":2,"title":"MyBatis 정리",...},{"id":1,"title":"Spring Boot 시작",...},{"id":8,"title":"Spring Security 노트",...}],"page":1,"size":3,"totalElements":10,"totalPages":4}
GET /users/3/posts
-> 200 {"id":3,"name":"park","posts":[{"id":10,"title":"Docker 입문"},{"id":11,"title":"CI 정리"},{"id":12,"title":"Spring 배포"}]}
- 첫 요청은 키워드와 상태 조건이
AND로 합쳐져 3건(id 8, 4, 1)입니다. - 둘째 요청은 상태 두 개를 목록으로 받고 제목순으로 정렬한 두 번째 페이지입니다. 전체 10건을 3건씩이라 4페이지입니다.
- 셋째 요청은 1:N 중첩 응답입니다.
items의...은 지면을 위해 줄인 표기입니다.
테스트 22건
| 테스트 클래스 | 건수 | 고정하는 약속 |
|---|---|---|
Ch10ApplicationTests |
1 | 컨텍스트가 뜬다 |
PostMapperTests |
13 | 조건 조합, 빈 값 처리, foreach, 정렬 허용 목록, OFFSET, JOIN 중첩 매핑, collection |
PostApiTests |
8 | 페이지 메타데이터, 마지막·끝 넘은 페이지, 반복 파라미터, 조합 검색, 400, 중첩 응답, 404 |
Mapper 테스트는 데이터베이스 SQL을 바로 검증하고, API 테스트는 파라미터 변환과 응답 모양을 검증합니다. 두 층으로 나누면 SQL이 틀린 것인지 컨트롤러 설정이 틀린 것인지 바로 구분됩니다.
./gradlew :examples:ch10-dynamic-sql:build
22건이 모두 통과했습니다.
따라 하기
./gradlew :examples:ch10-dynamic-sql:test를 실행해 22건 통과를 확인합니다.- 확인용 조합을 직접 호출합니다.
curl "http://localhost:8080/posts?keyword=Spring&status=PUBLISHED"
curl "http://localhost:8080/posts?status=PUBLISHED&status=DRAFT&sort=title&size=3&page=1"
curl "http://localhost:8080/users/3/posts"
- 이 절의 응답(id 8, 4, 1 / 제목순 두 번째 페이지 / 사용자 3과 글 세 건)과 같은지 비교합니다.
확인 문제
- 이 Chapter의 검색 API 하나가 함께 처리하는 것은 무엇인가요?
- Mapper 테스트와 API 테스트를 나누면 어떤 점이 좋은가요?
답: 1) AND 조합, 반복 파라미터, 정렬, 페이징을 함께 처리합니다. 2) 테스트가 실패했을 때 SQL 쪽 문제인지 API 쪽 문제인지 원인을 좁히기 쉽습니다.
직접 해 보기
- 서버를 켜고
keyword,authorId,status,sort,page,size를 다양하게 조합해 응답이 위 실행 결과와 맞는지 확인하세요. PostApiTests에authorId=2로 검색하는 테스트를 추가해 보세요.- Mapper 테스트와 API 테스트가 각각 어떤 종류의 실수를 먼저 잡아 줄지 한 문장씩 적어 보세요.
동적 SQL 오류와 해결 방법
동적 SQL은 만들어진 SQL을 눈으로 볼 수 없어서 오류가 한 단계 뒤에서 나옵니다. 아래는 이 예제에서 같은 실수를 일부러 만들어 얻은 메시지입니다. 망가뜨린 코드는 되돌렸습니다.
오류 1: WHERE 없이 AND로 시작한다
<where> 태그를 빼고 <if>만 남기면, 조건이 있을 때 SQL이 AND로 시작합니다. 22건 중 4건이 실패했습니다.
JdbcSQLSyntaxErrorException: Syntax error in SQL statement "SELECT COUNT(*) FROM posts p ... [*]AND p.title LIKE ..."
조건이 있는 요청만 실패한다는 점이 단서입니다. 조건 없는 요청은 WHERE도 AND도 없어 통과합니다. <where>는 맨 앞의 AND를 지우고 조건이 없으면 WHERE를 생략합니다.
오류 2: IN 절의 괄호가 없다
<foreach>에서 open="(" close=")"를 빼면 IN a, b가 됩니다.
JdbcSQLSyntaxErrorException: Syntax error in SQL statement "... WHERE p.title LIKE CONCAT('%', ?, '%') AND p.status IN [*]?, ? ..."
오류 메시지의 [*] 표시가 문법이 깨진 지점입니다. IN 바로 뒤에 괄호 없이 ?, ?가 이어진 것이 보입니다.
오류 3: Error evaluating expression — 속성 이름이 다르다
<if test="cond.status != null ...">처럼 PostSearch에 없는 이름(status)을 쓰면 요청이 들어올 때마다 실패합니다. 22건 중 16건이 실패했습니다.
BuilderException: Error evaluating expression 'cond.status != null and !cond.status.isEmpty()'. Cause: org.apache.ibatis.ognl.NoSuchPropertyException: com.jqdom.curriculum.ch10.PostSearch.status
test의 이름은 컴파일 때 검사되지 않아 실행해 봐야 압니다. 메시지가 존재하지 않는 속성(PostSearch.status)을 알려 주므로 실제 필드 이름(statuses)과 비교합니다.
오류 4: Error instantiating class with invalid types
record에 값을 넣는 생성자 매핑에서 javaType="_long"을 "long"으로 바꾸면 값이 있는데도 생성자를 못 찾습니다. 12건이 실패했습니다.
ReflectionException: Error instantiating class com.jqdom.curriculum.ch10.PostSummary with invalid types (Long,String,String,Author) or values (12,Spring 배포,ARCHIV...
메시지 앞의 타입 목록 (Long,String,String,Author)이 단서입니다. record는 기본형 long을 받는데 Long으로 찾았기 때문입니다. 기본형 인자에는 _long, _int처럼 밑줄을 붙입니다(“JOIN 결과를 중첩 객체로 묶기” 절).
오류가 의심될 때 가장 먼저 할 일: 최종 SQL 보기
동적 SQL 오류는 “만들어진 SQL이 무엇인가”를 알면 대부분 풀립니다. Mapper의 로그 수준을 DEBUG로 올리면 최종 SQL과 바인딩 값이 출력됩니다.
./gradlew :examples:ch10-dynamic-sql:bootRun --args='--logging.level.com.jqdom.curriculum.ch10.PostMapper=DEBUG'
정상일 때의 모습은 “값이 있는 조건만 이어 붙이기” 절에서 확인했습니다. 오류가 났다면 로그의 Preparing: 줄을 읽어 WHERE 뒤가 AND로 시작하는지, IN 뒤에 괄호가 있는지를 바로 알 수 있습니다.
오류별 따라 하기
| 실험 | 확인할 것 |
|---|---|
XML에서 <where>를 빼고 keyword를 넣어 호출 |
조립된 SQL이 AND로 시작해 구문 오류 |
<foreach>의 open, close를 지움 |
IN ? , ?처럼 괄호가 없는 SQL |
test="cond.status != null"로 오타 |
요청마다 Error evaluating expression |
세 실험 모두 확인 후 반드시 되돌리고 ./gradlew :examples:ch10-dynamic-sql:test로 22건이 통과하는지 확인합니다.
증상별 점검표
| 증상 | 가장 먼저 볼 것 |
|---|---|
조건이 있을 때만 AND 구문 오류 |
<where> 태그 |
IN 뒤 구문 오류 |
foreach의 open, close |
Error evaluating expression |
test 안의 속성 이름 |
Error instantiating class with invalid types |
javaType (_long 등 기본형 표기) |
직접 해 보기
- 오류 1~4를 복사본에서 하나씩 만들어 실패 건수를 직접 세어 보세요. 확인 후 되돌립니다.
- 오류 3의 메시지에서 “존재하지 않는 속성” 이름을 찾아
PostSearch의 실제 필드와 대조해 보세요. - 동적 SQL을 수정한 뒤 어떤 조합을 반드시 테스트해야 하는지 목록을 만들어 보세요(조건 없음, 하나, 여러 개, 맞는 결과 없음).
다음 “이체는 두 UPDATE가 한 덩어리여야 합니다” 절부터는 데이터를 안전하게 바꾸는 주제, 트랜잭션입니다.
이체는 두 UPDATE가 한 덩어리여야 합니다
계좌 이체는 두 줄이면 됩니다. 보내는 쪽에서 빼고, 받는 쪽에 더합니다. 그런데 받는 계좌가 없어서 두 번째 줄이 실패했다면 첫 번째 줄은 어떻게 될까요? 트랜잭션이 없을 때 직접 실행해 봤습니다. “출금은 됐는데 입금이 안 된” 상태를 이 절에서 직접 만나고 해결합니다.
트랜잭션이란
트랜잭션은 여러 작업을 하나로 묶어 모두 성공하거나 모두 취소되게 하는 단위입니다. 변경을 확정하는 것을 커밋, 되돌리는 것을 롤백이라고 합니다.
두 UPDATE가 하나의 단위로 묶입니다. 둘 중 하나라도 실패하면 처음 상태로 되돌아갑니다.
Chapter 08까지의 CRUD는 한 번에 SQL 하나만 실행해서 문제가 없었습니다. 둘 이상의 SQL이 하나의 업무를 이룰 때 트랜잭션이 필요해집니다.
이체 예제
테이블은 계좌와 감사 기록 두 개입니다. 시드로 alice에 1000, bob에 500을 넣었습니다.
CREATE TABLE accounts (
id BIGINT PRIMARY KEY,
owner VARCHAR(50) NOT NULL,
balance BIGINT NOT NULL,
CONSTRAINT chk_balance CHECK (balance >= 0)
);
CHECK (balance >= 0)은 잔액이 음수가 되는 것을 데이터베이스가 막는 제약입니다. Mapper의 두 쿼리는 영향받은 행 수로 성공을 알립니다.
/** 잔액이 충분할 때만 차감한다. 반환값 0은 계좌가 없거나 잔액이 부족하다는 뜻이다. */
@Update("UPDATE accounts SET balance = balance - #{amount} WHERE id = #{id} AND balance >= #{amount}")
int withdraw(@Param("id") long id, @Param("amount") long amount);
@Update("UPDATE accounts SET balance = balance + #{amount} WHERE id = #{id}")
int deposit(@Param("id") long id, @Param("amount") long amount);
withdraw:WHERE ... AND balance >= #{amount}로 잔액이 충분할 때만 차감합니다. 조건이 맞지 않으면 0행이 갱신되어 0을 돌려줍니다.deposit: 계좌가 없으면 0행이 갱신되어 0입니다.
서비스의 공통 동작은 출금 후 입금이고, 어느 쪽이 0행이면 예외를 던집니다.
private void move(long from, long to, long amount) {
if (accounts.withdraw(from, amount) == 0) {
throw new InsufficientFundsException(from, amount);
}
if (accounts.deposit(to, amount) == 0) {
throw new AccountNotFoundException(to);
}
}
영향받은 행 수를 읽는 패턴이 여기서 쓰입니다. 이 move를 호출하는 메서드를 트랜잭션 설정만 바꿔 여러 개 만들었습니다.
가장 기본: 있을 때와 없을 때
/** 정상 경로. 두 UPDATE가 하나의 트랜잭션이라 함께 성공하거나 함께 취소된다. */
@Transactional
public void transfer(long from, long to, long amount) {
move(from, to, amount);
}
/** 트랜잭션이 없으면 출금은 이미 커밋되고, 입금 실패는 되돌려지지 않는다. */
public void transferWithoutTransaction(long from, long to, long amount) {
move(from, to, amount);
}
@Transactional을 메서드에 붙이면 Spring이 메서드 시작에 트랜잭션을 열고, 정상 종료하면 커밋, 예외가 나면 롤백합니다. 각 시나리오 전에 alice 1000, bob 500으로 초기화하고 300을 보냈습니다.
| 시나리오 | 상황 | 결과 |
|---|---|---|
@Transactional 정상 |
출금, 입금 모두 성공 | alice 700, bob 800 (커밋) |
@Transactional, 잔액 부족 |
5000을 보냄 | 둘 다 그대로 (예외) |
@Transactional, 없는 계좌 |
입금 대상 99 | alice 1000 (출금이 롤백됨) |
| 트랜잭션 없음, 없는 계좌 | 입금 대상 99 | alice 700 (돈이 사라짐) |
네 번째 줄이 문제 상황입니다. 트랜잭션이 없으면 출금은 이미 커밋된 뒤라서 입금이 실패해도 되돌릴 수 없습니다. 같은 입력에 @Transactional만 붙인 세 번째 줄은 출금이 롤백되어 alice가 1000으로 남습니다.
테스트 설계
/**
* 테스트 메서드에 @Transactional을 붙이지 않는다.
* 붙이면 테스트 전체가 하나의 트랜잭션이 되어 서비스의 커밋/롤백 경계를 확인할 수 없다.
*/
@SpringBootTest
class TransactionTests {
// ...
}
Chapter 08에서는 테스트에 @Transactional을 붙여 롤백으로 격리했습니다. 여기서는 반대로 붙이지 않습니다. 서비스의 커밋과 롤백 경계 자체를 확인하는 테스트이기 때문입니다. 대신 각 테스트 전에 @BeforeEach로 잔액을 원래 값으로 초기화합니다.
따라 하기
examples/ch11-transaction을bootRun으로 켭니다. 시드는 alice 1000, bob 500입니다.- 정상 이체와 실패 이체를 보냅니다.
curl -i -X POST http://localhost:8080/transfers -H "Content-Type: application/json" \
-d '{"from":1,"to":2,"amount":300}' # 200, alice 700, bob 800
curl -i -X POST http://localhost:8080/transfers -H "Content-Type: application/json" \
-d '{"from":1,"to":2,"amount":9999}' # 409, INSUFFICIENT_FUNDS
- 두 번째 요청 뒤에도 잔액이 그대로인지 확인합니다.
용어 정리
| 용어 | 의미 |
|---|---|
| 트랜잭션 | 모두 성공하거나 모두 취소되는 작업 단위 |
| 커밋 | 변경을 확정 |
| 롤백 | 변경을 모두 취소 |
| 원자성 | 트랜잭션이 “전부 아니면 전무”로 동작하는 성질 |
확인 문제
@Transactional이 없을 때 출금 후 입금이 실패하면 alice의 잔액은 어떻게 되나요?CHECK (balance >= 0)제약이 있는데WHERE balance >= #{amount}조건도 두는 이유는 무엇인가요?
답: 1) 출금이 이미 커밋되었으므로 줄어든 채로 남습니다(돈이 사라짐). 2) DB 제약은 마지막 방어선이고, 조건은 부족한 경우를 일반 흐름(행 수 0)으로 처리해 업무 예외로 바꾸기 위해서입니다.
직접 해 보기
transfer(1, 2, 300)후 alice와 bob의 잔액이 700, 800인지GET /accounts/1로 확인하세요.transferWithoutTransaction으로 없는 계좌 99에 보내 alice가 700이 되는 것을 확인하세요. 돈이 사라지는 상황입니다.withdraw의AND balance >= #{amount}조건을 지우면 잔액 부족 시 어떻게 될지 예측하세요.CHECK제약이 막는 동작을 같이 생각해 보세요.
롤백 규칙: 런타임 예외와 체크 예외
@Transactional을 붙였다고 모든 예외에서 롤백되는 것은 아닙니다. 예외의 종류에 따라 롤백 여부가 달라집니다. 이 절에서는 두 UPDATE가 끝난 뒤 예외가 났을 때의 결과를 비교합니다. 가장 놀라운 결과는 체크 예외에서 롤백되지 않는다는 점입니다.
두 종류의 예외
| 구분 | 예 | 컴파일러 처리 강제 | @Transactional 기본 동작 |
|---|---|---|---|
| 런타임 예외 | IllegalStateException, NullPointerException |
없음 | 롤백 |
| 체크 예외 | IOException, SQLException |
throws/try-catch 강제 |
롤백하지 않음(커밋) |
@Transactional은 기본적으로 RuntimeException과 Error에서만 롤백합니다. 체크 예외는 “예상 가능한 업무 흐름”으로 보고 롤백하지 않는 것이 스프링의 기본 입장입니다.
시나리오 세 가지
/** 두 UPDATE가 모두 끝난 뒤 런타임 예외가 나면 둘 다 롤백된다. */
@Transactional
public void transferThenFail(long from, long to, long amount) {
move(from, to, amount);
throw new IllegalStateException("이체 후 후속 작업 실패");
}
/** 체크 예외는 기본 설정에서 롤백하지 않는다. 커밋되어 돈이 이동한 채로 남는다. */
@Transactional
public void transferThenCheckedFailure(long from, long to, long amount) throws IOException {
move(from, to, amount);
throw new IOException("외부 시스템 통지 실패");
}
/** rollbackFor로 체크 예외도 롤백 대상에 넣는다. */
@Transactional(rollbackFor = Exception.class)
public void transferThenCheckedFailureWithRollbackFor(long from, long to, long amount) throws IOException {
move(from, to, amount);
throw new IOException("외부 시스템 통지 실패");
}
세 메서드 모두 이체(move)가 끝난 뒤 예외를 던집니다. 즉 돈이 이미 이동한 상태에서 후속 작업이 실패한 상황입니다.
| 시나리오 | 예외 | 결과 |
|---|---|---|
@Transactional |
IllegalStateException (런타임) |
둘 다 그대로 (롤백) |
@Transactional |
IOException (체크) |
alice 700, bob 800 (커밋됨) |
@Transactional(rollbackFor = Exception.class) |
IOException (체크) |
둘 다 그대로 (롤백) |
두 번째 줄은 가장 놀라웠습니다. 두 UPDATE가 끝난 뒤 체크 예외가 났는데 돈이 이동한 채로 커밋되었습니다. 외부 시스템 통지가 실패했으니 이체도 취소되길 기대했지만, 기본 규칙은 그렇게 동작하지 않았습니다.
테스트가 이 결과를 고정한다
@Test
void checkedExceptionDoesNotRollBackByDefault() {
assertThrows(IOException.class, () -> service.transferThenCheckedFailure(1, 2, 300));
assertEquals(700, balance(1));
assertEquals(800, balance(2));
}
@Test
void rollbackForMakesCheckedExceptionRollBack() {
assertThrows(IOException.class, () -> service.transferThenCheckedFailureWithRollbackFor(1, 2, 300));
assertEquals(1000, balance(1));
assertEquals(500, balance(2));
}
예외는 두 경우 모두 호출한 쪽으로 올라옵니다(assertThrows). 하지만 잔액은 다릅니다. 예외가 올라왔다는 것과 롤백되었다는 것은 별개입니다.
어떻게 대응할까
- 업무에서 체크 예외를 던지며 롤백도 원한다면
rollbackFor = Exception.class를 명시합니다. - 더 단순한 방법은 업무 예외를
RuntimeException을 상속해 만드는 것입니다. Chapter 06의BusinessException이RuntimeException을 상속한 이유와도 이어집니다. - 어느 쪽이든 돈이 오가는 흐름에는 잔액을 직접 단정하는 테스트가 있어야 합니다. 예외 타입만 검사하는 테스트는 이 실수를 잡지 못합니다.
따라 하기
TransactionTests에서 세 시나리오를 실행하고 잔액 단정을 확인합니다.
./gradlew :examples:ch11-transaction:test --tests '*TransactionTests*'
테스트는 위 “시나리오 세 가지” 표의 결과를 잔액(alice, bob)으로 단정합니다. 런타임 예외와 rollbackFor를 지정한 체크 예외는 1000, 500으로 롤백되고, 기본 설정의 체크 예외만 700, 800으로 커밋됩니다.
확인 문제
- 체크 예외를 던지는
@Transactional메서드가 롤백되게 하는 방법 두 가지는 무엇인가요? - 예외가 호출자에게 올라왔다는 사실과 롤백되었다는 사실은 같은가요?
답: 1) rollbackFor = Exception.class를 지정하거나, 업무 예외를 RuntimeException으로 만듭니다. 2) 같지 않습니다. 이 절의 체크 예외 시나리오처럼 예외가 올라와도 커밋될 수 있습니다.
직접 해 보기
transferThenCheckedFailure에서@Transactional에rollbackFor를 추가하고 잔액이 어떻게 되는지 확인하세요. 확인 후 되돌립니다.- 던지는 예외를
IOException대신UncheckedIOException(런타임)으로 바꾸면rollbackFor없이도 롤백되는지 확인해 보세요. rollbackFor = IOException.class처럼 구체적인 타입을 지정하면IllegalStateException은 여전히 롤백되는지 예측해 보세요. 이 Chapter에서는 실행하지 않았습니다.
실패해도 남아야 하는 기록: REQUIRES_NEW
이체가 롤백되더라도 “이체를 시도했다”는 감사 기록은 남아야 합니다. 이체와 같은 트랜잭션에 기록하면 이체와 함께 롤백되어 기록도 사라지기 때문입니다. 이때는 기록을 별도 트랜잭션에서 커밋하는 REQUIRES_NEW를 씁니다.
전파: 이미 트랜잭션이 있을 때
@Transactional 메서드가 다른 @Transactional 메서드를 부르면 안쪽 메서드는 바깥 트랜잭션을 어떻게 다룰까요? 이것을 정하는 설정이 전파입니다.
| 전파 | 동작 |
|---|---|
REQUIRED (기본) |
바깥 트랜잭션이 있으면 참여하고 없으면 새로 만듭니다. |
REQUIRES_NEW |
바깥 트랜잭션을 잠시 멈추고 새 트랜잭션에서 실행해 따로 커밋합니다. |
감사 서비스
@Service
public class AuditService {
private final AuditMapper mapper;
public AuditService(AuditMapper mapper) {
this.mapper = mapper;
}
@Transactional(propagation = Propagation.REQUIRES_NEW)
public void recordInNewTransaction(String message) {
mapper.insert(message);
}
/** 기본 전파(REQUIRED): 바깥 트랜잭션이 있으면 거기에 참여한다. */
@Transactional
public void recordJoiningCaller(String message) {
mapper.insert(message);
}
}
recordInNewTransaction:REQUIRES_NEW라 호출될 때 새 트랜잭션을 열고 INSERT 후 바로 커밋합니다.recordJoiningCaller: 기본 전파라 바깥 트랜잭션에 참여합니다. 바깥이 롤백되면 이 기록도 함께 롤백됩니다. 두 메서드는 비교용입니다.
이체 서비스에서 호출하기
/** 다른 Bean의 REQUIRES_NEW 메서드를 호출한다. 감사 기록은 이체가 롤백되어도 남는다. */
@Transactional
public void transferWithAuditInNewTransaction(long from, long to, long amount) {
audit.recordInNewTransaction("이체 시도 from=" + from + " to=" + to + " amount=" + amount);
move(from, to, amount);
throw new IllegalStateException("롤백을 일으키기 위한 실패");
}
순서는 이렇습니다. 감사 기록(별도 커밋) → 이체 → 예외로 롤백. 감사 서비스는 다른 Bean(AuditService)이어서 Spring의 프록시를 거칩니다.
@Test
void requiresNewAuditSurvivesOuterRollback() {
assertThrows(IllegalStateException.class, () -> service.transferWithAuditInNewTransaction(1, 2, 300));
assertEquals(1000, balance(1));
assertEquals(List.of("이체 시도 from=1 to=2 amount=300"), audits.findAll());
}
잔액은 그대로(이체 롤백)이고 감사 기록은 남았습니다(별도 커밋). 이체가 실패해도 “시도했다”는 사실이 남는 것입니다.
어디에 쓰나
- 실패해도 남겨야 하는 감사 기록, 실패 로그
- 바깥 트랜잭션의 성공 여부와 무관한 독립 작업
주의할 점도 있습니다. REQUIRES_NEW는 새 DB 연결을 하나 더 쓰므로 커넥션 풀을 더 소모합니다. 풀이 작으면 바깥이 연결을 쥔 채 안쪽이 새 연결을 기다리는 교착 상황이 생길 수 있습니다. 이 Chapter에서는 이 위험을 재현하지 않았습니다.
두 방식의 차이를 한눈에
| 감사 기록의 전파 | 감사 기록이 실행되는 곳 | 바깥 이체가 롤백되면 |
|---|---|---|
REQUIRED (기본) |
이체 트랜잭션에 참여 | 이체와 감사 기록 모두 취소 |
REQUIRES_NEW |
이체 트랜잭션을 일시 정지하고 새 트랜잭션에서 즉시 커밋 | 이체만 취소, 감사 기록은 남음 |
따라 하기
TransactionTests의 두 테스트를 비교합니다.
./gradlew :examples:ch11-transaction:test --tests '*TransactionTests*'
| 테스트 | 이체 결과 | 감사 기록 |
|---|---|---|
requiresNewAuditSurvivesOuterRollback |
롤백(잔액 그대로) | 남음 |
| 같은 트랜잭션에 참여하는 비교 메서드 | 롤백 | 사라짐 |
확인 문제
- 감사 기록이 이체와 같이 롤백되면 안 되는 이유는 무엇인가요?
REQUIRES_NEW가 커넥션 풀에 주는 부담은 무엇인가요?
답: 1) 이체가 실패해도 “시도했다”는 기록이 남아야 추적할 수 있기 때문입니다. 2) 바깥 트랜잭션이 연결을 쥔 채 안쪽이 새 연결을 하나 더 쓰므로, 풀이 작으면 안쪽이 연결을 기다리는 상황이 생길 수 있습니다.
직접 해 보기
recordInNewTransaction을recordJoiningCaller로 바꿔 호출하면 감사 기록이 사라지는지 확인하세요. 확인 후 되돌립니다.REQUIRES_NEW메서드가 예외를 던지면 바깥 이체에 어떤 영향이 있을지 예측해 보세요.- 실제 서비스에서 “실패해도 남아야 하는 기록”에 해당하는 예를 두 가지 적어 보세요.
같은 클래스 안에서 부르면 무시됩니다
앞의 “실패해도 남아야 하는 기록: REQUIRES_NEW” 절에서 본 REQUIRES_NEW를 이체 서비스 안의 다른 메서드가 this로 호출하면 어떻게 될까요? 가장 조심해야 할 함정입니다. 코드는 멀쩡해 보이는데 감사 기록이 사라집니다. 원인은 Spring이 @Transactional을 적용하는 방식, 프록시에 있습니다.
같은 코드, 다른 결과
@Transactional
public void transferWithSelfInvokedAudit(long from, long to, long amount) {
auditInNewTransaction("이체 시도 from=" + from + " to=" + to + " amount=" + amount); // 같은 Bean 안의 호출
move(from, to, amount);
throw new IllegalStateException("롤백을 일으키기 위한 실패");
}
@Transactional(propagation = Propagation.REQUIRES_NEW)
public void auditInNewTransaction(String message) {
// 프록시를 거치지 않은 내부 호출이라 이 애노테이션은 적용되지 않는다.
audit.recordJoiningCaller(message);
}
“실패해도 남아야 하는 기록: REQUIRES_NEW” 절의 transferWithAuditInNewTransaction과 거의 같습니다. 차이는 감사 기록 메서드가 같은 클래스 안에 있고 this로 호출된다는 점입니다. 안쪽은 recordJoiningCaller를 불러 기본 전파로 바깥에 참여하게 했습니다.
@Test
void selfInvocationIgnoresRequiresNewSoAuditIsRolledBackToo() {
assertThrows(IllegalStateException.class, () -> service.transferWithSelfInvokedAudit(1, 2, 300));
assertEquals(1000, balance(1));
assertEquals(List.of(), audits.findAll());
}
잔액은 그대로이고 감사 기록도 사라졌습니다. 감사 기록이 바깥 트랜잭션과 함께 롤백된 것입니다. REQUIRES_NEW가 붙어 있는데도 효과가 없었습니다.
왜 무시되나: 프록시
@Transactional은 Spring이 Bean을 프록시(대리 객체)로 감싸서 구현합니다. 다른 곳에서 서비스를 호출하면 실제 객체가 아니라 프록시가 먼저 받아서, 트랜잭션을 열고 → 실제 메서드를 실행하고 → 커밋·롤백합니다.
같은 객체 안에서 this.auditInNewTransaction(...)을 호출하면 프록시를 거치지 않고 실제 객체의 메서드로 바로 갑니다. 그래서 REQUIRES_NEW를 적용할 기회가 없고, 새 트랜잭션도 만들어지지 않았습니다. Chapter 03에서 컨테이너가 Bean을 만든다고 했는데, 이 프록시도 컨테이너가 Bean 대신 끼워 넣은 객체입니다. 프록시가 무엇이고 어떻게 만들어지는지는 Chapter 18의 AOP에서 직접 확인합니다.
해결: 다른 Bean으로 옮긴다
“실패해도 남아야 하는 기록: REQUIRES_NEW” 절처럼 감사 기록을 별도의 Bean(AuditService)으로 옮기면 호출이 프록시를 거치므로 REQUIRES_NEW가 적용됩니다. 이것이 가장 단순하고 안전한 방법입니다.
| 상황 | @Transactional 적용 |
|---|---|
| 다른 Bean이 호출 | 적용됨 (프록시 경유) |
같은 Bean 안에서 this로 호출 |
무시됨 |
다른 곳에서도 마찬가지
이 함정은 @Transactional에만 있지 않습니다. 프록시로 동작하는 모든 부가 기능(캐시, 비동기, 보안 검사, 직접 만든 AOP 등)에서 똑같이 나타납니다. 애노테이션을 붙였는데 효과가 없다면 호출이 다른 Bean을 통해 들어오는지 먼저 확인합니다. 이 현상은 Chapter 18에서 @Around 어드바이스로 다시 재현합니다.
따라 하기
./gradlew :examples:ch11-transaction:test --tests '*selfInvocation*'
selfInvocationIgnoresRequiresNewSoAuditIsRolledBackToo 테스트가 통과하면 “자기 호출에서는 REQUIRES_NEW가 무시되고 감사 기록도 롤백된다”는 설명이 실제로 확인된 것입니다. 이 테스트의 단정(감사 기록 비어 있음)이 “실패해도 남아야 하는 기록: REQUIRES_NEW” 절의 requiresNewAuditSurvivesOuterRollback(감사 기록 남음)과 정반대인 점을 비교하세요.
확인 문제
- 자기 호출에서
REQUIRES_NEW가 무시되는 이유를 한 문장으로 설명해 보세요. - 이 문제를 가장 단순하게 피하는 방법은 무엇인가요?
답: 1) 트랜잭션은 프록시가 열고 닫는데, this 호출은 프록시를 거치지 않기 때문입니다. 2) 해당 메서드를 다른 Bean으로 옮겨 호출이 프록시를 거치게 합니다.
직접 해 보기
transferWithSelfInvokedAudit의 감사 호출을audit.recordInNewTransaction(...)으로 바꿔 감사 기록이 남는지 확인하세요. 확인 후 되돌립니다.- 자기 호출 메서드에서
@Transactional을 지워도 결과가 같은지 생각해 보세요(이미 무시되고 있습니다). - 자신의 프로젝트에서 같은 클래스 안에서
@Transactional메서드를 서로 부르는 곳이 있는지 찾아보세요.
이체 API 확인과 트랜잭션 오류 진단
트랜잭션 오류는 예외가 아니라 돈이 틀린 채로 조용히 끝나는 모양으로 나옵니다. 이 절에서는 이체 API의 응답을 확인하고, 설정을 한 군데씩 바꿔 얻은 오류 결과와 readOnly의 의외의 결과를 정리합니다.
API로 본 이체
POST /transfers {"from":1,"to":2,"amount":300}
-> 200 {"to":{"id":2,"owner":"bob","balance":800},"from":{"id":1,"owner":"alice","balance":700}}
POST /transfers {"from":1,"to":2,"amount":9999}
-> 409 {"code":"INSUFFICIENT_FUNDS","message":"잔액이 부족하거나 계좌가 없습니다. accountId=1, amount=9999"}
POST /transfers {"from":1,"to":99,"amount":100}
-> 404 {"code":"ACCOUNT_NOT_FOUND","message":"계좌를 찾을 수 없습니다. accountId=99"}
GET /accounts/1
-> 200 {"id":1,"owner":"alice","balance":700}
없는 계좌로 보낸 세 번째 요청 뒤에도 alice의 잔액은 700 그대로입니다. 100이 출금된 채로 남지 않았습니다. 출금이 롤백된 결과입니다.
| OS | 실행 | 이 모듈만 빌드 |
|---|---|---|
| Linux / macOS | ./gradlew :examples:ch11-transaction:bootRun |
./gradlew :examples:ch11-transaction:build |
| Windows | gradlew.bat :examples:ch11-transaction:bootRun |
gradlew.bat :examples:ch11-transaction:build |
테스트 14건
| 테스트 클래스 | 건수 | 내용 |
|---|---|---|
Ch11ApplicationTests |
1 | 컨텍스트 로딩 |
TransactionTests |
10 | 위 시나리오 전체, CHECK 제약 |
TransferApiTests |
3 | 이체 응답, 잔액 부족 409, 없는 계좌 404와 롤백 |
14건이 모두 통과했습니다. CHECK 제약 테스트는 애플리케이션의 검사를 우회해 balance = -1로 갱신하려 할 때 데이터베이스가 거부하는 것까지 확인합니다. 마지막 방어선입니다.
자주 만나는 오류
설정을 한 군데씩 바꿔 테스트를 돌린 결과입니다(H2 기준). 바꾼 코드는 되돌렸습니다.
1. @Transactional을 빼면 반만 바뀐다
transferThenFail에서 @Transactional을 지우면 두 UPDATE가 각각 커밋됩니다.
runtimeExceptionAfterBothUpdatesRollsBackBoth()
AssertionFailedError: expected: <1000> but was: <700>
예외는 그대로 올라오는데 출금된 300이 되돌려지지 않았습니다. 오류 메시지에 트랜잭션이라는 말이 없고 잔액만 틀린 것이 단서입니다.
2. 체크 예외는 롤백되지 않는다
rollbackFor = Exception.class를 지우면 IOException 뒤에 롤백되지 않습니다.
rollbackForMakesCheckedExceptionRollBack()
AssertionFailedError: expected: <1000> but was: <700>
메시지가 1번과 같아서 구분하기 어렵습니다. 던지는 예외가 RuntimeException인지 체크 예외인지를 먼저 봅니다.
3. REQUIRES_NEW를 빼면 감사 기록도 사라진다
recordInNewTransaction의 propagation = REQUIRES_NEW를 빼면 감사 기록이 바깥 트랜잭션에 참여해 함께 롤백됩니다.
requiresNewAuditSurvivesOuterRollback()
AssertionFailedError: expected: <[이체 시도 from=1 to=2 amount=300]> but was: <[]>
“남아야 하는 기록이 비었다”가 증상입니다.
4. readOnly = true는 쓰기를 막지 않았다
transfer에 @Transactional(readOnly = true)를 붙여도 이 예제의 H2에서는 14건이 모두 통과했습니다. UPDATE도 성공했습니다. readOnly는 DB에 주는 힌트라서, 쓰기를 강제로 막아 주는 장치로 믿으면 안 됩니다. 다른 DB에서도 같은지는 확인하지 않았습니다.
트랜잭션 오류를 진단하는 순서
- 예외가 났는데 잔액이 일부만 반영되었다면 메서드에
@Transactional이 있는지 봅니다. 없으면 애노테이션을 추가합니다. @Transactional이 있다면 던진 예외가 체크 예외인지 봅니다. 체크 예외면rollbackFor를 지정하거나RuntimeException으로 바꿉니다.- 체크 예외가 아니라면 같은 클래스 안에서
this로 호출했는지 봅니다. 그렇다면 다른 Bean으로 분리합니다. - 잔액은 맞는데 남아야 할 기록이 사라졌다면
REQUIRES_NEW와 프록시를 거치는 호출인지 확인합니다.
트랜잭션 오류는 예외 메시지가 아니라 최종 상태(잔액, 기록)가 틀린 형태로 나타나므로, 위 순서로 원인을 하나씩 지워 가는 것이 효율적입니다.
따라 하기: API로 롤백 확인
curl -s -X POST http://localhost:8080/transfers -H "Content-Type: application/json" \
-d '{"from":1,"to":99,"amount":100}' # 404, 없는 계좌
이 요청의 응답이 404여도 alice의 출금 100이 되돌려져 잔액이 변하지 않았는지가 핵심입니다. 이후 POST /transfers로 정상 이체를 한 번 더 보내 응답의 from.balance가 기대한 값인지 확인하세요.
증상별 점검표
| 증상 | 가장 먼저 볼 것 |
|---|---|
| 예외 뒤에도 잔액이 변한 채로 남음 | @Transactional 유무, 같은 클래스 안 호출 |
| 체크 예외 뒤 롤백 안 됨 | rollbackFor |
| 남아야 할 기록이 사라짐 | REQUIRES_NEW와 프록시를 거치는 호출 |
readOnly인데 쓰기가 됨 |
힌트일 뿐 강제가 아님 |
이 Chapter에서 다루지 않은 것
격리 수준과 락, 동시에 같은 계좌를 갱신할 때의 경합, NESTED 전파, 분산 트랜잭션은 다루지 않았습니다. 실제 이체 서비스는 이 주제들을 반드시 고려해야 합니다.
직접 해 보기
- 위 오류 네 가지를 복사본에서 하나씩 만들어 같은 메시지가 나오는지 확인하세요.
- 새로운 시나리오(예: 출금 후
NullPointerException)를 추가하고 롤백되는지 잔액으로 검증하세요. - 이체 로직에서 “잔액을 직접 단정하는 테스트”가 없을 때 어떤 버그가 발견되지 않을지 적어 보세요.
자주 하는 실수 한눈에 보기
절마다 나온 자주 하는 실수를 한 표로 모았습니다. 동적 SQL이나 트랜잭션 코드를 고친 뒤 점검표로 쓰세요.
| 주제 | 실수 | 증상 | 해결 |
|---|---|---|---|
| 동적 조건 | <where> 없이 <if>만 사용 |
조건이 있을 때만 AND로 시작해 구문 오류 |
<where> 사용 |
| 동적 조건 | <foreach>에 open, close 누락 |
IN a, b 구문 오류 |
open="(" close=")" |
| 동적 조건 | test에 오타 |
Error evaluating expression |
레코드의 필드 이름과 대조 |
| 동적 조건 | 빈 문자열을 null만 검사 |
빈 키워드가 LIKE '%%' 조건으로 붙음 |
!= null and != '' |
| 정렬 | ORDER BY ${sort}로 입력을 그대로 넣음 |
SQL 주입 | <choose>로 허용 목록 |
| 정렬 | ORDER BY #{sort} |
정렬이 의도대로 동작하지 않음 | 이름은 <choose>로 선택 |
| 정렬 | <otherwise>를 빠뜨림 |
모르는 값일 때 ORDER BY가 비어 의도치 않은 순서 |
기본 정렬을 <otherwise>에 |
| 정렬 | 정렬 키를 하나만 두고 동률 처리를 안 함 | 같은 값의 순서가 요청마다 달라져 페이징이 흔들림 | title ASC, id DESC처럼 마지막에 고유 키 추가 |
| JOIN 중첩 매핑 | javaType="long"으로 기본형 인자를 지정 |
NoSuchMethodException ... (java.lang.Long, ...) |
기본형은 _long |
| JOIN 중첩 매핑 | 글 id와 사용자 id 컬럼을 별칭 없이 조회 |
두 값이 섞여 잘못 매핑 | u.id AS author_id처럼 별칭 |
| JOIN 중첩 매핑 | 생성자 인자 순서가 record와 다름 | 인스턴스 생성 오류 | <arg> 순서를 record 선언 순서와 맞춤 |
| JOIN 중첩 매핑 | 작성자 없는 글이 목록에서 사라짐 | INNER JOIN이라 제외됨 | 모든 글이 필요하면 LEFT JOIN과 null 처리 |
| 1:N 매핑 | <collection>의 ofType을 빠뜨림 |
목록 원소 타입을 알 수 없어 오류 | ofType에 원소 클래스 지정 |
| 1:N 매핑 | 결과 객체를 record로 만듦 | 목록에 값을 채울 수 없음 | setter가 있는 클래스 사용 |
| 1:N 매핑 | <id> 없이 매핑 |
같은 사용자가 중복되거나 합쳐지지 않음 | 부모를 구분하는 컬럼에 <id> |
| 1:N 매핑 | 글이 없는 사용자를 INNER JOIN으로 조회 | 사용자 자체가 안 나옴 | LEFT JOIN |
| 페이징 | 페이지 번호를 1부터라고 착각 | 첫 페이지를 건너뜀 | 이 API는 0부터 |
| 페이징 | 정렬 없이 OFFSET만 사용 | 페이지 경계에서 중복·누락 | 고유 키를 포함한 정렬을 항상 지정 |
| 페이징 | size에 상한이 없음 |
한 번에 수만 건 요청 | @Max(50) 같은 상한 |
| 페이징 | 목록과 건수의 조건이 다름 | 총 건수와 실제 목록이 어긋남 | <sql> 조각 공유 |
| 실행과 테스트 | 시드 데이터를 바꾸고 테스트 기대값을 그대로 둠 | 건수 단정 실패 | 테스트의 기대값과 data.sql을 함께 수정 |
| 실행과 테스트 | 상태를 여러 개 보내는 방법을 모름 | 한 개만 적용된 것처럼 보임 | status=A&status=B처럼 이름을 반복(쉼표로 이은 status=A,B도 목록으로 변환되지만, 이 절은 반복 방식을 기준으로 함) |
| 실행과 테스트 | 서버를 켠 채 같은 포트로 재실행 | Port 8080 was already in use |
이전 서버 종료 |
| 트랜잭션 기본 | 여러 UPDATE를 트랜잭션 없이 실행 | 중간 실패 시 일부만 반영(돈이 사라짐) | 서비스 메서드에 @Transactional |
| 트랜잭션 기본 | 테스트에 @Transactional을 붙이고 커밋·롤백 경계를 검증하려 함 |
테스트 전체가 한 트랜잭션이라 경계를 확인할 수 없음 | 경계 검증 테스트는 붙이지 않음 |
| 트랜잭션 기본 | 예외를 잡아서 삼킴 | 롤백이 일어나지 않고 일부만 반영 | 예외를 다시 던지거나 롤백을 명시 |
| 롤백 규칙 | 업무 예외를 체크 예외로 만들고 롤백을 기대 | 예외가 났는데 변경이 확정됨 | RuntimeException 상속 또는 rollbackFor |
| 롤백 규칙 | 예외 타입만 단정하는 테스트 | 롤백 실패를 못 잡음 | 잔액 같은 최종 상태를 단정 |
| 롤백 규칙 | catch로 예외를 삼킴 |
@Transactional이 예외를 못 봐 커밋 |
예외를 다시 던지기 |
| REQUIRES_NEW | 감사 기록을 같은 트랜잭션에 넣음 | 이체가 롤백되면 기록도 사라짐 | 기록을 REQUIRES_NEW로 분리 |
| REQUIRES_NEW | REQUIRES_NEW를 같은 클래스 안에서 호출 |
효과 없음 | 다른 Bean으로 분리(앞의 “같은 클래스 안에서 부르면 무시됩니다” 절) |
| REQUIRES_NEW | 풀이 작은데 REQUIRES_NEW를 중첩 호출 |
새 연결을 얻지 못해 대기·교착 | 풀 크기와 중첩 깊이 점검 |
| REQUIRES_NEW | REQUIRES_NEW를 남용 |
일관성 경계가 흐려짐 | 꼭 남겨야 하는 작업에만 사용 |
| 자기 호출 | 같은 클래스 안 메서드에 @Transactional이나 @Async를 붙이고 this로 호출 |
애노테이션이 무시됨 | 다른 Bean으로 분리 |
| 자기 호출 | private이나 final 메서드에 @Transactional |
프록시가 가로채지 못해 무시될 수 있음 | public 메서드에 사용 |
| 자기 호출 | 자기 자신을 주입받아 호출하는 우회에 의존 | 구조가 복잡해지고 순환 의존 위험 | 책임을 별도 Bean으로 나눔 |
| 진단 | readOnly = true로 쓰기를 막을 수 있다고 믿음 |
H2에서는 쓰기가 성공함 | 쓰기 방지는 권한과 코드 설계로, readOnly는 조회 최적화 힌트로 이해 |
| 진단 | 롤백 테스트 없이 @Transactional만 신뢰 |
설정 실수가 조용히 통과 | 최종 잔액을 단정하는 테스트 작성 |
용어와 참고 자료
이 Chapter에 나온 용어와 참고 사이트를 모았습니다. Chapter 07과 Chapter 08에서 설명한 용어는 다시 쓰지 않습니다.
참고한 자료
- MyBatis Dynamic SQL:
<if>,<where>,<foreach>,<choose>의 동작과<where>가 앞의AND를 지우는 규칙을 확인했습니다. - MyBatis Mapper XML Files: Result Maps:
collection, 생성자 매핑을 확인했습니다.javaType에 기본형을 가리키는_long별칭은 이 문서의 별칭 표에 있습니다. - Spring Framework Reference: Declarative Transaction Management: 롤백 규칙(런타임 예외에서만 기본 롤백),
rollbackFor, 프록시 기반 동작과 자기 호출의 제약을 확인했습니다. 표의 결과는 직접 실행해 이 설명과 대조했습니다. - Spring Framework Reference: Transaction Propagation:
REQUIRED와REQUIRES_NEW의 차이를 확인했습니다. - Use The Index, Luke: 페이징
- Spring Framework Reference: Using @Transactional
동적 SQL
| 용어 | 설명 |
|---|---|
| 동적 SQL | 조건에 따라 SQL 조각을 붙였다 뺐다 하는 MyBatis의 기능입니다. |
<if> |
조건식이 참일 때만 안의 SQL을 붙입니다. |
<where> |
내용이 있을 때만 WHERE를 붙이고 맨 앞의 AND/OR을 지웁니다. |
<foreach> |
목록을 IN (...) 같은 반복 구문으로 펼칩니다. open, close, separator가 있습니다. |
<sql> / <include> |
SQL 조각을 만들어 여러 쿼리에서 재사용합니다. |
<choose> / <when> / <otherwise> |
여러 조건 중 하나만 선택하는 태그입니다. 허용 목록 정렬에 씁니다. |
| 허용 목록(allow-list) | 허용된 값 안에서만 고르게 하는 방식입니다. 입력이 SQL이 되지 않게 합니다. |
LIKE |
부분 일치 검색 조건입니다. %와 _가 특수 문자입니다. |
매핑과 페이징
| 용어 | 설명 |
|---|---|
<constructor> / <idArg> / <arg> |
record처럼 setter가 없는 객체에 생성자 인자로 값을 넘기는 매핑입니다. |
association 계열 중첩 매핑 |
JOIN 결과의 일부 컬럼을 중첩 객체 하나로 묶습니다. 이 Chapter는 <arg resultMap>으로 구현했습니다. |
collection |
같은 키를 가진 여러 행을 목록으로 묶습니다. 1:N 관계에 씁니다. |
javaType="_long" |
기본형 long을 가리키는 MyBatis 별칭입니다. long은 래퍼 Long입니다. |
별칭(AS) |
SELECT 컬럼에 붙이는 이름으로, 같은 이름의 컬럼을 구분합니다. |
| INNER JOIN / LEFT JOIN | 양쪽에 모두 있는 행만 / 왼쪽은 모두 남기는 JOIN입니다. |
OFFSET/FETCH |
몇 건을 건너뛰고 몇 건을 가져올지 정하는 표준 페이징 구문입니다. |
totalElements / totalPages |
전체 건수 / 올림 계산한 전체 페이지 수입니다. |
| keyset 페이징 | 마지막으로 본 키를 기준으로 이어 읽는 방식입니다. 큰 오프셋의 한계를 피합니다. |
트랜잭션
| 용어 | 설명 |
|---|---|
| 트랜잭션 | 여러 작업을 하나로 묶어 모두 성공하거나 모두 취소하는 단위입니다. |
| 커밋 / 롤백 | 변경을 확정하는 일 / 변경을 되돌리는 일입니다. |
@Transactional |
메서드를 트랜잭션 경계로 만드는 애노테이션입니다. |
| 런타임 예외 / 체크 예외 | 컴파일러가 처리를 강제하지 않는 예외 / 강제하는 예외입니다. 기본 롤백은 런타임 예외에서만 일어납니다. |
rollbackFor |
롤백할 예외 종류를 추가로 지정하는 속성입니다. |
| 전파(propagation) | 이미 진행 중인 트랜잭션이 있을 때 안쪽 메서드의 동작을 정하는 설정입니다. |
REQUIRED / REQUIRES_NEW |
바깥에 참여(기본) / 바깥을 멈추고 새 트랜잭션에서 따로 커밋합니다. |
| 프록시 | Spring이 Bean을 감싸 트랜잭션 같은 부가 동작을 끼워 넣는 대리 객체입니다. |
| 자기 호출 | 같은 객체 안에서 this로 메서드를 부르는 일. 프록시를 거치지 않아 애노테이션이 무시됩니다. |
CHECK 제약 |
컬럼 값이 조건을 만족해야 하도록 DB가 강제하는 제약입니다. |
readOnly |
읽기 전용 힌트입니다. 쓰기를 막는 보장은 아닙니다. |
직접 해보기
./gradlew :examples:ch10-dynamic-sql:test와./gradlew :examples:ch11-transaction:build를 실행해 테스트 22건과 14건이 모두 통과하는지 확인하세요.- Mapper 로그 수준을
DEBUG로 올려ch10-dynamic-sql을 켜고, 조건 없음, 키워드 하나, 키워드와 상태 여러 개, 맞는 결과 없음의 네 가지 요청을 보내Preparing:줄의WHERE와IN이 어떻게 달라지는지 비교하세요. <choose>에sort=author분기를 추가하고,id; DROP TABLE posts같은 값을sort로 보내도 기본 정렬로 처리되는지 로그로 확인하세요.ch11-transaction의TransactionTests에서 런타임 예외, 체크 예외,rollbackFor,REQUIRES_NEW, 자기 호출 시나리오의 잔액과 감사 기록을 표로 정리하고, “이체 API 확인과 트랜잭션 오류 진단” 절의 진단 순서로 각 결과를 설명해 보세요.
이번 장의 정리
- 동적 SQL은
<if>,<where>,<foreach>로 값이 있는 조건만 붙이고, 목록과 건수 쿼리는<sql>/<include>로 같은 조건을 공유합니다. 최종 SQL은 Mapper 로그로 확인합니다. - 정렬처럼 이름을 바꿔야 하는 자리는
${}에 입력을 넣지 않고<choose>허용 목록으로 분기만 고릅니다. - JOIN 결과는
<constructor>와<arg resultMap>으로 중첩 record에, 1:N 관계는<collection>과<id>로 하나의 객체와 목록에 담습니다. 기본형 인자는_long처럼 밑줄 표기를 씁니다. - 페이징은
count와OFFSET/FETCH두 쿼리로 나누고, 총 페이지는 올림 나눗셈으로 계산하며size에 상한을 둡니다. - 트랜잭션은 여러 UPDATE를 모두 성공 또는 모두 취소로 묶습니다.
@Transactional기본 규칙은 런타임 예외에서만 롤백하므로 체크 예외는rollbackFor나 런타임 예외로 대응합니다. REQUIRES_NEW는 실패해도 남아야 하는 기록을 별도 트랜잭션으로 커밋하지만, 같은 클래스 안의this호출은 프록시를 거치지 않아 애노테이션이 무시됩니다.- 트랜잭션 오류는 예외 메시지가 아니라 잔액과 기록이 조용히 틀리는 모양이므로, 최종 상태를 직접 단정하는 테스트가 필요합니다.
다음 Chapter 10 MyBatis-Plus에서 반복되는 CRUD SQL을 얼마나 줄일 수 있는지 봅니다.