뚝딱 뚝딱 개발일기

Spring Data JPA save() vs saveAll(), 진짜 차이는 SQL 이 아니라 트랜잭션 경계였다

경딩 — Mon, 25 May 2026 02:04:55 +0900

부제 : async-profiler Flame Graph 로 직접 파헤쳐 본 다건 저장 성능 차이

이 글에서 얻어갈 것들

saveAll() 이 빠른 진짜 이유를 설명할 수 있게 된다.
- ("INSERT 한 방"이라는 오해를 정확히 깨뜨릴 수 있다)
SimpleJpaRepository.saveAll() 내부 코드를 보고, saveAll도 결국 save()를 반복 호출함을 이해한다.
트랜잭션 경계가 다건 저장 성능에 미치는 영향을 async-profiler Flame Graph 실측 데이터로 확인한다.
서비스 계층 @Transactional의 의미를 성능 관점에서 이해한다.
saveAll()과 JDBC Batch insert 를 구분할 수 있게된다.

1. 시작 - 흔한 오해

처음 saveAll()을 쓸 때 나도 당연하게 생각했다.

"save() 여러 번 호출하는 것보다 한 방에 INSERT 날리니까 빠르겠지."

실제로 빠르긴 하다. 그런데 이유가 틀렸다.
직접 확인해봤다.

2.코드부터 보기 - save() vs saveAll() 내부

먼저 saveAll() 의 코드를 보자.

Spring Data JPA의 SimpleJpaRepository 에서 발췌한 내용이다. (버전에 따라 세부 코드는 다를 수 있지만 핵심 구조는 동일하다)

// SimpleJpaRepository.java
@Transactional
public <S extends T> List<S> saveAll(Iterable<S> entities) {

	List<S> result = new ArrayList<>();
    
    for (S entity : entities) {
        save(entity);   // ← 결국 save()를 호출한다
    }
    return result;
}

@Transactional
public <S extends T> S save(S entity) {
    if (entityInformation.isNew(entity)) {
        entityManager.persist(entity);
    } else {
        entityManager.merge(entity);
    }
    return entity;
}

saveAll() 내부를 보면 루프를 돌며 save()를 하나씩 호출한다.

SQL 을 한 방에 날리는 마법 같은 건 없다.

그렇다면 왜 saveAll()이 빠를까?

두 방식의 진짜 차이는 @Transactional의 범위에 있다.

// 방식 1: save() 반복 (서비스 메서드에 @Transactional 없음)
public void saveUsersIndividually(List<String> names) {
    for (String name : names) {
        userRepository.save(new User(name));
        // save()마다 SimpleJpaRepository의 @Transactional이 동작
        // → 트랜잭션 시작 → INSERT → 커밋  이 N번 반복
    }
}

// 방식 2: saveAll()
public void saveUserBatch(List<String> names) {
    List<User> users = names.stream().map(User::new).toList();
    userRepository.saveAll(users);
    // saveAll() 하나의 @Transactional 안에서 전부 처리
    // → 트랜잭션 시작 → INSERT × N → 커밋  1번
}

이론적으로는 이렇다. 실제로 얼마나 차이가 나는지 직접 측정해봤다.

3. 성능 측정 - async-profiler + Flame Graph

단순 시간 측정은 JVM 워밍업 없이 재면 신뢰하기 어렵다.
async-profiler를 사용해서 CPU 샘플 기반으로 측정했다.

@Test
public void testPerformanceComparisonWithProfiler() throws Exception {
    profiler = AsyncProfiler.getInstance();

    // JVM 워밍업 (측정 전 필수)
    warmup();

    final int MEASURE_COUNT = 3;
    // ...
    for (int i = 0; i < MEASURE_COUNT; i++) {
        // save() 측정
        profiler.execute("start,event=cpu,interval=10ms");
        userService.saveUsersIndividually(names1);
        profiler.execute("stop,file=save-profile-" + i + ".html");

        // saveAll() 측정
        profiler.execute("start,event=cpu,interval=10ms");
        userService.saveUserBatch(names2);
        profiler.execute("stop,file=saveAll-profile-" + i + ".html");
    }
}

측정 조건: 10만 건, 3회 측정 후 대표값 기재, JVM 워밍업 포함

방식	CPU Samples (대표값)
save() 반복	849
saveAll()	274

대표 CPU profile 기준으로 save() 반복 쪽이 saveAll() 보다 약 3.1배 더 많은 CPU sample을 보였다.

단 이는 wall-clock 실행 시간이 정확히 3.1배라는 뜻이 아니라, CPU sample 기준으로 약 3.1 배 더 많이 관측된 것이다.

그런데 왜일까?

4. Flame Graph 분석 — 느린 진짜 이유

Flame Graph에서 save() 반복 쪽 경로를 보면 이런 프레임이 넓게 잡힌다.

UserService.saveUsersIndividually
 └─ $Proxy.save
     └─ TransactionAspectSupport.invokeWithinTransaction
         ├─ createTransactionIfNecessary       ← 트랜잭션 시작
         │   └─ JpaTransactionManager.doBegin
         │       └─ HikariDataSource.setAutoCommit
         └─ commitTransactionAfterReturning    ← 트랜잭션 커밋
             └─ JpaTransactionManager.doCommit
                 └─ HikariProxyConnection.commit

이 경로가 save() 1번마다 반복된다. 10만 건이면 이 흐름이 10만번 생성된다.

이번 실험처럼 서비스 메서드에 @Transacional이 없는 상태에서 save()를 반복 호출하면, Repository save() 의 트랜잭션 경계가 호출 횟수만큼 반복될 수 있다.

saveAll()쪽은 다르다.

UserService.saveUserBatch
 └─ SimpleJpaRepository.saveAll   ← 트랜잭션 1번 시작
     └─ SimpleJpaRepository.save  ← N번 반복, 외부 트랜잭션에 참여 (새 트랜잭션 생성 안 함)
         └─ EntityManager.persist
             └─ ActionQueue
                 └─ EntityInsertAction

doBegin, doCommit, setAutoCommit 같은 트랜잭션 관리 프레임이 눈에 띄지 않는다.
트랜잭션이 딱 1번만 열리기 때문이다.

save()가 느린 핵심 원인은 SQL 실행이 아니라, AOP 트랜잭션 처리가 N번 반복되는 것이다.

5. 그럼 @Transactional을 붙이면 같아질까?

여기서 자연스럽게 따라오는 질문이 있다.

"서비스 메서드에 @Transactional을 붙이면 save() 반복도 빨라지지 않을까?"

@Transactional   // ← 추가
public void saveUsersIndividually(List<String> names) {
    for (String name : names) {
        userRepository.save(new User(name));
        // 이제 외부 트랜잭션에 참여 → save() 내부 @Transactional은 새 트랜잭션을 만들지 않고 기존 트랜잭션에 합류
    }
}

이렇게 하면 save() 반복도 트랜잭션이 1번으로 묶인다.

이 상태에서 비교하면 save() 와 saveAll()의 성능 차이는 현저히 줄어든다.

결국 saveALL() 이 빠르다는 말은 조건이 붙는다.

서비스 메서드에 @Transactional이 없을 때, saveAll()이 save() 반복보다 빠르다. @Transactional 로 묶이 상태라면 두 방식은 거의 같다.

6. JDBC Batch - 추가로 얻을 수 있는 것

트랜잭션을 하나로 묶는 것만으로도 큰 차이가 난다. 여기서 한발 더 나아가면 JDBC Batch를 활용할 수 있다.

application.yml에 설정을 추가한다.

spring:
  jpa:
    properties:
      hibernate:
        jdbc:
          batch_size: 2
        generate_statistics: true   # 아래 로그 확인용

batch_size 를 설정하면 Hibernate는 INSERT 를 즉시 보내지 않고, 지정한 수만큼 쌓아뒀다가 한 번에 DB로 전송한다.

// batch_size=2, 엔티티 3개일 때 내부 동작
ps.setValues("User 1"); ps.addBatch();   // 큐에 쌓기만
ps.setValues("User 2"); ps.addBatch();
ps.executeBatch();   // ← 1번째 전송 (2개 → 네트워크 1번)
ps.setValues("User 3"); ps.addBatch();
ps.executeBatch();   // ← 2번째 전송 (1개 → 네트워크 1번)

결과는 generate_statistics 로그에서 확인할 수 있다.

// batch 적용 후 Session Metrics 로그
executing 1 JDBC statements;
executing 2 JDBC batches;   ← batch_size=2로 3개 처리

배치 없이 3번의 네트워크 왕복이 2번으로 줄었다.

10만 건에 batch_size=1000이면 100번의 왕복으로 끝난다.

주의할 점

saveAll() != JDBC batch insert 자동 적용

batch_size 설정이 되어 있어야 한다
GenerationType.IDENTITY는 사용 불가 — INSERT 직후 DB가 ID를 생성해야 해서 Hibernate가 배치를 원천 차단한다
GenerationType.SEQUENCE 또는 TABLE을 써야 한다

@Entity
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE)  // ← 필수
    private Long id;
}

7. 정리

	save() 반복	saveAll()
내부 동작	save() N번 호출	save() N번 호출 (동일)
트랜잭션 (@Tx 없을 때)	N번	1번
성능 차이 원인	트랜잭션 AOP 반복	트랜잭션 1번
JDBC Batch 적용	@Tx + batch_size + SEQUENCE 필요	batch_size + SEQUENCE 필요

save()가 느린 이유 우선순위 (이번 실험 기준)

트랜잭션 반복 비용 — AOP doBegin/doCommit이 N번 실행 (Flame Graph에서 직접 확인)
네트워크 왕복 — batch_size 설정으로 추가 개선 가능 (CPU profile로는 단정 불가)

"saveAll()이 더 빠릅니다" — 맞는 말이다.
"INSERT를 한 방에 날려서요" — 틀린 이유다.

이번 실험 기준을 saveAll() 이 빠른 진짜 이유는 이거다.

saveAll() 은 하나의 @Transactional 안에서 모든 저장을 처리한다.

save() 반복은 (서비스 트랜잭션 없이) 호출할 때마다 트랜잭션이 반복된다.

그 차이가 AOP, JpaTransactionManager, Hikari Connection 비용을 n 배로 키운다.

save() 반복 방식도 서비스 메서드 명에 @Transactional 을 붙이면 saveAll() 과 거의 같은 성능이 나온다.

그렇다면 saveAll() 을 쓰는 이유는 성능 때문만이 아니다.

"다건 저장" 이라는 의도를 코드로 명확하게 표현하는데 있다.

다건 저장 성능을 개선할 때는 "어떤 메서드를 쓸까" 보다 "트랜잭션 경계가 어디에 있는가" 를 먼저 확인하는 것이 맞다.

이 글은 async-profiler CPU profile과 Flame Graph 실측 데이터를 기반으로 작성되었습니다.
측정 조건(서비스 메서드 @Transactional 없음)이 결과에 핵심적인 영향을 미쳤으며,
표현에서도 "이번 실험 기준", "이번 조건에서는" 등을 의도적으로 사용했습니다.
다른 환경에서는 결과가 다를 수 있으므로, 직접 측정해보는 것을 권장합니다.

질문이 답변을 수정해서는 안 된다 - CQS, 읽히는 코드를 만드는 원칙

경딩 — Tue, 21 Apr 2026 21:29:23 +0900

코드는 동작하는 것만 봤는데, 이번에 왜 이렇게 설계했는지 보려고 했다.

이 글에서 얻어갈 것들

동작은 되는데 찜찜한 코드의 정체
명령과 쿼리를 왜 나눠야 하는지에 대한 실무적인 이유
메서드 시그니처만 보고 부수효과를 예측하는 방법
CQS 를 단순 개념이 아닌 설계 기준으로 사용하는 방법
값 객체와 결합해 부수효과 범위를 좁히는 패턴
CQS가 오히려 독이 되는 상황과 그 판단 기준

개발을 하다 보면 이런 코드를 만나게 된다.

boolean result = schedule.includes(day);

겉으로 보면 "값을 반환하는 함수"다.

그런데 실행해보면 결과가 달라진다.

같은 파라미터인데, 두 번째 호출은 다른 값을 돌려준다.

이런 코드는 처음엔 잘 동작한다.

하지만 시간이 지날수록 점점 이해하기 어려워진다.

이 글에서 그 이유를 설명하고, 어떻게 고쳐야 하는지를 다룬다.

명령과 쿼리 - 개념 정리

모든 메서드는 두 가지로 나뉜다.

종류	설명
명령 (Command)	객체의 상태를 변경하지만 값을 반환하지 않는 메서드
쿼리 (Query)	객체의 상태를 변경하지 않지만 값을 반환하는 메서드

CQS - 질문이 답변을 수정해서는 안된다

Command-Query Separation (CQS)
메서드는 명령이거나 쿼리여야 하고, 둘 다여서는 안된다.

원칙은 단순하다.

명령은 반환값을 가져서는 안 된다. 상태를 바꾸면 void로 끝낸다.
쿼리는 상태를 바꿔선 안 된다. 값을 반환하면 읽기 전용이어야 한다.

왜 이게 중요할까?

명령과 쿼리의 역할이 섞이면, 코드를 실행해보기 전까지 결과를 예측할 수 없다.

내부 구현을 직접 열어보지 않으면 "이 메서드를 부르면 상태가 바뀌는가" 를 알 수 없게 된다.

나쁜 예시 - includes()가 상태를 바꾸는 순간

반복 일정을 관리하는 Schedule 클래스가 있다.

새로운 요구사항이 추가됐다.

"날짜가 일정 조건을 만족하지 않으면, 그 날짜를 포함하도록 일정을 자동으로 조정해라."

이걸 구현한 결과가 이렇다.

public boolean includes(LocalDate day) {
    if (!plan.includes(day)) {
        plan.reschedule(day); // ← 상태를 변경!
        return false;
    }
    return true;
}

시그니처만 보면 boolean includes(LocalDate day) - 쿼리처럼 생겼다. "오늘 일정이 있나요" 라고 묻는 것 같다.

그런데 실제로는 일정을 조정해버린다.

assertThat(schedule.includes(LocalDate.of(2025, 1, 16))).isFalse(); // false — 그리고 일정이 조정됨
assertThat(schedule.includes(LocalDate.of(2025, 1, 16))).isTrue();  // true — 방금 조정됐으니까

같은 인자로 같은 메서드를 두 번 불렀는데 결과가 달라진다. 이게 바로 CQS 위반이 만들어내는 함정이다.

협업에서 이런 버그는 찾기 매우 어렵다. 메서드 이름은 쿼리인데 명령처럼 동작하기 떄문에, 테스트를 짤 때도 "설마 이게 상태를 바꾸겠어?" 하고 방심하게 된다. 이런 코드가 쌓이면 팀 전체가 메서드 이름을 믿지못하고, 결국 모든 코드를 내부까지 열어봐야 이해할 수 있는 코드 베이스가 된다.

리펙토링 - 명령과 쿼리를 분리한다.

// 쿼리: 값만 반환, 상태 변경 없음
public boolean includes(LocalDate day) {
    return plan.includes(day);
}

// 명령: 상태만 변경, 반환값 없음
public void adjust(LocalDate day) {
    plan.reschedule(day);
}

이제 includes()를 몇 번 불러도 결과가 항상 같다.

assertThat(schedule.includes(day)).isFalse();
assertThat(schedule.includes(day)).isFalse();
assertThat(schedule.includes(day)).isFalse(); // 몇 번을 불러도 안전

schedule.adjust(day); // 명시적으로 상태 변경

assertThat(schedule.includes(day)).isTrue();

그리고 여기서 중요한 게 하나 더 생긴다.

명령 전후로 쿼리를 여러 번 호출해도 결과가 동일하다는 보장이 생긴다.

includes() 를 열 번 부르고 adjust()를 한 번 부른 뒤 다시 includes()를 열 번 불러도, adjust()호출 전까지는 모든 includes() 결과가 동일하다고 확신할 수 있다.

한 번만 분석하면 나머지는 신뢰할 수 있다는 뜻이다.

이게 단순히 "코드가 깔끔해진다" 를 넘어서, 읽는 사람이 머릿속에 추적해야 할 상태의 양이 줄어드는 것이다.

메서드 시그니처가 계약이 되는 순간

CQS 를 팀 전체가 따르면, 메서드 시그니처가 계약서가 된다.

시그니처	의미	사용방식
boolean includes(...)	쿼리 — 상태 변경 없음	마음껏 여러 번 호출 가능
void adjust(...)	명령 — 상태 변경 있음	신중하게, 의도적으로 호출

반환 타입이 있으면 쿼리다. 부수효과 없이 안전하게 사용할 수 있다.

반환 타입이 없으면 명령이다. 부수효과가 있으니 주의가 필요하다.

이 코드를 처음 보는 사람이 내부를 열지 않고도 이해 할 수 있는가? 를 생각하면 된다.

코드는 작성하는 시간보다 읽는 시간이 훨씬 길다.

메서드 이름과 시그니처만으로 동작을 예측할 수 있어야, 팀이 그 코드를 믿고 사용할 수 있다.

한 단계 더 - 값 객체와 결합하면 부수효과 범위가 좁아진다.

명령과 쿼리를 분리해도 문제가 하나 남는다.

schedule.adjust(day)를 호출하면 상태 변경이 일어나는데, 실제 변경은 Schedule이 아니라 WeeklyPlan 또는 MonthlyPlan 내부에서 일어난다.

schedule.adjust() 호출
  → plan.reschedule() 호출
    → WeeklyPlan 또는 MonthlyPlan 내부 상태 변경

부수 효과를 이해하려면 세 개의 클래스를 동시에 봐야 한다는 뜻이다.

메시지를 받는 객체와 상태가 바뀌는 객체가 다르기 때문이다.

해결책은 RecurringPlan을 불변 값 객체로 만드는 것이다

// 기존: 자신의 상태를 직접 변경 (명령)
public void reschedule(LocalDate day) {
    this.dayOfWeek = day.getDayOfWeek();
    this.ordinal = (day.getDayOfMonth() / DAYS_IN_WEEK) + 1;
}

// 변경 후: 새로운 객체를 반환 (쿼리처럼 동작)
public MonthlyPlan reschedule(LocalDate day) {
    return new MonthlyPlan(
        day.getDayOfWeek(),
        (day.getDayOfMonth() / DAYS_IN_WEEK) + 1
    );
}

이제 Schedule.adjust()는 이렇게 된다.

public void adjust(LocalDate day) {
    this.plan = plan.reschedule(day); // ← 여기서만 상태 변경
}

RecurringPlan 계층은 더 이상 스스로 상태를 바꾸지 않는다.

부수효과가 Schedule.adjust()하나로 집약된다.

"이 코드에서 상태가 어디서 바뀌는가" 라는 질문에 이제 Schedule 클래스 하나만 보면 된다.

구체적으로 어떤 값이 바뀌는지 궁금할 때만 RecurringPlan 계층을 들여다보면 된다.

값 객체는 단순히 불변성을 위한 기술이 아니다. 부수효과의 범위를 명시적으로 좁히는 설계 전략이다. 부수효과가 어디서 일어나는지 눈에 보이게 만들면, 버그가 생겼을 때 찾아야 하는 코드의 양이 극적으로 줄어든다.

실전 예제 — 텍스트 어드벤처 게임

게임 플레이어의 이동 코드다.

public boolean move(Direction direction) {
    if (worldMap.isBlocked(position.shift(direction))) {
        return false;
    }
    this.position = this.position.shift(direction); // 부수효과!
    return true;
}

시그니처만 보면 쿼리처럼 보인다. boolean 을 반환하니까, "동쪽으로 이동할 수 있나요" 라고 묻는 것 같다.

그런데 내부에서는 위치를 바꾸고 있다.

player.move(Direction.EAST); // 이동하면서 true 반환
player.move(Direction.EAST); // 이미 벽에 닿았으니 false 반환

두 번째 호출이 다른 결과를 내는 이유를 알려면, 첫 번째 호출이 상태를 바꿨다는 사실을 알아야 한다.

시그니처만 믿었다가 틀리는 전형적인 패턴이다.

어떤 문제가 발생하는지 알아보기 위해 테스트 케이스를 하나 만들어 보겠습니다.

    @Test
    public void day_of_week_in_month_includes() {
        Schedule schedule = new Schedule(
                "월간 회의", LocalTime.of(13, 0), Duration.ofHours(1),
                new MonthlyPlan(DayOfWeek.MONDAY, 2));

        assertThat(schedule.includes(LocalDate.of(2025, 1, 16))).isFalse();
        assertThat(schedule.includes(LocalDate.of(2025, 1, 16))).isTrue();
    }

리팩토링:

// 쿼리: 이동 가능 여부만 확인
public boolean canMove(Direction direction) {
    return !worldMap.isBlocked(position.shift(direction));
}

// 명령: 실제 이동 (이동 불가 시 예외)
public void move(Direction direction) {
    if (!canMove(direction)) {
        throw new IllegalStateException();
    }
    this.position = this.position.shift(direction);
}

사용하는 쪽은 이렇게 된다.

public void tryMove(Direction direction) {
    if (player.canMove(direction)) {
        player.move(direction);
        showRoom();
    } else {
        showBlocked();
    }
}

여기서 하나 짚고 넘어갈 것이 있다.

누군가는 이렇게 물을 수 있다.

"Game이 player에게 canMove()로 물어보고 나서 move()를 시키는 건 묻지말고 시켜라 원칙 위반 아닌가?"

아니다.

Player.move() 내부를 보면, canMove()를 호출해서 이동 가능한 경우에만 위치를 변경한다.

플레이어가 자신이 이동할 수 있는지 스스로 판단하고, 스스로 상태를 변경하고 있다.

Game은 그저 "이동해라"고 시킬 뿐이다.

판단과 실행의 주체가 Game이 아니라 Player 자신이라는게 핵심이다.

CQS 를 따를 때 이 패턴은 자주 나온다. 클라이언트가 쿼리로 상태를 확인하고, 명령으로 변경을 요청하는 구조다.

CQS의 트레이드오프 — 원칙이 독이 되는 순간

CQS를 배우고 나면 모든 메서드에 적용하고 싶어진다. 그런데 현업에서는 이 원칙을 기계적으로 적용했다가 오히려 코드가 나빠지는 경우가 있다.

대표적인 케이스가 검증 비용이 클 때다.

canMove() → move() 패턴을 보면, canMove() 내부에서 이미 벽 충돌 여부를 계산한다. 그리고 move() 내부에서도 같은 계산을 다시 한다.

public boolean canMove(Direction direction) {
    return !worldMap.isBlocked(position.shift(direction)); // 계산
}

public void move(Direction direction) {
    if (!canMove(direction)) { // 같은 계산을 다시
        throw new IllegalStateException();
    }
    this.position = this.position.shift(direction);
}

지금 예제에서는 단순한 위치 계산이라 비용이 거의 없다. 하지만 이 검증 로직이 DB 조회거나 외부 API 호출이라면 이야기가 달라진다.

같은 검증을 두 번 수행하는 셈이 된다.

일정 조정이 필요한 경우에는 adjust 명령을 이용해서 명시적으로 상태를 변경시켜야 합니다.

이런 상황에서 실무 감각은 이렇다.

검증 비용이 무시할 없는 때는, 쿼리를 분리하지 않고 명령 안에 검증을 포함시킨다.

public void move(Direction direction) {
    if (worldMap.isBlocked(position.shift(direction))) {
        throw new IllegalStateException("이동 불가");
    }
    this.position = this.position.shift(direction);
}

호출하는 쪽은 분기 없이 명령만 던지고, 실패 시 예외로 처리한다. 검증이 한 번만 일어나고, 책임도 Player 안에 있다.

물론 이 방식은 CQS 를 엄격하게 따르지 않는다.

move()가 성공/실패를 예외로 전달하기 때문에, 호출자가 사전에 가능 여부를 확인 할 수 없다.

이게 나쁜 선택인가? 상황에 따라 다르다.

상황	선택
검증 비용이 낮고, 호출 전 확인이 필요한 경우	canMove() + move() 분리
검증 비용이 높거나, 항상 실행 후 결과만 필요한 경우	명령 안에 검증 포함

핵심 판단 기준은 하나다.

이 쿼리를 분리하는 게 복잡도를 낮추는가? 아니면 높이는가?

CQS 는 복잡도를 낮추기 위한 도구다. 원칙을 지키기 위해 복잡도가 올라간다면, 그건 도구를 잘 못 쓰는것이다.

원칙을 처음 배울 때는 "항상 적용해야 한다"고 생각하기 쉽다. 하지만 실무에서는 원칙과 판단을 위한 기준이지, 사고를 대신하는 규칙이 아니다. CQS를 이해했다면 다음 질문은 "어떻게 적용하지" 가 아니라 "지금 이 상황에 분리하는 게 맞는가" 여야 한다.

정리

CQS가 주는 것을 한 줄씩 정리하면 이렇다.

쿼리는 믿을 수 있다. 몇 번을 불러도 결과가 같다.
명령은 표시가 난다. void 시그니처가 여기서 상태가 바뀐다고 선언한다.
명령 사이 쿼리는 안전하다. 명령이 호출되기 전까지 쿼리 결과는 동일하다고 확신할 수 있다.
값 객체와 결합하면 부수효과 범위가 좁아진다. 분석해야 할 클래스가 줄어든다.
분리가 복잡도를 높인다면 분리하지 않는다. 원칙은 목적이 아니라 수단이다.

좋은 코드는 단순히 오해하지 않는 코드가 아니다.

읽는 사람이 이전 호출과 숨겨진 상태 변화를 머릿속에 계속 추적하지 않아도 되는 코드다.

CQS 는 그 인지 비용을 줄이기 위한 설계 원칙이다.

이렇게 명령 쿼리 분리 원칙과 값 객체를 혼합하면 도
수 효과를 이해하기 위해 분석해야 하는 코드의 수를 감소시킬 수 있습니다.

결제는 중요할까? 주문이 중요할까 - 결제 코드를 읽다가 깨달은 설계의 기준

경딩 — Mon, 30 Mar 2026 21:35:25 +0900

코드는 동작하는 것만 봤는데, 이번에 왜 이렇게 설계했는지 보려고 했다.

이 글에서 얻어갈 것들

결제 vs 주문 - 무엇이 본질인지 판단하는 기준
"돈이 빠지는 순간" 을 기준으로 시스템을 나누는 방법
요구사항을 기능이 아니라 흐름으로 읽는 시각
도메인 객체로 로직을 캡슐화하는 패턴 - PaymentDiscount 설계
상태, 이력, 실패를 설계하는 방식

핵심 요악

결제는 복잡하지만 본질이 아니다. 주문이 본질이고, 결제는 그 주문을 완성시키는 수단이다.

그리고 결제 시스템에서 반드시 새겨야 할 한 가지

돈이 빠지기 전과 후는 완전히 다른 세계다. 이 경계를 모르면 시스템은 반드시 깨진다.

1. 결제를 공부하면서 처음 든 질문

처음 결제 코드를 봤을 때는 API 3개, PG 연동, 할인 계산 정도로 읽혔다. 그냥 외부 API 붙이는 거 아닌가? 싶었는데, 파고들수록 다른 기능들과 성질이 달랐다.

상품 조회, 장바구니, 주문 생성은 전부 우리 서버 안에서 끝난다. 실패해도 재시도하면 그만이다. 결제는 다르다. 외부 시스템(PG사) 이 개입하는 순간, 우리가 통제할 수 없는 변수가 들어온다.

네트워크가 끊기면?
PG사가 장애나면?
응답이 오긴 했는데 금액이 다르면?

이런 걸 생각하다 보니 결제 설계의 핵심이 "성공을 만드는 것"" 이 아니라 "실패를 흡수하는 구조를 만드는 것" 이라는 게 보이기 시작했다.

2. 진짜 요구사항은 해피케이스 바깥에 있다.

강의에서 인상 깊었던 부분이 있다. 커머스 서비스에서 기획서는 보통 이런 식으로 온다고 했다.

주문 생성 -> 결제 -> 주문 처리 완료

이게 가장 가장 위험한 문장이라는 말이 와닿았다. 기획자가 모르는게 아니라, 예외 케이스는 원래 개발자가 먼저 들고 가야 하는 거라고, 그래서 기획에 역으로 물어봐야 할 것들이 있다.

PG사가 장애 났을 때 주문이 어떻게 됩니까?
결제 실패한 주문을 다시 결제할 수 있어야 합니까?
잔액부족, 한도 초과 실패 이력을 별도로 보관해야 합니까?
결제 타임아웃이 발생하면 주문 상태는 어떻게 처리합니까?

흐름도만 받아서 구현하면 기능은 돌아간다. 하지만 실제 운영에서 터지는 문제의 대부분은 이 흐름도에 없다는 것, 이게 공부하면서 가장 크게 느낀 점이다.

요구사항은 주어지는 것이 아니라, 개발자가 끌어내는 것이다.

3. 세 개의 API 가 말해주는 구조

POST /v1/payments                    ← 우리가 받는다 (결제 계획 생성)
POST /v1/payments/callback/success   ← PG사가 우리를 호출한다
POST /v1/payments/callback/fail      ← PG사가 우리를 호출한다

처음에 그냥 API 3개라고 봤는데, 콜백 두 개는 성질이 다르다. 우리가 호출하는게 아니라 PG사가 결과를 우리에게 알려주는 것이다.

결제의 흐름 제어권은 외부에 있고, 우리는 그 결과를 받아서 처리하는 역할이다.

그래서 사실 우리가 능동적으로 설계하는 건 1개뿐이고, 나머지 2개는 외부의 언어에 맞춰 열어두는 창구다.

이걸 이해하니까 왜 콜백 파라미터가 우리 컨벤션이 아닌 PG사 스펙을 따르는지도 납득이 됐다.

4. 결제 생성 - "의도"를 저장하는 단계

결제 생성 API 에서 실제 돈은 빠지지 않는다.

이 단계에서 본질은

이 주문을 어떻게 결제할지 확정하는 것

@PostMapping("/v1/payments")
fun create(user: User, @RequestBody request: CreatePaymentRequest): ApiResponse<CreatePaymentResponse> {
    val order = orderService.getOrder(user, request.orderKey, OrderState.CREATED)
    val ownedCoupons = ownedCouponService.getOwnedCouponsForCheckout(user, order.items.map { it.productId })
    val pointBalance = pointService.balance(user)
    val id = paymentService.createPayment(
        order = order,
        paymentDiscount = request.toPaymentDiscount(ownedCoupons, pointBalance),
    )
    return ApiResponse.success(CreatePaymentResponse(id))
}

코드를 보면 순서가 있다. 주문 조회 -> 보유 쿠폰 조회 -> 포인트 잔액 조회.

이 세가지를 먼저 가져오는 이유는 사용자가 요청한 할인이 실제로 가능한지 검증하기 위해서다. 그리고 이 검증과 계산을 PaymentDiscount라는 객체에 위임한다.

PaymentDiscount

이 객체의 진짜 역할은 단순 계산이 아니다.

비즈니스 규칙을 객체 안에 가두는 것

data class CreatePaymentRequest(
    val orderKey: String,
    val useOwnedCouponId: Long?,
    val usePoint: BigDecimal?,
) {
    fun toPaymentDiscount(ownedCoupons: List<OwnedCoupon>, pointBalance: PointBalance): PaymentDiscount {
        return PaymentDiscount(
            ownedCoupons = ownedCoupons,
            pointBalance = pointBalance,
            useOwnedCouponId = useOwnedCouponId ?: -1,
            usePointAmount = usePoint ?: BigDecimal.valueOf(-1),
        )
    }
}

data class PaymentDiscount(
    private val ownedCoupons: List<OwnedCoupon>,
    private val pointBalance: PointBalance,
    val useOwnedCouponId: Long,
    private val usePointAmount: BigDecimal,
) {
    val couponDiscount: BigDecimal
    val usePoint: BigDecimal

    init {
        // 쿠폰을 쓰겠다고 했으면, 실제 보유 쿠폰 목록에서 찾아서 할인 금액 계산
        // 없거나 유효하지 않으면 예외 — 서비스 레이어가 이 로직을 알 필요 없음
        couponDiscount = if (useOwnedCouponId > 0) {
            ownedCoupons.firstOrNull { it.id == useOwnedCouponId }
                ?.coupon?.discount ?: throw CoreException(ErrorType.OWNED_COUPON_INVALID)
        } else {
            BigDecimal.ZERO
        }

        // 포인트를 쓰겠다고 했으면, 잔액 초과 여부 먼저 검증
        // 포인트 잔액은 이미 위에서 조회해서 넘겨줬기 때문에 DB 재조회 없음
        usePoint = if (usePointAmount > BigDecimal.ZERO) {
            if (usePointAmount > pointBalance.balance)
                throw CoreException(ErrorType.POINT_EXCEEDS_BALANCE)
            usePointAmount
        } else {
            BigDecimal.ZERO
        }
    }

    fun paidAmount(orderPrice: BigDecimal): BigDecimal {
        val amount = orderPrice - (couponDiscount + usePointAmount)
        // 할인 금액이 주문 금액보다 크면 음수 — 비즈니스상 허용하지 않음
        if (amount < BigDecimal.ZERO) throw CoreException(ErrorType.PAYMENT_INVALID_AMOUNT)
        return amount
    }
}

처음 이 코드를 보면서 "왜 굳이 클래스로 만들었지?" 라는 생각이 든다. 서비스에서 직접 계산해도 되지 않을까?

근데 서비스 레이어에 쿠폰 검증 로직, 포인트 잔액 검증 로직, 최종 금액 계산 로직을 다 넣으면 어느 순간 함수가 50줄을 넘는다. 그리고 할인 정책이 바뀌는 날, 어디를 고쳐야 할지 몰라서 코드 전체를 뒤진다.

PaymentDiscount 는 "할인" 이라는 개념을 하나의 경계로 묶은 것이다. 쿠폰과 포인트가 어떻게 계산되는지는 이 객체만 알면 된다. 서비스는 그냥 결과를 받아 쓰면 된다. 할인 정책이 바뀌어도 변경 범위가 이 객체 안으로 제한된다.

즉 로직을 옮긴 것이 아니라 책임의 경계를 만든 것이다.

한 가지 더 눈에 띈 것. paidAmount 에서 0원을 허용하고 있다.

쿠폰 + 포인트로 주문 금액이 전부 커버되면 0원 결제가 가능하다는 뜻이다. "0원 결제를 허용할 것인가" 는 비즈니스 결정이고, 코드는 그 결정의 기록이다. 이런 것들이 요구 사항으로 확인돼야 하는 것들이라는 걸 이번에 배웠다.

5. 결제 성공 - 이 코드에서 가장 중요한 경계

이것이 이 글의 핵심이다.

경계

승인 전 → 돈이 안 빠짐
승인 후 → 돈이 이미 빠짐

// ── 여기까지는 고객 돈이 빠지지 않는다 ──
val order = orderRepository.findByOrderKeyAndStateAndStatus(
    orderKey, OrderState.CREATED, EntityStatus.ACTIVE
) ?: throw CoreException(ErrorType.NOT_FOUND_DATA)
// CREATED 상태인지 확인 — 이미 결제된 주문이 중복 처리되는 걸 막는다

val payment = paymentRepository.findByOrderId(order.id)
    ?: throw CoreException(ErrorType.NOT_FOUND_DATA)

if (payment.userId != order.userId) throw CoreException(ErrorType.NOT_FOUND_DATA)
// 결제건의 유저와 주문의 유저가 같은지 확인 — 타인의 주문을 결제하는 케이스를 막는다

if (payment.state != PaymentState.READY) throw CoreException(ErrorType.PAYMENT_INVALID_STATE)
// READY가 아니면 이미 처리됐거나 비정상 상태 — 중복 승인 방지

if (payment.paidAmount != amount) throw CoreException(ErrorType.PAYMENT_AMOUNT_MISMATCH)
// 우리 DB의 결제 금액과 PG사가 실제 청구한 금액이 다르면 위험 신호 — 반드시 차단

/**
 * NOTE: PG 승인 API 호출 => 성공 시 다음 로직으로 진행 | 실패 시 예외 발생
 * 이 줄 이후부터 실제로 고객 돈이 빠진다
 */

// ── 여기부터는 고객 돈이 이미 빠졌다 ──
payment.success(externalPaymentKey, PaymentMethod.CARD, approveCode)
order.paid()
// 쿠폰 사용 처리
// 포인트 차감 + 적립
// 이력 저장

승인 전 : 얼마든지 검증하고 예외를 던져도 된다. 고객 돈은 안전하다.

승인 후: 고객 통장에서 이미 돈이 나갔다. 여기서 예외가 터지면 "돈은 빠졌는데 주문 상태가 완료가 안 된" 최악의 상황이 된다. 커머스 장애 중 상당수가 이 지점에서 발생한다고 한다.

복구하려면 수동으로 DB를 직접 조작하거나, PG사와 데이터를 대사(reconciliation)해서 불일치 건을 하나씩 찾아야 한다.

그래서 승인 이후의 부수 작업(이력 저장 등)은 실패해도 예외를 삼키고 로깅만 하도록 처리하는 게 더 안전할 수 있다. 이력 저장 실패 때문에 결제 완료 처리 자체가 막혀서는 안 되기 때문이다.

6. 결제 실패 - 상태가 아니라 기록이다.

이 코드는 실패 처리는 의도적으로 심플하다.

fun fail(orderKey: String, code: String, message: String) {
    val order = orderRepository.findByOrderKeyAndStateAndStatus(
        orderKey, OrderState.CREATED, EntityStatus.ACTIVE
    ) ?: throw CoreException(ErrorType.NOT_FOUND_DATA)
    val payment = paymentRepository.findByOrderId(order.id)
        ?: throw CoreException(ErrorType.NOT_FOUND_DATA)

    // 주문 상태: 변경하지 않는다
    // 결제 상태: 변경하지 않는다
    // 트랜잭션 히스토리에 실패 이력만 남긴다
    transactionHistoryRepository.save(
        TransactionHistoryEntity(
            type = TransactionType.PAYMENT_FAIL,
            ...
            message = "[$code] $message",
        )
    )
}

처음 보면 이상하다.

상태 변경 없음, 주문도 그대로, 결제 상태도 그대로 대신 "이력"만 남긴다.

실패했으면 상태를 PAYMENT_FAILED로 바꿔야 하지 않나?

바꾸지 않은 이유가 있다. 결제가 실패해도 주문은 여전히 CREATED상태다. 고객은 같은 주문으로 다시 결제를 시도할 수 있다. 만약 PAYMENT_FAILED 상태를 추가하면, 이 상태에서 제결재를 허용하는 로직이 새로 필요해진다. 상태 전이 규칙이 하나 더 생기고, 그걸 처리하는 코드도 늘어난다.

상태가 늘어날수록 시스템은 조용히 복잡해진다. 버그는 보통 상태 전이가 다르게 흘렀을 때 터진다.

운영팀에서 "결제 실패한 주문 현황을 보고 싶다" 는 요청이 오면?

트랜잭션 히스토리로 조회하면 된다.

-- 주문은 생성됐지만 결제가 실패한 건
SELECT o.*
FROM orders o
WHERE o.state = 'CREATED'
  AND EXISTS (
      SELECT 1 FROM transaction_history th
      WHERE th.order_id = o.id
        AND th.type = 'PAYMENT_FAIL'
  )

상태를 늘리지 않아도 필요한 정보는 다 꺼낼 수 있다. 이 부분이 공부하면서 인상 깊었다. 상태를 추가하는게 기본값처럼 생각됐는데, 이력 테이블을 잘 설계해두면 상태 없이도 충분한 경우가 있다는 것.

7. 왜 주문이 결제보다 중요한가?

강의 초반부터 "결제가 중요할까, 주문이 중요할까?" 라는 질문을 계속 가져가라고 했다. 코드를 다 보고 나서 내린 결론은 주문이 더 중요하다는 것이다.

관점	주문 (Order)	결제 (Payment)
본질	핵심 도메인	수단
의존성	내부 중심	외부 의존 (PG사)
확장 방향	배송, 취소, 반품 등 연결	PG사 연동에 국한
데이터 오너십	우리가 주도	외부 데이터 포함

주문은 순수하다. 어떤 쿠폰으로 할인됐는지, 포인트가 얼마나 쓰였는지 모른다. 그건 결제의 관심사다. 이 순수함을 지켜야 나중에 배송,취소, 반품이 붙어도 주문이 흔들리지 않는다.

언어에서 드러나는 차이

주문이 배송된다. 결제가 배송된다고는 하지 않는다.

이 언어의 차이가 설계의 방향을 알려준다.

결제 수단은 바뀔 수 있다. PG사를 갈아타거나, 간편결제가 추가될 수 있다. 하지만 "고객이 무엇을 얼마에 샀는가" 라는 주문의 본질은 바뀌면 안된다. 그래서 결제의 복잡도가 주문 쪽으로 스며들지 않도록 경계를 지키는 게 중요하다는 것. 코드를 통해 실제로 느꼈다.

결제는 바뀔 수 있지만 주문은 바뀌면 안된다.

설계로 번역하면

결제 로직이 주문을 오염시키면 안된다.
외부 복잡도가 내부로 전파되면 안된다.

처음 결제 코드를 봤을 떄는 그냥 기능 하나였다. 파고들수록 이 코드 안에 꽤 많은 결정들이 담겨 있었다.

왜 할인 계산을 객체로 분리했는지, 왜 실패 시 상태를 바꾸지 않았는지, 왜 주문을 중심 축으로 잡았는지

코드를 읽는다는 건 동작을 이해하는 것이고, 잘 읽는다는 건 그 코드가 왜 그 선택을 했는지를 이해하는 것이다. 이번 공부에서 그 차이를 조금 느낀 것 같다.

결제는 수단이고, 주문이 본질이다. 이걸 이해하는 순간 코드는 단순해지고 설계는 강해진다.

좋은 객체는 부끄럼을 탄다

경딩 — Tue, 17 Mar 2026 23:51:03 +0900

디미터 법칙과 Tell, Don't Ask 로 만드는 자율적인 객체 설계

이 글에서 얻어갈 것들

Anemic Domain Model (빈혈 도메인 모델이 무엇인지, 그리고 내 코드가 이미 그 상태인지 알게 된다.
디미터 법칙과 Tell, Don't Ask를 추상적 원인이 아니라 코드 한 줄 단위에서 적용할 수 있게 된다.
Feature Envy, 열차 충돌 같은 코드 냄새를 감지하는 기준과 코드 패턴을 갖게 된다
Spring + JPA 환경에서 이 원칙들이 @Transactional, Dirty Checking과 어떻게 연결되는지 이해하게 된다
규칙을 언제 지키고 언제 의도적으로 어겨야 하는지 — 이유를 설명할 수 있는 판단 기준을 얻는다

프폴로그 - 이미 짜고 있을지도 모른다

Spring 기반 프로젝트에서 아래 패턴, 한 번쯤 써봤을 것이다.

@Service
public class OrderService {

    @Transactional
    public void shipOrder(Long orderId) {
        Order order = orderRepository.findById(orderId).orElseThrow();

        if (order.getStatus() != OrderStatus.PAID) {
            throw new IllegalStateException("결제 완료 상태에서만 배송 가능합니다.");
        }

        order.setStatus(OrderStatus.SHIPPED);
        order.setShippedAt(LocalDateTime.now());
    }
}

동작한다. 테스트도 가능하다. 그런데 시간이 지나면 문제가 드러난다.

"배송 가능 조건" 이 바뀌면 어디를 찾아가야 하는가? Order 가 아니라 OrderService 다. 이 로직이 다른 서비스에도 흩어져 있다면?

Order를 열어보면 getter/setter 만 있고 비즈니스 로직은 단 한줄도 없다.

이것이 Anemic Domain Model(빈혈 도메인 모델)이다.

1. 빈혈 도메인 모델의 본질

Martin Fowler 가 2003년 명명한 안티패턴이다.

// Anemic Domain Model — 상태는 있지만 행동이 없다
public class Order {
    private OrderStatus status;
    private LocalDateTime shippedAt;

    public OrderStatus getStatus() { return status; }
    public void setStatus(OrderStatus status) { this.status = status; }
    public LocalDateTime getShippedAt() { return shippedAt; }
    public void setShippedAt(LocalDateTime shippedAt) { this.shippedAt = shippedAt; }
}

이 객체는 상태만 있고 행동이 없다. 겉보기에는 객체지향 같지만 실제 구조는 이렇다.

데이터 -> Entity
로직 -> Service (절차지향 트랜잭션 스트립트)

반면 Rich Domain Model은 행동이 데이터와 함께 있다.

// Rich Domain Model — 스스로 판단하고 행동한다
public class Order {
    private OrderStatus status;
    private LocalDateTime shippedAt;

    public void ship() {
        if (this.status != OrderStatus.PAID) {
            throw new IllegalStateException("결제 완료 상태에서만 배송 가능합니다.");
        }
        this.status = OrderStatus.SHIPPED;
        this.shippedAt = LocalDateTime.now();
    }
}

Order 를 열면 배송인 언제 가능한지 바로 알 수 있다. 로직이 데이터 곁에 있다.

Anemic Domain Model과 Rich Domain Model 의 차이는 getter/setter 의 유무가 아니다. "이 객체에 대한 결정을 이 객체가 내리고 있는가" 다. 그리고 더 중요한 건, "그 결정이 외부에서 중복되고 있는가"다. 빈혈 도메인 모델의 진짜 위험은 로직이 여러 Service에 흘어져 일관성을 잃는 것이다.

2. 문제 정의 - 책임이 섞이면 테스트가 무너진다.

게임 코드의 tryMove를 보자.

// Game.java
private void tryMove(Direction direction) {
    if (worldMap.isBlocked(position.shift(direction))) {
        showBlocked();
    } else {
        position = position.shift(direction);
        showRoom();
    }
}

이 메서드 안에는 세 가지 서로 다른 관심사가 섞여 있다.

비즈니스 로직 - 이동 가능 여부 판단
상태 변경 - position 업데이트
외부 출력 - 콘솔에 결과 출력

결과적으로 테스트는 이렇게 된다.

// 로직 검증이 아니라 "환경 제어"가 된다
OutputStream output = new ByteArrayOutputStream();
System.setOut(new PrintStream(output));

player.tryMove(Direction.EAST);

assertThat(output.toString()).containsSequence("당신은 [(1,0)]에 있습니다.\n", " 방 (1,0)");

픽스처(초기 상태)와 결과의 관계가 눈에 들어오지 않는다. 플레이어 위치가 바뀌었는지 검증하는게 아니라, 콘솔이 어떤 문자열이 출력됐는지 검증하고 있다.

테스트가 어려운 이유는 private이기 때문이 아니다. 책임과 외부 의존성이 섞여 있기 때문이다. private 은 증상이고, 설계 과부하가 원인이다.

3. 1차 리펙토링 - 책임의 주인을 바꾼다.

tryMove는 플레이어를 이동시킨다. 플레이어 스스로가 이 책임을 져야 한다.

메서드를 이동시킬 때는 그 메서드가 접근하는 인스턴스 변수와 관련 메서드도 함께 이동해야 한다.

// Player.java — 1차 분리
public class Player {
    private WorldMap worldMap;
    private Position position;

    public void tryMove(Direction direction) {
        if (worldMap.isBlocked(position.shift(direction))) {
            showBlocked();
        } else {
            position = position.shift(direction);
            showRoom();
        }
    }

    private void showRoom() {
        System.out.println("당신은 [" + worldMap.roomAt(position).name() + "]에 있습니다.");
    }

    private void showBlocked() {
        System.out.println("이동할 수 없습니다.");
    }
}

책임은 이동했다. 하지만 문제는 그대로다. 콘솔 의존성을 함께 끌고 왔기 때문이다.

테스트는 여전히 콘솔 스트림을 가로채야 한다.

책임을 올바른 클래스로 옮기는 것은 첫 번째 단계다. 그 다음에 나쁜 의존성까지 함께 따라왔는지 확인해야 한다. 메서드를 옮기면서 문제의 위치만 바뀐 것인지, 실제로 개선됐는지를 테스트가 알려준다.

4. 2차 리펙토링 - 외부 의존성 제거

System.out은 정적 멤버다. 외부에서 교체하거나 주입할 수 없다. 이게 테스트를 어렵게 만드는 근본 원인이다.

Player 에서 출력을 걷어내고, 이동 성공 여부만 반환하게 만든다.

// Player.java
public boolean move(Direction direction) {
    if (worldMap.isBlocked(position.shift(direction))) {
        return false;
    }
    this.position = this.position.shift(direction);
    return true;
}

// Game.java — 흐름만 조율한다
public void tryMove(Direction direction) {
    if (player.move(direction)) {
        showRoom();
    } else {
        showBlocked();
    }
}

테스트가 바뀐다.

// Before — 환경을 제어해야 했다
assertThat(output.toString()).containsSequence("당신은 [(1,0)]에 있습니다.\n", " 방 (1,0)");

// After — 상태를 직접 검증한다
assertThat(player.move(Direction.EAST)).isTrue();
assertThat(player.position()).isEqualTo(Position.of(1, 0));

단순하고 명확하다. 픽스처와 결과의 관계가 한눈에 들어온다.

테스트가 쉬어진 건 테스트 기술이 좋아진 게 아니다. 객체의 역할이 명확해졌기 때문이다. 테스트 용이성 목표가 아니라 좋은 설계의 결과물이다.

5. 3차 리팩토링 - 디미터 법칙: 내부를 드러내지 말라

showRoom 을 보면 새 문제가 보인다.

// Game.java — 열차 충돌(Train Wreck)
player.worldMap().roomAt(player.position()).name()

점(.)이 연이어 나오는 이 코드를 열차 충돌(Train Wreck)이라 부른다. 겉모습 문제가 아니다. 구조적 위험이다.

Game은 Player의 내부 구조를 모두 알고 있다. WorldMap이 있고, Posion이 있고, worldMap.roomAt(position)이 Room을 반환한다는 것까지. Player 내부 구조가 바뀌면 Game도 함께 바뀐다. 결합도가 높다.

그리고 실질적인 버그도 있다. player.worldMap().roomAt(player.position())를 두 번 호출하고 있다. 같은 내부 탐색을 중복 수행한다.

디미터 법칙: 오직 인접한 이웃에게만 말하라

// Player.java — 내부 구조를 캡슐화한다
public Room currentRoom() {
    return worldMap.roomAt(position);
}

// Game.java
public void showRoom() {
    Room room = player.currentRoom(); // 한 번만 호출, 내부 구조 비노출
    System.out.println("당신은 [" + room.name() + "]에 있습니다.");
    System.out.println(room.description());
}

디미터 법칙의 본질은 점의 개수 줄이기가 아니다. 변경될 가능성이 있는 내부 구조를 숨기는 것이다. player.currentRoom().name()이 괜찮은 이유는 Room의 name()이 내부 구조가 아니라 Room의 공개 인터페이스이기 때문이다. 판단 기준은 점의 수가 아니라 내부 구조가 노출되는가다.

디미터 법칙을 따르는 코드를 부끄럼 타는 코드라고 부른다. 자기 내부를 드러내지 않는다는 뜻이다. 이 부끄럼이 캡슐화가 살아있는 증거다.

6. 4차 리팩토링 — Tell, Don't Ask: Feature Envy 제거

tryMove의 최초 형태를 다시 보자

// Game이 Player를 대신해서 판단한다 — Feature Envy
if (player.worldMap().isBlocked(player.position().shift(direction))) {
    showBlocked();
} else {
    player.move(player.position().shift(direction));
    showRoom();
}

이 코드는 Player 상태를 꺼내 Game이 직접 판단하고, 판단 결과에 따라 Player의 상태를 변경한다. 이것을 Featur Envy(기능에 대한 부러움)라고 부른다. Fowler 의 Refactoring에서 정의한 코드 냄새다. Game이 Player의 데이터를 지나치게 부러워하며 가져다 쓰고 있는 것이다.

묻지 말고 시켜라(Tell, Don' Ask): 상태를 꺼내 외부에서 판단하는 대신, 객체에게 직접 수행하도록 위임하라.

// Player.java — 스스로 판단하고 행동한다
public boolean move(Direction direction) {
    if (worldMap.isBlocked(position.shift(direction))) {
        return false;
    }
    this.position = this.position.shift(direction);
    return true;
}

// Game.java — 묻지 않고 시킨다
public void tryMove(Direction direction) {
    if (player.move(direction)) {
        showRoom();
    } else {
        showBlocked();
    }
}

데이터와 그 데이터를 이용하는 로직이 서로 다른 클래스에 있으면., 그 로직은 반드시 중복된다. if (order.getStatus() == PAID)가 OrderService, ShippingService, NotificationService에 각각 흩어지는 것이 그 예다. GRASP의 Information Expert 원칙은 이 문제의 해법을 명확히 말한다. "어떤 책임을 수행하기 위해 필요한 정보를 가진 클래스에 그 책임을 부여하라."

7. 실무 적용 - Spring/JPA에서 이게 어떤 의미인가

나쁜 코드 - Servie 가 Entity를 대신해서 결정한다.

@Transactional
public void shipOrder(Long orderId) {
    Order order = orderRepository.findById(orderId).orElseThrow();

    // Feature Envy: Service가 Order 상태를 꺼내 판단한다
    if (order.getStatus() != OrderStatus.PAID) {
        throw new IllegalStateException("결제 완료 상태에서만 배송 가능합니다.");
    }

    // Anemic Model: Order는 setter만 제공한다
    order.setStatus(OrderStatus.SHIPPED);
    order.setShippedAt(LocalDateTime.now());
    // orderRepository.save(order) — 이걸 명시적으로 호출하는 코드도 많다
}

좋은 코드 - Entity가 스스로 결정하고 행동한다.

// Order.java
public void ship() {
    if (this.status != OrderStatus.PAID) {
        throw new IllegalStateException("결제 완료 상태에서만 배송 가능합니다.");
    }
    this.status = OrderStatus.SHIPPED;
    this.shippedAt = LocalDateTime.now();
    // "배송 가능 조건"이 바뀌면 이 메서드 하나만 수정한다
}

// OrderService.java
@Transactional
public void shipOrder(Long orderId) {
    Order order = orderRepository.findById(orderId).orElseThrow();
    order.ship(); // Order가 스스로 판단하고 상태를 변경한다
    // orderRepository.save(order) 불필요
}

좋은 코드 - Entity가 스스로 결정하고 행동한다.

// Order.java
public void ship() {
    if (this.status != OrderStatus.PAID) {
        throw new IllegalStateException("결제 완료 상태에서만 배송 가능합니다.");
    }
    this.status = OrderStatus.SHIPPED;
    this.shippedAt = LocalDateTime.now();
    // "배송 가능 조건"이 바뀌면 이 메서드 하나만 수정한다
}

// OrderService.java
@Transactional
public void shipOrder(Long orderId) {
    Order order = orderRepository.findById(orderId).orElseThrow();
    order.ship(); // Order가 스스로 판단하고 상태를 변경한다
    // orderRepository.save(order) 불필요
}

JPA Dirty Checking과의 연결

@Transactional 안에서 영속성 컨텍스트가 관리하는 Entity 의 상태가 변경되면, 트랜잭션 커밋 시점에 JPA가 자동으로 변경을 감지하고, UPDATE 쿼리를 실행한다. 이를 Dirty Checking 이라 한다.

order.ship() 한 줄이 내부 상태 (status, shippedAt)를 바꾸면 JPA 가 그 변경을 감지해서 save() 호출없이 DB에 반영한다.

Rich Domain Model 은 Dirty Checking과 자연스럽게 맞는다.

8. 코드 냄새 감지 체크 리스트

실제 코드를 짜거나 리뷰할 때 아래 팬턴이 보이면 멈추고 생각하라.

Feature Envy

// 이 패턴이 보이면 경고
if (something.getX() == SOME_CONDITION) {
    something.setY(newValue);
}

somthing 에게 상태를 묻고, 판단하고, 다시 something 의 상태를 바꾼다. 이 판단과 변경 로직을 something 안으로 옮겨라.

something.doY() 형태로 위임할 수 있다면 거의 항상 그게 낫다.

열차 충돌 (Train Wreck)

// 점이 두 개 이상 연속으로 나오면 의심하라
a.getB().getC().doSomething();

a 가 B 를 갖고 있고, B 가 C 를 갖고 있다는 내부 구조가 외부에 노출됐다. B 와 C 사이에 뭔가 끼어들면 a를 사용하는 모든 곳이 바뀐다.

a 에게 doSomthingOnC() 메서드를 위임할 수 있는지 확인하라.

Anemic Domain Model

// Entity 파일을 열었을 때 이게 전부라면 경고
public class Order {
    private OrderStatus status;
    public OrderStatus getStatus() { return status; }
    public void setStatus(OrderStatus status) { this.status = status; }
}

Order에 관한 비즈니스 판단이 Service에 있지 않은지 찾아라. if (order.getStatus() == ...) 패턴이 Service 여러 곳에 흩어져 있다면 빈혈 상태다.

과도한 Mock 설정

// 테스트에서 Mock 설정이 4개 이상 필요하다면 경고
when(mockA.getB()).thenReturn(b);
when(mockB.getC()).thenReturn(c);
when(mockC.doSomething()).thenReturn(result);
when(mockRepository.findById(id)).thenReturn(Optional.of(order));

테스트 대상이 너무 많은 외부 의존성을 갖고 있거나, 디미터 법칙을 위반하고 있다는 신호다.

순수한 도메인 로직 테스트에는 Mock이 거의 필요 없어야 한다.

거대한 Service

Servive 메서드가 50줄을 넘거나, Service 클래스가 500 줄을 넘기 시작하면 거의 확실하게 Anemic Domain Model 상태다.

Service 가 Entity 대신 모든 결정을 내리고 있기 때문이다.

하나라도 보이면 설계를 다시 보자. 당장 고칠 수 없더라도, 다음 번 수정 시 개선할 포인트로 기록해두는 것만으로도 달라진다.

9. 언제 규칙을 어겨도 되는가

규칙을 외운 사람과 이해한 사람의 차이는 예외를 이유와 함께 말할 수 있는가에서 드러난다.

Builder / Fluent Interface — OK

new StringBuilder()
    .append("Hello")
    .append(", World")
    .toString();

같은 타입을 반환하는 체이닝이다. 내부 구조가 바뀌어도 사용하는 쪽은 영향받지 않는다. 열차 충돌처럼 보이지만 내부 구조를 노출하지 않기 때문에 디미터 법칙 위반이 아니다.

Stream API — OK

list.stream()
    .filter(Item::isActive)
    .map(Item::getName)
    .collect(Collectors.toList());

각 연산이 스트림 파이프라인의 공개 인터페이스를 통해 연결된다. 어떤 컬렉션인지 내부 구조가 노출되지 않는다.

조회용 getter — OK

// 판단하려는 게 아니라 표시하려는 것
String displayName = order.getCustomerName();
response.setName(displayName);

상태를 꺼내 표시하는 건 Tell, Don't Ask 위반이 아니다. 문제는 상태를 꺼내서 그 객체를 대신해 판단하고 변경할 때 발생한다.

디미터 법칙과 Tell, Don't Ask는 목적이 있는 원칙이다. 결합도를 낮추고 캡슐화를 지키기 위한 것이다. 이 목적에 부합하지 않는 경우에는 의도적으로 어겨도 된다. 중요한 건 "왜 어기는지 설명할 수 있는가"다. 설명할 수 있는 예외는 판단이고, 설명 못 하는 예외는 실수다.

10. 최종 구조

4단계의 리펙토링을 거쳐 두 클래스의 역할이 명확해졌다.

Player - 자율적인 도메인 객체

이동 가능 여부를 스스로 판단한다.
자신의 상태를 스스로 관리한다.
외부 의존성 (콘솔, DB) 이 없다.
테스트가 단순하다. Mock 없이 , 상태 기반으로 검증 가능하다.

Game - 흐름 조율자

사용자 입력을 받아 명령을 해석한다.
Player에게 이동을 위임하고 결과에 따라 흐름을 결정한다.
콘솔 출력(외부 의존성)을 담당한다.

역할 분리 완료- 각자 하나의 이유로만 변경된다.

에필로그 - 누가 결정해야 하는가

이 모든 변화의 출발점은 기술이 아니었다.

"이 결정은 누가 내려야 하는가?"

이 질문 하나가 tryMove를 Player로 옮기게 했고, 콘솔 의존성을 분리하게 했고, Game이 묻는 대신 시키도록 만들었다.

나는 코드를 작성할 때 이 질문으로 설계를 검증한다.
테스트가 어색하다 -> 책임이 잘못된 위치에 있다
코드가 질문을 많이 한다 -> 객체가 수동적이다.
점이 연이어 나온다 -> 내부 구조가 노출되고 있다.

이 신호들을 읽는 눈이 생겼다면, 코드를 고치는 방향은 이미 보이기 시작한 것이다.

좋은 객체는 내부를 드러내지 않는다. 부끄럼을 탄다. 그리고 그 부끄럼이 캡슐화가 살아있다는 증거다.

테스트가 무거운 건 의지 문제가 아니라 설계 문제다

경딩 — Mon, 16 Mar 2026 00:57:22 +0900

레이어트 아키텍처의 함정과 도메인 중심 설계로의 탈출

이 글에서 얻어갈 것들

테스트가 무거운 이유가 의지 문제가 아니라 설계 문제라는 것
레이어드 아키텍처가 Fat Service 와 Anemic Domain Model을 만들기 쉬운 구조적 이유
이 문제가 코드 수준을 넘어 팀 협업과 생산성에 어떤 영향을 주는지
의존성 역전(DIP)을 통해 외부 기술을 분리하는 실전 흐름
Mock과 Fack 테스트의 차이와 언제 무엇을 써야 하는지
Spring Context 없이도 가능한 순수 Java 단위 테스트 구조
이 내용이 클린 아키텍처, 헥사고날 아키텍처와와 어떻게 연결되는지 큰 그림

1. 레이어드 아키텍처는 왜 기본이 되었을까?

Sprig 기반 프로젝트를 시작하면 대부분 자연스럽게 다음 구조를 사용한다.

Controller → Service → Repository → Database

직관적이고 배우기 쉽다. 빠르게 기능을 만들 수 있고, 초기에 이해도 어렵지 않다. 많은 CRUD 중심 서비스에서는 지금 충분히 실용적인 구조다.

문제는 프로젝트가 커지고 비즈니스 로직이 복잡해지기 시작할 때 나타난다. 특히 테스트를 진지하게 작성하기 시작하면 이런 질문이 등장한다.

테스트 한 번 돌리는 게 왜 이렇게 부담스럽지?

이 질문이 나오기 시작하면, 대부분의 경우 테스트 문제가 아니라 설계가 보내는 신호다.

현재 거의 모든 테스트가 h2 를 필요로 한다.

h2 를 사용하는 순간 그 테스트는 중형 테스트가 된다.

다시 말해 현재 시스템에는 소형 테스트가 없다.

그래서 테스트 한번 돌리는 것이 부담스럽다.

2. 코드 문제이기 전에, 팀 문제다

레이어드 아키텍처의 문제는 코드에서 시작하지만 팀에서 완성된다. 이 구조가 무너지는 건 항상 같은 패턴이다.

온보딩이 오래 걸린다. controller, service , respository 패키지를 열어도 이 시스템이 어떤 도메인을 다루는지 보이지 않는다.

기능 하나를 이해하려면 Controller → Service → Repository → Entity 를 계속 따라가야 한다. 도메인이 코드 구조에서 드러나지 않기 때문이다.

개발은 순차적으로 진행된다. Repository가 준비되기 전까지 Service 개발이 블로킹되고, Service가 나오기 전까지 Controller를 짤 수 없다. 팀 규모가 커질수록 이 병목은 선형이 아니라 지수적으로 커진다.

리펙토링이 두려운 코드가 된다. Service가 DB와 강결합되어 있으며 Service 를 건드릴 때 DB 코드도 영향을 받는다. 테스트도 무겁기 때문에 변경 검증이 느려진다. 자연스럽게 "이 부분은 건드리지 말자" 는 문화가 생긴다.

코드가 레거시가 되는 건 오래되어서가 아니라 아무도 건드리지 않기 때문이다.

아키텍처는 코드 품질보다 팀의 협업 방식을 결정한다. 좋은 구조는 좋은 코드를 만들기 쉽게 만들고, 나쁜 구조는 나쁜 코드를 만들기 쉽게 만든다.

3. 테스트가 무거워지는 이유

레이어드 아키텍처에서 테스트를 작성하다 보면 대부분 이런 환경이 된다.

Spring Context + H2 + Mockito

왜 이런 상황이 생길까? Service 가 외부 기술에 직접 의존하기 때문이다.

@Transactional
public UserEntity create(UserCreateDto dto) {
    UserEntity user = new UserEntity();
    user.setEmail(dto.getEmail());
    user.setNickname(dto.getNickname());
    userRepository.save(user);
    sendCertificationEmail(user.getEmail());
    return user;
}

이 코드의 문제는 테스트 코드가 아니라 의존성 구조다.

UserRepository, Database, MailSender, Spring Transaction에 직접 의존하기 때문에
이 메서드를 검증하려는 순간 테스트는 자연스럽게 Spring Context와 DB를 필요로 하는 테스트가 된다.

이 시점에서 테스트는 이미 단위 테스트가 아니라 중형 통합 테스트가 된다.

이런 테스트는 보통 1-3초 이상 걸리고, 수백 개가 쌓이면 CI 시간이 크게 늘어난다.

테스트 실행 시간이 느려지고, 작성 비용은 올라가며 개발자는 테스트 자체를 부담스럽게 느끼기 시작한다.

이것 역시 테스트 문제가 아니라 설계 문제다.

더 근본적인 문제도 있다. Elasticsearch 처럼 임베디드 테스트 서버가 없는 외부 시스템은 어떻게 테스트할 것인가? H2 나 Mockito 사용법을 익히는 것이 테스트의 전부가 되어버리는 구조다.

4. 레이어드 아키텍처가 만드는 구조적 문제

데이터베이스 중심 사고

레이어드 아키텍처에서는 개발 흐름이 자연스럽게 이렇게 된다

테이블 설계 → Entity → Repository → Service → Controller

하지만 비즈니스 관점에서는 이 순서가 더 자연스럽다.

Use Case → Domain Model → Database

비즈니스 규칙이 먼저고, 데이터 저장 방식은 그 다임이다. 레이어드 아키텍처에서는 이 순서가 종종 뒤집히면서 도메인이 DB구조를 따라가게 된다.

Fat Servie 와 Anemic Domain Model

레이어드 아키텍처에서는 도메인 객체가 다음처럼 되기 쉽다.

class UserEntity {
    private String email;
    private String nickname;
    // getter/setter만 존재. 스스로 아무것도 하지 않는다.
}

데이터만 담는 수동적인 컨테이너다 이를 Anemic Domain Model (빈혈 도메인 모델) 이라 부른다.

반면 실제 로직은 모두 Servie 에 몰린다. Service 는 점점 커지고 결국 절차형 프로그램의 메인 함수처럼 변한다.

낮은 테스트 가능성

Service 가 외부 기수로가 직접 결합되어 있다.

Service
  ├── JpaRepository
  ├── JavaMailSender
  └── Database

이 구조에서는 작은 단위 테스트가 만들어지기 어렵다.

해결 방안 - 도메인을 중심으로 설계하기

문제의 핵심은 레이어드 아키텍처가 아니라 도메인이 구조에서 드러나지 않는 것이다.

DDD의 창시자 Eric Evans 는 이렇게 말했다.

소프트웨어의 복잡성은 기술이 아니라 도메인에서 발생한다.

그래서 구조를 이렇게 재구성한다.

Presentation  (Controller)
Application   (Service)
Domain        (순수 Java 비즈니스 객체)
Infrastructure (DB, 메일 등 외부 기술)

Domain Layer 가 핵심이다. 도메인은 외부 기술에 의존하지 않는 순수 Java 객체들의 협력 공간이다.

여기서 중요한 분리가 하나있다. JPA Entity(영속성 객체) 와 Domain Entity를 분리하는 것이다.

User          // Domain Entity — 비즈니스 규칙을 담는다
UserJpaEntity // Persistence Entity — DB에 저장하기 위한 객체

이 둘을 동일한 객체로 쓰는 순간, 도메인이 DB 기술에 종속된다. 분리하는 순간, 도메인은 DB가 바뀌어도 영향받지 않는 독립적이 존재가 된다.

참고: Business Layer = Application Layer + Domain Layer. 기존에 "비즈니스 레이어"라고 통칭하니 도메인이 눈에 보이지 않았던 것이다.

6. 의존성에는 방향이 있다 - 클린 아키텍처

Robert C. Martin은 클린 아키텍처에서 이것을 하나의 규칙으로 정리했다.

"소스 코드의 의존성은 반드시 안쪽, 즉 고수준 정책을 향해야 한다"

'안쪽' 이란 도메인이다. '바깥쪽'이란 DB, 메일, 프레임워크 같은 세부기술이다. 이 규칙을 어기는 순간, Service 테스트에 DB가 따라오기 시작한다.

도메인은 세부 기술이 바뀌어도 영향받이 않아야 한다. MySQL 을 MongoDB로 바꾸든, JavaMailSender 를 다른 서비스로 교체하든, 비즈니스 규칙 자체는 변하지 않는다.

이 글에서 적용하는 것이 바로 이 원칙 구현이다. 이 구조를 일반적으로 Port-Adapter 패턴, 또는 헥사고날 아키텍처라고 부른다.

7.Port-Adapter 의존성 역전하기

Service 는 이제 인터페이스 (Port)에만 의존한다. 구현체(Adapter)는 Infrastructure 레이어에 둔다.

// Service Layer / port 패키지 — Port (인터페이스)
public interface UserRepository {
    Optional<UserEntity> findById(long id);
    UserEntity save(UserEntity user);
}

// Infrastructure Layer — Adapter (구현체)
public class UserRepositoryImpl implements UserRepository {
    private final UserJpaRepository jpaRepository;
    // JPA는 구현체 안에서만 존재한다
}

메일 발송도 동일하게 분리한다.

// Port
public interface MailSender {
    void send(String email, String title, String content);
}

// Adapter
public class MailSenderImpl implements MailSender {
    private final JavaMailSender javaMailSender;
}

그리고 UserService 에서 인증 메일 로직을 분리해 CertificationService 로 독립시킨다. SRP (단일 책임 원칙) 실천이다.

@Service
@RequiredArgsConstructor
public class CertificationService {

    private final MailSender mailSender; // 구현체가 아닌 인터페이스에 의존

    public void send(String email, long userId, String certificationCode) {
        String url = generateCertificationUrl(userId, certificationCode);
        mailSender.send(email,
            "Please certify your email address",
            "Please click the following link: " + url);
    }

    private String generateCertificationUrl(long userId, String certificationCode) {
        return "http://localhost:8080/api/users/" + userId
            + "/verify?certificationCode=" + certificationCode;
    }
}

이 단순한 변경이 만들어내는 효과가 크다. MySQL을 MongoDB로 교체해도 Service 코드는 변하지 않는다.

테스트할 때는 Facke 구현체를 자유롭게 교체할 수 있다.

8. Fack 객체로 만드는 단위 테스트

class FakeMailSender implements MailSender {
    String email;
    String title;
    String content;

    @Override
    public void send(String email, String title, String content) {
        this.email = email;
        this.title = title;
        this.content = content;
    }
}

테스트는 이렇게 작성된다.

@Test
void 이메일이_정상적으로_전송되는지_확인한다() {
    FakeMailSender mailSender = new FakeMailSender();
    CertificationService service = new CertificationService(mailSender);

    service.send("test@test.com", 2L, "code");

    assertThat(mailSender.email).isEqualTo("test@test.com");
    assertThat(mailSender.content).contains("certificationCode=code");
}

Spring 없음. DataBase. 없음. Mockito 없음. 순수 Java 단위 테스트다.

이 테스트는 보통 수 밀리초(ms)안에 실행된다.

앞서 말한 1-3초짜리 중현 테스트와 비교해보면, 설계 하나가 테스트 속도를 수십배 바꾼다. 같은 기능을 테스트 하더라고 어떻게 테스트 하느냐가 테스트 크기를 결정한다.

테스트하기 어려운 코드에는 공통점이 있다. 책임이 분리되지 않았거나, 의존성이 잘못 설계되었거나, 도메인 로직이 Service 에 몰려있다.

반대로 테스트 하기 쉬운 코드는 결국 변경하기 쉬운 코드다.

테스트 전략을 보면 아키텍처가 보인다.

그리고 중요한 역설이 있다. 테스트 커버리지를 측정했는데 Domain/Sevice 제외하면 너무 낮게 나온다면, 그건 도메인이 빈약하다는 신호다.

CRUD 외에 비즈니스 로직이 거의 없다는 의미다. 커버리지를 높이기 위해 테스트를 추가하기 전에, 도메인이 충분히 표현되어 있는지를 먼저 검점하는 것이 좋다.

9.Mock 과 Fack - 무엇을 언제 쓸까?

Mock은 행동을 검증한다.

// 호출 여부를 검증
verify(mailSender).send(eq("test@test.com"), anyString(), anyString());

Fake는 상태를 검증한다.

// 결과값을 검증
assertThat(mailSender.email).isEqualTo("test@test.com");

Mock 자체가 나쁜 것은 아니다. 외부 API 호출 횟수나 호출 순서가 비즈니스 요구사항인 경우, , 임베디드 서버가 없는 외부 시스템을 다룰 때는 여전히 Mock이 유용하다.

다만 Mock이 지나치게 많다면 설계가 테스트 친화적이지 않을 가능성을 의심해볼 수 있다. Fack를 만들 수 없다는 건 인터페이스로 추상화되지 않았다는 의미이기도 하기 때문이다.

10. 패키지 구조 개선

변경 전 (계층형)

controller / service / repository / entity / dto

변경 후 (도메인형)

user/
  ├── domain/           ← User, UserStatus (순수 Java)
  ├── service/
  │    └── port/        ← UserRepository (인터페이스)
  ├── infrastructure/   ← UserJpaEntity, UserRepositoryImpl
  └── controller/
post/
  ├── domain/
  ├── service/
  │    └── port/
  ├── infrastructure/
  └── controller/

패키지를 열면 이 시스템이 무슨 문제를 해결했는지 바로 드러난다. 이 구조는 Vertical Slice Architecture라고도 불린다. 응집도가 높아지고, MSA 전환 시 도메인 단위 분리도 훨씬 쉬워진다.

11. 언제 이런 구조가 필요한가

효과적인 경우

- 비즈니스 규칙이 복잡한 서비스

- 테스트 자동화가 중요한 서비스

- 장기적으로 유지보수해야 하는 프로젝트

과한 경우

- 단순 CRUD 서비스

- 내부 관리 툴, 빠른 프로토타입

아키텍처에는 항상 트레이드오프가 존재한다. 팀 규모, 도메인 복잡도, 프로젝트 수명에 따라 적절한 구조는 달라진다./\

중요한 건 특정 패턴을 따르는 것이 아니라 도메인을 명확하게 드러내고 변경 비용을 낮추는 방향으로 설계하는 것이다.

마치며

좋은 아키텍처의 목적은 새로운 패턴을 적용하는 것이 아니다. 변화를 쉽게 만드는 것이다.

도메인이 살아있는 시스템은 이해하기 쉽고, 테스트하기 쉽고, 확장하기 쉽다.

반대로 도메인이 죽어 있는 시스템은 결국 Service 가 모든 것을 처리하는 거대한 절차형 프로그램이 된다.

아키텍처 패턴은 정단이 아니다. 하지만 방향은 있다. "도메인을 명확히 드러내고, 외부 기술로부터 핵심 규칙을 보호하는 것.

이 두 가지가 지켜진 시스템은 기술이 바뀌어도, 팀이 바뀌어도 살아남는다.

이 글에서 다룬 개념들의 위치를 정리하면 이렇다.

이 글에서 다룬 것
  ├── Fat Service → 도메인 분리        (DDD - Rich Domain Model)
  ├── 의존성 역전 + Port-Adapter       (Hexagonal Architecture)
  ├── 계층형 → 도메인형 패키지         (Vertical Slice Architecture)
  └── Fake 기반 단위 테스트            (Clean Architecture 테스트 전략)

아키텍처 공부는 책을 읽는 것보다, 내가 짠 코드가 왜 힘든지 설명할 수 있게 되는 과정이다. 이 글이 그 출발점이 되길 바란다.

HTTP 메서드와 멱등성 - REST API 설계에서 중요한 이유

경딩 — Sat, 14 Mar 2026 02:57:16 +0900

이 글에서 얻어갈 것들

HTTP 메서드(GET, POST, PUT, PATCH, DELETE) 의 역할과 차이를 명확히 이해할 수 있다.
멱등성(Idempotency)이 무엇인지, 왜 실무에서 중요한지 체감할 수 있다.
결제 시스템 등에서 Idempotency Key 전략이 왜 필요한지 이해할 수 있다.
REST API 설계에서 흔히 발생하는 실수 TOP 7 을 점검할 수 있다.
Spring 기반 Java 백엔드에서 HTTP 메서드를 어떻게 적용하는지 코드로 확인할 수 있다.

왜 HTTP 메서드를 제대로 알아야 할까?

REST API를 설계할 때 단순히 CRUD 에 맞춰 HTTP 메서드를 선택하는 것만으로는 충분하지 않습니다.

실제 서비스에서는 언제든 다음과 같은 상황이 발생할 수 있습니다.

네트워크 타임아웃으로 인한 재시도
클라이언트 버그로 인한 중복 요청
로드밸런서의 자동 재전송

이때 멱등성을 고려하지 않은 API는 데이터 정합성 문제로 직결됩니다. 특히 결제, 주문, 포인트 적립처럼 금전이 오가는 도메인에서는 멱등성 개념이 서비스 품질을 가르는 핵심 설계 기준이 됩니다.

네트워크는 항상 불안정하다고 가정하고 설계해야 합니다. "요청이 한 번만 도달할 것" 이라는 전제는 개발 환경에서만 유효합니다.
실제 서비스에서 멱등성을 고려하지 않은 API는 장애가 났을 때 비로소 그 빈틈이 드러난다. 멱등성은 좋은 습관이 아리나 실제 장애를 막는 방어선이다.

1.HTTP 메서드란?

HTTP 메서드는 클라이언트가 서버에 요청을 보낼 때 "이 요청이 어떤 행위를 수행하는지" 를 명시하는 수단입니다.

HTTP는 이미지, 영상, HTML, JSON, 텍스트 등 모든 데이터를 바이너리로 전송할 수 있는 프로토콜이며,

메서드는 요청이 조회인지, 생성인지, 수정인지, 삭제인지를 서버에 알려주는 역할을 합니다.

HTTP 메시지 구조

요청 메시지 (Request)

GET /users/1 HTTP/1.1
Host: api.example.com
Content-Type: application/json

(바디가 없으면 생략)

응답 메시지 (Response)

HTTP/1.1 200 OK
Content-Type: application/json

{"id":1,"name":"홍길동"}

공백라인은 단순 구분자가 아니라 HTTP 파서가 헤더와 바디를 분리하는 기준입니다.

REST API에서 메서드 역할

REST 설계의 핵심 원칙은 단순하다.

URI 는 리소스(명사) 만 표현하고, 행위(동사) 는 HTTP Method 로 표현합니다.

잘못된 설계: /getUsers, /createUser, /deleteUser
올바른 설계:

GET /users
POST /users
DELETE /users/1

URI 에 동사를 넣으면 메서드와 역할이 중복됩니다. POST /createUser 는 "POST 로 생성한다" 는 의미가 이미 담겨 있느데 URL 에 또 create를 넣는 건 같은 말을 두 번 하는 것과 같습니다. 코드는 읽히는 것입니다. 중복은 혼란을 만듭니다.

2. 주요 HTTP 메서드

GET - 조회

GET /users

서버 상태를 변경하지 않는다. (Safe)
멱등성을 가진다.
캐싱이 가능하다.

GET은 멱등성을 보장하므로 캐싱 전략을 활용하면 트래픽 폭주 상황에서도 서버 부하를 크게 줄일 수 있습니다.

대표적인 캐싱 헤더: Cache-Control, ETag, Last-Modified

POST - 생성/처리

POST /users

새로운 리소스를 생성하거나 서버 측 특정 처리를 수행
멱등성이 없다 -> 호출할 때마다 상태가 바뀔 수 있음
생성된 리소스 ID는 서버가 결정

POST 는 본질적으로 멱등하지 않으므로, 결제나 주문 같은 핵심 도메인에서는 Idempotency Key 전략을 반드시 도입해야 합니다.
이를 통해 중복 요청 시 안전하게 기존 결과를 반환할 수 있습니다.

PUT - 전체 교체

PUT /users/1

클라이언트가 지정한 URI의 리소스를 전체 교체
리소스 존재 시 -> 전체 교체/ 없으면-> 생성 (Upsert)
멱등성을 가진다.

PUT upsert는 실무에서 거의 사용하지 않습니다.
클라이언트가 ID를 직접 결정해야 하기 때문에, 중복 ID 충돌이나 보안/정합성 문제를 야기할 수 있습니다.

PATCH - 부분 수정

PATCH /users/1
{
  "email": "new@email.com"
}

지정한 필드만 변경하고 나머지는 유지
멱등성은 설계에 따라 달라진다.

실무에서는 수정 API 는 PATCH를 기본으로 사용하고, PUT은 "리소스 전체를 명시적으로 교체할 떄만" 사용하는 것이 안전합니다.

DELETE - 삭제

DELETE /users/1

리소스를 삭제
멱등성을 가진다. -> 이미 없는 리소스를 삭제해도 서버 상태 동일

DELETE는 Safe 하지 않지만 멱등입니다.
삭제된 리소스가 없으면 상태 그대로 라는 특징 덕분에 여러 번 호출해도 안전합니다.

3. PUT vs PATCH - 실무에서 PATCH를 선호하는 이유

기존 유저 데이터

{
  "name": "Hwang",
  "email": "hwang@email.com",
  "age": 30,
  "phone": "010-1111-2222"
}

PUT 요청:

PUT /users/1
{
  "name": "Hwang",
  "email": "hwang@email.com"
}

결과(서버 구현에 따라):

{
  "name": "Hwang",
  "email": "hwang@email.com",
  "age": null,       // 데이터 손실
  "phone": null      // 데이터 손실
}

-> 일부 데이터 손실 위험

PATCH 요청:

PATCH /users/1
{
  "email": "new@email.com"
}

결과:

{
  "name": "Hwang",
  "email": "new@email.com",   // 변경됨
  "age": 30,                   // 유지
  "phone": "010-1111-2222"     // 유지
}

기존 데이터 유지, 필요한 부분만 안전하게 수정

PUT을 쓰다가 실수로 일부 필드만 전송하면 기존 데이터가 null로 덮어씌어지는 사고가 발생합니다. 실제 운영 환경에서 이런 실수는 생각보다 자주 일어납니다. 수정 API는 기본적으로 PATCH를 선택하고. PUT은 "리소스 전체를 명시적으로 교체 하는 경우" 에만 의도적으로 사용하는 것을 권장합니다.

4. 멱등성(Idempotency)이란?

동일한 요청을 여러 번 보내도 서버의 최종 상태가 항상 동일한 성질입니다.

수학적으로 표현하면

f(f(x)) = f(x)

한 번 호출하든 100번 호출하든 결과가 같아야 합니다.

메서드	멱등성	Safe	캐싱
GET	O	O	O
POST	X	X	X
PUT	O	X	X
PATCH	설계에 따라	X	X
DELETE	O	X	X

Safe 와 멱등성 - 헷갈리기 쉬운 개념

Safe는 서버 상태를 아예 변경하지 않는 것이고(GET, HEAD만 해당), 멱등은 여러 번 호출해도 최종 상태가 같은 것입니다. DELETE는 서버의 리소스를 삭제하므로 Safe 하지 않습니다.

하지만 몇 번을 호출해도 "해당 리소스가 없음" 상태가 유지되므로 멱등합니다.

PATCH의 멱등성은 설계에 따라 달라집니다.

// 멱등한 PATCH — 몇 번 호출해도 결과 동일
PATCH /users/1  { "status": "active" }

// 비멱등 PATCH — 호출할 때마다 값이 달라짐
PATCH /counter  { "op": "increment" }

PATCH 는 어떤 로직을 담느냐에 따라 멱등할 수도, 아닐 수도 있습니다.

PATCH 는 비멱등이다 라고 단정 짓는 것 자체가 틀렸습니다. 내가 설계하는 PATCH가 멱등인지 아닌지를 의식적으로 판단하는 것이 핵심입니다.

5. 멱등성과 결제 시스템 - Idempotency Key 전략

멱등성 개념이 실제로 어떻게 쓰이는지는 결제 도메인을 보면 가장 잘 이해됩니다.

문제 상황

1. 사용자가 결제 버튼 클릭
2. POST /payments 요청
3. 서버 결제 처리 완료
4. 응답이 클라이언트에 도달하지 않음
5. 재시도 → POST /payments 재전송
6. 결제 두 번 발생 ⚠️

서버 입장에서는 두 요청 모두 유효한 새 요청입니다. 멱등성을 보장하는 장치가 없다면 결제는 두 번 일어납니다.

해결책 - Idempotency Key:

POST /payments
Idempotency-Key: payment-unique-key-abc123

{
  "amount": 10000,
  "method": "card"
}

서버는 이 키를 기준으로 요청을 판단합니다.

처음 요청 -> 결제 처리 후 키와 결과를 저장
같은 키 재요청 -> 새로 처리하지 않고 기존 결과 반환

POST 는 본질적으로 멱등하지 않기 때문에, 안전한 결제 처리를 위해 반드시 API 레벨에서 구현해야 합니다.

6. REST API 설계 실수 TOP 7

URI에 동사를 사용합니다.
- 잘못된 설계
  - /getUsers /createUser /deleteUser
- 올바른 설계
  - GET /users POST /users DELETE /users/1
- URL은 자원을 표현하고, 동사는 메서드가 담당합니다. 두 곳에 동사를 넣는 건 역할 중복입니다.
POST 를 모든 곳에 사용합니다.
- 잘못된 설계
  - POST /users/update
  - POST /users/getList
- 올바른 설계
  - POST /users/delete
  - GET /users
  - PATCH /users/1
  - DELETE /users/1
- HTTP 메서드 자체가 행위를 표현하는 수단인데 이를 무시하고 POST로 통일하면 API를 읽는 사람이 의도를 파악하기 어렵습니다,
리소스를 단수로 표현합니다.
- 컬렉션을 나타낼 때는 복수 명사를 사용하는 것이 관례다. 팀 내에서 통일하는 것이 중요합니다.
리소스의 소유 관계를 URI 로 표현하지 않습니다.
- 쿼리 파라미터로 조건을 거는 방식
  - GET /orders?userId=1
- 소유 관계를 URI 계층 구조로 표현하는 방식
  - GET /users/1/orders
- 두 설계 모두 틀리지 않습니다 차이는 의도에 있습니다.
- GET /orders?userId=1은 "전체 주문 중 userId=1인 것을 필터링"하는 느낌입니다.
- 반면 GET /users/1/orders는 URI 계층 구조 자체가 "이 주문들은 유저 1에 종속된 것"이라는 소유 관계를 명확히 드러냅니다. 읽는 사람이 URI만 봐도 관계를 바로 파악할 수 있습니다.
- 실무에서는 이렇게 구분하는 경우가 많다.
  - GET /users/1/orders → 유저 1의 주문 목록 (소유 관계)
    GET /orders?status=pending → 전체 주문 중 대기 중인 것 (필터링/검색)
상태 코드를 판단 기준 없이 사용합니다
- 상황에 맞는 코드 선택
멱등성 고려 안함 -> 중복 요청 시 Idempotency Key전략 필요
API 버전 관리하지 않습니다
- 버전 없음 - 스펙 변경 시 하위 호환이 불가합니다.
  - users
- URI 버전 관리
  - /v1/users, /v2/users 등 명시
- 서비스가 커지면 반드시 API 버전 관리가 필요해집니다. 처음부터 /v1을 붙이는 습관을 들이십다.
- 나중에 추가하려면 이미 배포된 클라이언트가 있어 되돌리기 어렵습니다.

실무에서는 사소한 설계 실수도 장애, 버그. UX 문제로 이어집니다.

미리 규칙과 기준을 잡는 것이 유지보수와 서비스 안정성에 큰 차이를 만듭니다.

7. Spring에서 HTTP 메서드 적용

@RestController
@RequestMapping("/v1/users")
public class UserController {
    private final UserService userService;
    public UserController(UserService userService) {
        this.userService = userService;
    }

    @GetMapping
    public ResponseEntity<List<UserResponse>> getUsers() {
        return ResponseEntity.ok(userService.findAll());
    }

    @GetMapping("/{id}")
    public ResponseEntity<UserResponse> getUser(@PathVariable Long id) {
        return ResponseEntity.ok(userService.findById(id));
    }

    @PostMapping
    public ResponseEntity<UserResponse> createUser(@RequestBody UserCreateRequest request) {
        UserResponse response = userService.create(request);
        URI location = URI.create("/v1/users/" + response.getId());
        return ResponseEntity.created(location).body(response);
    }

    @PutMapping("/{id}")
    public ResponseEntity<UserResponse> replaceUser(@PathVariable Long id, @RequestBody UserReplaceRequest request) {
        return ResponseEntity.ok(userService.replace(id, request));
    }

    @PatchMapping("/{id}")
    public ResponseEntity<UserResponse> updateUser(@PathVariable Long id, @RequestBody UserUpdateRequest request) {
        return ResponseEntity.ok(userService.update(id, request));
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
        userService.delete(id);
        return ResponseEntity.noContent().build();
    }
}

최종 정리

메서드	역할	멱등	Safe	캐싱	실무 포인트
GET	조회	✅	✅	✅	서버 상태 변경 금지
POST	생성/처리	❌	❌	❌	ID는 서버 결정, 중복 주의, Idempotency Key 고려
PUT	전체 교체	✅	❌	❌	일부 필드만 보내면 null 위험, Upsert 거의 안 씀
PATCH	부분 수정	⚠️	❌	❌	설계에 따라 멱등 여부 달라짐, 수정 API 기본 선택
DELETE	삭제	✅	❌	❌	200 vs 204 팀 기준 통일 필요

마치며

HTTP 메서드는 CRUD 표현 도구가 아니라, 서비스 안정성과 데이터 정합성을 지키는 설계 기반입니다.

항상 스스로 물어야 합니다.

이 요청이 여러 번 호출되면 어떤 일이 발생하는가?

이 사고 방식은 HTTP 에만 국한되지 않습니다.

Kafka Consumer 중복 처리, 분산 트랜잭션, 이벤트 소싱 등 안정적 시스템 설계 전반에서 반복적으로 등장합니다.

HTTP 메서드와 멱등성 개념을 이해한 개발자는, 그 사고방식을 더 큰 시스템 설계에도 자연스럽게 적용할 수 있습니다.

왜 모든 데이터 처리에는 map 이 존재할까?

경딩 — Thu, 12 Mar 2026 01:26:08 +0900

Java Stream, Spark, Reactive가 공유하는 하나의 아이디어.

map을 직접 구현하면서 람다, 제네릭, 선언형 프로그래밍의 본질을 이해한다.

개발을 하다보면 어떤 API는 너무 자연스럽게 사용하게 된다.

그 중 하나가 바로 Java의 map() 이다.

그런데 왜 존재하는지 깊게 생각해본 적 있는가?

단순히 "있으니까 쓰는" API가 아니다. map 의 본질은 데이터 변환이다.

이 글에서 얻어갈 것들

map의 본질 을 개념이 아닌 코드 수준에서 직접 이해할 수 있다,
람다와 Function 인터페이스 가 왜 등장했는지 그 필연성을 이해하게 된다,
제네릭 을 활용해 어떤 타입에도 동작하는 범용 map을 직접 만들어 볼 수 있다.
명령형 vs 선언형 프로그래밍 의 차이를 코드로 직접 체감한다,
Java Stream API 가 어떤 사고방식에서 탄생했는지, 왜 그런 구조인지 이해한다.
filter + map 조합이 데이터 파이프라인 이라는 더 큰 개념의 시작임을 알게 된다.

map 이란 무엇인가?

map 은 mapping(매핑)의 줄임말이다. 매핑이란 어떤 값을 다른 값으로 변환하는 과정을 의미한다.

문자열 "1" 을 숫자 1로 바꾸는 것, "apple" 을 "APPLE"로 바꾸는 것, 학생 객체에서 이름만 꺼내는 것.

이 모든 것이 매핑이다. 하나의 데이터를 다른 형태로 변환하는 작업이다.

그렇다면 왜 map 은 어디에나 존재할까?

이유는 단순하다. 데이터 처리의 본질이 결국 "어떤 형태의 데이터를 다른 형태로 바꾸는 것" 이기 때문이다. 이름은 달라도 내부에는 동일한 철학이 흐른다. map을 이해하면 이 모든 기술이 낯설지 않게 된다.

즉 데이터 처리의 핵심은 데이터 변환이다.

이 때문에 Java Stream뿐 아니라 Spark, Reactive, Kafka Streams 등 모든 데이터 처리 프레임워크에 map 이 존재한다.

처음엔 항상 중복이 보인다

가장 단순한 방식으로 시작해보자. 문자열 리스트를 두 가지 방식으로 변환하는 코드다.

private static List<Integer> mapStringToInteger(List<String> list) {
    List<Integer> numbers = new ArrayList<>();
    for (String s : list) {
        numbers.add(Integer.valueOf(s));  // ← 이 한 줄만 다름
    }
    return numbers;
}

private static List<Integer> mapStringToLength(List<String> list) {
    List<Integer> numbers = new ArrayList<>();
    for (String s : list) {
        numbers.add(s.length());  // ← 이 한 줄만 다름
    }
    return numbers;
}

두 메서드를 나란히 놓고 보면 딱 한줄만 다르다.

나머지는 리스트를 순회하고, 값을 담아 반환하는 완전히 동일한 구조다. 경험 있는 개발자라면 이 순간 본능적인 불쾌감을 느낀다.

이 불쾌감을 중요하다. 좋은 코드를 향한 감각은 이 찝찝함에서 시작된다.

좋은 코드의 목표는 단순히 중복을 제거하는 것이 아니다. 변하는 것과 변하지 않는 것을 분리하는 것이다.

여기서 변하지 않는 것은 "리스트를 순회하면서 변환한 값을 모은다" 는 구조, 변하는 것은 "어떻게 변환하느냐" 다.

이런 감각이 쌓이면 개발자는 점점 더 작은 중복도 참지 못하게 된다. 그리고 그 순간이 바로 추상화가 태어나는 순간이다.

람다로 변환 전략을 외부에서 주입하기

변하는 부분, 즉 "변환 방법" 을 외부에서 주입하면 된다.

public static void main(String[] args) {
    List<String> list = List.of("1", "12", "123", "1234");

    // 변환 전략을 람다로 전달
    Function<String, Integer> toNumber = s -> Integer.valueOf(s);
    List<Integer> numbers = map(list, toNumber);

    Function<String, Integer> toLength = s -> s.length();
    List<Integer> lengths = map(list, toLength);
}

private static List<Integer> map(List<String> list,
                                   Function<String, Integer> mapper) {
    List<Integer> numbers = new ArrayList<>();
    for (String s : list) {
        Integer value = mapper.apply(s);  // 전달받은 람다를 실행
        numbers.add(value);
    }
    return numbers;
}

map 은 이제 변환 방법을 모른다.

단지 "리스트를 순회하며 mapper를 적용하고 결과를 모은다" 는 역할만 한다. 변환 전략은 완전히 외부에 위임됐다.

이 구조는 객체지향의 전략 패턴(Strategy Pattern)과 본질적으로 동일하다. 전략 패턴에서는 인터페이스를 구현한 클래스를 주입했다면, 람다에서는 클래스 없이 코드 조각 자체를 직접 주입한다.

제네릭으로 범용성 획득하기

현재 map은 String -> Integer 변환만 가능하다. 제네릭을 도입하면 어떤 타입 조합도 처리할 수 있는 범용 map이 된다.

public class GenericMapper {

    public static <T, R> List<R> map(List<T> list,
                                          Function<T, R> mapper) {
        List<R> results = new ArrayList<>();
        for (T item : list) {
            R value = mapper.apply(item);
            results.add(value);
        }
        return results;
    }
}

T는 입력 타입, R은 출력 타입이다. String이었던 자리에 T가, Integer였던 자리에 R이 들어갔을 뿐이다.

List<String> fruits = List.of("apple", "banana", "orange");

// String → String
List<String> upper = map(fruits, s -> s.toUpperCase());

// String → Integer
List<Integer> lengths = map(fruits, s -> s.length());

// Integer → String
List<Integer> nums = List.of(1, 2, 3);
List<String> stars = map(nums, n -> "*".repeat(n));

upper = [APPLE, BANANA, ORANGE]
lengths = [5, 6, 6]
stars = [*, **, ***]

여기서 중요한 건 단순히 코드가 유연해졌다는게 아니다.

타입에 대한 추상화 수준이 올라갔다는 것이다.

처음 구현에서 코드는 이렇게 생각했다. "String 을 Integer 로 바꾼다"

제네릭을 도입 시 "어떤 타입이든 다른 타입으로 변환할 수 있다."

문제를 바라보는 관점이 구체적인 타입 → 변환이라는 행위 자체로 올라간다. 이것이 고차 함수(Higher-Order Function)의 특징이다.

즉 행위 자체(변환)에 집중하게 된다 → 고차 함수(Higher-Order Function) 특징

filter + map: 데이터 파이프라인의 탄생

filter 로 걸러내고 map으로 변환하는 조합은 강력하다. 이 두 가지를 함께 사용하는 순간 단순한 유틸리티가 아니라 데이터 파이프라인이라는 더 큰 개념이 모습을 드러낸다.

학생 목록에서 80점 이상인 학생의 이름만 추출해보자.

List<Student>

Apple/100, Banana/80, Berry/50, Tomato/40

▼

filter( score >= 80 )

Apple/100, Banana/80 → 통과

▼

map( s → s.getName() )

Student → String 변환

OUT

List<String>

["Apple", "Banana"]

명령형 스타일 - 어떻게 (HOW)

static List<String> direct(List<Student> students) {
    List<String> result = new ArrayList<>();
    for (Student s : students) {
        if (s.getScore() >= 80) {
            result.add(s.getName());
        }
    }
    return result;
}

집중 포인트: 어떻게 순회하고, 조건 검사하고, 결과를 수집할지
문제점: 실행 흐름을 머릿속에서 시뮬레이션해야 로직을 이해
중복/변화: 조건과 수집 로직이 코드 곳곳에 섞여 있음

선언형 스타일 - 무엇을(WHAT)

코드 자체가 요구사항을 표현

static List<String> lambda(List<Student> students) {
    List<Student> filtered =
        GenericFilter.filter(students,
            s -> s.getScore() >= 80);   // 80점 이상만

    List<String> names =
        GenericMapper.map(filtered,
            s -> s.getName());            // 이름만 추출

    return names;
}

집중 포인트: "80점 이상 학생의 이름"이라는 의도 자체를 선언
장점: 코드만 봐도 요구사항과 데이터 흐름이 직관적으로 이해됨
추상화: 변하는 부분(람다)과 변하지 않는 부분(순회/수집) 완전히 분리
재사용성: 제네릭과 고차 함수를 활용하면 다른 타입/조건에도 그대로 재사용 가능

direct() 는 for 와 if 를 직접 제어한다. 어떻게 할지를 설명한다.

lambda() 는 filter와 map 으로 선언한다. 무엇을 원하는지 말한다.

같은 결과를 내지만 코드를 읽는 방식이 완전히 다르다. direct() 는 실행 흐름을 따라가야 의도가 보이고, lambad() 는 코드 자체가 요구사항이다.

이게 filter + map 조합이 단순한 유틸리티를 넘어서는 이유다. 데이터가 어떤 조건으로 걸러지고, 어떤 형태로 변환되는지를 파이프라인처럼 선언적으로 표현할 수 있게 된다.

핵심 차이

구분	명령형(HOW)	선언형(WHAT)
사고 초점	어떻게 구현할까	무엇을 원하는가
로직 이해	실행 흐름 시뮬레이션 필요	코드만 읽어도 요구사항 직관적
코드 구조	조건/순회/수집 혼합	변하는 부분과 변하지 않는 부분 분리
재사용성	타입마다 코드 반복 필요	제네릭+람다로 범용적
가독성	복잡해질수록 난해	요구사항이 코드 그대로 드러남

결론: map + 람다 + 제네릭 + 선언형 패턴은, 단순히 문법이 아니라 데이터 변환 사고방식을 '무엇을 원하는가' 중심으로 바꾸는 도구다.

명령형 vs 선언형 : 사고 방식의 전환

두 스타일의 차이는 단순히 코드 길이가 아니다. 문제를 바라보는 방식 자체가 다르다.

명령형 프로그래밍

어떻게(HOW) 할 것인가에 집중
각 단계를 명확하게 지시
상태 변화를 직접 관리
로직이 복잡해질수록 코드도 복잡해짐
세밀한 제어가 필요할 때 유리

선언형 프로그래밍

무엇을(WAHT) 할 것인가에 집중
원하는 결과를 선언
내부 구현은 추상화
요구사항이 코드에 그대로 드러남
가독성과 유지보수에 유리

스타일	초점	특징
명령형	어떻게(HOW)	for, if, 상태 직접 제어, 로직 따라가며 이해 필요
선언형	무엇(WHAT)	요구사항을 직접 표현, 내부 구현 추상화, 가독성·유지보수 유리

선언형 코드는 코드가 곧 문서가 된다.

filter(score >= 80)를 읽으면 "80점 이상 필터: 라는 비즈니스 요구사항이 한눈에 보인다.

반면 명령형 코드는 for, if, add가 뒤섞여 의도를 파악하려면 머릿속에서 시뮬레이션을 돌려야한다. 비즈니스 로직이 복잡해질수록 이 차이는 더 극명하게 드러난다.

좋은 코드는 대부분 "무엇을 하고 싶은지" 가 더 잘 드러나는 코드다.

결국 중요한 건 사고 방식이다.

글 앞에서 이 글에서 얻어갈 것들을 나열했다. 하나씩 되짚어보자.

map 의 본질은 변환이다. 어떤 값을 다른 값으로 바꾸는 행위. 단순한 메서드가 아니라 데이터 처리의 본질을 표현하는 추상화다.

람다 → 변환 전략을 외부에서 주입
제네릭 → 타입 추상화
선언형 → 무엇을 원하는지 명시

결국 데이터를 어떻게 변환할 것인가라는 사고 방식 자체를 바꿔주는 도구가 바로 map 이다.

map이 바꾸는 사고방식: 전후 비교

전(명령형)	후(선언형)
어떻게(HOW) 할지를 고민	무엇(WHAT)을 원하는지 표현
for/if로 직접 순회, 조건 체크, 결과 담기	filter/map으로 의도 그대로 선언
실행 흐름을 머릿속으로 시뮬레이션해야 로직 이해	코드만 읽어도 요구사항과 데이터 흐름 직관적 이해
중복과 변하는 부분이 코드 곳곳에 흩어짐	변하는 부분(람다)과 변하지 않는 부분(순회/수집) 분리
타입마다 별도 코드 필요	제네릭으로 모든 타입에서 재사용 가능

핵심 차이:

map + 람다 + 제네릭 + 선언형 스타일을 쓰면, “어떻게 구현할지”가 아니라 “무엇을 원하는지”에 집중할 수 있고, 데이터 변환 로직을 추상화하여 재사용과 가독성이 극대화된다.

람다는 "변하는 것" 을 꺼내기 위해 등장했다. 두 메서드가 한 줄만 다를 때, 그 한 줄을 밖으로 꺼내는 도구가 람다다. Function<T ,R> 은 그 계약이다.

제네릭은 타입이라는 구체성을 지웠다. String -> Integer 가 아니라, T ->R. "변환한다" 는 행위만 남긴 것이다.

명령형은 어떻게를, 선언형은 무엇을 말한다. for/if 로 흐름을 제어하는 코드와, filter / map 으로 의도를 선언하는 코드는 읽히는 방식 자체가 다르다.

Java Stream API 는 이 모든 것의 완성형이다. 우리가 GenericFilter, GenericMapper 를 직접 만든 것처럼, Java 가 범용적으로 만들어둔 것이 Stream 이다. filter + map 의 체이닝, 그게 Stream 의 본질이다.

filter + map 은 데이터 파이프 라인의 시작이다. Spark도, Reactive도, Kafka Streams도 결국 같은 질문에서 출발한다. "데이터를 어떻게 걸러내고, 어떤 형태로 바꿀 것인가"

이걸 직접 만들면 어떤 구조가 나올까?

새로운 API 를 배울 때마다 이 질문을 한 번씩 던져보는 것을 권한다. 직접 구현해 보면 단순한 문법 뒤에 숨어 있던 설계 의도가 보이기 시작한다.

stream().map() 한 줄 안에는 세 가지가 들어 있다. 변하는 것과 변하지 않은 것의 분리, 타입을 넘어선 추상화, 의도를 드러내는 코드. 그게 람다와 map 이 단순한 문법 설탕이 아닌 이유다.

테스트가 어렵다면 코드 탓이 아니라 설계 탓이다 - 숨겨진 의존성의 진실

경딩 — Sun, 8 Mar 2026 02:25:58 +0900

이 글에서 얻어갈 것들

이 글을 다 읽고 나면 다음 질문들에 스스로 답할 수 있게 된다.

"테스트 짜기 어렵다"는 느낌이 사실은 무엇을 의미하는가?
외부 연동 (I/O, DB, 네트워크) 을 왜 도메인 로직과 받드시 분리해야 하는가?
분리했을 때 의존성 방향은 어느 쪽이어야 하며, 외 그 방향이어야한 하는가?
의존성 역전 원칙(DIP) 이 이론이 아니라 생존 전략인 이유는 무엇인가?
패키지로 분리하는 것만으로 충분한가? 의존성 방향까지 확인해야 하는 이유

프롤로그: 수동 테스트를 반복하는 개발자의 하루

아마 이런 경험이 있을 것이다.

코드를 수정했다. 프로그램을 직접 실행하고, 키보드로 명령어를 입력하고, 눈으로 결과를 확인한다. 또 수정했다. 또 실행한다. 또 확인한다.

자동화 테스트를 작성하려고 시도해봤지만 뭔가 이상하다.

System.setIn()으로 입력을 주입하고 ByteArrayOutputStream으로 출력을 가로채야 한다.

테스트 코드가 점점 마법처럼 보이기 시작한다.

이걸 처음 겪을 떄는 보통 두 가지 결론 중 하나를 내린다.

첫째, "나는 테스트를 못짠다" 둘째, "이 코드는 테스트하기 어려운 코드다"

둘다 틀렸다. 진짜 결론은 이것이다. "이 코드는 설계가 잘못됐다"

1. 테스트 케이스는 설계의 거울이다

아래 테스트 코드를 보자. 텍스트 어드벤처 게임의 이동 테스트다.

@Test
public void move_north_passed() {
    OutputStream output = new ByteArrayOutputStream();
    System.setOut(new PrintStream(output));
    System.setIn(new ByteArrayInputStream("go north\nquit\n".getBytes()));

    Game game = new Game();
    game.run();

    assertThat(output.toString().split("\\R")).containsSequence(
            "> 당신은 [다리]에 있습니다.",
            "큰 강 위에 돌로 만든 커다란 다리가 있습니다.",
            "> ",
            "게임을 종료합니다.");
}

처음 이 코드를 마주한 사람이라면 이런 질문이 생긴다.

"go north\nquit\n" 이 문자열은 게임과 어떤 관련이 있나? 명령어인가? 어디서 처리되나?
플레이어가 왜 "다리" 로 이동했나? 원래 어디 있었다?
System.setIn과 Game 사이를 연결하는 코드가 어디 있나?

코드 어디를 봐도 힌트가 없다. 정보가 숨겨져 있다.

이 숨겨진 정보의 원인은 테스트 코드를 못 짠게 아니다. Game 클래스 내부를 열어보면 원인이 드러난다.

package hello.objectprinciple;


// 단일 책임 원칙 사전 작업- 단일 추상화 수준 원칙 적용 (추상화 수준이 동일한 조합 메서드 형태로 만들기)
// 객체 지향 핵심: 자신의 상태를 스스로 책임지는 객체
public class Game {

    private WorldMap worldMap;
    private Position position;
    private boolean running = false;
    private Console console;

    public Game() {
        this.position = Position.of(0, 2);
        this.worldMap = new WorldMap(
                Size.with(2,3),
                new Room(Position.of(0,0), "샘", "아름다운 샘물이 흐르는 곳입니다. 이곳에서 휴식을 취할 수 있습니다."),
                new Room(Position.of(0, 1), "다리", "큰 강 위에 돌로 만든 커다란 다리가 있습니다."),
                new Room(Position.of(1, 1), "성", "용왕이 살고 있는 성에 도착했습니다."),
                new Room(Position.of(0,2), "언덕", "저 멀리 성이 보이고 언덕 아래로 좁은 길이 나 있습니다."),
                new Room(Position.of(1,2), "동굴", "어둠에 잠긴 동굴 안에 작은 화톳불이 피어 있습니다.")
        );
        this.console = new Console();
    }

    // 1. 책임을 한문장으로 적어본다.
    // 게임이 종료될때까지 루프를 실행하고,
    // 사용자에게서 입력을 받고,
    // 입력을 파싱하고,
    // 명령을 처리하고,
    // 처리 결과를 출력한다.
    private void play() {
        // 게임 플레이

        start();
        while (isRunning()) {
            showPrompt();
            parseCommand();
        }
    }



    public void run() {
        welcome();
        play();
        farewell();
    }


    private void welcome() {
        showGreeting();
        showRoom();
        showHelp();
    }

    private void showHelp() {
        console.showLine("다음 명령어를 사용할 수 있습니다.");
        console.showLine("go {north|east|south|west} - 이동, quit - 게임 종료");
    }

    private void showRoom() {
        console.showLine("당신은 ["+ worldMap.roomAt(position).name() + "]에 있습니다.");
        console.showLine(worldMap.roomAt(position).description());
    }

    private  void showGreeting() {
        console.showLine("환영합니다!");
    }


    private void parseCommand() {
        String[] commands = console.input().split("\\s+");
        switch (commands[0]) {
            case "go" -> {
                switch (commands[1]) {
                    case "north" -> tryMove(Direction.NORTH);
                    case "south" -> tryMove(Direction.SOUTH);
                    case "east" -> tryMove(Direction.EAST);
                    case "west" -> tryMove(Direction.WEST);

                    default -> showUnknown();
                }
            }
            case "quit" -> stop();
            default -> showUnknown();
        }
    }



    private void showPrompt() {
        console.show("> ");

    }

    private void showUnknown() {
        console.showLine("이해할 수 없는 명령어입니다.");
    }

    private void stop() {
        running = false;
    }

    private boolean isRunning() {
        return running;
    }

    private void start() {
        running = true;
    }




    private void tryMove(Direction direction) {
        if (worldMap.isBlocked(position.shift(direction))) {
            showBlocked();
        } else {
            position = position.shift(direction);
            showRoom();
        }
    }




    private void showBlocked() {
        console.showLine("이동할 수 없습니다.");
    }



    private  void farewell() {
        // 작별 문구 출력
        console.showLine("\n게임을 종료합니다.");
    }

}

Game은 내부에서 Scanner 를 직접 생성해 입력을 받고, System.out으로 출력한다. 외부에서는 이 사실을 알 방법이 없다. 의존성이 클래스 안에 완전히 감춰져 있기 때문이다.

테스트 코드가 이해하기 어려운 건 설계가 나쁘다는 신호다.

테스트 코드는 설계를 가장 솔직하게 드러내는 거울이기 때문이다.

2. 의존성을 분리해봤다 — 하지만 여전히 어렵다

문제를 인식했다. 외부 의존성을 별도 클래스로 분리해 명시적으로 드러내본다. 입출력 의존성을 Console 클래스로 분리한다.

public class Console {
    private Scanner scanner;

    public Console() {
        this.scanner = new Scanner(System.in);
    }

    public String input() {
        return scanner.nextLine().toLowerCase().trim();
    }

    public void showLine(String text) {
        System.out.println(text);
    }

    public void show(String text) {
        System.out.print(text);
    }
}

이제 Game은 Scanner와 System에 직접 의존하지 않는다. Console에만 의존한다.

ConsoleTest도 별도로 작성할 수 있다.

@Test
public void showLine() {
    OutputStream output = new ByteArrayOutputStream();
    System.setOut(new PrintStream(output));

    new Console().showLine("showLine");

    Assertions.assertThat(output.toString()).isEqualToIgnoringNewLines("showLine");
}

입출력 테스트는 ConsoleTest 안에서만 검증한다. 논리적으로 맞다.

그런데... GameTest를 다시 열어본다. 여전히 System.setIn()을 써야 하고, ByteArrayOutputStream으로 출력을 가로채야 한다. 달라진 게 없다.

왜일까?

3. 의존성 전이 — 분리해도 해결이 안 된 진짜 이유

이 현상의 이름은 의존성 전이(Dependency Transitivity) 다.

Game → Console → Scanner / System → 키보드 / 콘솔 화면

Game이 Console에 의존하면, Console이 의존하는 Scanner와 System의 의존성이 Game으로 전파된다. Game은 Scanner를 직접 쓰지 않지만, 간접적으로 의존하게 된다.

Console이라는 중간계층을 만들었지만, 그 콘솔이 여전히 외부 세계와 단단히 연결되어 있다. 의존성의 실뭉치가 풀린게 아니라 한겹 더 감긴 것이다.

의존성 전이가 발목을 잡는 이유는 두 가지다.

첫째, 구체 클래스에 의존하고 있다. Game은 구체 클래스인 Console에 의존하고, Console은 구체 클래스인 Scanner와 System에 의존한다. 구체 클래스에 의존한다는 건 그 내부 구현이 바뀔 때 영향을 받는다는 뜻이고, 필요할 때 다른 구현으로 교체하기도 어렵다는 뜻이다. 결합도가 높아진다.

둘째, 의존성이 숨겨져 있다. Game은 생성자에서 Console을 직접 생성한다. Console은 생성자에서 Scanner를 직접 생성한다. 이 모든 의존성이 클래스 내부에 숨어 있어서, 인터페이스만 봐서는 무엇에 의존하는지 알 수 없다. 내부 구현을 열어봐야 비로소 드러난다.

정리하면 이렇다. 구체 클래스에 의존하고, 그 의존성이 숨겨져 있는 클래스는 테스트 하기 어렵다. 외부 의존성을 감추고 있다면 문제가 더 커진다. 트릭을 동원한 난해한 테스트를 쓰거나, 개발자가 직접 손으로 테스트할 수밖에 없게 된다.

4. 변경의 관점에서 본 의존성 — 진짜 위험은 여기에 있다

테스트 문제만으로 끝나면 그나마 다행이다. 숨겨진 의존성의 진짜 위험은 변경에서 드러난다.

코드 수정의 여파는 의존성의 반대 방향으로 흐른다.

Scanner 수정 → Console 영향 → Game 영향

저수준 세부사항이 바뀌면 고수준 핵심 로직이 흔들린다.

이건 설계에서 가장 위험하다.

왜 위험한지, 클래스가 담당하는 책임을 정리하면 명확해진다.

Console: 키보드 입력과 화면 출력을 담당하는 저수준 메커니즘
Game: 게임 실행에 필요한 규칙과 흐름을 담당하는 고수준 정책

이게 왜 문제일까? 게임 정보를 화면이 아니라 파일에 출력하고 싶어졌다고 가정해보자. Disk라는 클래스가 필요하다. 그런데 Console은 Game 생성자 안에 숨겨져 있다. Console 대신 Disk를 쓰려면 Game 클래스를 직접 수정해야 한다.

출력 방식 변경 때문에 게임 로직을 건드려야 한다.

이건 단순히 불편한 게 아니다. 핵심 정책을 세부사항 때문에 수정하는 건 위험하다. 출력 방식을 바꾸다가 게임 로직에 버그가 생길 수 있다. 변경의 이유와 변경의 영향 범위가 일치하지 않는 상태다.

바람직한 방향은 반대다. 고수준 정책이 변경됐을 떄 저수준 메커니즘이 그에 맞춰 변경되어야 한다. 저수준 세부사향의 변경이 고수준 정책에 영향을 주어선 안된다.

5. 의존성 역전 — 방향을 바꾸면 모든 게 달라진다

이 문제를 근본적으로 해결하는 원칙이 의존성 역전 원칙(Dependency Inversion Principle, DIP) 이다.

DIP의 핵심은 인터페이스를 쓰는 것이 아니라, 의존성의 방향을 바꾸는 것이다.

구체 클래스가 아닌 추상화(인터페이스) 에 의존할 때 비로소 바꿀 수 있다.

지금의 의존성 구조:

Game(구체) → Console(구체) → Scanner/System(구체)

의존성을 역전시킨 구조

Game → IO 인터페이스 ← Console
                     ← Disk
                     ← MockIO (테스트용)

Game 은 Console 이 무엇인지 모른다. 그냥 "입력을 받고 출력을 할 수 있는 무언가" 라는 계약(인터페이스)만 알고 있다. 실제 구현이 Console인지 Disk인지는 Game 바깥에서 결정된다.

테스트할 때는 MockIO를 주힙하면 된다. System.setIn() 트릭이 사라진다. 파일 출력으로 바꾸고 싶으면 Disk를 주입한다. Game은 한줄도 건드리지 않는다. 의존성이 인터페이스를 통해 외부에 드러나기 때문에, 숨겨진 의존성도 사라진다.

이게 가능한 이유는 의존성의 방향이 바뀌었기 때문이다. Console이 IO 인터페이스를 구현함으로써 Game이 원하는 방식으로 동작한다. 저수준이 고수준의 규약을 따르는 구조다.

6. 패키지로 분리했다 — 그것만으로 충분한가?

외부 연동을 client나 infrastructure 같은 별도 패키지로 분리하는 것은 좋은 방향이다. 도메인과 물리적으로 분리한 것만으로도 코드 수정 시 영향 범위가 줄어드는 효과가 있다.

하지만 패키지 분리는 필요조건이지 충분 조건이 아니다. 진짜 질문은 이것이다.

도메인이 외부 연동 구현을 알고 있나?

만약 도메인 코드 안에서 외부 연동 구현체를 직접 생성하거나 참조하고 있다면, 물리적으로 패키지를 나눴더라도 논리적 결합은 그대로다. Console을 별도 클래스로 분리했지만 Game안에서 직접 생성했던 것처럼.

이상적인 구조는 이렇다.

domain 패키지
  ├── Game (고수준 정책)
  ├── IO (인터페이스 - 도메인이 정의)
  └── ...

infrastructure 패키지 (또는 client, adapter)
  ├── ConsoleIO implements IO
  ├── DiskIO implements IO
  └── ...

도메인이 인터페이스를 정의하고, infrastructure 가 그 인터페이스를 구현한다. 의존성의 방향이 infrastructure → domain이다. 도메인은 외부 연동 구현을 모른다.

패키지 이름이 client든 infrastructure든 adapter든 크게 중요하지 않다. 중요한 건 의존성의 방향과 인터페이스를 누가 소유하느냐다.

7. 외부 연동을 분리하는 진짜 이유

마지막으로 가장 본질적인 질문이다. 왜 외부 연동은 도메인 로직과 분리해야 할까?

표면적 대답은 "테스트하기 쉬워서" 다. 맞지만 충분하지 않다.

더 깊은 이유는 변경의 이유가 다르기 때문이다.

게임 로직은 게임 규칙이 바뀔 때 변경된다. 콘솔 코드는 출력 방식이 바뀔 때 변경된다. DB 연결 코드는DB 가 바뀔 때 변경된다. HTTP 클라이언트는 외부 API 스펙이 바뀔 떄 변경된다.

이것들의 변경 주기와 변경 이유는 전혀 다르다. 다른 이유로 변하는 것을 같은 클래스에 두면, 하나가 바뀔 때 다른 것도 수정해야 하는 상황이 반복된다.

특히 외부 연동은 도메인보다 훨씬 자주, 예측하기 어려운 이유로 변한다. DB가 MySQL에서 PostgreSQL로 바뀔 수 있고, 콘솔 출력이 REST API 응답으로 바뀔 수 있으며, 키보드 입력이 메시지 큐 이벤트로 바뀔 수 있다. 이 변화들이 핵심 도메인 로직을 건드리게 두어선 안 된다.

한 문장으로 정리하면 이렇다.

변하는 이유가 다른 코드는 같은 곳에 두면 안 된다. 안정적인 것이 불안정한 것에 의존하면 시스템 전체가 불안정해진다.

에필로그: 테스트가 어려우면 설계를 먼저 의심하라

테스트 코드를 짜다가 막힐 때 가장 쉬운 반응은 "이건 원래 테스트하기 어려운 코드야"라고 합리화하는 것이다.

하지만 그 막힘은 거의 항상 설계 문제에서 온다. 숨겨진 의존성이 있지 않은지, 구체 클래스에 직접 의존하고 있지 않은지, 고수준 정책이 저수준 세부사항에 묶여 있진 않은지 확인해보자.

테스트가 쉬운 코드는 대부분 좋은 설계를 갖고 있다. 반대도 성립한다. 좋은 설계를 가진 코드는 대부분 테스트하기 쉽다.

테스트하기 어렵다는 느낌은 설계를 개선하라는 신호다. 그 신호를 무시하지 말자.

왜 실무에서는 Criteria를 안 쓰고 QueryDSL을 선택할까? (JPA 쿼리 선택 기준 정리)

경딩 — Sun, 1 Mar 2026 02:37:37 +0900

JPA 가 지원하는 다양한 쿼리 방법 - JPQL부터 QueryDSL까지

JPA를 처음 배우면 em.find() 로 단건 조회하는 것부터 시작한다. 엔티티를 조회하고 연관관계를 따라 객체 그래프 탐색하는 방식은 매우 직관적이다.

하지만 실무로 넘어가면 상황이 완전히 달라진다. 다양한 검색 조건, 동적필터, 조인, 정렬, 페이징, 집계까지 단순 조회만으로 해결할 수 없는 복잡한 쿼리가 필수적으로 등장한다.

이 글을 읽고 나면 네 가지를 명확히 판단할 수 있게 된다.

JPA 가 지원하는 쿼리 방법의 종류와 각각의 실무 활용도를 이해하게 된다.
JPQL이 왜 "객체 지향 SQL"이라고 불리는지 본질적인 의미를 알게 된다.
Criteria 가 이론적으로 좋지만 실무에서 외면받는 이유를 납득하게 된다.
QueryDSL이 단순한 편의 도구가 아니라 설계 도구로 평가받는 이유를 이해하게 된다.

JPA가 지원하는 쿼리 방법

JPA는 다음과 같은 다양한 쿼리 방법을 지원한다.

JPQL
JPA Criteria
QueryDSL
네이티브 SQL
JDBC API 직접 사용 (MyBatis, SpringJdbcTemplate 등)

이 중 Criteria와 QueryDSL은 새로운 쿼리 언어가 아니라 자바 코드로 JPQL 을 생성하는 (Generator) 계열 도구다.

실무에서는 대부분의 쿼리가 JPQL과 QueryDSL로 해결되며, 특정 데이터베이스에 종속적인 기능이 필요할 때만 네이티브 SQL이나 MyBatis 등을 함께 사용한다.

JPQL - 객체를 대상으로 하는 객체 지향 SQL

em.find()나 객체 그래프 탐색만으로는 복잡한 검색 조건을 처리할 수 없다.

"18세 이상 회원 전체 조회" 같은 요구사항이 있다면 결국 WHERE 조건이 포함된 쿼리가 필요하다.

그렇다고 모든 데이터를 애플리케이션으로 가져온 뒤 메모리에서 필터링하는 것은 현실적으로 불가능하다. 네트워크 비용과 메모리 사용량이 폭발적으로 증가하고 DB 성능도 나오지 않는다. 결국 필요한 데이터만 DB에서 조회하려면 조건이 포함된 쿼리를 DB 레벨에서 실행해야 한다.

이 문제를 해결하기 위해 등장한 것이 JPQL이다.

List<Member> resultList = em.createQuery(
        "select m from Member m where m.name like '%kim%'",
        Member.class
).getResultList();

SQL과 문법이 매우 유사하지만 가장 본질적인 차이는 하나다. 테이블이 아니라 엔티티 객체를 대상으로 쿼리한다.

실행 로그를 보면 JPQL 이 먼저 주석으로 나오고, 엔티티 매핑 정보를 기반으로 실제 SQL 로 변환되어 실행된다.

/* select m from Member m where m.name like '%kim%' */
select m1_0.id, m1_0.age, m1_0.name
from MBR m1_0
where m1_0.name like '%kim%' escape ''

Criteria — 이론적으로 완벽하지만 실무에서 외면받는 이유

JPQL의 가장 큰 한계는 문자열 기반이라는 점이다. 동적 쿼리를 작성할 때 조건을 상황에 따라 붙였다 뗏다 해야 하는데, 오타 위험, WHERE/AND 순서 관리, 가독성 저하 같은 문제가 따라온다.

이를 해결하기 위해 등장한 것이 JPA Criteria다.

CriteriaBuilder cb = em.getCriteriaBuilder();
CriteriaQuery<Member> query = cb.createQuery(Member.class);
Root<Member> m = query.from(Member.class);

CriteriaQuery<Member> cq = query.select(m);

String name = "test";
if (name != null) {
    cq = cq.where(cb.equal(m.get("name"), "kim"));
}

List<Member> resultList = em.createQuery(cq).getResultList();

자바 코드 기반이라 컴파일 타임 검증이 가능하고 동적 쿼리 작성도 용이하다. 장점은 분명하다.

하지만 실무에서는 거의 사용도지 않는다. 이유는 단순히 복잡해서가 아니다.

컴파일 안전성보다 가독성과 유지보수 비용이 더 중요하기 때문이다. Criteria 로 복잡한 쿼리를 작성하면 코드만 보고 어떤 SQL이 실행되는지 직관적으로 파악하기 어렵다. 이론적으로 우수하지만 실무 생산성 관점에서는 불리한 기술이라는 평가를 받는 이유다.

QueryDSL — 가독성과 타입안전성을 동시에 해결한 실무 표준

Criteria의 단점을 실질적으로 해결한 것이 QueryDSL이다.

JPAQueryFactory query = new JPAQueryFactory(em);
QMember m = QMember.member;

List<Member> list = query
        .selectFrom(m)
        .where(m.age.gt(18))
        .orderBy(m.name.desc())
        .fetch();

문자열이 아닌 자바 코드로 JPQL 을 작성하면서도 SQL 과 유사한 형태를 유지하기 때문에 가독성이 훨씬 좋다. 컴파일 타임 문법 검증, 타입 안전성, 동적 쿼리 작성의 용이성, 리팩토링 안정성까지 Criteria 의 장점을 그대로 가져오면서 단점을 극복했다.

한 가지 중요한 점은 QueryDSL이 새로운 쿼리 언어가 아니라는 것이다. QueryDSL 은 JPQL을 타입 안정하게 생성해주는 DSL 이다. 따라서 QueryDSL을 제대로 사용하려면 JPQL 에 대한 이해가 선행되어야 한다.

네이티브 SQL — DB 종속 기능이 필요할 때

JPQL로 해결할 수 없는 특정 데이터베이스 종속 기능이 필요한 경우 네이티브 SQL 을 사용한다.

Oracle의 CONNECT BY나 특정 DB 성능 튜닝 쿼리가 대표적인 예다.

em.createNativeQuery("select id, name from Member", Member.class)
        .getResultList();

데이터베이스 종속성이 생기므로 유지보수 관점에서 신중하게 사용해야 한다.

JDBC 직접 사용 시 주의사항 — flush를 놓치지 말자

JPA를 사용하면서 JDBC, MyBatis, SpringJdbcTemplate을 함께 사용하는 것은 가능하다. 단 반드시 알아야 할 중요한 동작원리가 있다. JPA를 우회하는 SQL은 영속성 컨텍스트가 인식하지 못한다.

Member member = new Member();
member.setName("test1");
em.persist(member);

// JPA를 우회하는 SQL 실행 전 수동 flush
// createNativeQuery 의 경우 jpa 가 자동 플러시함
em.flush();

List<Member> resultList = em.createNativeQuery(
        "select id, name from Member", Member.class)
        .getResultList();

JPQL은 실행 전에 자동으로 flush가 발생하지만, JDBC를 직접 사용할 경우 JPA가 쿼리 실행을 인지하지 못하기 때문에 명시적인 flush 처리가 필요하다. 이 부분을 놓피면 정합성 문제로 이어질 수 있다.

정리 — 실무에서의 JPA 쿼리 선택 기준

방법	특징	실무 활용
JPQL	객체 지향 SQL, 문자열 기반	대부분의 쿼리
Criteria	자바 코드 기반, 가독성 낮음	거의 미사용
QueryDSL	자바 코드 기반, 가독성 높음	동적 쿼리
네이티브 SQL	DB 종속 기능 필요 시	필요할 때
JDBC / MyBatis	JPA 우회, flush 주의	필요할 때

가장 현실적인 접근 순서는 JPQL을 먼저 정확히 이해하고, 동적 쿼리와 유지보수 복잡도가 증가하는 지점에 QueryDSL 을 도입하는 것이다. 중요한 것은 특정 기술을 맹목적으로 선택하는 것이 아니라 쿼리의 복잡도, 유지보수 비용, 팀 생산성을 기준으로 적절한 도구를 선택하는 설계 관점이다.

JPQL이 있는데 왜 Querydsl을 쓸까?

경딩 — Wed, 25 Feb 2026 23:36:03 +0900

같은 쿼리로 비교하며 이해하는 Querydsl 의 진짜 가치

Querydsl 을 접하면 이런 의문이 든다.

JPQL도 있는데 왜 또 다른 쿼리 도구를 써야 하지?

겉으로 보면 JPQL과 Querydsl 은 결국 같은 JPQL을 실행한다. 하지만 실무에서의 차이는 문법이 아니라 오류를 발견하는 시점과 안전성에 갈린다.

이 글에서는 동일한 쿼리를 JPQL과 Querydsl로 각각 작성해보면서 두 방식의 차이를 코드와 동작 관점에서 직접 비교해본다.

이 글을 읽고 나면 네 가지를 명확히 이해하게 된다.

JPQL과 Querydsl의 차이를 단순 문법이 아닌 안전성 관점에서 비교할 수 있다.
Q 타입이 왜 존재하는지, 컴파일 타임 검증 구조를 이해하게 된다.
Querydsl 의 자동 파라미터 바인딩이 보안과 성능에 주는 이점을 알 수 있다.
JPAQueryFactory 를 필드로 선언해도 안전한 이유를 스프링 동작 원리 관점에서 납득하게 된다.

테스트 환경 세팅

먼저 JPQL과 Querydsl을 동일한 조건에서 비교하기 위해 테스트 환경을 구성한다.

@SpringBootTest
@Transactional
public class QuerydslBasicTest {

    @Autowired
    private EntityManager em;

    JPAQueryFactory queryFactory;

    @BeforeEach
    public void setUp() {
        queryFactory = new JPAQueryFactory(em);

        Team teamA = new Team("teamA");
        Team teamB = new Team("teamB");
        em.persist(teamA);
        em.persist(teamB);

        Member member1 = new Member("member1", 10, teamA);
        Member member2 = new Member("member2", 20, teamA);
        Member member3 = new Member("member3", 30, teamB);
        Member member4 = new Member("member4", 40, teamB);
        em.persist(member1);
        em.persist(member2);
        em.persist(member3);
        em.persist(member4);
    }
}

JPAQueryFactory 생성 시 EntityManager 를 전달받는다. 내부적으로 이 EntityManager 를 기반으로 JPQL을 생성하고, JPA 구현체(Hibernate)를 통해 최종적으로 SQL이 실행되는 구조다.

참고로 Querydsl 은 새로운 쿼리 언어가 아니라 JPQL을 타입 안전하게 생성하는 DSL(Domain Specific Language)이다.

JPQL로 member1 조회하기

먼저 전통적인 JPQL방식이다.

@Test
public void startJPQL() {
    String jpql = "select m from Member m where m.name = :name";

    Member findMember = em.createQuery(jpql, Member.class)
            .setParameter("name", "member1")
            .getSingleResult();

    Assertions.assertThat(findMember.getName()).isEqualTo("member1");
}

JPQL의 특징은 쿼리를 문자열로 작성한다는 점이다.

:name 과 같은 파라미터를 선언하고 setParameter() 로 값을 직접 바인딩한다.

문법 자체는 단순하지만 구조적인 한계가 있다.

가장 대표적인 문제는 다음과 같다.

필드명 오타를 컴파일 단계에서 검증할 수 없음
쿼리 오류가 런타임에 발견됨
리팩토링 시 안전성 낮음

예를 들어 다음과 같은 오타가 있어도 컴파일 에러는 발생하지 않는다.

"select m from Member m where m.nmae = :name" // 오타

이 경우 애플리케이션 실행 시점에서야 예외가 발생한다.
즉, 코드가 정상 컴파일되더라도 운영 환경에서 쿼리 오류가 발생할 수 있는 구조다.

Querydsl로 member1 조회하기

이제 동일한 쿼리를 Querydsl로 작성해보자.

@Test
public void startQuerydsl() {
    QMember member = QMember.member; // 이미 생성된 Q타입 사용

    Member findMember = queryFactory
            .select(member)
            .from(member)
            .where(member.name.eq("member1"))
            .fetchOne();

    Assertions.assertThat(findMember.getName()).isEqualTo("member1");
}

Querydsl은 JPAQueryFactory를 시작점으로, Q 타입(메타모델 클래스)을 이용해 쿼리를 자바 코드 형태로 작성한다.

QMember 는 Querydsl 이 빌드 과정에서 자동으로 생성하는 클래스이며, 엔티티 필드를 타입 안전하게 참조할 수 있도록 돕는다.

일반적으로 이미 생성된 정적 인스턴스를 사용한다.

QMember member = QMember.member;

new QMember("m")처럼 직접 생성할 수도 있지만, 생성자에 전달된 문자열은 별칭(alias)용도이기 때문에 특수한 조인 상황이 아니라면 기본 인스턴스를 사용하는 것이 일반적이다.

JPQL과 Querydsl의 핵심 차이

1. 오류 발견 시점 — 런타임 vs 컴파일 타임

JPQL은 문자열 기반 쿼리다.

"select m from Member m where m.nmae = :name" // 오타 발생

위와 같이 필드명을 잘못 작성해도 컴파일러가 이를 검증할 수 없다. 애플리케이션이 실행되고 해당 쿼리가 호출되는 시점에서야 오류가 발생한다.

반면 Querydsl 은 Q타입을 기반으로 쿼리를 작성한다.

member.name.eq("member1")

존재하지 않는 필드를 호출하면 컴파일 단계에서 즉시 오류가 발생한다. Querydsl 의 진짜 가치는 문법 편의성이 아니라 컴파일 타임 안전성에 있다.

2. 파라미터 바인딩 방식과 안정성

JPQL은 파라미터를 직접 선언하고 바인딩해야 한다.

.setParameter("name", "member1")

반면 Querydsl은 값을 직접 전달하는 형태로 작성할 수 있다.

.where(member.name.eq("member1"))

하지만 내부적으로 문자열을 직접 이어붙이는 방식이 아니라 JDBC의 PreparedStatement 기반 파라미터 바인딩이 자동으로 적용된다. 실행 로그를 보면 값이 ? 로 바인딩되는 것을 확인할 수 있다.

where member0_.name=?

이 구조는 두 가지 장점을 가진다.

SQL Injection 공격에 대한 방어,
그리고 동일한 쿼리 구조 재사용으로 인한 DB 성능 이점이다.

Querydsl은 편의성뿐 아니라 보안과 성능 측면에서도 안전한 기본 구조를 제공한다.

JPAQueryFactory를 필드로 선언해도 안전한 이유

실무에서 자주 나오는 질문 중 하나가 이것이다.

"JPAQueryFactory를 필드로 선언하면 멀티스레드 환경에서 안전할까?"

결론부터 말하면 안전하다.

@SpringBootTest
@Transactional
public class QuerydslBasicTest {

    @Autowired
    private EntityManager em;

    JPAQueryFactory queryFactory; // 필드 레벨 선언
}

그 이유는 스프링이 주입하는 EntityManager 가 실제 구현체가 아니라 트랜잭션 스코프 프록시이기 때문이다.

즉,

요청마다 새로운 EntityManager 를 직접 공유하는 것이 아니라
현재 트랜잭션에 바인딩된 EntityManager 가 동적으로 할당된다.

따라서 여러 스레드가 동시에 접근하더라고 각 트랜잭션에 맞는 EntityManager 가 사용되며 동시성 문제 없이 동작한다.

이 구조 덕분에 JPAQueryFactory 는 필드로 선언하여 재사용하는 것이 일반적으로 권장된다.

정리: Querydsl의 진짜 가치는 가독성이 아니다

많은 사람들이 Querydsl을 "코드가 더 깔끔해지는 쿼리 도구"라고 생각한다. 하지만 실무에서의 핵심 가치는 다르다.

	JPQL	Querydsl
쿼리 작성 방식	문자열	자바 코드
오류 발견 시점	런타임	컴파일 타임
파라미터 바인딩	직접 처리	자동 처리
SQL Injection 방어	주의 필요	자동 방어
리팩토링 안정성	낮음	높음

결국 Querydsl은 단순히 쿼리를 편하게 작성하는 도구라기보다, 런타임에 발생할 수 있는 쿼리 리스크를 컴파일 타임으로 끌어올리는 설계 도구에 가깝다. 기능 구현 속도보다 유지보수성과 안정성이 더 중요한 문제가 되는 경우가 많다.
이러한 관점에서 Querydsl은 단순한 생산성 도구가 아니라 장기적인 코드 안정성을 위한 선택지라고 볼 수 있다.

따라서 현실적인 접근은 다음과 같다.

JPQL의 동작 원리를 먼저 정확히 이해하고,
동적 쿼리와 유지보수 복잡도가 증가하는 시점에
Querydsl을 도입하는 것이 가장 합리적인 전략이다.