사용자가 작성한 서약서를 스마트 컨트랙트로 배로 하려고 했는데, 이슈가 발생했습니다. 만들어진 서약서를 DB에 넣은 뒤 스마트 컨트랙트로 트랜잭션을 만들어 등록하는 과정에서 15초나 걸리는 문제가 발생했습니다.

'아, 이 작업 너무 오래 걸리는데... 사용자 기다리게 할 순 없지!🤔' 라는 생각으로 사용자가 원활하게 서비스를 이용할 수 있도록 비동기를 사용했습니다.

그래서 오늘은 Spring Boot의 유용한 기능 @Async를 사용해서 시간이 오래 걸리는 작업을 비동기로 처리했던 경험과, 그 과정에서 활용했던 CompletableFuture, Mockito 테스트 경험😅, 그리고 가장 중요했던 @Transactional과의 관계🚨까지 상세히 정리해보려고 합니다.

---

1단계: @ASYNC 기본 적용

가장 먼저, Spring Boot에 "비동기 기능을 사용하겠다"고 알려주어야 합니다. 메인 클래스나 @Configuration 클래스에 @EnableAsync를 추가하면 준비가 끝납니다.

import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.scheduling.annotation.EnableAsync;

@SpringBootApplication
@EnableAsync // 추가!
public class MyAwesomeApplication {
    // ... main ...
}

그리고 비동기로 실행하고 싶은 메서드에 @Async만 붙여주면 됩니다. 매우 간단합니다. (단, public 메서드여야 하고 Spring Bean 안에 있어야 합니다.)

import org.springframework.scheduling.annotation.Async;
import org.springframework.stereotype.Service;

@Service
public class MySlowService {

    @Async // 이렇게 하시면 됩니다.
    public void doSomethingSlow() {
        System.out.println("느린 작업 시작... (다른 스레드에서)");
        // ... 시간 걸리는 작업 ...
        System.out.println("느린 작업 끝!");
    }
}

2단계: "그래서... 성공했는가?" 🤔

단순히 '실행하고 잊어버리는(Fire-and-Forget)' 작업이라면 위처럼 void로 충분하지만, 제 경우에는 스마트 컨트랙트 등록이 성공했는지 실패했는지 알아야 했습니다.

이럴 때 유용하게 사용할 수 있는 것이 바로 CompletableFuture!

비동기 작업의 결과를 나중에 받아보거나, 성공/실패에 따른 후속 처리를 깔끔하게 할 수 있게 해줍니다.

저희가 스마트 컨트랙트의 트랜잭션을 등록하는 addContract를 다음과 같이 변경했었습니다. 👇

import org.springframework.scheduling.annotation.Async;
import org.springframework.stereotype.Component;
import java.util.concurrent.CompletableFuture;

@Component
public class ContractHandler {
    // ... (생성자 등) ...

    @Async // 비동기 실행!
    public CompletableFuture<Boolean> addContract(ContractInput input) { // 반환 타입 변경!
        try {
            // ... (블록체인과 통신하는 로직) ...
            boolean isSuccess = blockchainTransaction.isStatusOK(); // 성공 여부 확인
            log.info("✅ 스마트 컨트랙트 등록 성공!");
            return CompletableFuture.completedFuture(isSuccess); // 결과를 담은 완료된 Future 반환
        } catch (Exception e) {
            log.error("❗ 스마트 컨트랙트 등록 실패!: {}", e);
            return CompletableFuture.completedFuture(false); // 실패 시 false 반환
        }
    }
}

호출하는 쪽에서는 이렇게 결과를 비동기적으로 처리할 수 있습니다. 👍

CompletableFuture<Boolean> future = contractHandler.addContract(input);

future.thenAccept(success -> { // 성공했을 때 (다른 스레드에서 실행됨)
    if (success) {
        log.info("✨ 스마트 컨트랙트 등록 성공 알림 보내야지!");
    } else {
        log.error("💧 실패 알림 보내야겠다...");
    }
}).exceptionally(ex -> { // 예외 발생했을 때 (다른 스레드에서 실행됨)
    log.error("🔥 예외 발생!", ex);
    return null;
});

log.info("메인 스레드는 기다리지 않고 다음 일을 하러 갑니다.");

3단계: 테스트 코드 작성

자, 이제 테스트 코드를 작성할 시간입니다! @Async 메서드를 Mockito로 Mocking하는데... 여기서 제가 잠시 어려움을 겪었던 부분이 있었습니다. 😅

🚨 잘못된 시도 (무한 대기) 🚨

// given
when(mockContractHandler.addContract(any()))
    .thenReturn(new CompletableFuture<>()); // 텅 빈 Future 반환...

// when
CompletableFuture<Boolean> future = service.callAddContract();

// then
assertTrue(future.join()); // 여기서 영원히 대기... 😵

new CompletableFuture<>()는 완료되지 않은 Future를 만들어서 join()이 계속 기다리게 만듭니다.

✨ 올바른 방법 ✨

테스트 시나리오에 맞게 이미 완료된 Future를 반환해주어야 합니다.

✅성공 시나리오

when(mockContractHandler.addContract(any()))
    .thenReturn(CompletableFuture.completedFuture(true)); // 성공(true)으로 완료된 Future!

❌실패 시나리오

when(mockContractHandler.addContract(any()))
    .thenReturn(CompletableFuture.completedFuture(false)); // 실패(false)로 완료된 Future!

사용된 TEST 코드

package com.ssafy.chaing.blockchain.handler;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.times;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.when;

import com.ssafy.chaing.blockchain.config.Web3jConnectionManager;
import com.ssafy.chaing.blockchain.handler.contract.ContractHandler;
import com.ssafy.chaing.blockchain.handler.contract.input.ContractInput;
import com.ssafy.chaing.blockchain.handler.contract.input.LiveAccountInput;
import com.ssafy.chaing.blockchain.handler.contract.input.PaymentInfoInput;
import com.ssafy.chaing.blockchain.handler.contract.output.ContractOutput;
import com.ssafy.chaing.blockchain.handler.contract.output.ContractOverviewOutput;
import com.ssafy.chaing.blockchain.handler.contract.output.ContractRentOutput;
import com.ssafy.chaing.blockchain.web3j.ContractManager;
import com.ssafy.chaing.blockchain.web3j.ContractManager.PaymentInfo;
import java.math.BigInteger;
import java.util.List;
import java.util.concurrent.CompletableFuture;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;
import org.mockito.stubbing.Answer;
import org.web3j.abi.datatypes.generated.Uint256;
import org.web3j.crypto.Credentials;
import org.web3j.protocol.Web3j;
import org.web3j.protocol.core.methods.response.TransactionReceipt;
import org.web3j.tuples.generated.Tuple13;
import org.web3j.tuples.generated.Tuple3;
import org.web3j.tuples.generated.Tuple6;
// TransactionManager는 이제 직접 주입받지 않음

@ExtendWith(MockitoExtension.class) // JUnit5 와 Mockito 연동
class ContractHandlerTest {

    private final String TEST_CONTRACT_ADDRESS = "0x로 시작하는 스마트 컨트랙트 주소가 들어가면 됩니다.";
    private final long TEST_CHAIN_ID = 137L; // 테스트용 체인 ID

    @Mock
    private Web3jConnectionManager mockConnectionManager; // 수정: ConnectionManager Mock
    @Mock
    private Credentials mockCredentials; // 수정: Credentials Mock
    @Mock
    private ContractManager mockContractManager; // 수정: ContractManager는 여전히 Mock 필요
    @Mock
    private Web3j mockWeb3j; // 수정: execute 콜백에 전달될 Web3j Mock

    // @InjectMocks 사용 시 Mockito가 생성자에 Mock 객체들을 주입 시도
    // 단, 생성자 주입 외 @Value 등이 있으면 직접 생성해야 할 수 있음
    private ContractHandler contractHandler;

    // --- Helper for mocking connectionManager.execute ---
    // 이 Answer는 connectionManager.execute가 호출될 때
    // 1. ContractManager.load가 mockContractManager를 반환하도록 설정하고 (정적 메서드 모킹 필요)
    // 2. 전달된 람다(callable)를 실행하는 것을 시뮬레이션합니다.
    // 정적 메서드 모킹 대신, 람다가 반환해야 할 최종 결과만 설정하는 것이 더 간단합니다.
    private <T> Answer<T> simulateExecution(T expectedResult) {
        return invocation -> {
            // 1. invocation에서 람다(Web3jCallable) 가져오기 (선택적)
            // Web3jConnectionManager.Web3jCallable<T> callable = invocation.getArgument(0);

            // 2. 람다가 실행될 때 반환될 결과 (가장 중요)
            //    실제 람다 실행 대신, 람다 실행의 *결과*를 반환하도록 설정합니다.
            //    이 결과는 보통 ContractManager의 메서드 호출(.send()) 결과입니다.
            //    따라서 각 테스트 메서드에서 mockContractManager의 동작을 미리 설정해두어야 합니다.
            return expectedResult;
        };
    }

    // execute가 예외를 던지도록 시뮬레이션하는 Answer
    private <T> Answer<T> simulateExecutionWithError(Exception exceptionToThrow) {
        return invocation -> {
            throw exceptionToThrow;
        };
    }


    @BeforeEach
    void setUp() {
        // MockitoAnnotations.openMocks(this) 대신 @ExtendWith(MockitoExtension.class) 사용
        // @InjectMocks를 사용하지 않고 수동으로 생성자 호출
        contractHandler = new ContractHandler(
                mockConnectionManager,
                mockCredentials,
                TEST_CHAIN_ID,
                TEST_CONTRACT_ADDRESS
        );
        // CustomGasProvider는 내부적으로 new로 생성되므로 별도 주입 불필요
        // ContractManager는 loadContractManager 헬퍼 내에서 로드되므로 필드 주입 불필요
    }

    @Test
    void testAddContract_Success() throws Exception { // CompletableFuture 예외 처리를 위해 throws Exception 추가
        // --- Input Data ---
        PaymentInfoInput paymentInfo1 = new PaymentInfoInput(BigInteger.valueOf(1), BigInteger.valueOf(2100000),
                BigInteger.valueOf(7));
        // ... (다른 PaymentInfoInput)
        ContractInput input = new ContractInput(/* ... input data 설정 ... */);
        input.setId(BigInteger.ONE);
        input.setPaymentInfos(List.of(paymentInfo1)); // 예시

        // --- Mocking ---
        // 1. 최종 결과인 TransactionReceipt Mock 설정
        TransactionReceipt mockReceipt = mock(TransactionReceipt.class);
        when(mockReceipt.isStatusOK()).thenReturn(true);

        // 2. connectionManager.execute가 호출되면 mockReceipt를 반환하도록 설정
        //    any()를 사용하여 어떤 Web3jCallable이든 동일하게 동작하도록 설정
        when(mockConnectionManager.execute(any(Web3jConnectionManager.Web3jCallable.class)))
                .thenAnswer(simulateExecution(mockReceipt)); // 성공 시 Receipt 반환

        // --- Execution ---
        CompletableFuture<Boolean> futureResult = contractHandler.addContract(input);

        // --- Verification ---
        assertTrue(futureResult.join(), "Contract should be added successfully");

        // connectionManager.execute가 정확히 1번 호출되었는지 검증 (선택적)
        verify(mockConnectionManager, times(1)).execute(any(Web3jConnectionManager.Web3jCallable.class));
    }

    @Test
    void testAddContract_Failure_ExceptionDuringExecution() throws Exception {
        // --- Input Data ---
        ContractInput input = new ContractInput(/* ... input data 설정 ... */);
        input.setId(BigInteger.TWO);

        // --- Mocking ---
        // connectionManager.execute가 호출될 때 RuntimeException을 던지도록 설정
        RuntimeException simulatedException = new RuntimeException("Blockchain connection failed");
        when(mockConnectionManager.execute(any(Web3jConnectionManager.Web3jCallable.class)))
                .thenAnswer(simulateExecutionWithError(simulatedException));

        // --- Execution ---
        CompletableFuture<Boolean> futureResult = contractHandler.addContract(input);

        // --- Verification ---
        assertFalse(futureResult.join(), "Should return false when an exception occurs");

        // connectionManager.execute가 호출되었는지 검증
        verify(mockConnectionManager, times(1)).execute(any(Web3jConnectionManager.Web3jCallable.class));
    }

    @Test
    void testGetContract() throws Exception {
        // --- Mocking Data ---
        BigInteger contractId = BigInteger.ONE;
        Tuple13<BigInteger, String, String, BigInteger, BigInteger, String, String, BigInteger, List<PaymentInfo>, String, Boolean, BigInteger, BigInteger> dummyTuple =
                new Tuple13<>(
                        contractId, "2025-01-01Z", "2025-12-31Z", BigInteger.valueOf(3000000), BigInteger.valueOf(5),
                        "112233445566", "998877665544", BigInteger.TEN,
                        List.of(new PaymentInfo(new Uint256(1), new Uint256(2100000), new Uint256(7))),
                        "123456789012", true, BigInteger.valueOf(3), BigInteger.valueOf(123)
                );

        // --- Mocking ---
        // connectionManager.execute가 호출되면 최종 결과인 dummyTuple을 반환하도록 설정
        when(mockConnectionManager.execute(any(Web3jConnectionManager.Web3jCallable.class)))
                .thenAnswer(simulateExecution(dummyTuple));

        // --- Execution ---
        ContractOutput result = contractHandler.getContract(contractId);

        // --- Verification ---
        assertNotNull(result);
        assertEquals(contractId, result.getId());
        assertEquals("2025-01-01Z", result.getStartDate());
        // ... (다른 필드 검증)

        // connectionManager.execute가 1번 호출되었는지 검증
        verify(mockConnectionManager, times(1)).execute(any(Web3jConnectionManager.Web3jCallable.class));
        // 중요: contractManager 자체의 메서드 호출을 직접 검증하는 대신,
        // connectionManager.execute의 호출과 그 결과를 검증합니다.
    }

    @Test
    void testGetContractOverview() throws Exception {
        // --- Mocking Data ---
        BigInteger contractId = BigInteger.ONE;
        Tuple3<BigInteger, String, String> dummyTuple =
                new Tuple3<>(contractId, "2025-01-01", "2025-12-31");

        // --- Mocking ---
        when(mockConnectionManager.execute(any(Web3jConnectionManager.Web3jCallable.class)))
                .thenAnswer(simulateExecution(dummyTuple));

        // --- Execution ---
        ContractOverviewOutput result = contractHandler.getContractOverview(contractId);

        // --- Verification ---
        assertNotNull(result);
        assertEquals(contractId, result.getId());
        assertEquals("2025-01-01", result.getStartDate());

        verify(mockConnectionManager, times(1)).execute(any(Web3jConnectionManager.Web3jCallable.class));
    }

    // ... (getPaymentInfoCount, getRentData 등 다른 읽기 테스트도 유사하게 수정) ...
    // 예시: getRentData
    @Test
    void testGetRentData() throws Exception {
        // --- Mocking Data ---
        BigInteger contractId = BigInteger.ONE;
        Tuple6<BigInteger, BigInteger, String, String, BigInteger, BigInteger> dummyTuple =
                new Tuple6<>(
                        BigInteger.valueOf(3000000), BigInteger.valueOf(5), "112233445566",
                        "665544332211", BigInteger.TEN, BigInteger.valueOf(3)
                );

        // --- Mocking ---
        when(mockConnectionManager.execute(any(Web3jConnectionManager.Web3jCallable.class)))
                .thenAnswer(simulateExecution(dummyTuple));

        // --- Execution ---
        ContractRentOutput result = contractHandler.getRentData(contractId);

        // --- Verification ---
        assertNotNull(result);
        assertEquals("112233445566", result.getRentAccountNo());

        verify(mockConnectionManager, times(1)).execute(any(Web3jConnectionManager.Web3jCallable.class));
    }


    @Test
    void testAddLiveAccount_Success() throws Exception {
        // --- Input ---
        BigInteger contractId = BigInteger.ONE;
        LiveAccountInput liveAccountInput = new LiveAccountInput("validAccountNo");

        // --- Mocking ---
        TransactionReceipt mockReceipt = mock(TransactionReceipt.class);
        when(mockReceipt.isStatusOK()).thenReturn(true);

        when(mockConnectionManager.execute(any(Web3jConnectionManager.Web3jCallable.class)))
                .thenAnswer(simulateExecution(mockReceipt));

        // --- Execution ---
        boolean result = contractHandler.addLiveAccount(contractId, liveAccountInput);

        // --- Verification ---
        assertTrue(result, "Adding live account should succeed");
        verify(mockConnectionManager, times(1)).execute(any(Web3jConnectionManager.Web3jCallable.class));
    }

    @Test
    void testAddLiveAccount_Failure_ReceiptNotOk() throws Exception {
        // --- Input ---
        BigInteger contractId = BigInteger.ONE;
        LiveAccountInput liveAccountInput = new LiveAccountInput("validAccountNo");

        // --- Mocking ---
        TransactionReceipt mockReceipt = mock(TransactionReceipt.class);
        when(mockReceipt.isStatusOK()).thenReturn(false); // 트랜잭션 실패 시뮬레이션

        when(mockConnectionManager.execute(any(Web3jConnectionManager.Web3jCallable.class)))
                .thenAnswer(simulateExecution(mockReceipt));

        // --- Execution ---
        boolean result = contractHandler.addLiveAccount(contractId, liveAccountInput);

        // --- Verification ---
        assertFalse(result, "Should return false when transaction receipt is not OK");
        verify(mockConnectionManager, times(1)).execute(any(Web3jConnectionManager.Web3jCallable.class));
    }

}