정리

영속성 컨텍스트 안에는 1차 캐시와 스냅샷이 존재.

1. 비영속(New)
   • 상태 : 방금 new 키워드로 생성된 순수한 자바 객체
   • 위치 : 영속성 컨텍스트 바깥에 위치. 당연히 1차 캐시에도 없음
   • JPA 추적 : X (JPA는 이 객체의 존재 자체를 모름. 값을 아무리 바꿔도 DB에 영향X)
   • 코드 : Post pst = new Post(”새 글”);
2. 영속(Managed)
   • 상태: 객체가 영속성 컨텍스트 안으로 들어와 정식 관리를 받는 상태
   • 위치 : 영속성 컨텍스트 내부의 1차 캐시에 이름(PK)과 현재 상태가 등록되고, 동시에 스냅샷에 들어올 때의 최초 모습이 복사되어 안전하게 보관
   • JPA 추적 : O (트랜잭션이 끝날 떄, JPA가 1차 캐시와 스냅샷을 비교해서 다르면 UPDATE 쿼리를 날린다. 즉, 변경 감지가 동작하는 유일한 상태)
   • 코드 : em.persist(post); (저장) 또는 postRepository.findById(1L); (조회해서 영속성 컨텍스트로 끌고 옴)
3. 준영속(Detached)
   • 상태 : 한때는 영속 상태였지만, 지금은 관리가 끊긴 상태
   • 위치 : 객체 자체는 자바 메모리에 살아있지만, 1차 캐시와 스냅샷에서는 기록이 완전히 삭제 되었다.(DB에 데이터가 남아있든 말든 상관없다)
   • JPA 추적 : X (영속성 컨텍스트에서 지워졌으므로, 이제 객체의 값을 바꿔도 JPA 관리를 받지 않기 때문에 변경 감지가 작동되지 않는다)
   • 발생 시점 : 트랜잭션이 끝나서 영속성 컨텍스트 자체가 파괴될 때
4. 삭제(Removed)
   • 상태: 관리소 안에는 있지만, '삭제 예정' 딱지가 붙은 상태입니다.
   • 위치: 여전히 영속성 컨텍스트 안의 1차 캐시에 있지만, 트랜잭션이 끝날 때 DB에 DELETE 쿼리를 날리기로 예약되어 있습니다.
   • 코드: em.remove(post); 또는 postRepository.delete(post);

제가 들었던 코스 링크입니다. https://f-lab.kr/mentoring-courses/java-backend

전부터 계속 백엔드 서버만 개발을 해오다 보니, 프론트엔드와 협업 또는 독자적인 프론트 공부를 한 적이 없었습니다. 하지만 이번 인턴 생활을 하던 도중 과제에 프론트엔드도 구현하라는 요구사항이 있었습니다. 프론트 쪽은 일단 AI 에이전트 도움을 받아가면서 구현 및 공부를 했는데, 프론트와 백엔드를 연동하면서 서버에서 발생한 문제를 Http Status와 Custom Error Message를 사용자 화면에 보여주게 하고 싶었는데, 백엔드 서버만 만들 때 처럼 Service 계층에서 특정 로직이 발생했을 때

throw new IllgerArgumentException("중복된 이메일입니다");

위 코드처럼 오류를 처리해왔었습니다. 하지만 프론트와 연동을 시작하니 문제가 생겼습니다. 저는 "중복된 이메일입니다"라는 메시지를 프론트 alert에 보여주고 싶었지만 실제 응답은 이랬습니다.

{
  "timestamp": "...",
  "status": 500,
  "error": "Internal Server Error",
  "path": "/api/users"
}

그래서 이번 글은 왜 우리가 서버에서 메시지를 담아서 오류가 나도 프론트에서는 그 메시지가 보이지 않았을까? 이걸 해결하려면 어떻게 해야할까?에 대하여 글을 작성하겠습니다.

문제 해결 과정

위에 말로만 설명해서 감이 잘 안 오셨을 수도 있을텐데 일단 이해를 돕기위한 간단한 코드 예제를 보면서 진행해보겠습니다.

// Controller
@RestController
@RequestMapping("/api/users")
@RequiredArgsConstructor
public class Controller {

    private final UserService service;

    @PostMapping
    public ResponseEntity<?> register(@RequestBody RequestDto request) {
        return ResponseEntity.status(HttpStatus.CREATED).body(service.register(request));
    }
}

// Service 
@Service
@RequiredArgsConstructor
public class UserService {
    private final UserRepository userRepository;

    @Transactional
    public ResponseDto register(RequestDto request) {
        if (userRepository.existsByEmail(request.getEmail())) {
            throw new IllegalArgumentException("중복된 이메일 입니다.");
        }

        User user = User.create(request);
        userRepository.save(user);

        return ResponseDto.of(user.getEmail(), user.getName());
    }
}

일단 코드를 보시면 바로 유저의 가입 API라는 것이 보이실텐데 이 코드를 실행해서 Postman으로 통해 최초 가입하고 이후 똑같은 이메일로 가입을 다시 해보겠습니다.

혹시 차이가 보이실까요? 저희는 프론트엔드와 작업을 하기 위해서는 JSON을 통해 프론트에서 알기 쉽게 데이터를 가공하여 보여줘야 합니다. 물론 오류도 마찬가지입니다. 하지만 위에를 보면 저희 서버 콘솔에만 Service에서 작성한 오류 메세지가 보이고 Postman으로 API 요청을 통해 받은 응답에는 JSON이긴 하지만 저희가 작성한 오류 메시지가 보이지 않고, 그냥 Spring에서 기본적으로 발생시키는 오류를 JSON 형태로 올려보내서 500 Internal Server Error가 나타나는 것입니다.

왜 이런 일이 발생했을까?

현재 코드로 중복 이메일 가입 시도 흐름을 보겠습니다.

1. Service에서 예외 발생 → 컨트롤러 응답까지 가지 못함

(1) Tomcat이 HTTP 요청 수신 → DispatcherServlet의 doDispatch()로 진입 합니다. (2) 핸들러 탐색 HandlerMapping이 /api/users POST와 매칭되는 컨트롤러 메서드(Controller#register)를 찾습니다. (3) 컨트롤러 실행 HandlerAdapter가 컨트롤러 메서드 호출. @RequestBody로 JSON → RequestDto 바인딩 완료 (4) 서비스 호출 service.register(request) 진입 → existsByEmail(email) 호출 → true 반환(이미 등록됨) (5) 예외 발생

@PostMapping
    public ResponseEntity<?> register(@RequestBody RequestDto request) {
        ResponseDto response = service.register(request); → 예외 발생!
        return ResponseEntity.status(HttpStatus.CREATED).body(response); → 코드 실행 X
    }

throw new IllegalArgumentException("중복된 이메일 입니다."); 여기서 컨트롤러 메서드의 return ResponseEntity.status(CREATED)... 라인은 실행되지 못하고 중단됩니다.(스택이 예외로 튀어나감)

2. DispatcherServlet의 예외 처리 흐름

(1) 예외 전파 → DispatcherServlet 예외 처리 단계 doDispatch()가 예외를 잡아 processHandlerException()으로 넘깁니다. HandlerExceptionResolver 리스트를 순회합니다. - ExceptionHandlerExceptionResolver → @ExceptionHandler 있는지 확인 - ResponseStatusExceptionResolver → @ResponseStatus 붙어있는지 확인 - DefaultHandlerExceptionResolver → MVC 표준 예외 처리 하지만 IllegalArgumentException은 어느 곳에서도 처리되지 않습니다 → 결국 Null 반환

3. 컨테이너의 에러 디스패치

(1)컨테이너 에러 디스패치 모든 Resolver가 패스하면 예외는 ServletContainer로 전파됩니다.→ 이를 서블릿 컨테이너가 ERROR 디스패치를 수행, /error로 forward 합니다. (2) Spring Boot의 BasicErrorController 동작 컨테이너가 실어 준 javax.servlet.error.* 속성을 ErrorAttributes로 읽어 기본 에러 맵(JSON/HTML) 생성합니다. Content Negotiation 결과 JSON 선호면 기본 JSON 에러 바디(timestamp/status/error/message/path 등)로 응답합니다.

{
  "timestamp": "2025-09-13T00:30:12.345+09:00",
  "status": 500,
  "error": "Internal Server Error",
  "path": "/api/users"
}

위 코드가 500 기본 JSON 에러 포맷입니다.

그럼 어떻게 이 방법을 해결할까? : 전역 예외 처리기 도입

Spring에서 @RestControllerAdvice와 @ExceptionHandler를 통해 발생한 예외를 한 곳에서 모아 처리할 수 있습니다. 이를 기반으로 CustomException과 ErrorCode를 정의하고, ErrorResponse로 변환해 내려주는 구조를 만듭니다.

코드 구성과 동작 원리

1. ErrorCode - 에러 사전 정의

   @AllArgsConstructor
   @Getter
   public enum ErrorCode {
    NOT_FOUND_EMAIL(HttpStatus.NOT_FOUND, "U001","없는 이메일 입니다.");
   
    private final HttpStatus status;
    private final String code;
    private final String message;
   }

• HttpStatus : Http 상태코드 (404, 400, 409 등)
• code : 서비스 내부에서 정의한 식별 코드(U001, A001 등)
• message : 사용자에게 보여줄 메시지

2. CustomException - 예외 객체

   @Getter
   public class CustomException extends RuntimeException{
    private final ErrorCode errorCode;
   
    public CustomException(ErrorCode errorCode) {
        super(errorCode.getMessage()); // RuntimeException.message에 저장
        this.errorCode = errorCode;
    }
   }

• 개발자가 예외를 던질 때는 throw new CustomException(ErrorCode.NOT_FOUND_EMAIL)처럼 사용 가능합니다.
• 내부적으로 ErrorCode를 품고 있어 예외가 발생했을 때 상태/코드/메시지를 함께 전달 가능 합니다.

3. ErrorResponse - 응답 DTO

   @Getter
   @AllArgsConstructor
   public class ErrorResponse {
    private final int status;
    private final String code;
    private final String message;
   
    public static ErrorResponse of(ErrorCode errorCode) {
        return new ErrorResponse(
            errorCode.getStatus().value(),
            errorCode.getCode(),
            errorCode.getMessage()
        );
    }
   }

• 클라이언트로 내려가는 JSON 구조를 명확히 고정합니다.
• ErrorCode를 받아 바로 변환 가능합니다.

4. GlobalExceptionHandler - 전역 예외 처리기

   @RestControllerAdvice
   public class GlobalExceptionHandler {
   
    @ExceptionHandler(CustomException.class)
    public ResponseEntity<ErrorResponse> handleCustomException(CustomException e, HttpServletRequest request) {
        ErrorCode errorCode = e.getErrorCode();
        ErrorResponse errorResponse = ErrorResponse.of(errorCode);
   
        return ResponseEntity.status(errorCode.getStatus()).body(errorResponse);
    }
   
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleEtc(Exception e) {
        e.printStackTrace();
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body(new ErrorResponse(500, "S001", "서버 오류가 발생했습니다."));
    }
   }

• CustomException 처리
  • @ExceptionHandler(CustomException.class)가 잡는다
  • ErrorCode를 꺼내 ErrorResponse로 변환
  • ResponseEntity로 상태코드와 함께 반환
• 그 외 모든 예외 처리
  • Exception 핸들러에서 500 상태로 통일

5. 그럼 위 코드를 조합한 후 어떻게 동작하는지? 위에서 설명한 processHandlerException()에서 예외 resolver 체인 순회를 한다는 것을 기억할 것입니다. 스프링 컨테이너에 등록된 HandlerExceptionResolver 리스트를 순서대로 호출합니다. 그럼 첫 번째로 ExceptionHandlerExcetpionResolver를 먼저 호출하는데 @ExceptionHandler 메서드를 갖는 컨트롤러/@ControllerAdvice(= 우리가 만든 @RestControllerAdvice)를 스캔해, 현재 예외와 매칭되는 메서드를 찾습니다. 일단 저희의 오류는 바로 매칭이 됩니다. 이후 메서드 호출을 준비 → 핸들러 메서드 실행(ErrorResponse를 만들고 ResponseEntity로 감싸서 반환) → 리턴 값 처리(ErrorResponse를 HttpMessageConverter에게 전달되어 JSON 직렬화) 하여 프론트에게 JSON 형태로 에러 포맷을 보여줍니다.

6. 적용 후 확인

   UserService.register()
   ...
   if (userRepository.existsByEmail(request.getEmail())) {
            throw new CustomException(ErrorCode.EMAIL_ALREADY_IN_USE); → 변경
        }
   ...

이로써 프론트는 언제나 response.data.message로 사용자 메시지를 안전하게 꺼낼 수 있습니다.

이번 글에서는 실제 프로젝트 서비스 중 Create() 로직을 Mockito를 활용하여 Unit Test를 진행하는 과정을 보여드리겠습니다. Mockito를 사용한 유닛 테스트는 저에게도 낯설었기 때문에 직접 코드를 작성하면서 어려웠던 부분과 헷갈렸던 부분을 공유하며 자세히 설명하고자 합니다. 참고) 이 글은 테스트 코드 작성 경험이 한 번이라도 있으신 분들을 위한 내용입니다.

들어가기 전

일단 테스트 코드를 작성하기 전에 왜 Mockito를 활용하여 UnitTest를 진행하는지에 대한 필요성을 알고 들어갑시다.

먼저 유닛 테스트는 소프트웨어의 가장 작은 단위, 즉 하나의 메서드나 클래스가 예상대로 동작하는지 검증하는 과정입니다. 핵심은 테스트 대상이 외부 환경이나 다른 코드의 영향을 받지 않고 완전히 독립적인 상태에서 테스트 되어야 합니다.

Isolated : Unit tests are standalone, can run in isolation, and have no dependencies on any outside factors, such as a file system or database. MS Test 공식 문서

하지만 Service 계층의 메서드는 보통 Repository나 다른 Service 등 외부 의존성을 가집니다. 예를 들어 저의 프로젝트 Service 계층에서, ContractService의 createContract() 메서드는 ContractRepository를 사용하여 데이터를 조회하거나 저장합니다.

ContractService.java

private final ContractRepository contractRepository; // 외부 의존성

 @Transactional
 public Contract createContract(ContractCreateRequest request) {
        Optional<Contract> checkDuplicateContract = contractRepository.findByBorrowerPhoneNumberAndPrincipalAndRepaymentDateAndStatusIn(
                request.getBorrowerPhoneNumber(),
                request.getPrincipal(),
                request.getRepaymentDate(),
                ContractStatus.getActiveStatuses()
        );

        if (checkDuplicateContract.isPresent()) {
            throw new IllegalArgumentException("중복된 계약이 존재합니다.");
        }

        Contract contract = Contract.create(request);

        // 추후 DTO 변환해서 반환, 현재까지는 엔티티 반환 유지
        return contractRepository.save(contract);
    }

만약 contractRepository가 실제 DB에 연결되어 있다면, 테스트는 느려질 수 밖에 없을 것입니다. 그래서 Mockito가 등장하는데 Mockito는 이러한 외부 의존성 객체들을(여기서는 contractRepository) Mock Object로 만들어 줍니다. 이 Mock Object들에게 어떠한 메소드가 호출되면 이런 값을 반환해달라고 설정할 수 있고, 예상대로 호출되었는지 확인도 할 수 있습니다.

createContract() 성공 케이스 테스트 코드

이제 ContractService의 createContract() 메서드가 정상적으로 동작할 때를 가정한 성공 케이스 테스트 코드를 살펴보겠습니다,

Service CreateContract().test

@ExtendWith(MockitoExtension.class)
public class ContractServiceTest {

    @Mock 
    private ContractRepository contractRepository;

    @InjectMocks
    private ContractService contractService; 

    @Test
    @DisplayName("계약 생성 성공 - 유효한 요청")
    void createContract_success() {
        //Given
        ContractCreateRequest request = ContractCreateRequest.builder()
                .borrowerPhoneNumber("010-9665-1195")
                .principal(BigDecimal.valueOf(100000))
                .repaymentDate(LocalDate.of(2025, 8, 30))
                .build();

        List<ContractStatus> activeStatuses = ContractStatus.getActiveStatuses();

        when(contractRepository.findByBorrowerPhoneNumberAndPrincipalAndRepaymentDateAndStatusIn(
                anyString(),
                any(BigDecimal.class),
                any(LocalDate.class),
                eq(activeStatuses)
        )).thenReturn(Optional.empty());
        //쉽게 이해하자면 createContract()가 내부에서 사용하는 DB 접근 로직(findBy.., save)은 실제로 동작하지 않기 때문에 그 동작을 이렇게 반응해라 고 미리 설정해줘야 정상 흐름으로 테스트가 진행된다.

        when(contractRepository.save(any(Contract.class)))
                .thenAnswer(invocation -> {
                    Contract contract = invocation.getArgument(0);
                    return Contract.builder()
                            .id("test-contract-id-" + contract.getBorrowerPhoneNumber())
                            .borrowerPhoneNumber(contract.getBorrowerPhoneNumber())
                            .principal(contract.getPrincipal())
                            .repaymentDate(contract.getRepaymentDate())
                            .status(ContractStatus.PENDING_AGREEMENT)
                            .createdAt(LocalDateTime.now())
                            .updatedAt(LocalDateTime.now())
                            .build();
                });

        // When
        Contract createContract = contractService.createContract(request);

        // then
        assertNotNull(createContract, "생성된 계약은 null이 아니어야 합니다.");
        assertNotNull(createContract.getId(), "생성된 계약의 ID는 null이 아니어야 합니다.");
        assertEquals(request.getBorrowerPhoneNumber(), createContract.getBorrowerPhoneNumber(), "휴대폰 번호가 일치해야 합니다.");
        assertEquals(request.getPrincipal(), createContract.getPrincipal(), "원금이 일치해야 합니다.");
        assertEquals(request.getRepaymentDate(), createContract.getRepaymentDate(), "상환일이 일치해야 합니다.");
        assertEquals(ContractStatus.PENDING_AGREEMENT, createContract.getStatus(), "초기 상태는 PENDING_AGREEMENT여야 합니다.");

        verify(contractRepository, times(1)).findByBorrowerPhoneNumberAndPrincipalAndRepaymentDateAndStatusIn(
                eq(request.getBorrowerPhoneNumber()),
                eq(request.getPrincipal()),
                eq(request.getRepaymentDate()),
                eq(activeStatuses)
        );

        verify(contractRepository, times(1)).save(any(Contract.class));
    }
}

• @ExtendWith(MockitoExtension.class) : Junit5에게 이 테스트 클래스에서 Mockito 어노테이션을 사용하겠다고 선언을 합니다.
• @Mock : 이 어노테이션이 붙은 필드에 Mockito가 해당 타입의 가짜 객체를 만들어줍니다. 이 가짜 객체는 contractRepository는 실제 로직을 수행하지 않고, 저희가 설정한 대로만 응답합니다.
• @InjectMocks : 이 어노테이션이 붙은 필드에 Mockito가 인스턴스를 생성하고, @Mock으로 생성된 모든 Mock 객체들을 자동으로 주입해줍니다. 쉽게 말해서 위 실제 service 계층에서 실제contractRepository를 주입 받고 있는데 테스트 과정에서는 우리가 만든 가짜 contractRepository를 사용하게 됩니다.

Given

ContractCreateRequest request = ContractCreateRequest.builder()
                .borrowerPhoneNumber("010-9665-1195")
                .principal(BigDecimal.valueOf(100000))
                .repaymentDate(LocalDate.of(2025, 8, 30))
                .build();

        List<ContractStatus> activeStatuses = ContractStatus.getActiveStatuses();

1. 일단 저희 Service 코드에서도 Controller에서 request를 인자로 받았으니 똑같이 테스트 코드에서도 createContract()에 전달할 request DTO를 생성해줍니다.

when(contractRepository.findByBorrowerPhoneNumberAndPrincipalAndRepaymentDateAndStatusIn(
                anyString(),
                any(BigDecimal.class),
                any(LocalDate.class),
                eq(activeStatuses)
        )).thenReturn(Optional.empty());

2. 이제부터가 중요한데, Mock Repository의 동작을 Stubbing 하는 과정입니다. 저희가 Mockito에게 (When)"만약 contractRepository의 findBy... 메서드가 어떤 문자열, 어떤 BigDecimal, 어떤 LocalDate, activeStatuse 리스트를 인자로 받아 호출되면, (Then)그때는 'Optional.empty()를 반환해라. 라는 의미입니다. 왜냐하면 저희는 일단 성공 케이스를 테스트 작성하는 과정이니 중복 계약이 있어서는 안되겠죠? 그래서 Optional.empty()를 반환 받아 중복 계약이 없음을 의미하는 뜻으로 작성했습니다.

when(contractRepository.save(any(Contract.class)))
            .thenAnswer(invocation -> {
                Contract argContract = invocation.getArgument(0); 
                return Contract.builder()
                        .id("test-contract-id-" + argContract.getBorrowerPhoneNumber()) 
                        .borrowerPhoneNumber(argContract.getBorrowerPhoneNumber())
                        .principal(argContract.getPrincipal())
                        .repaymentDate(argContract.getRepaymentDate())
                        .status(ContractStatus.PENDING_AGREEMENT)
                        .createdAt(LocalDateTime.now())
                        .updatedAt(LocalDateTime.now())
                        .build();
            });

3. 이 부분도 보면 실제 Service 코드를 보면 save() 메서드를 호출하고 있는데, (When)만약 ContractRepository의 save 메서드가 어떤 Contract 객체를 인자로 받아 호출되면,(Then)해당 Contract 객체에 가상의 Id와 시간 정보를 추가한 Contract 객체를 만들어서 반환해라 라는 의미입니다. 이 부분도 어쨋든 성공 케이스를 작성하는 것이기 때문에 저장이 성공하여 Id가 부여된 것처럼 시뮬레이션 한 것입니다.

이렇게 하면 Given 부분이 완료되었습니다.

When

1. 이제 테스트 대상인 contractService.createContract()를 실제로 호출합니다. 이 시점에서는 Service 내부의 로직이 실행되며, 주입된 Mock contractRepository의 메소드 들이 호출됩니다. Mockito는 이 호출들을 가로채서 저희가 위에서 작성한 Given 단계에서 설정한 대로 응답합니다.

   Contract createdContract = contractService.createContract(request);;

하면서 궁금했던 점

공식문서, 블로그에 작성된 Test 코드, Gemini 등 활용하면서 공부하고 TestCode를 작성했는데 쓰고나서도 제가 왜 쓴지 몰랐습니다...'그래서 when.then..()은 왜 쓰는건데?'라고 계속 생각했습니다. 혹시 저와 같은 상황에 있으신 분들을 위해 일단 제가 이해한대로 아래 그림과 같이 설명드리겠습니다.

1. 실제 createContract() 메서드 로직을 봅시다. contractRepository를 활용해 처음부터 중복 계약이 있는지 확인 하는 로직이 있습니다. 또한 마지막 return 반환 부분에서 contractRepository를 이용해서 save 메서드를 호출하고 있습니다. 이 두 부분은 모두 외부 의존성 즉, 실제 DB와 연동에 해당합니다.
2. Unit Test의 목적은 createContract() 메서드 자체의 로직 검증입니다. createContract()가 중복이 없으면 저장하고 성공적으로 반환한다는 비지니스 로직을 제대로 수행하는지 보고싶지, Repository가 실제 DB에 데이터를 어떻게 저장하는지는 이 테스트에서 관심사가 아니라는겁니다.

   "그래, 그건 알겠는데 그래서 when.then..()을 왜 쓰냐고?"

3. 만든 ContractRepository는 Mock 객체입ㅂ니다. 이 Mock객체는 스스로 아무것도 할 수 없는 바보입니다. 그래서 우리는 when().then..() 구문을 통해Mockito에게 Mock Repository의 특정 메서드가 호출되면 이런 값을 반환해 줘와 같이 미리 시나리오를 정해주는 것입니다. 1) 파란색 화살표 1번 성공 테스트 목적을 달성하려면 createContract() 메서드 안의 중복 확인 로직이 중복이 없다고 판단해야 합니다. 그래서 when(contractRepository.findBy...).thenReturn(Optional.empty()); 라고 설정하여, 실제 findBy... 메서드가 호출될 때 Optional.empty()를 즉시 반환하게끔 강제하는 것입니다. 이렇게 되면 service는 중복이 없다고 판단하고 다음 로직으로 넘어갈 수 있게 됩니다. 만약 이 부분을 중복 계약이 있다고 가정으로 설정하면 createContract()는 바로 IllegalArgumentException을 던지며 오류가 발생했을 것입니다.<- 이 부분은 실패케이스에서 활용 2) 파란색 화살표 2번 마찬가지로 createContract()가 return 까지 성공적으로 도달하려면 save 메서드 호출도 성공해야 합니다. when(contractRepository.save(...)).thenAnswer(...) 라고 설정하여 save 메서드가 호출될 때 마치 DB에 정상적으로 저장되고 ID가 부여된 Contract 객체가 반환된 것처럼 가상의 객체를 만들어 돌려주도록 강제한 것입니다.

(질문) 왜 가상의 객체를 만들어 돌려주도록 했을까요? -> createContract() 메서드의 반환타입은 Contract이니깐 당연히 Contract 객체를 반환해줘야죠.

이제는 느낌이 와야합니다..

Then

이제 마지막 부분은 검증을 하는 구간입니다. when().then..()이 Mock 객체가 무엇을 반환할지를 설정하는 것이라면, verify()는 service 로직이 Mock 객체(외부 의존성)를 예상한 대로 호출했는지를 확인하는 역할입니다. 테스트 대상 메서드가 실행되는 동안 외부 의존성(Mock객체(여기서는 repository))과 어떻게 상호작용했는지를 검증합니다. 예를 들어 findBy... 메서드가 정확히 1번 호출되었는지, save 메서드도 정확히 1번 호출되어서 어떤 Contract 객체를 반환했는지 등을 확인하여 Service의 비지니스 로직이 의존성을 올바르게 사용했는지 검증합니다.

마무리

이제 코드를 실행한 결과 성공적으로 테스트를 통과한 것을 볼 수가 있습니다. 실패 케이스도 이와 비슷하게 작성하시면 될 것 같습니다. 이 글이 Mockito를 활용하여 UnitTest를 작성하시는 분들에게 도움이 되기를 바랍니다.

프로젝트를 진행하면서 단일 프로젝트 구조에 익숙했던 나에게 처음으로 도입한 Gradle Multi-Module 구조는 많은 시행착오를 안겨줬다. 공식 문서나 기업들의 Multi-Module 도입 영상도 찾아보면서 구조를 분리해봤지만 설정을 추가할 때마다 문제가 생겨서 구조에 문제가 있는 것을 깨닫고 수차례 재정비해야 했다. 이 글은 그 과정을 되짚으며, 내가 겪은 문제와 그 해결 과정, 특히 Gradle이 권장하는 구조로의 전환을 중심으로 정리한 것이다.

1. 초기에 도입했던 Gradle 구조와 설정

1) 초기 디렉토리 구조

credit(root)
├── settings.gradle -> root.projectName과 하위 모듈을 정의하는 include 존재   
├── build.gradle        
├── credit-api/
│   └── build.gradle     
│   └── settings.gradle -> root.projectName만 존재
├── credit-common/
│   └── build.gradle     
│   └── settings.gradle -> root.projectName만 존재
├── credit-core/
│   └── build.gradle     
│   └── settings.gradle -> root.projectName만 존재
└── credit-external-api/
    └── build.gradle     
    └── settings.gradle -> root.projectName만 존재

모듈을 나눈 건 좋아 보였지만 실제로 프로젝트를 운영하면서 몇 가지 구조적 한계에 부딪혔다.

2) root build.gradle 내용

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.5.3'
    id 'io.spring.dependency-management' version '1.1.7'
}
allprojects {
    group = 'com'
    version = '0.0.1-SNAPSHOT'
}
subprojects {
    apply plugin: 'java'
    apply plugin: 'org.springframework.boot'
    apply plugin: 'io.spring.dependency-management'
    repositories {
        mavenCentral()
    }
    dependencies {
        testImplementation 'org.springframework.boot:spring-boot-starter-test'
        testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
        compileOnly 'org.projectlombok:lombok'
        annotationProcessor 'org.projectlombok:lombok'
    }
    tasks.named('test') {
        useJUnitPlatform()
    }
}
java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}
configurations {
    compileOnly {
        extendsFrom annotationProcessor
    }
}

3. 주요 문제점

문제점 1 : allProjects{} / subProjects{} 사용

Gradle 공식 문서에서도 언급되듯 cross-project configuration 방식은 configuration-on-demand 기능을 방해하고, 각 모듈의 설정을 외부에서 암묵적으로 주입하는 방식이라 유지보수에 불리하다.

왜 문제가 될까?

• Configuration-Time coupling 유발 : 프로젝트 간에 구성 시간 결합을 유발하여 configuration-on-demand와 같은 최적화 기능이 제대로 작동하지 못하게 할 수 있다.
• configuration-on-demand*는 빌드 시간을 줄이기 위해 요청된 Task에 관련된 프로젝트만 구성하려고 시도하는데 allProjects{}나 subProjects{}와 같은 구성을 통한 주입은 프로젝트 간의 결합을 만들어서 최적화를 방해할 수 있다.
• 숨겨진 빌드 로직 : 빌드 로직이 하위 모듈 프로젝트의 빌드 스크립트에서 명확하게 드러나지 않고 상위 수준에서 주입되기 때문에, 해당 프로젝트의 빌드 스크립트만으로는 어떤 로직이 적용되는지 파악하기 어려울 수 있다.

해결책

• Convention Plugins 사용 : Convention Plugins는 프로젝트 루트에 있는 특별한 buildSrc 디렉토리 내에 위치하며, 공통 빌드 로직(Plugin 적용, 공통 의존성, Task 설정 등)을 중앙 집중화하고 재사용성을 높일 수 있다. 예를 들어, 특정 유형의 하위 프로젝트에 플러그인이나 기타 구성을 적용하는 로직은 해당 유형의 하위 프로젝트에 직접 Convention Plugin을 적용하는 것으로 대체할 수 있다.

문제점 2 : plugin 버전 하드코딩

루트 디렉토리의 build.gradle에 plugin의 의존성 버전이 직접 하드코딩 될 경우, 여러 하위 프로젝트에서 동일한 의존성을 사용할 때 버전이 중복 선언될 수 있다.

왜 문제가 될까? 버전이 중복이 되면 나중에 버전을 업그레이드하거나 변경할 때 모든 파일을 일일이 수정해야 해서 번거롭고 실수를 유발할 수 있습니다. 또 프로젝트 간의 의존성 충돌 문제가 발생할 수 도 있다.

해결책 의존성 버전 관리의 비효율성 문제를 해결하기 위해 settings.gradle 파일에서 pluginManagement{} 블록을 이용하여 Gradle 빌드에서 사용될 플러그인들의 버전 관리를 한 곳에서 할 수 있다.

초기 Sub-Module credit-api/build.gradle (다른 하위 모듈들 아래 모듈 gradle 설정이 비슷하기에 1개만 대표로 올립니다.)

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.5.3'
    id 'io.spring.dependency-management' version '1.1.7'
}
dependencies {
    implementation project(':credit-core')
    implementation project(':credit-external-api')
    implementation project(':credit-common')
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-validation'
    testImplementation 'com.h2database:h2'
}
tasks.named('test') {
    useJUnitPlatform()
}

2. 개선: Gradle이 권장하는 구조로 전환

위에서 언급된 문제점들을 해결하고, Gradle이 권장하는 중앙 집중화와 Convention Plugins 방식을 도입하여 빌드 구조를 개선했습니다.

1) 변경된 디렉토리 구조

credit(root)
├── settings.gradle      
├── buildSrc
│   └── src
│       └── main
│           └── groovy
│               └── java-common-convention.gradle
│               └── spring-boot-convention.gradle
│   └── build.gradle
├── credit-api/
│   └── build.gradle     
├── credit-common/
│   └── build.gradle     
├── credit-core/
│   └── build.gradle     
└── credit-external-api/
    └── build.gradle     

• 모든 하위 모듈에서 settings.gradle 제거

• 공통 로직은 buildSrc로 convention plugin으로 재구성
• 모듈별로 필요한 설정만 명시적으로 선언하도록 변경

2) settings.gradle 개선

credit/settings.gradle

pluginManagement { 
    repositories {
        gradlePluginPortal()
        mavenCentral()
    }
    plugins { 
        id 'org.springframework.boot' version '3.5.3' 
        id 'io.spring.dependency-management' version '1.1.7'
    }
}
rootProject.name = 'credit'

include 'credit-api'
include 'credit-core'
include 'credit-external-api'
include 'credit-common'

이제 모듈을 추가하거나 제거할 때 이 root settings.gradle 파일만 수정하면 되니깐 유지 보수성 측면에서 많이 편해졌다.

3) buildSrc + Java 공통 Convention plugin

초기 구조에서는 모든 공통 설정을 루트 build.gradle에서 처리하다 보니 모듈별로 불필요한 설정까지 강제로 적용되고 있었다. 이를 개선하기 위해 Gradle에서 권장하는 buildSrc 디렉토리를 만들어 Custom Gradle Plugin을 정의했다.

buildSrc란? Gradle에서 buildSrc는 자동으로 빌드에 포함되는 특별한 디렉토리 입니다. 여기에 정의한 플로그인은 프로젝트 내 어떤 모듈에서도 바로 사용할 수 있습니다.

buildSrc/build.gradle

plugins {
    id 'groovy-gradle-plugin' 
}
repositories {
    gradlePluginPortal()
    mavenCentral()
}

buildSrc/.../java-common-coventions.gradle (New)

plugins {
    id 'java' 
}
group = 'com' 
version = '0.0.1-SNAPSHOT'

repositories {
    mavenCentral()
}
dependencies { 
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher:1.10.2'
    compileOnly 'org.projectlombok:lombok:1.18.30'
    annotationProcessor 'org.projectlombok:lombok:1.18.30'
}
tasks.named('test') {
    useJUnitPlatform()
}
java { 
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

이제 각 모듈에서는 다음과 같이 id 'java-common-coventions' 한 줄만 선언하면 java 공통 설정을 바로 사용할 수 있습니다.

credit-api/build.gradle

plugins {
    id 'java-common-conventions' 
    id 'org.springframework.boot' 
    id 'io.spring.dependency-management'
}
dependencies { 
    implementation project(':credit-core')
    implementation project(':credit-external-api')
    implementation project(':credit-common')
    implementation 'org.springframework.boot:spring-boot-starter-web'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    implementation 'org.springframework.boot:spring-boot-starter-validation'
    testImplementation 'com.h2database:h2'
}
(credit-core/build.gradle 및 credit-external-api/build.gradle, credit-common/build.gradle도 위와 유사하게 개선)

4) Spring Boot Covnention Plugin 도입

이전 개선된 구조에서 java-common-conventions.gradle을 통해 java 관련 공통 설정을 중앙에서 관리했다. 하지만 여전히 org.springframework.boot 및 io.spring.dependency-management플러그인 적용과 특정 Spring Boot starter 의존성(spring-boot-starter-web, spring-boot-starter-validation, test 등)은 각 모듈의 build.gradle 파일에 직접 명시되어 있었다.

나는 이게 마음에 들지 않아서, 모든 Spring Boot 관련 공통 관심사도 Java 처럼 별도의 Convention Plugin으로 통합함으로써 각 모듈의 build.gradle 파일을 간결하게 만들고싶었다.

buildSrc/.../spring-boot-coventions.gradle (New)

plugins {
    id 'java-common-conventions'
    id 'org.springframework.boot'
    id 'io.spring.dependency-management'
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-validation'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

buildSrc/build.gradle

...

dependencies { -> 새롭게 추가된 부분
    implementation 'org.springframework.boot:spring-boot-gradle-plugin:3.2.5'
    implementation 'io.spring.dependency-management:io.spring.dependency-management.gradle.plugin:1.1.4'
}

credit-api/build.gradle

plugins {
    id 'spring-boot-conventions'
}

dependencies { 
    implementation project(':credit-core')
    implementation project(':credit-external-api')
    implementation project(':credit-common')

    testImplementation 'com.h2database:h2'
}
(credit-core/build.gradle 및 credit-external-api/build.gradle, credit-common/build.gradle도 위와 유사하게 개선)

3. 트러블 슈팅 : UnknownPluginException

문제 상황

spring boot 관련 Convention Plugin을 만들고 적용하려 했을 때 아래 오류가 발생했다.

buildSrc/build.gradle (오류 발생 당시)

plugins {
    id 'groovy-gradle-plugin'
}

repositories { 
    gradlePluginPortal() 
    mavenCentral()
}

원인 분석

왜 UnknownPluginException이 발생했을까?

이 오류의 핵심은 "Plugin with id 'org.springframework.boot' not found" 라는 메시지에 있었다. 이는 buildSrc가 spring-boot-conventions.gradle을 Convention Plugin으로 컴파일하여 만들려고 할 때 발생한 문제였다.

공식문서를 찾아보며 더 깊이 파고들면 그 이유를 찾을 수 있었다.

1. Gradle은 buildSrc 디렉토리를 발견하면, 이를 독립적인 Gradle 서브 프로젝트처럼 취급하고 메인 빌드 보다 먼저 빌드 한다.

2. spring-boot-conventions.gradle 파일은 그 자체로 Groovy 코드 스크립트이기도 하면서 buildSrc가 컴파일하여 생성할 커스텀 플러그인의 정의이다. 이 스크립트 내부에 plugins {id 'org.springframework.boot`}와 같이 다른 플러그인을 참조하는 구문이 있다.

3. 문제는 buildSrc가 이 spring-boot-conventions.gradle을 컴파일할 때 발생했다. spring-boot-conventions.gradle 내부에서 참조하는 org.springframework.boot 플러그인 (org.springframework.boot:spring-boot-gradle-plugin JAR 파일 내부의 클래스 및 메타데이터)이 buildSrc 프로젝트의 컴파일 타임 클래스패스에 존재하지 않았던 것이다.

4. 오류 발생 당시의 buildSrc/build.gradle 파일에는 groovy-gradle-plugin만 적용되어 있었고, org.springframework.boot 플러그인 자체에 대한 의존성 선언이 누락되어 있었다. 즉, buildSrc는 자신이 빌드해야 할 spring-boot-conventions가 참조하는 org.springframework.boot 플러그인이 무엇인지, 그리고 어디에서 그 정의를 찾을 수 있는지 전혀 알 방법이 없었던 것이다. 이로 인해 UnknownPluginException이 발생했던 것입니다.

결론적으로, buildSrc/build.gradle에 org.springframework.boot:spring-boot-gradle-plugin과 io.spring.dependency-management:io.spring.dependency-management.gradle.plugin JAR 파일을 implementation 의존성으로 추가함으로써 문제가 해결되었다.

buildSrc/build.gradle

...
dependencies {
    implementation 'org.springframework.boot:spring-boot-gradle-plugin:3.2.5'
    implementation 'io.spring.dependency-management:io.spring.dependency-management.gradle.plugin:1.1.4'
}

이로써,성공적으로 빌드가 완료되었다.

결과적으로 문제가 해결된 이유

1. buildSrc의 build.gradle 파일에 Spring Boot Gradle Plugin과 Spring Dependency Management Gradle Plugin을 implementation 의존성으로 추가했다.

2. Gradle은 메인 프로젝트 빌드를 시작하기 전에 buildSrc 디렉토리를 독립적인 프로젝트로 먼저 빌드한다. 이 과정에서 implementation으로 선언된 두 플러그인의 JAR 파일들이 buildSrc 프로젝트의 컴파일 타임 및 런타임 클래스패스에 포함된다.

3. 이렇게 빌드된 buildSrc의 결과물(커스텀 컨벤션 플러그인들)은 메인 빌드의 클래스패스에 자동으로 추가된다.

4. 결과적으로, 메인 프로젝트의 하위 모듈(credit-api 등)에서 plugins { id 'spring-boot-conventions' }와 같이 spring-boot-conventions 플러그인을 적용할 때, 이 플러그인 내에서 참조하는 org.springframework.boot 플러그인에 대한 정의가 이미 buildSrc를 통해 메인 빌드의 클래스패스에 로드되어 있으므로 Gradle은 해당 플러그인을 성공적으로 찾아 적용할 수 있게 된 것이다.

출처

Gradle 8.14.3 공식문서

많은 도움이 되셨으면 좋겠습니다!