전체 메뉴

테마

Chapter 17

모듈 호출 오케스트레이션

Spring Boot 4.1.1과 JDK 21에서 회원 목록을 모듈마다 한 번만 조회하도록 Handler·Registry·Orchestrator를 설계하고, IN 청크·실패 정책·트랜잭션·ArchUnit 테스트를 구현합니다.

난이도
중급 심화
예상 학습
150분
Spring Boot 기준
Spring Boot 4.1.1
JDK 기준
JDK 21
최종 검토

전체 24개 Chapter 중 Chapter 17입니다. 예제 코드는 공개 저장소 spring-boot-curriculum의 examples/ch36-bulk-orchestration 폴더에서 확인할 수 있습니다.

Learning goals

오늘 배울 내용

  • 가변 길이 id 목록을 검증하고 타입 있는 호출 맥락으로 전달하기
  • Handler와 Registry로 모듈 호출을 논리 키와 계약으로 분리하기
  • Orchestrator에서 호출 순서와 STOP·CONTINUE·WARNING·SKIP 정책 적용하기
  • IN 목록을 청크로 나누고 트랜잭션 경계와 rollback-only 함정 확인하기
  • ArchUnit으로 모듈 사이 호출 방향 고정하기
  1. 목록 검증
  2. 호출 맥락
  3. Handler Registry
  4. 실패 정책
  5. 모듈별 일괄 조회
  6. 구조 테스트
이 Chapter의 진행 흐름

화면에서 회원 id를 여러 개 고르고 “요약 보기”를 누르면, 서버는 회원 정보(등급), 적립 포인트, 주문 건수를 한 번에 돌려줘야 합니다. 이 세 정보는 서로 다른 업무 모듈이 가지고 있습니다. 가장 쉬운 구현은 id마다 세 모듈을 부르는 것인데, 100명이면 300번 호출이고 모듈마다 DB를 300번 조회합니다(N+1). 다른 모듈의 테이블을 JOIN으로 직접 읽으면 호출은 줄지만 모듈 경계가 무너집니다.

이 Chapter는 이 문제를 다음 원칙으로 풉니다.

  • 값 목록(가변 IN)을 타입 있는 객체로 들고 다닙니다.
  • 모듈마다 한 번만 부릅니다. 목록은 통째로 넘깁니다.
  • 누구를 어떤 순서로, 실패하면 어떻게 할지(호출 정책)는 업무 로직과 분리합니다.
  • 모듈 안에서는 IN 목록을 묶음(chunk)으로 나누어 조회하고, 업무 판단은 Composite 규칙이 맡습니다.

이 구조의 바탕에는 네 가지 설계 원칙이 있습니다. 호출 정책과 업무 로직을 분리하고, 만능 Map 대신 명시적인 타입을 쓰고, 호출 대상을 클래스 이름이 아닌 논리 키로 찾고, 실패했을 때의 동작을 정책으로 선언합니다. 이 Chapter는 이 원칙을 member, reward, order 모듈 시나리오에 적용합니다. 호출 규칙을 DB 표로 관리하는 부분은 구현하지 않고, 코드로 정의한 규칙까지만 만들었습니다.

이 Chapter에서 만드는 것

만드는 것 설명
POST /api/members/summaries 회원 id 목록을 받아 요약을 돌려주는 API
SummaryRequest 비어 있음, 1000개 초과, null, 양수 아님을 입구에서 거절
CallContext, SummaryDraft 호출 흐름이 공유하는 타입 있는 맥락과 결과 초안
CallHandler, HandlerRegistry 모듈 api 호출 직전의 번역기와 논리 키 조회
CallRule, SummaryOrchestrator 순서와 실패 정책(STOP/CONTINUE/WARNING/SKIP)
member/reward/order 모듈 각각 api, internal, 모듈 안 Composite 규칙
Chunks 중복 제거와 IN 목록 분할
테스트 구조 4, 오케스트레이터 9, 모듈 API 7, 규칙 2, 묶음 5, 요약 API 6, 실패 정책 1, 트랜잭션 2 (이 Chapter 범위 36건)

배치 쪽 테스트(배치 7건)와 컨텍스트 1건까지 합하면 ch36 전체는 44건이고, 배치는 Chapter 18에서 다룹니다.

전체 흐름

  1. POST /api/members/summaries로 회원 id 목록을 받습니다.
  2. 입구에서 SummaryRequest로 목록을 검증합니다.
  3. SummaryOrchestrator가 규칙의 순서와 실패 정책에 따라 Handler를 실행합니다.
  4. 각 Handler(member, reward, order)는 자기 모듈 api를 목록 전체로 한 번 부릅니다.
  5. 모듈 안에서는 Chunks로 IN 목록을 나누어 조회하고, Composite 규칙으로 업무 판단을 합니다.
  6. 결과를 SummaryDraft에 모아 SummaryResult로 돌려줍니다.

직접 실행해 확인한 결과

확인 결과
ch36-bulk-orchestration test 44건 통과(12개 클래스, 실패·건너뜀 0)
[], [0], [1,null] 요청 400, issues에 해당 메시지
[1,2,3,99] 요청 200, missingIds:[99], outcomes 3개 모두 OK
[1,1,2] 요청 중복이 제거되어 회원 2명만 응답
GET /api/members/summaries?ids=1,2 405 (POST만 받음)

사전 지식과 준비물

  • Chapter 09의 동적 SQL(foreach)과 트랜잭션, Chapter 15의 Port, Chapter 16의 Composite·모듈.
  • 코드는 examples/ch36-bulk-orchestration입니다.

확인 환경

Docker 컨테이너(JDK 21.0.11), Spring Boot 4.1.1, H2 인메모리입니다. 테스트 44건(ch36 전체)은 cleanTest test로 다시 실행해 모두 통과했고, JAR를 실행해 curl로 받은 응답을 본문에 실었습니다. IN 목록 길이 제한은 DB마다 다르며 이 예제는 H2에서만 확인했습니다. 설정값 500은 예시입니다. Windows는 확인하지 못했습니다.

예제 코드

대상 링크
Chapter 전체 ch36-bulk-orchestration/
Chapter 설명(저장소 문서) README.md
요청 SummaryRequest.java
컨트롤러 MemberSummaryController.java
요약 API 테스트 SummaryApiTests.java
맥락 CallContext.java
member API MemberApi.java
모듈 API 테스트 ModuleApiTests.java
orchestration 패키지 orchestration/
Orchestrator 테스트 OrchestratorTests.java
실패 정책 API 테스트 FailurePolicyApiTests.java
member 모듈 member/
reward 모듈 reward/
규칙 테스트 ModuleRuleTests.java
Chunks ch36/
Chunks 테스트 ChunksTests.java
설정 application.yml
트랜잭션 테스트 TransactionPolicyTests.java
구조 테스트 ArchitectureTests.java

id마다 부르면 생기는 문제와 입구 검증

회원 id 목록을 받아 세 모듈의 정보를 합치는 API를 만든다고 합시다. 처음 떠오르는 구현은 반복문입니다(설명용 코드입니다).

for (long id : memberIds) {
    grade  = memberApi.gradeOf(id);        // 모듈 1 호출
    points = rewardApi.pointsOf(id);       // 모듈 2 호출
    count  = orderApi.orderCountOf(id);    // 모듈 3 호출
}

100명이면 호출이 300번이고, 각 호출은 DB 쿼리 한 번입니다. 이것이 N+1 문제입니다. 반대로 한 번에 처리하려고 요약 쿼리 하나로 세 모듈의 테이블을 JOIN하면 호출은 줄지만, 다른 모듈의 테이블 구조에 직접 의존하게 됩니다(Chapter 16).

해법은 목록을 통째로 모듈 api에 한 번 넘기는 것입니다. 이 절은 그 시작점인, 가변 길이 목록을 입구에서 받고 검증하는 부분을 다룹니다.

입구 검증

/** 가변 길이 id 목록. 비어 있거나, 1000개를 넘거나, 양수가 아닌 값이 있으면 컨트롤러 입구에서 400으로 거절한다. */
public record SummaryRequest(
        @NotEmpty(message = "memberIds는 비어 있을 수 없습니다.")
        @Size(max = 1000, message = "memberIds는 최대 1000개까지 보낼 수 있습니다.")
        List<@NotNull(message = "memberIds에 null이 있습니다.") @Positive(message = "memberIds는 양수여야 합니다.") Long> memberIds) {
}

코드 읽기

  • @NotEmpty: 빈 목록은 의미가 없는 요청이라 거절합니다. (모듈 api는 빈 목록을 빈 결과로 처리하지만, 입구에서는 사용자 실수로 보고 막습니다.)
  • @Size(max = 1000): 한 요청의 상한입니다. 입구에서 상한을 정해야 서버가 무한히 큰 요청을 떠안지 않습니다.
  • List<@NotNull @Positive Long>: 원소 하나하나에 검증을 거는 문법입니다(Chapter 06의 Bean Validation). null이나 0 이하의 id를 막습니다.
  • 이 상한(1000)과, DB로 나가는 IN 목록의 크기(bulk.in-chunk-size, 500)는 다른 값입니다. 앞은 요청의 크기, 뒤는 한 번의 SQL에 넣는 크기입니다(아래 “IN 목록을 나누는 Chunks와 MyBatis foreach” 절).

컨트롤러는 입구일 뿐

/** 입구. 검증하고 공통 맥락을 만들어 Orchestrator에 넘길 뿐, 어떤 모듈이 불리는지 모른다. */
@RestController
@RequestMapping("/api/members")
class MemberSummaryController {

    private final SummaryOrchestrator orchestrator;

    @PostMapping("/summaries")
    SummaryResult summaries(@Valid @RequestBody SummaryRequest request) {
        return orchestrator.summarize(new CallContext(request.memberIds()));
    }
}
  • GET이 아니라 POST로 받습니다. 목록이 길면 쿼리 문자열(?ids=1,2,3,...)로 보내기에 길이 제한 문제가 있고, POST 본문이 안전합니다. 서버나 프록시의 URL 길이 제한은 이 Chapter에서 직접 확인하지 않았습니다.
  • 컨트롤러는 어떤 모듈이 불리는지 모릅니다. Chapter 15의 “컨트롤러는 서비스만 부른다” 원칙입니다.

실제 응답

JAR를 실행해 curl로 받은 결과입니다.

POST /api/members/summaries {"memberIds":[]}
  -> 400 {"message":"요청 값이 올바르지 않습니다.","issues":["memberIds는 비어 있을 수 없습니다."]}

POST /api/members/summaries {"memberIds":[0]}
  -> 400 {"message":"요청 값이 올바르지 않습니다.","issues":["memberIds는 양수여야 합니다."]}

테스트(SummaryApiTests)는 null 원소([1,null])도 400, 1001개는 400, 정확히 1000개는 200이며 1000개 중 존재하는 회원 5명만 요약되고 missingIds가 995개인 것을 확인합니다. 경계값(1000/1001)을 모두 시험한 것이 핵심입니다.

따라 하기

./gradlew :examples:ch36-bulk-orchestration:bootRun
curl -s -X POST http://localhost:8080/api/members/summaries -H 'Content-Type: application/json' -d '{"memberIds":[]}'
curl -s -X POST http://localhost:8080/api/members/summaries -H 'Content-Type: application/json' -d '{"memberIds":[1,null]}'
{"message":"요청 값이 올바르지 않습니다.","issues":["memberIds는 비어 있을 수 없습니다."]}
{"message":"요청 값이 올바르지 않습니다.","issues":["memberIds에 null이 있습니다."]}

자주 하는 실수

실수 증상 해결
id마다 모듈을 호출하는 반복문 호출 수가 N × 모듈 수로 늘어남 목록을 통째로 한 번에
상한 없이 목록을 받음 거대한 요청이 서버를 압박 @Size(max = ...)
List<Long>만 검증 원소의 null·0이 통과 List<@NotNull @Positive Long>
긴 목록을 GET 쿼리로 전달 길이 제한, 405 혼동 POST 본문

확인 문제

  1. 100명을 모듈 3개에서 조회할 때 id마다 부르면 호출은 몇 번인가요?
  2. 요청 상한(1000)과 쿼리의 IN 크기(500)가 다른 값인 이유는 무엇인가요?

답: 1) 300번입니다. 2) 앞은 한 요청이 받을 수 있는 크기, 뒤는 DB 쿼리 한 번에 넣는 크기라 서로 다른 일을 하기 때문입니다.

직접 해 보기

  1. 1000개와 1001개를 직접 보내 경계를 확인하세요.
  2. @Size의 상한을 100으로 줄이면 어떤 테스트가 바뀔지 예측하세요.
  3. 자신의 API 중 목록을 받는 곳에서 상한과 원소 검증이 있는지 점검하세요.

타입 있는 맥락과 모듈 호출 계약

호출 흐름 전체가 공유하는 값을 Map<String, Object>나 JSON 노드로 만들면 편하지만, 어떤 키가 들어 있는지는 실행해 봐야 압니다. 이 과정은 명시적인 record 타입을 씁니다. 이 절은 공통 맥락 CallContext와, 모듈 api가 값 목록을 받는 계약을 읽습니다.

CallContext

/**
 * 호출 흐름 전체가 공유하는 공통 맥락. Map이나 JsonNode가 아니라 명시적 타입을 쓴다.
 * 가변 IN 값(회원 id 목록)도 List<Long> 타입으로 들고 다니며, 만들 때 중복을 제거하고 불변으로 고정한다.
 */
public record CallContext(List<Long> memberIds) {
    public CallContext {
        if (memberIds == null) {
            throw new IllegalArgumentException("회원 id 목록이 없습니다.");
        }
        memberIds = List.copyOf(new ArrayList<>(new LinkedHashSet<>(memberIds)));
    }
}

코드 읽기

  • 컴팩트 생성자(Chapter 16의 ShippingRequest에서 본 문법)에서 중복을 제거하고 순서를 유지(LinkedHashSet)한 뒤 List.copyOf로 불변으로 고정합니다. 이후 어떤 Handler가 받아도 같은 목록입니다.
  • [1, 1, 2]를 넣으면 맥락 안에서 [1, 2]가 됩니다. 중복을 제거하는 위치를 한 곳으로 정한 것입니다.
  • 타입이 List<Long>이라 Handler 코드를 읽을 때 무엇이 들어 있는지 즉시 압니다.
  • 이렇게 한 이유는 이 Chapter 첫머리에서 밝힌 원칙 “만능 Map 금지, 명시적 record 유지”와 같습니다.

모듈 api의 계약

/**
 * member 모듈이 다른 모듈에 공개하는 유일한 입구.
 *
 * <p>계약:
 * <ul>
 *   <li>gradesOf: 값 목록을 한 번에 받는다. 빈 목록이면 빈 결과, 중복은 한 번만 조회한다.
 *       없는 회원은 결과에 키를 두지 않는다(예외가 아니다). 목록이 null이면 IllegalArgumentException.
 *       목록 길이에는 제한이 없다. IN 길이는 모듈 안에서 나누어 처리한다.</li>
 *   <li>memberIdsAfter: 배치가 전체를 한 번에 읽지 않도록 id 순서로 이어 읽는다.</li>
 * </ul>
 */
public interface MemberApi {
    Map<Long, MemberGrade> gradesOf(Collection<Long> memberIds);
    List<Long> memberIdsAfter(long lastId, int limit);
}

이 인터페이스의 Javadoc이 계약서입니다. Chapter 12에서 말한 “무엇을 약속하고 무엇을 몰라도 되는가”를 문장으로 적었습니다.

입력 약속
빈 목록 빈 결과(예외 아님)
중복 한 번만 조회
없는 값 결과에 키를 두지 않음(예외 아님)
null IllegalArgumentException
길이 제한 없음. 나누는 일은 모듈 안에서

“없는 값은 예외가 아니다”가 중요합니다. 100명 중 1명이 없다고 전체가 실패하면 호출하는 쪽이 감당하기 어렵습니다. 대신 호출하는 쪽이 missingIds를 계산해 알려 줍니다(아래 “실패 정책 네 가지와 응답 모양” 절). 빈 목록과 null의 의미를 구분해 적는 것은 조건 목록을 다루는 일반 원칙입니다.

반환 타입도 계약입니다. Map<Long, MemberGrade>의 MemberGrade는 모듈이 공개하는 record이고, 내부 행(MemberRow)은 밖으로 나가지 않습니다.

/** member 모듈이 공개하는 회원 요약. 내부 행(MemberRow)은 밖으로 나가지 않는다. */
public record MemberGrade(long id, String name, String grade) { }

reward와 order도 같은 모양입니다: pointsOf(Collection<Long>) → Map<Long, Long>, orderCountsOf(Collection<Long>) → Map<Long, Long>. 기록이 없는 회원은 키가 없습니다.

계약을 테스트로 고정

ModuleApiTests는 묶음 크기를 2로 줄여 경계를 만들고 계약을 확인합니다.

테스트 확인
emptyListGivesEmptyResult 세 모듈 모두 빈 목록 → 빈 결과
unknownIdsHaveNoKey [1, 99] → 키 {1}만
duplicatesAreQueriedOnce [1,1,2,2] → 키 {1, 2}
allFiveMembersAcrossChunkBoundaries 5명 → 등급 SENIOR, REGULAR, DORMANT, REGULAR, SENIOR
pointsAreSummedPerMemberAcrossChunks {1:600, 2:100, 4:600}
orderCountsAreGroupedPerMember {1:3, 2:1, 5:2}
idsAreReadInKeysetPages 이어 읽기(Chapter 18)

테스트 7건이 모두 통과했습니다.

따라 하기

curl -s -X POST http://localhost:8080/api/members/summaries -H 'Content-Type: application/json' \
  -d '{"memberIds":[1,1,2]}'

중복된 1이 한 번만 처리되어 summaries에 kim(1), lee(2) 두 명만 나오고 missingIds는 비어 있습니다.

자주 하는 실수

실수 증상 해결
맥락을 Map<String,Object>로 전달 어떤 키가 있는지 코드를 따라가야 앎 타입 있는 record
중복 제거를 여러 곳에서 함 곳마다 결과가 다름 맥락 생성 시 한 곳에서
없는 값을 예외로 처리 100명 중 1명 때문에 전체 실패 결과에 키를 두지 않음

확인 문제

  1. 모듈 api가 “없는 회원”을 예외로 처리하지 않는 이유는 무엇인가요?
  2. 응답의 points가 0이면 무엇을 뜻하나요?

답: 1) 호출하는 쪽이 일부 없음을 정상 결과로 다루도록 하기 위해서입니다(missingIds로 표시). 2) 조회했는데 기록이 없다는 뜻입니다(조회 실패는 null).

직접 해 보기

  1. Map<Long, MemberGrade> 대신 List<MemberGrade>를 돌려주면 호출하는 쪽에서 무엇이 불편해질지 적어 보세요.
  2. 계약을 “없는 값은 예외”로 바꾸면 호출 코드가 어떻게 달라지는지 상상해 보세요.
  3. 자신의 모듈 api 하나에 이 표(빈 목록, 중복, 없는 값, null, 길이)를 채워 보세요.

Handler와 Registry: 논리 키로 호출 대상 찾기

Orchestrator가 MemberApi, RewardApi, OrderApi를 직접 들고 있으면, 모듈이 하나 늘 때마다 Orchestrator를 고쳐야 합니다. 그래서 모듈 하나당 Handler 하나를 두고, Orchestrator는 Handler를 논리 키("member", "reward", "order")로만 찾습니다. 클래스 이름이 아니라 키로 부르면 클래스를 옮기거나 이름을 바꿔도 규칙이 깨지지 않습니다.

CallHandler

/** 모듈 하나의 api 호출을 맡는 번역기. 업무 판단은 하지 않고, 맥락을 api 호출로 바꿔 초안에 채운다. */
public interface CallHandler {
    String key();
    void execute(CallContext context, SummaryDraft draft);
}

각 Handler는 자기 모듈의 api를 한 번만, 목록 전체로 호출합니다.

Handler 키 호출
MemberHandler member memberApi.gradesOf(context.memberIds())
RewardHandler reward rewardApi.pointsOf(context.memberIds())
OrderHandler order orderApi.orderCountsOf(context.memberIds())

업무 규칙(등급을 어떻게 정하는가)은 Handler에 없습니다. 그것은 모듈 안의 일입니다(아래 “모듈 안에서는 Composite가 일한다” 절). Handler는 얇은 번역기라서 모듈 내부가 바뀌어도 Handler는 그대로입니다.

HandlerRegistry

/** 키로 Handler를 찾는다. 같은 키가 둘이면 기동 시 실패한다. */
@Component
public class HandlerRegistry {

    private final Map<String, CallHandler> handlers;

    public HandlerRegistry(List<CallHandler> found) { /* 키별로 모아 불변 Map으로 만든다 */ }

    public CallHandler get(String key) {
        CallHandler h = handlers.get(key);
        if (h == null) {
            throw new IllegalArgumentException("등록되지 않은 Handler 키입니다: " + key);
        }
        return h;
    }
}

코드 읽기

  • 스프링이 CallHandler를 구현한 Bean을 List로 모아 생성자에 넣어 줍니다(Chapter 03의 DI). 새 Handler를 추가하려면 @Component 클래스 하나를 만들면 되고 Registry는 고치지 않습니다.
  • 같은 키가 둘이면 애플리케이션이 뜨는 시점에 실패합니다. 운영 중에 어느 쪽이 불릴지 모르는 상황을 막는 것이 목적입니다.
  • 없는 키를 요청하면 IllegalArgumentException("등록되지 않은 Handler 키입니다: ...")이 납니다.
  • 맵은 불변입니다. 실행 중에 Handler가 바뀌지 않습니다.

확인한 것

OrchestratorTests는 가짜 Handler(호출 기록만 남김)로 Orchestrator를 검증하며 9건이 모두 통과했습니다. 없는 키를 가리키는 규칙이 기동 시 거절되는 것은 아래 “호출 규칙과 Orchestrator” 절에서 확인합니다. Registry의 중복 키 실패는 소스에서 확인한 동작이고, 이 절에서 별도 테스트로 재현해 실행하지는 않았습니다.

자주 하는 실수

실수 증상 해결
두 Handler가 같은 key() 앱 기동 실패 키를 유일하게
Handler에 업무 규칙을 넣음 호출·업무 책임이 섞임 업무 규칙은 모듈 내부
규칙이 가리키는 키의 Handler가 없음 호출 시점에 IllegalArgumentException 기동 시 검증 확인
Handler에서 id마다 모듈 api를 호출 N+1 재발 목록 전체를 한 번에

확인 문제

  1. Handler가 하는 일을 한 문장으로 말해 보세요.
  2. 새 모듈을 추가할 때 Orchestrator를 수정해야 하나요?

답: 1) 맥락을 모듈 api 호출로 번역하고 결과를 초안에 채우는 얇은 어댑터입니다. 2) 아닙니다. Handler와 규칙을 추가하면 됩니다.

직접 해 보기

  1. shipping 키를 쓰는 새 Handler를 @Component로 추가하고 Registry가 인식하는지 확인하세요.
  2. 키가 같은 Handler를 두 개 만들고 기동 실패 메시지를 읽어 보세요.
  3. Handler 안에 등급 계산을 넣고 싶어지면 왜 모듈 안으로 가야 하는지 Chapter 16의 모듈 경계에 비추어 설명해 보세요.

호출 규칙과 Orchestrator

호출 정책(누구를, 어떤 순서로, 실패하면 어떻게)은 업무 로직과 분리합니다. 이 Chapter는 정책을 CallRule이라는 값으로 만들고, Orchestrator가 그 값을 읽어 실행하게 합니다. 정책이 바뀌어도 모듈 코드는 바뀌지 않습니다.

규칙은 값이다

public enum FailPolicy { STOP, CONTINUE, WARNING, SKIP }

public record CallRule(String handlerKey, int execSeq, FailPolicy failPolicy) { }

public interface CallRuleSource {
    List<CallRule> rules();
}

CodeCallRules가 이 Chapter의 규칙입니다.

순서(execSeq) 키 실패 정책
1 member STOP
2 reward CONTINUE
3 order WARNING

의미는 이렇습니다. 회원 정보가 없으면 요약 자체가 불가능하므로 멈춥니다(STOP). 포인트가 실패해도 나머지는 보여 줍니다(CONTINUE). 주문 건수는 실패하면 경고만 남깁니다(WARNING).

왜 인터페이스(CallRuleSource)로 두는가

이 Chapter는 규칙을 DB 표로 관리하지 않고 코드로 정의합니다. 그래도 CallRuleSource라는 구멍을 남겨 두었기 때문에, 나중에 DB 표에서 읽는 구현으로 바꿀 때 Orchestrator는 그대로입니다. 규칙을 DB에 두는 일에는 운영 화면, 변경 이력, 권한 같은 부가 요구가 따라오는데, 그것을 이 입문 Chapter의 범위로 삼지 않았습니다. 구현하지 않았고 검증도 하지 않았습니다.

Orchestrator의 뼈대

@Service
public class SummaryOrchestrator {

    public SummaryOrchestrator(CallRuleSource ruleSource, HandlerRegistry registry) {
        // 규칙을 execSeq 순으로 정렬하고, 규칙이 가리키는 Handler가 모두 있는지 확인한다.
        // 없으면: IllegalStateException("규칙이 가리키는 Handler가 없습니다: shipping (등록된 키: [member])")
    }

    @Transactional(readOnly = true)
    public SummaryResult summarize(CallContext context) {
        SummaryDraft draft = new SummaryDraft(context.memberIds());
        for (CallRule rule : rules) {
            // Handler 실행. 실패하면 rule.failPolicy()에 따라 처리 (이어지는 절)
        }
        return draft.toResult();
    }
}

코드 읽기

  • 생성자에서 검증합니다. 규칙이 가리키는 키에 Handler가 없으면 앱이 뜨지 않습니다. 오류 메시지에 등록된 키 목록까지 붙어 있어 원인을 바로 알 수 있습니다. 운영 중 첫 호출에서야 터지는 것보다 훨씬 낫습니다.
  • 규칙을 execSeq로 정렬하므로, 규칙 목록의 선언 순서와 실행 순서가 달라도 됩니다.
  • @Transactional(readOnly = true): 조회만 하는 흐름이라 읽기 전용으로 둡니다. 쓰기가 섞일 때의 함정은 아래 “트랜잭션 경계: 읽기 전용과 REQUIRES_NEW” 절에서 봅니다.

실행 순서 테스트

가짜 Handler가 호출을 기록합니다. 한 회원 [1]을 요청하면 기록이 member:[1], reward:[1], order:[1] 순서입니다. [1,1,2]를 요청해도 각 모듈은 한 번만, 중복이 제거된 [1, 2]로 불립니다(member:[1, 2], reward:[1, 2]). 호출 횟수가 회원 수가 아니라 모듈 수(3)에 비례한다는 것이 이 구조의 핵심 성과입니다.

따라 하기

./gradlew :examples:ch36-bulk-orchestration:test --tests '*OrchestratorTests*'

재검증에서 OrchestratorTests 9건이 통과하는 것을 확인했습니다(가짜 Handler가 호출을 기록해 순서를 검사).

자주 하는 실수

실수 증상 해결
규칙이 존재하지 않는 키를 가리킴 기동 시 IllegalStateException 오류 메시지의 등록된 키 목록으로 수정
execSeq 중복·누락 순서가 의도와 다름 정렬 기준을 명확히
규칙을 DB에서 읽을 수 있다고 오해 이 Chapter는 코드 정의만 구현 CallRuleSource는 확장점일 뿐

확인 문제

  1. 호출 정책과 업무 로직을 분리하면 무엇이 좋아지나요?
  2. Orchestrator 생성자에서 규칙을 검증하는 이유는 무엇인가요?

답: 1) 정책(순서·실패 처리)과 업무 규칙(등급 계산)을 서로 다른 이유로 따로 바꿀 수 있습니다. 2) 잘못된 규칙이 운영 중이 아니라 기동 시점에 드러나게 하기 위해서입니다.

직접 해 보기

  1. CodeCallRules에서 reward의 execSeq를 4로 바꾸면 순서가 어떻게 바뀌는지 테스트로 확인하세요.
  2. 존재하지 않는 키 shipping 규칙을 추가하고 기동 실패 메시지를 읽어 보세요.
  3. 호출 횟수를 세는 가짜 Handler로 100명을 보내도 호출이 1번인지 확인하는 테스트를 써 보세요.

실패 정책 네 가지와 응답 모양

세 모듈 중 하나가 실패했을 때 전체를 실패시킬지, 일부만 보여 줄지는 정책의 문제입니다. 이 절은 네 가지 정책이 실제 응답에서 어떻게 달라지는지 테스트 값으로 확인합니다.

네 가지 정책

정책 해당 Handler가 실패하면 이 Chapter의 사용처
STOP 즉시 중단. 뒤 Handler는 호출하지 않고 CallFailedException(handlerKey) member
CONTINUE 실패를 기록하고 다음으로 진행 reward
WARNING 진행하되 warnings에 문장을 남김 order
SKIP 해당 Handler를 건너뜀(상태 SKIPPED) 규칙 변경 시험용

정상 응답

JAR를 실행해 POST /api/members/summaries {"memberIds":[1,2,3,99]}를 보낸 실제 응답입니다.

{"summaries":[
  {"id":1,"name":"kim","grade":"SENIOR","points":600,"orderCount":3},
  {"id":2,"name":"lee","grade":"REGULAR","points":100,"orderCount":1},
  {"id":3,"name":"park","grade":"DORMANT","points":0,"orderCount":0}],
 "missingIds":[99],
 "warnings":[],
 "outcomes":[
  {"key":"member","status":"OK","message":null},
  {"key":"reward","status":"OK","message":null},
  {"key":"order","status":"OK","message":null}]}

읽는 법은 이렇습니다.

  • missingIds:[99]: 요청한 id 중 member 모듈에 없는 것입니다. 호출한 쪽이 api의 결과(키 없음)로 계산합니다.
  • park(3)은 포인트와 주문 기록이 없어 0입니다. 모듈은 조회는 성공했는데 기록이 없다는 뜻으로 키를 두지 않았고, 초안이 그것을 0으로 채웠습니다.
  • outcomes는 Handler마다의 결과표라 어느 모듈이 어떻게 처리되었는지 응답만 보고 알 수 있습니다.

reward가 실패하면

FailurePolicyApiTests는 FlakyModules로 reward를 일부러 실패시킵니다. 응답은 200이고 내용은 다음과 같습니다.

항목 값
1번 회원 grade SENIOR, points null, orderCount 3
outcomes[1] key reward, status FAILED, message reward 모듈 장애

points가 null인 것과 0인 것은 다릅니다. 0은 “조회했더니 없었다”, null은 “조회하지 못했다”입니다. 화면은 이 둘을 다르게 보여 줘야 하므로(예: - 대 0) 의미를 섞지 않은 것입니다.

Orchestrator 단위 테스트가 확인한 것

상황 결과
STOP Handler 실패 CallFailedException, 뒤 Handler는 호출되지 않음
WARNING Handler 실패 warnings에 order 호출 실패: order 장애
SKIP 상태 SKIPPED

STOP은 웹 계층에서 503으로 바뀌고 응답에 handler 필드가 담깁니다. 이 상태 코드 변환은 소스에서 확인했고 응답 JSON의 정확한 모양은 이 절에 옮기지 않았습니다. 정확한 값은 SummaryApiTests를 참고하세요.

응답 읽는 순서

응답은 네 부분으로 나누어 읽습니다.

  1. outcomes: 모듈별 처리 결과(OK, FAILED, SKIPPED)입니다.
  2. warnings: WARNING 정책이 남긴 문장입니다.
  3. summaries: 회원별 요약입니다. points가 null이면 조회에 실패한 것입니다.
  4. missingIds: member 모듈에 없는 id입니다.

자주 하는 실수

실수 증상 해결
null과 0을 같은 값으로 표시 조회 실패가 “포인트 0”으로 보임 null은 “불러오지 못함”으로 구분
핵심 모듈을 CONTINUE로 둠 이름 없는 요약이 200으로 나감 필수 모듈은 STOP
STOP의 상태 코드를 500으로 오해 클라이언트 재시도 판단 오류 503과 handler 필드 확인

확인 문제

  1. member가 실패하면 왜 STOP인가요?
  2. reward가 실패해도 응답 상태가 200인 이유는 무엇인가요?

답: 1) 회원 정보가 없으면 요약 자체가 성립하지 않기 때문입니다. 2) CONTINUE 정책이라 실패를 outcomes에 기록하고 나머지 결과를 돌려주기 때문입니다.

직접 해 보기

  1. order를 STOP으로 바꾸면 위 reward 실패 시나리오의 응답이 어떻게 바뀔지 예측하고 테스트로 확인하세요.
  2. 화면에서 points == null일 때와 0일 때 각각 무엇을 보여 줄지 정해 보세요.
  3. 자신의 API에서 일부 실패를 허용해도 되는 항목과 안 되는 항목을 구분해 보세요.

모듈 안에서는 Composite가 일한다

Orchestrator와 Handler는 호출을 담당하고, 업무 판단은 모듈 안에서 합니다. 이 절은 member 모듈의 등급 규칙과 reward 모듈의 포인트 규칙이 Chapter 16의 Composite로 구성된 모습을 봅니다. 규칙을 호출 정책과 섞지 않는 것이 이 Chapter의 분리선입니다.

두 계층의 분리

계층 책임 바뀌는 이유
Orchestrator, Handler 누구를 어떤 순서로, 실패 시 어떻게 호출 정책이 바뀔 때
모듈 내부 Composite 등급, 포인트를 어떻게 계산하나 업무 규칙이 바뀔 때

등급: 첫 일치형

new FirstMatchGradeRule(List.of(new DormantRule(), new SeniorRule(2020)), "REGULAR")

규칙을 순서대로 시험해 처음 맞는 규칙의 등급을 쓰고, 아무것도 맞지 않으면 기본값 REGULAR입니다. 시드 데이터에 이 규칙을 적용한 결과는 다음과 같습니다(ModuleApiTests가 확인).

회원 가입 연도 등급
kim(1) 2018 SENIOR
lee(2) 2024 REGULAR
park(3) 2019 DORMANT
choi(4) 2025 REGULAR
jung(5) 2020 SENIOR

SeniorRule(2020)의 기준 연도에서 2020년 가입자(jung)가 SENIOR인 것으로 보아 기준 연도 이하가 SENIOR로 판정되는 것을 알 수 있습니다. DormantRule은 member 표의 dormant 컬럼이 참인 회원(시드에서는 park만)을 DORMANT로 판정합니다. 순서가 중요한 이유는 park(2019)이 가입 연도만 보면 SENIOR 조건에도 해당할 수 있는데 DORMANT로 나왔다는 점입니다. 휴면 규칙이 앞에 있기 때문입니다.

포인트: 합산형

new SumPointRule(List.of(new EarnRule(), new UseRule()))

적립 규칙과 사용 규칙이 각각 값을 내고, 합산형 Composite가 더합니다. 시드 데이터의 결과는 {1:600, 2:100, 4:600}이며 기록이 없는 회원은 키가 없습니다. 합산은 회원별로 이루어져야 하므로 pointsAreSummedPerMemberAcrossChunks 테스트가 청크 경계를 넘는 회원의 합산이 어긋나지 않는지 확인합니다.

규칙을 따로 시험

ModuleRuleTests 2건이 규칙만 따로 검증합니다. Spring도 DB도 필요 없는 순수 단위 테스트라서 빠릅니다. 규칙은 이렇게 따로 시험할 수 있도록 모듈 안쪽(internal)에 두고, 밖에는 api만 공개합니다.

따라 하기

./gradlew :examples:ch36-bulk-orchestration:test --tests '*ModuleRuleTests*'

Spring과 DB 없이 규칙만 검증하는 2건이 통과합니다.

자주 하는 실수

실수 증상 해결
첫 일치형에서 규칙 순서를 바꿈 등급 결과가 달라짐 순서가 결과를 정한다는 점을 테스트로 고정
규칙을 Handler에 둠 호출·업무 책임 혼합 모듈 안의 Composite
합산형에 상한을 두지 않음 비정상 값 필요하면 상한 규칙 추가

확인 문제

  1. 첫 일치형과 합산형의 차이를 한 줄로 말해 보세요.
  2. 규칙 테스트가 Spring 없이 빠른 이유는 무엇인가요?

답: 1) 첫 일치형은 처음 맞는 규칙의 값 하나를 쓰고, 합산형은 모든 규칙의 값을 더합니다. 2) 순수 객체이므로 컨테이너와 DB가 필요하지 않기 때문입니다.

직접 해 보기

  1. SeniorRule 기준 연도를 2019로 바꿨을 때 어떤 회원의 등급이 바뀔지 예측하고 테스트를 고쳐 확인하세요.
  2. DormantRule와 SeniorRule의 순서를 바꾸면 park의 등급이 어떻게 되는지 예측하세요.
  3. 합산형과 첫 일치형 외에 필요한 모양이 있을지 생각해 보세요.

IN 목록을 나누는 Chunks와 MyBatis foreach

모듈 안에서는 받은 id 목록으로 WHERE id IN (...)을 실행합니다. 목록이 아주 길면 DB가 거절하거나 느려질 수 있으므로 일정 크기로 나누어 여러 번 조회하고 합칩니다. DB마다 IN 목록 한계가 다르므로 이 절의 크기 500은 예시이고, H2에서만 확인했습니다. (Chapter 09의 동적 SQL foreach와 이어집니다.)

MyBatis foreach

WHERE id IN
<foreach collection="ids" item="id" open="(" separator="," close=")">
    #{id}
</foreach>

#{id}는 값마다 바인드 변수가 되므로 SQL 인젝션 걱정 없이 값을 넘길 수 있습니다. 반면 ids가 비어 있으면 IN ()이라는 잘못된 SQL이 만들어집니다. 그래서 호출 전에 빈 목록을 걸러야 합니다.

Chunks

public final class Chunks {
    /** 중복을 제거하고 size개씩 나눈다. */
    public static <T> List<List<T>> partition(Collection<T> values, int size) { ... }

    /** 조각마다 fn을 한 번씩 호출해 결과를 합친다. 빈 목록이면 fn을 한 번도 호출하지 않는다. */
    public static <T, R> List<R> lookup(Collection<T> values, int size, Function<List<T>, List<R>> fn) { ... }
}

코드 읽기

  • partition은 LinkedHashSet으로 중복을 제거해 순서를 유지한 뒤 size개씩 자릅니다.
  • lookup은 조각마다 fn(실제 쿼리)을 한 번씩 부릅니다. 빈 목록이면 한 번도 부르지 않으므로 IN () 오류가 구조적으로 생기지 않습니다.
  • 크기는 설정 bulk.in-chunk-size(기본 500)입니다. 코드에 박지 않고 설정에서 읽으므로 테스트는 2로 줄여 경계를 쉽게 만듭니다.

경계 테스트

ChunksTests(5건)와 ModuleApiTests가 경계를 확인합니다. 묶음 크기를 2로 하면 5명은 [1,2] [3,4] [5] 세 조각입니다. 마지막 조각이 1개인 경계, 크기와 개수가 딱 나누어떨어지는 경계, 빈 목록, 중복이 있는 경우가 모두 시험 대상입니다. 5명의 등급이 조각 경계를 넘어도 SENIOR, REGULAR, DORMANT, REGULAR, SENIOR로 정확히 합쳐졌고, 포인트도 회원별 합산이 어긋나지 않았습니다.

요청 상한과 청크 크기

설정 값 뜻
@Size(max = 1000) 1000 한 요청에 받을 수 있는 id 수
bulk.in-chunk-size 500 쿼리 한 번에 넣는 id 수

요청이 최대일 때 1000개는 쿼리 2번입니다. 두 값은 서로 다른 일을 하므로 하나로 합치지 않습니다.

따라 하기

./gradlew :examples:ch36-bulk-orchestration:test --tests '*ChunksTests*' --tests '*ModuleApiTests*'

재검증에서 ChunksTests 5건과 ModuleApiTests 7건이 통과하는 것을 확인했습니다.

자주 하는 실수

실수 증상 해결
빈 목록으로 IN () 실행 SQL 문법 오류 빈 목록이면 쿼리를 보내지 않음
청크 크기를 코드에 박음 테스트에서 경계를 만들기 어려움 bulk.in-chunk-size 설정
중복 제거 없이 분할 같은 id를 중복 조회 partition에서 제거
값을 문자열로 이어 붙여 IN 구성 SQL 인젝션 위험 foreach + #{} 바인딩

확인 문제

  1. 청크 크기가 2일 때 [1,2,3,4,5]는 몇 조각이 되나요?
  2. 빈 목록에서 fn을 호출하지 않는 이유는 무엇인가요?

답: 1) [1,2] [3,4] [5] 세 조각입니다. 2) IN ()이 잘못된 SQL이고 불필요한 DB 호출이기 때문입니다.

직접 해 보기

  1. bulk.in-chunk-size를 1로 바꾸고 ModuleApiTests가 통과하는지 확인하세요.
  2. 빈 목록으로 lookup을 호출하는 테스트를 쓰고 fn 호출 횟수가 0인지 검증하세요.
  3. 사용하는 DB의 IN 목록 한계를 공식 문서에서 찾아 적어 보세요(이 예제는 확인하지 않았습니다).

트랜잭션 경계: 읽기 전용과 REQUIRES_NEW

Orchestrator의 summarize는 @Transactional(readOnly = true)입니다. 조회만 하는 흐름이라 문제가 없습니다. 그런데 이런 구조에 쓰기 Handler가 섞이고 CONTINUE(“실패해도 계속”)를 쓰면 함정이 있습니다. Chapter 09의 트랜잭션 전파를 이 시나리오에 적용해 테스트로 확인합니다.

함정: 참여한 트랜잭션의 예외

기본 전파(REQUIRED)에서 안쪽 @Transactional 메서드는 바깥 트랜잭션에 참여합니다. 안쪽이 예외를 던지면 트랜잭션에 롤백 표시가 붙고, 바깥에서 예외를 잡아 계속 진행해도 마지막 커밋 시점에 실패합니다.

TransactionPolicyTests의 결과입니다.

시나리오 결과
안쪽(참여)이 예외, 바깥이 잡고 계속 UnexpectedRollbackException, 바깥이 쓴 행도 함께 롤백 (0건)
안쪽을 REQUIRES_NEW로 분리 안쪽만 롤백되고 바깥 쓰기는 커밋 (1건)

즉 CONTINUE 정책이 “한 모듈이 실패해도 나머지는 진행”이라는 약속을 지키려면, 쓰기를 하는 Handler는 독립된 트랜잭션이어야 합니다.

@Transactional(propagation = Propagation.REQUIRES_NEW)
public void writeSomething() { ... }

이 Chapter가 안전한 이유

이 Chapter의 조회 흐름은 읽기 전용이고, 쓰기 Handler가 없습니다. 그래서 위 함정에 걸리지 않으며 이 절은 함정이 어떤 구조에서 생기는지를 테스트로 보여 주는 용도입니다. 실제로 쓰기 Handler를 붙인 오케스트레이션은 구현하지 않았고 검증하지도 않았습니다.

같은 클래스 안 호출 주의

@Transactional은 프록시가 처리합니다. 같은 클래스 안에서 다른 메서드를 부르면 프록시를 거치지 않아 REQUIRES_NEW가 무시됩니다. 이 함정은 Chapter 09에서 다뤘고, Chapter 18의 AOP에서 원리를 설명합니다.

따라 하기

./gradlew :examples:ch36-bulk-orchestration:test --tests '*TransactionPolicyTests*'

재검증에서 2건이 통과하는 것을 확인했습니다. 두 시나리오의 기대값(0건과 1건)이 위 표와 같습니다.

자주 하는 실수

실수 증상 해결
안쪽 예외를 잡았으니 괜찮다고 판단 바깥이 UnexpectedRollbackException 안쪽을 REQUIRES_NEW로 분리
같은 클래스 안 메서드 호출에 @Transactional 프록시를 거치지 않아 적용 안 됨 다른 Bean으로 분리
CONTINUE 정책인데 쓰기 Handler가 참여 트랜잭션 일부 실패가 전체 롤백 쓰기는 REQUIRES_NEW

확인 문제

  1. rollback-only란 무엇인가요?
  2. 이 Chapter의 조회 흐름이 함정에 걸리지 않는 이유는 무엇인가요?

답: 1) 참여한 트랜잭션에서 예외가 나면 바깥 트랜잭션이 커밋되지 못하도록 표시되는 상태입니다. 2) 읽기 전용이고 쓰기 Handler가 없기 때문입니다.

직접 해 보기

  1. REQUIRES_NEW를 REQUIRED로 바꿔 두 번째 테스트가 어떻게 실패하는지 읽어 보세요.
  2. 안쪽을 noRollbackFor로 바꾸면 결과가 어떻게 될지 예측하세요.
  3. CONTINUE로 둘 Handler 중 쓰기가 있는 것이 있는지 점검하세요.

호출 방향을 구조 테스트로 고정하기

모듈 경계는 약속만으로는 금방 무너집니다. 누군가 급하게 member 안에서 reward.internal을 import해도 컴파일은 됩니다. Chapter 12에서 배운 ArchUnit으로 이 Chapter의 호출 방향을 테스트로 고정합니다.

네 가지 규칙 (ArchitectureTests 4건)

규칙 뜻
최상위 패키지 사이에 순환이 없다 member와 reward처럼 서로를 부르는 구조 금지 (순환 참조)
모듈 밖에서는 api 패키지만 쓴다 internal은 모듈 안에서만
모듈은 서로를, 그리고 호출자(orchestration/web/batch)를 모른다 의존 방향은 호출자 → 모듈 한 방향
컨트롤러는 모듈을 직접 부르지 않는다 웹은 Orchestrator만 안다

호출은 web에서 orchestration으로, orchestration에서 각 모듈의 api(member.api, reward.api, order.api)로 이어지고, batch도 orchestration을 거칩니다. 각 모듈의 internal은 그 모듈의 api 뒤에만 있습니다.

의존 방향은 호출자에서 모듈로 한 방향이고, 모듈끼리는 서로를 가리키지 않는다는 것이 핵심입니다.

테스트의 모양

@AnalyzeClasses(packages = "com.jqdom.curriculum.ch36")
class ArchitectureTests {
    @ArchTest
    static final ArchRule noCycles =
        SlicesRuleDefinition.slices().matching("com.jqdom.curriculum.ch36.(*)..").should().beFreeOfCycles();
    // 나머지 세 규칙도 같은 방식으로 선언
}

위 코드는 규칙을 이해하기 위한 개념 예시입니다. 실제 테스트의 정확한 표현은 저장소의 ArchitectureTests.java를 보세요. 4건은 모두 통과했습니다.

효과

호출 방향이 바뀌면 코드 리뷰어의 눈이 아니라 CI가 알려 줍니다. Handler와 컨트롤러는 코드를 읽는 사람이 구조를 짐작하게 하고, ArchUnit은 그 짐작이 틀리지 않게 합니다. 대신 규칙을 지나치게 많이 두면 모든 수정이 테스트 수정을 요구하므로, 지키지 않으면 큰 문제가 되는 방향 규칙에 한정하는 것이 좋습니다.

따라 하기

./gradlew :examples:ch36-bulk-orchestration:test --tests '*ArchitectureTests*'

재검증에서 구조 테스트 4건이 통과하는 것을 확인했습니다.

자주 하는 실수

실수 증상 해결
모듈 간 직접 의존을 추가 순환·방향 규칙 실패 호출은 Orchestrator를 거침
컨트롤러가 모듈 api를 직접 호출 “컨트롤러는 Orchestrator만” 규칙 실패 Orchestrator 경유
규칙을 코드 리뷰에만 의존 방향이 조용히 무너짐 ArchUnit으로 빌드에서 차단

확인 문제

  1. 호출 방향은 어느 쪽으로 흘러야 하나요?
  2. 모듈끼리 서로 알지 못하게 하는 이유는 무엇인가요?

답: 1) 호출자(web/orchestration/batch) → 모듈 api 한 방향입니다. 2) 한 모듈의 변경이 다른 모듈로 번지지 않게 하기 위해서입니다.

직접 해 보기

  1. reward 모듈에서 member.internal의 클래스를 하나 import하고 빌드해 어느 규칙이 실패하는지 보세요.
  2. 반대로 member가 reward.api를 쓰는 의존을 추가하면 어떤 규칙에 걸리는지 예측하세요.
  3. 자신의 프로젝트에서 반드시 지켜야 할 방향 규칙 한 가지를 문장으로 적어 보세요.

규칙을 DB로 옮기려면, 그리고 이 설계의 한계

Chapter를 마무리하며, 이 설계가 Chapter 첫머리에서 밝힌 원칙을 어떻게 구현했는지 표로 대응하고, 구현하지 않은 것과 확인하지 않은 것을 정직하게 적습니다.

원칙과 구현의 대응

원칙 이 Chapter의 구현
호출 정책과 업무 로직 분리 CallRule·Orchestrator와 모듈 내부 Composite
만능 Map 금지 CallContext, SummaryDraft 같은 record
클래스 이름이 아닌 논리 키 Handler key(): member, reward, order
실패 정책 STOP, CONTINUE, WARNING, SKIP
호출 단위는 모듈 api 각 Handler는 api만 부름. ArchUnit으로 고정
조회 흐름은 읽기 전용 @Transactional(readOnly = true)
쓰기와 CONTINUE가 섞이면 REQUIRES_NEW TransactionPolicyTests로 0건 대 1건 확인
규칙을 DB 표로 관리 구현하지 않음. CallRuleSource로 확장점만 확보

규칙을 DB로 옮긴다면

CallRuleSource를 구현하는 클래스가 표에서 규칙을 읽어 오면 Orchestrator는 그대로입니다. 다만 다음이 새로 필요해집니다. 이것들은 이 Chapter에서 다루지 않았습니다.

  • 규칙의 변경 이력과 권한, 운영 화면
  • 규칙이 가리키는 키에 Handler가 없을 때의 검증 시점(이 Chapter는 기동 시 거절)
  • 규칙 캐시와 갱신 시점

한계와 확인하지 않은 것

항목 상태
IN 목록의 DB별 한계 H2에서만 확인. Oracle 등은 확인하지 않음
요청 상한 1000과 청크 500 예시값. 실제 값은 DB와 부하로 정해야 함
모듈을 별도 서버로 분리(원격 호출) 다루지 않음. 같은 JVM의 모듈 호출만
쓰기 Handler가 섞인 오케스트레이션 구현하지 않음
순서가 서로 의존하는 Handler 이 Chapter의 Handler는 서로 독립
대량 조회의 성능 측정하지 않음

이 Chapter가 확인한 범위

확인한 것은 코드로 정의한 규칙, H2, 같은 JVM 안의 모듈 호출, 조회 흐름입니다. DB 규칙 표, 원격 호출, 쓰기 오케스트레이션, 성능은 확인하지 않았습니다.

H2에서 통과한 IN 목록 동작이 다른 DB에서도 같다고 단정하지 않습니다. 사용하는 DB의 한계는 해당 공식 문서와 직접 실행으로 확인해야 합니다.

직접 해 보기

  1. 위 대응 표를 자신의 프로젝트에 대입해 비어 있는 칸을 찾아 보세요.
  2. CallRuleSource를 읽는 구현을 인메모리 Map으로 하나 더 만들어 테스트에서 규칙을 바꿔 보세요.
  3. Chapter 16의 계약 지도에서 이 Chapter의 호출 계약이 어디에 놓이는지 찾아 보세요.

용어와 참고 자료

Chapter 17의 용어를 모았습니다. 이전 Chapter에서 설명한 용어는 해당 Chapter의 용어 정리를 가리킵니다.

용어

용어 설명
N+1 문제 목록 N개를 처리하며 항목마다 쿼리나 호출을 한 번씩 더 하는 비효율입니다.
가변 IN 길이가 정해지지 않은 값 목록으로 IN (...)을 만드는 상황입니다.
입구 검증 컨트롤러에서 요청 값을 검사해 400으로 거절하는 단계입니다.
호출 맥락(CallContext) 호출 흐름이 공유하는 값을 담은 타입 있는 record입니다.
모듈 api 계약 모듈이 밖에 공개하는 호출의 약속(빈 목록, 중복, 없는 값, null)입니다.
Handler 맥락을 모듈 api 호출로 번역하는 얇은 어댑터입니다.
Registry 논리 키로 Handler를 찾는 저장소입니다.
논리 키 클래스 이름 대신 쓰는 안정적인 식별자(member 등)입니다.
CallRule 키, 실행 순서, 실패 정책을 담은 호출 규칙 값입니다.
CallRuleSource 규칙을 공급하는 확장점입니다. 코드 정의를 DB로 바꿀 자리입니다.
Orchestrator 규칙에 따라 Handler를 순서대로 실행하는 조율자입니다.
실패 정책 실패 시 STOP, CONTINUE, WARNING, SKIP 중 무엇을 할지의 선언입니다.
청크(chunk) 긴 목록을 나눈 한 조각입니다.
rollback-only 참여한 트랜잭션이 예외로 롤백 표시가 되어 바깥도 커밋하지 못하는 상태입니다.
REQUIRES_NEW 항상 새 트랜잭션을 시작하는 전파 옵션입니다.
ArchUnit 패키지 의존 규칙을 테스트로 검사하는 라이브러리입니다.

Composite, 계약, Port는 Chapter 16 용어 정리와 Chapter 15 용어 정리, 트랜잭션과 foreach는 Chapter 09 용어 정리를 참고하세요.

참고 자료

이 Chapter의 구현과 값은 저장소의 examples/ch36-bulk-orchestration 코드와 테스트, JAR 실행 결과에서 확인했습니다. 개념은 아래 문서를 참고했습니다.

직접 해보기

  1. ./gradlew :examples:ch36-bulk-orchestration:bootRun으로 앱을 띄우고 curl로 {"memberIds":[1,1,2]}와 {"memberIds":[1,2,3,99]}를 보내, 중복이 한 번만 처리되는 것과 missingIds:[99], outcomes 세 개를 응답에서 확인하세요.
  2. CodeCallRules에서 reward의 실패 정책을 CONTINUE에서 STOP으로 바꾸면 FailurePolicyApiTests의 reward 실패 시나리오 응답이 200에서 어떻게 바뀔지 예측하고, 테스트로 확인한 뒤 되돌리세요.
  3. bulk.in-chunk-size를 1로 바꾸고 ./gradlew :examples:ch36-bulk-orchestration:test --tests '*ChunksTests*' --tests '*ModuleApiTests*'를 실행해, 조각이 늘어나도 등급과 포인트가 같게 합쳐지는지 확인하세요.
  4. TransactionPolicyTests의 REQUIRES_NEW를 REQUIRED로 바꿔 ./gradlew :examples:ch36-bulk-orchestration:test --tests '*TransactionPolicyTests*'로 실행하고, UnexpectedRollbackException과 0건/1건 기대값이 어떻게 어긋나는지 읽은 뒤 되돌리세요.
  5. reward 모듈에서 member.internal의 클래스를 하나 import하고 ./gradlew :examples:ch36-bulk-orchestration:test --tests '*ArchitectureTests*'를 실행해 어느 규칙이 실패하는지 확인하세요.

이번 장의 정리

  • id마다 모듈을 부르면 호출이 N × 모듈 수로 늘어나므로, 목록은 입구의 SummaryRequest에서 빈 목록·상한 1000·null·양수 여부를 검증한 뒤 모듈마다 한 번만 통째로 넘깁니다.
  • 호출 흐름이 공유하는 값은 Map 대신 타입 있는 CallContext에 담고, 모듈 api의 계약(빈 목록, 중복, 없는 값, null)은 Javadoc과 ModuleApiTests로 고정합니다.
  • Handler는 맥락을 모듈 api 호출로 바꾸는 얇은 번역기이고, HandlerRegistry는 논리 키로 Handler를 찾으며 같은 키가 둘이면 기동 시 실패합니다.
  • 호출 정책은 CallRule 값으로 두고, SummaryOrchestrator가 execSeq 순으로 실행하며 규칙이 가리키는 Handler가 없으면 기동 시점에 거절합니다.
  • 실패 정책(STOP, CONTINUE, WARNING, SKIP)의 결과는 응답의 outcomes, warnings, null과 0의 구분으로 드러나고, STOP은 웹 계층에서 503이 됩니다.
  • 업무 판단은 모듈 안의 Composite 규칙(첫 일치형 등급, 합산형 포인트)이 맡아 호출 정책과 섞지 않습니다.
  • 모듈 안에서는 Chunks로 IN 목록을 나눠 조회하고 빈 목록이면 쿼리를 보내지 않으며, 요청 상한(1000)과 청크 크기(500)는 서로 다른 값으로 둡니다.
  • CONTINUE에 쓰기가 섞이면 쓰기 Handler를 REQUIRES_NEW로 분리해야 하고, 호출 방향은 ArchUnit 4건으로 고정했습니다. 규칙의 DB 관리, 원격 호출, 성능은 이 Chapter에서 확인하지 않았습니다.

다음 Chapter 18 AOP와 온디맨드 배치에서는 실행 시간 기록 같은 공통 관심사를 AOP로 분리하고, 이 Chapter의 오케스트레이션을 재사용하는 온디맨드 배치를 만듭니다.

FAQ

자주 묻는 질문

id마다 모듈을 호출하면 왜 N+1 문제가 되나요?

회원 N명마다 회원·적립·주문 모듈을 각각 호출하면 호출과 쿼리가 N×모듈 수만큼 늘어나기 때문입니다. 목록을 모듈 API에 통째로 넘겨 모듈마다 한 번씩 조회합니다.

요청 상한 1000과 IN 청크 크기 500은 왜 다른가요?

1000은 한 요청이 받을 수 있는 입력 크기이고, 500은 SQL 한 번에 넣는 값의 수입니다. 서로 보호하는 경계가 다르므로 별도 값으로 둡니다.

다른 모듈 테이블을 JOIN하면 더 간단하지 않나요?

호출 수는 줄지만 다른 모듈의 저장 구조에 직접 의존해 모듈 경계가 무너집니다. 각 모듈의 공개 API를 목록 단위로 호출해 계약을 유지합니다.

CONTINUE와 WARNING 정책은 무엇이 다른가요?

둘 다 다음 호출을 계속하지만 응답에 남기는 결과 의미가 다릅니다. 정책별 결과와 후속 처리 여부를 테스트로 고정해야 합니다.

작성·편집 ToolPado

콘텐츠 유형 Spring Boot 학습 가이드

기술 기준 Spring Boot 4.1.1 · JDK 21

마지막 검토