A-4: 에러 처리·경계 — 없음과 실패를 안전하게, 외부와는 깨끗하게

안녕하세요, 여러분의 코드 안목을 길러 드릴 홍순구 튜터입니다.

지난 시간엔 객체를 다뤘죠. 묻지 말고 시키고, 속을 감추고, 함부로 바뀌지 않게 지켰습니다. 그 마지막에 예약 명단을 불변으로 만들면서 제가 슬쩍 질문 하나를 남겼어요. "예약을 찾았는데 손님 명단이 비어 있거나, 아예 예약을 못 찾으면 뭘 돌려줘야 하지? 빈 명단? null? 예외?" 오늘이 바로 그 답을 푸는 시간입니다.

좋은 코드는 정상 흐름만 깔끔한 게 아닙니다. "없음"과 "실패"를 어떻게 다루느냐가 코드의 진짜 품질을 가릅니다. 그리고 우리 코드는 혼자 살지 않아요. 외부 라이브러리, 외부 API에 기대어 돌아갑니다. 그 외부와 만나는 경계를 어떻게 그으냐도 오늘의 주제입니다.

신입이 에러 처리와 경계에서 코드 리뷰 때 자주 듣는 두 마디가 있습니다.

• "여기 null 체크가 지옥이에요."
• "외부 API 바뀌니까 우리 코드가 다 터졌어요."

두 마디 모두 없음·실패·외부를 다루는 솜씨에 대한 지적입니다. 오늘은 에러 코드 대신 예외로 호출부를 깨끗하게 만들고, null 대신 빈 값과 Optional로 NPE 지옥을 끊고, 예외를 꼭 필요할 때만 쓰고, 외부 코드를 우리 경계로 감싸는 법을 봅니다. 그리고 이 과목이 늘 강조하는 한 가지, 각 원칙을 언제 깨야 하는지까지 함께요.

   A-3 좋은 객체            "객체에게 시키고, 속을 감추고, 안 바뀌게"
        │
        ▼
   A-4 에러 처리 · 경계      오늘 — "없음과 실패를 안전하게, 외부와 깨끗하게"
        │
        ├─ 에러 코드 대신 예외로         호출부를 깨끗하게
        ├─ null 대신 빈 값 · Optional    NPE 지옥 끊기
        ├─ 예외는 진짜 예외 상황에만      흐름 제어에 쓰지 않기
        └─ 외부는 감싸고 테스트로 고정    "API 바뀌어도 안 터지게"
        │
        ▼
   B-1 응집 · 결합 + SOLID   다음 — "클래스 사이의 구조"

💡 오늘 수업의 핵심 — "없음과 실패를 숨기지 말고, 타입과 예외로 또렷하게 말하라"

에러 코드와 null은 "문제가 생겼다"는 사실을 숫자나 빈 참조 뒤에 숨깁니다. 호출부가 그걸 일일이 외워서 검사해야 하죠. 오늘은 그 숨은 신호를 이름 있는 예외와 없음을 드러내는 타입(Optional)으로 끌어올려, 코드가 스스로 "여기서 이런 일이 생길 수 있다"고 말하게 만듭니다. 그리고 외부 코드는 우리 경계 안쪽에 가둬, 바깥이 흔들려도 우리 코드는 흔들리지 않게 합니다.

🎯 학습 목표

• 에러 코드 반환의 if 지옥을 예외로 풀고, null 대신 빈 컬렉션·특수 케이스 객체·Optional로 "없음"을 안전하게 표현한다.
• 예외를 흐름 제어가 아닌 진짜 예외 상황에만 쓰고, checked와 unchecked의 차이를 안다.
• 외부 라이브러리를 경계로 감싸고, 학습 테스트로 외부 동작을 우리 테스트에 고정한다.

Step 1: "에러 코드의 if 지옥 — 예외로 호출부를 깨끗하게"

코드 리뷰에서 이런 코드를 만나면 리뷰어가 멈칫합니다. "이 -1이 무슨 뜻이에요? -2는요?" 결과를 숫자로 돌려주는 코드의 흔한 풍경입니다.

포인트를 차감하는 서비스를 봅시다. 성공이면 0, 회원이 없으면 -1, 잔액이 부족하면 -2를 돌려줍니다.

public class ErrorCodePointService {

    public static final int SUCCESS = 0;
    public static final int MEMBER_NOT_FOUND = -1;
    public static final int INSUFFICIENT_POINT = -2;

    private final MemberRepository repository;

    public ErrorCodePointService(MemberRepository repository) {
        this.repository = repository;
    }

    public int withdraw(Long memberId, int amount) {
        Member member = repository.findById(memberId);
        if (member == null) {
            return MEMBER_NOT_FOUND;
        }
        if (member.getPoint() < amount) {
            return INSUFFICIENT_POINT;
        }
        member.deductPoint(amount);
        return SUCCESS;
    }
}

이 메서드를 쓰는 호출부는 어떻게 될까요? 돌려받은 숫자가 무슨 뜻인지 외워서, 하나하나 if로 분기해야 합니다.

public String pay(Long memberId, int amount) {
    int result = service.withdraw(memberId, amount);
    if (result == ErrorCodePointService.MEMBER_NOT_FOUND) {
        return "회원을 찾을 수 없습니다.";
    } else if (result == ErrorCodePointService.INSUFFICIENT_POINT) {
        return "포인트가 부족합니다.";
    } else {
        return "결제 완료";
    }
}

문제가 보이시나요? 정상 흐름(차감 성공)이 에러 분기 더미에 파묻혀 잘 안 보입니다. 진짜 하려던 일은 "포인트 차감 후 결제 완료"인데, 그 한 줄이 if-else 사이에 끼어 있어요. 게다가 호출부가 -1 검사를 깜빡하면, 컴파일러는 아무 말도 안 합니다. 그냥 잘못된 안내가 조용히 나갈 뿐이죠.

 에러 코드 방식의 흐름

   withdraw() ──▶ 0 / -1 / -2  (숫자만 돌아온다, 의미는 호출부가 외운다)
                     │
                     ▼
   호출부:  if (-1) ... else if (-2) ... else 정상
            └── 정상 흐름이 에러 검사에 파묻혀 안 보인다
            └── 검사를 깜빡해도 컴파일러는 모른다

이제 같은 일을 예외로 풀어 봅시다. 정상 처리는 그냥 끝내고(void), 잘못된 상황은 이름이 분명한 예외로 던집니다.

public class PointService {

    private final MemberRepository repository;

    public PointService(MemberRepository repository) {
        this.repository = repository;
    }

    public void withdraw(Long memberId, int amount) {
        Member member = repository.findById(memberId);
        if (member == null) {
            throw new MemberNotFoundException(memberId);
        }
        if (member.getPoint() < amount) {
            throw new InsufficientPointException(member.getPoint(), amount);
        }
        member.deductPoint(amount);
    }
}

-1 대신 MemberNotFoundException이라는 이름이 무엇이 잘못됐는지 스스로 말합니다. 예외 클래스는 맥락도 함께 담을 수 있어요.

public class InsufficientPointException extends RuntimeException {

    public InsufficientPointException(int current, int requested) {
        super("포인트가 부족합니다. 보유=" + current + ", 요청=" + requested);
    }
}

그러면 호출부는 어떻게 바뀔까요? 정상 흐름만 적으면 됩니다.

public String pay(Long memberId, int amount) {
    service.withdraw(memberId, amount);
    return "결제 완료";
}

withdraw가 정상이면 다음 줄로 가고, 문제가 생기면 예외가 위로 전달됩니다. 정상 시나리오가 한눈에 읽히고, 에러 처리는 그걸 책임질 위쪽에서 한 번에 모아 다룰 수 있습니다. 에러 코드를 외워 분기하던 if 더미가 통째로 사라졌어요.

⚠️ 언제 깨나 — 예외도 공짜가 아닙니다. 예외 객체는 만들어질 때 호출 스택을 기록하는데, 이게 생각보다 비용이 듭니다. 그래서 아주 흔하게 일어나는 정상적인 분기까지 예외로 만들면, 비용도 비용이고 흐름도 더 안 보여요. "회원이 없다"처럼 진짜 비정상인 상황에만 예외를 쓰고, 평범한 분기는 그냥 if로 두세요. 이 경계는 Step 4에서 더 깊이 봅니다. 또 예외 클래스를 지나치게 잘게 쪼개 수십 개로 불리는 것도 과합니다.

💡 한 줄 정리

에러 코드는 "문제가 생겼다"를 숫자에 숨겨 호출부에 검사를 떠넘기지만, 예외는 이름으로 무엇이 잘못됐는지 말하고 정상 흐름을 또렷하게 남긴다.

Step 2: "null을 주고받지 마라 — 빈 컬렉션과 특수 케이스 객체"

"여기 null 체크가 지옥이에요." 코드 리뷰 단골 멘트입니다. 그 지옥의 절반은, 메서드가 결과가 없을 때 null을 돌려주는 데서 시작됩니다.

등급으로 회원을 찾는 조회기를 봅시다. 해당하는 회원이 한 명도 없으면 null을 돌려줍니다.

public List<Member> findByGrade(String grade) {
    List<Member> found = new ArrayList<>();
    for (Member member : members) {
        if (member.grade().equals(grade)) {
            found.add(member);
        }
    }
    if (found.isEmpty()) {
        return null;  // 호출부가 검사를 잊으면 NPE 의 씨앗이 된다
    }
    return found;
}

이걸 쓰는 호출부는 순회하기 전에 매번 null인지 검사해야 합니다. 한 번이라도 깜빡하면, 바로 다음 줄에서 NullPointerException이 터져요.

 null 반환이 부르는 NPE 체인

   findByGrade("VIP")  ──▶  null   (결과 없음을 null 로 표현)
                              │
                              ▼
   for (Member m : result)         ← 검사 깜빡 → 여기서 NPE 폭발
   if (result != null) for (...)   ← 검사하면 호출부마다 null 가드가 번진다

해법은 단순합니다. "없음"을 null이 아니라 빈 컬렉션으로 표현하는 거예요.

public List<Member> findByGrade(String grade) {
    List<Member> found = new ArrayList<>();
    for (Member member : members) {
        if (member.grade().equals(grade)) {
            found.add(member);
        }
    }
    return found;  // 비어 있어도 null 이 아니라 빈 리스트
}

빈 리스트도 똑같이 for로 돌릴 수 있습니다. 0번 도는 것뿐이죠. 그래서 호출부는 null 검사 없이 그냥 순회하면 됩니다. "0건"은 컬렉션의 정상적인 상태이지, 오류 상황이 아니니까요.

값 하나를 돌려주는 경우엔 어떻게 할까요? 이때는 특수 케이스 객체가 잘 맞습니다. "아무 일도 하지 않는" 객체를 하나 만들어 null을 대신하는 방법이에요. 할인 정책을 예로 보죠. 먼저 정책 인터페이스와 기본 정책입니다.

public interface DiscountPolicy {

    int applyTo(int price);
}

public class BasicDiscountPolicy implements DiscountPolicy {

    private static final double DISCOUNT_RATE = 0.1;

    @Override
    public int applyTo(int price) {
        return (int) (price * (1 - DISCOUNT_RATE));
    }
}

이제 "할인 없음"도 null이 아니라 하나의 정책으로 봅니다. 아무것도 깎지 않는 정책을요.

public class NoDiscountPolicy implements DiscountPolicy {

    public static final NoDiscountPolicy NONE = new NoDiscountPolicy();

    @Override
    public int applyTo(int price) {
        return price;  // 원가 그대로 — 깎지 않는다
    }
}

정책을 찾아 주는 쪽은, 매칭되는 등급이 없을 때 null 대신 이 NONE을 돌려줍니다.

public DiscountPolicy findByGrade(String grade) {
    return policies.getOrDefault(grade, NoDiscountPolicy.NONE);
}

이제 호출부는 정책이 무엇이든 policy.applyTo(price)를 그냥 부르면 됩니다. "VIP면 깎고, 아니면 그대로"라는 if 분기가 필요 없어요. NoDiscountPolicy가 "그대로"를 알아서 처리하니까요. null 검사가 통째로 사라집니다.

그리고 한 가지 더. null을 돌려주지 않는 것만큼, null을 인자로 넘기지도 마세요. 메서드가 null을 받을 수 있다고 가정하는 순간, 그 메서드는 맨 앞에 방어 코드를 깔게 됩니다. 호출하는 쪽도 받는 쪽도 서로 null을 안 주고 안 받기로 약속하면, 그 방어 코드가 애초에 필요 없어집니다.

⚠️ 언제 깨나 — 빈 값이나 특수 케이스 객체로 "진짜 없음"을 뭉개 버리면 안 됩니다. "조회 결과가 0건"과 "조회 자체가 불가능한 잘못된 요청"은 의미가 다른데, 둘 다 빈 리스트로 돌려주면 호출부가 구분할 수 없어요. 후자라면 빈 컬렉션이 아니라 예외가 맞습니다. 특수 케이스 객체도 "아무것도 안 하는 게 올바른 기본 동작일 때"만 쓰세요. 억지로 만들면 버그를 조용히 삼킵니다.

💡 한 줄 정리

"없음"은 null이 아니라 빈 컬렉션이나 특수 케이스 객체로 표현하면, 호출부의 null 검사가 통째로 사라진다. 단, 진짜 없음을 빈 값으로 뭉개지는 말 것.

Step 3: "없음을 타입으로 — Optional"

지난 시간 마지막에 던진 질문 기억하시죠? "예약을 못 찾으면 뭘 돌려줄까?" 컬렉션이면 빈 리스트로 풀었습니다. 그런데 값 하나를 찾는데 없을 수도 있다면요? 여기에 자바 8부터 들어온 도구가 있습니다. Optional이에요.

먼저 문제 상황부터요. 이메일로 회원 한 명을 찾는 메서드가 없을 때 null을 돌려준다고 합시다. 시그니처만 봐서는 이게 null을 줄 수 있는지 아무도 모릅니다.

 Member findByEmail(String email)   ← 이 시그니처는 "없을 수 있음" 을 말하지 않는다
                                       호출부는 null 가능성을 모른 채 그냥 점을 찍는다 → NPE

Optional을 반환하면, 시그니처 자체가 "이 결과는 없을 수도 있다"고 강제로 알립니다.

public class MemberDirectory {

    private final List<Member> members;

    public MemberDirectory(List<Member> members) {
        this.members = members;
    }

    public Optional<Member> findByEmail(String email) {
        for (Member member : members) {
            if (member.email().equals(email)) {
                return Optional.of(member);
            }
        }
        return Optional.empty();
    }
}

Optional<Member>를 받은 호출부는 "그냥 점 찍기"를 할 수가 없습니다. 컴파일러가 "안에 값이 있는지 먼저 확인하라"고 요구하거든요. 덕분에 null 검사를 깜빡할 길이 막힙니다. 그리고 그 "없을 때 어떻게 할지"를 상황에 맞게 고를 수 있어요.

public class MemberLookup {

    private final MemberDirectory directory;

    public MemberLookup(MemberDirectory directory) {
        this.directory = directory;
    }

    /** 반드시 있어야 하는 경우 — 없으면 예외로 끝낸다. */
    public Member getOrThrow(String email) {
        return directory.findByEmail(email)
                .orElseThrow(() -> new IllegalArgumentException("회원이 없습니다. " + email));
    }

    /** 없어도 괜찮은 경우 — 기본 이름으로 대체한다. */
    public String nameOrGuest(String email) {
        return directory.findByEmail(email)
                .map(Member::name)
                .orElse("게스트");
    }

    /** 값이 있을 때만 변환한다 — 없으면 빈 Optional 그대로 흘려보낸다. */
    public Optional<String> emailUpperCase(String email) {
        return directory.findByEmail(email)
                .map(member -> member.email().toUpperCase());
    }
}

같은 "없을 수 있음"이라도 처리가 다릅니다. 반드시 있어야 하면 orElseThrow로 없을 때 예외를 던지고, 없어도 괜찮으면 orElse로 기본값을 주고, 있을 때만 변환하면 map으로 처리한 뒤 없으면 빈 Optional을 그대로 흘려보냅니다. null이었다면 이 셋을 전부 if로 직접 짰어야 했죠.

⚠️ 언제 깨나 — Optional은 "반환값"에만 쓰세요. 필드 타입이나 메서드 파라미터, 컬렉션의 원소 타입으로 Optional을 쓰는 건 남용입니다. 객체마다 Optional 껍데기가 하나씩 더 붙어 메모리와 복잡도만 늘고, 직렬화에서도 문제가 생겨요. 컬렉션이 비었으면 Optional<List>가 아니라 그냥 빈 리스트면 됩니다. 그리고 Optional을 받자마자 .get()으로 바로 까는 습관도 안티예요. 확인 없이 .get()을 부르면 비었을 때 예외가 나는데, 결국 null만큼 위험한 거니까요.

💡 한 줄 정리

Optional<T>은 "없을 수 있음"을 반환 타입으로 드러내 호출부가 그 가능성을 못 본 척할 수 없게 한다. 단 반환값 전용이고, 필드·파라미터·.get() 남발은 금물.

Step 4: "예외는 예외 상황에만 — 흐름 제어에 쓰지 마라"

Step 1에서 예외로 호출부를 깨끗하게 만들었죠. 그런데 예외를 너무 좋아하게 되면 정반대 함정에 빠집니다. 정상적인 흐름 제어에까지 예외를 쓰는 거예요. 코드 리뷰에서 이런 코드를 보면 리뷰어가 한 번 더 멈칫합니다. "이거 왜 try-catch로 루프를 돌아요?"

배열의 합을 구하는 코드를 봅시다. 배열 끝을 ArrayIndexOutOfBoundsException으로 감지해서 루프를 빠져나갑니다.

public int sum(int[] numbers) {
    int total = 0;
    int i = 0;
    try {
        while (true) {
            total += numbers[i];
            i++;
        }
    } catch (ArrayIndexOutOfBoundsException e) {
        // 배열 끝에 닿으면 예외로 루프 종료 — 정상 흐름을 예외로 다룬다
    }
    return total;
}

동작은 합니다. 하지만 "배열의 끝에 도달했다"는 건 지극히 정상적인 상황인데, 그걸 예외로 처리하고 있어요. 문제가 셋입니다. 첫째, 예외 객체를 만드느라 비용이 들고요. 둘째, 코드를 읽는 사람이 "이게 진짜 오류 처리인가, 아니면 정상 종료인가"를 구분할 수 없어요. 셋째, 의도가 코드에 안 드러납니다.

같은 일을 정상적인 경계 검사로 풀면 이렇게 됩니다.

public int sum(int[] numbers) {
    int total = 0;
    for (int i = 0; i < numbers.length; i++) {
        total += numbers[i];
    }
    return total;
}

i < numbers.length라는 조건이 "어디까지 도는지"를 그대로 말합니다. 예외는 진짜 예외 상황에만 남겨 두고요. 더 빠르고, 더 잘 읽힙니다.

그러면 진짜 예외는 어떻게 다룰까요? 여기서 checked 예외와 unchecked 예외의 구분이 나옵니다.

 checked 예외     컴파일러가 try-catch(또는 throws)를 강제한다
                  예: IOException — "복구를 고려해야 하는 상황" 을 의도
 unchecked 예외   강제하지 않는다 (RuntimeException 계열)
                  예: IllegalArgumentException — 프로그래밍 오류·복구 곤란

저수준에서 올라오는 예외를 그대로 위로 흘리면, 호출부가 외부 사정을 다 알아야 합니다. 그래서 경계에서 우리 도메인의 예외로 바꿔 감싸는 게 좋아요. 설정값을 정수로 읽는 작은 예를 봅시다.

public int loadTimeout(String raw) {
    try {
        return Integer.parseInt(raw);
    } catch (NumberFormatException cause) {
        throw new ConfigParseException("타임아웃 설정이 숫자가 아닙니다: " + raw, cause);
    }
}

Integer.parseInt가 던지는 저수준 기술 예외(NumberFormatException)를, 우리 도메인 언어인 ConfigParseException으로 바꿔 던집니다. 호출부는 "설정 파싱이 실패했다"는 우리 언어만 알면 되고, 저수준 예외의 종류는 몰라도 됩니다. 이때 원래 예외를 cause로 함께 넘기는 걸 잊지 마세요. 나중에 원인을 추적할 수 있도록요. 그리고 우리 ConfigParseException은 RuntimeException을 상속한 unchecked 예외라, 호출부에 try-catch를 강제하지 않습니다.

⚠️ 언제 깨나 — "예외를 0개로 만드는 것"이 목표가 아닙니다. 파일이 없거나, 네트워크가 끊기거나, 잔액이 부족한 것처럼 진짜 비정상인 상황은 예외가 정답이에요. 오늘 말한 건 "정상적인 흐름 제어에 예외를 쓰지 말라"는 거지, "예외 자체를 피하라"가 아닙니다. 예외를 옳게 쓰는 것과, 예외를 흐름 제어 도구로 남용하는 것을 가르세요.

💡 한 줄 정리

예외는 진짜 비정상에만 쓴다. 정상적인 종료·분기를 예외로 처리하면 비싸고 안 읽힌다. 저수준 예외는 경계에서 우리 도메인 예외로 감싸 호출부를 보호한다.

Step 5: "외부 코드와 우리 코드 사이 — 경계를 감싸라"

이제 두 번째 단골 지적입니다. "외부 API 바뀌니까 우리 코드가 다 터졌어요." 왜 이런 일이 생길까요?

외부 라이브러리는 우리가 못 고칩니다. 그 라이브러리의 API가 어색하든 말든, 다음 버전에서 갑자기 바뀌든 말든, 우리는 그쪽 사정에 끌려다닐 수밖에 없어요. 문제는 그 어색한 API가 우리 코드 곳곳에 스며들었을 때입니다. 외부가 한 번 바뀌면, 그걸 직접 쓰던 우리 코드가 사방에서 깨집니다.

예를 들어 봅시다. 외부 날씨 SDK가 하나 있는데, API가 어색합니다. 결과를 타입 없는 Map으로 돌려주고, 키 이름도 "temp", "hum" 같은 줄임말이에요.

public class AcmeWeatherSdk {

    public Map<String, Object> fetch(String cityCode) {
        Map<String, Object> result = new HashMap<>();
        if ("SEOUL".equals(cityCode)) {
            result.put("temp", 21);
            result.put("hum", 55);
        } else {
            result.put("temp", 18);
            result.put("hum", 40);
        }
        return result;
    }
}

이 SDK를 서비스 곳곳에서 직접 쓰면 어떻게 될까요? raw Map과 "temp", "hum" 같은 문자열 키가 우리 코드 한복판까지 그대로 들어옵니다.

public class DirectWeatherService {

    private final AcmeWeatherSdk sdk = new AcmeWeatherSdk();

    public String describe(String cityCode) {
        Map<String, Object> raw = sdk.fetch(cityCode);
        int temp = (int) raw.get("temp");
        int hum = (int) raw.get("hum");
        return temp + "도, 습도 " + hum + "%";
    }
}

SDK가 다음 버전에서 키 이름을 "temperature"로 바꾸거나 반환 타입을 손보면? 이 Map을 파싱하던 모든 곳이 한꺼번에 깨집니다. 우리가 그 SDK를 직접 부르는 곳이 많을수록 피해가 커지죠.

해법은 외부와 우리 사이에 경계를 긋는 겁니다. 우리가 원하는 모습으로 인터페이스를 정의하고, 외부 SDK는 그 뒤에 숨기는 거예요. 먼저 우리 도메인의 깨끗한 타입과 인터페이스를 만듭니다.

public record Weather(int temperature, int humidity) {
}

public interface WeatherClient {

    Weather getWeather(String city);
}

그리고 외부 SDK를 이 인터페이스 뒤에 가두는 어댑터를 둡니다. SDK의 어색한 Map을 다루는 코드가 오직 이 한 클래스 안에만 있게요.

public class AcmeWeatherAdapter implements WeatherClient {

    private final AcmeWeatherSdk sdk;

    public AcmeWeatherAdapter(AcmeWeatherSdk sdk) {
        this.sdk = sdk;
    }

    @Override
    public Weather getWeather(String city) {
        Map<String, Object> raw = sdk.fetch(city);
        int temperature = (int) raw.get("temp");
        int humidity = (int) raw.get("hum");
        return new Weather(temperature, humidity);
    }
}

이제 우리 서비스는 SDK의 존재를 전혀 모릅니다. 깨끗한 WeatherClient 인터페이스에만 기대거든요.

public class WeatherService {

    private final WeatherClient client;

    public WeatherService(WeatherClient client) {
        this.client = client;
    }

    public String describe(String city) {
        Weather weather = client.getWeather(city);
        return weather.temperature() + "도, 습도 " + weather.humidity() + "%";
    }
}

 경계를 긋기 전 (Before)               경계를 긋고 난 뒤 (After)

   WeatherService                       WeatherService
        │ 직접 호출                          │ 우리 인터페이스에만 의존
        ▼                                   ▼
   AcmeWeatherSdk (raw Map)             WeatherClient (우리 타입 Weather)
                                            ▲
   SDK 바뀌면 서비스가 깨진다               │ 구현
                                        AcmeWeatherAdapter ── 여기서만 SDK 를 안다
                                            │
                                        AcmeWeatherSdk ── 바뀌어도 어댑터 한 곳만 고친다

SDK가 바뀌어도 고칠 곳은 AcmeWeatherAdapter 하나뿐입니다. 우리 서비스 코드는 한 줄도 안 건드려요. 게다가 테스트할 때는 진짜 SDK 대신 가짜 WeatherClient를 끼워 넣어, 네트워크 없이도 서비스 동작을 확인할 수 있습니다. 외부에 묶여 있던 코드가 풀려난 거죠.

이렇게 "안 맞는 외부 인터페이스를 우리가 원하는 인터페이스에 끼워 맞추는" 방식에는 사실 이름이 있습니다. 어댑터예요. 이건 검증된 설계 패턴 중 하나인데, 패턴 자체는 디자인 패턴을 다루는 C-2에서 본격적으로 만납니다. 오늘은 "경계를 감싼다"는 원리만 익혀 두면 충분해요.

⚠️ 언제 깨나 — 모든 외부 코드를 다 감쌀 필요는 없습니다. 자바 표준 라이브러리의 List, String, Map처럼 안정적이고 바뀔 일이 거의 없는 표준 API까지 일일이 감싸면, 쓸데없는 껍데기만 늘고 코드가 오히려 복잡해져요. 경계로 감싸는 건 "어색하거나, 바뀔 위험이 있거나, 우리가 통제할 수 없는" 외부에 집중하세요. 모든 걸 감싸는 건 또 다른 과잉입니다.

💡 한 줄 정리

외부 라이브러리는 우리 인터페이스 뒤에 감싸 한 곳(어댑터)에 가둔다. 그러면 외부가 바뀌어도 그 한 곳만 고치면 되고, 테스트에서 가짜로 갈아 끼우기도 쉽다.

Step 6: "외부가 어떻게 동작하는지 우리 테스트로 고정 — 학습 테스트"

경계로 외부를 감쌌습니다. 그런데 그 외부가 정확히 어떻게 동작하는지는 어떻게 알까요? 보통은 문서를 읽고 "아 이렇게 동작하겠지" 하고 추측합니다. 문제는, 문서가 모든 함정을 다 알려주지 않는다는 거예요. 그리고 라이브러리가 업그레이드되면 동작이 슬쩍 바뀌기도 합니다.

여기에 좋은 장치가 있습니다. 학습 테스트(learning test)예요. 외부 라이브러리의 동작을 추측하는 대신, 우리 테스트로 직접 확인해서 고정해 두는 겁니다. 이 과목은 테스트가 코드를 지키는 안전망 자체를 학습 주제로 다루니, 오늘은 테스트 코드를 직접 들여다봅니다.

자바 표준 라이브러리의 BigDecimal을 예로 봅시다. 돈 계산에 자주 쓰는데, 동작에 놀라운 함정이 몇 개 있어요. 문서로 읽으면 흘려보내기 쉽지만, 테스트로 확인해 두면 절대 까먹지 않습니다.

class BigDecimalLearningTest {

    @DisplayName("equals 는 스케일까지 본다 — 1.0 과 1.00 은 같지 않다")
    @Test
    void equalsConsidersScale() {
        assertFalse(new BigDecimal("1.0").equals(new BigDecimal("1.00")));
    }

    @DisplayName("compareTo 는 값만 본다 — 1.0 과 1.00 은 0(같음)이다")
    @Test
    void compareToIgnoresScale() {
        assertEquals(0, new BigDecimal("1.0").compareTo(new BigDecimal("1.00")));
    }
}

놀랍지 않나요? new BigDecimal("1.0")과 new BigDecimal("1.00")은 값으로는 똑같은데, equals로 비교하면 다르다고 나옵니다. equals가 소수점 자릿수(스케일)까지 따지거든요. 반면 compareTo는 값만 보니까 0(같음)이 나와요. 이걸 모르고 BigDecimal을 equals로 비교하면, "분명히 같은 값인데 왜 다르다고 하지?" 하고 한참 헤매게 됩니다. 테스트로 확인해 두면 이 함정을 코드가 영원히 기억해 줍니다.

나눗셈에도 함정이 있어요.

    @DisplayName("무한소수 나눗셈은 RoundingMode 없이 하면 ArithmeticException 이 난다")
    @Test
    void divideWithoutRoundingThrows() {
        BigDecimal one = new BigDecimal("1");
        BigDecimal three = new BigDecimal("3");
        assertThrows(ArithmeticException.class, () -> one.divide(three));
    }

    @DisplayName("RoundingMode 를 주면 무한소수 나눗셈도 안전하게 동작한다")
    @Test
    void divideWithRoundingWorks() {
        BigDecimal one = new BigDecimal("1");
        BigDecimal three = new BigDecimal("3");
        assertEquals(new BigDecimal("0.33"),
                one.divide(three, 2, RoundingMode.HALF_UP));
    }
}

1 ÷ 3처럼 딱 떨어지지 않는 나눗셈을 그냥 하면 ArithmeticException이 터집니다. 반올림 방식(RoundingMode)을 알려 줘야 안전하게 동작해요. 이런 건 문서를 안 읽으면 운영 중에 처음 만나게 되는 함정인데, 학습 테스트로 미리 확인해 두는 거죠.

List.of로 만든 리스트의 동작도 고정해 둘 수 있습니다.

class ImmutableListLearningTest {

    @DisplayName("List.of 로 만든 리스트에 add 하면 UnsupportedOperationException 이 난다")
    @Test
    void addToImmutableListThrows() {
        List<String> list = List.of("a", "b");
        assertThrows(UnsupportedOperationException.class, () -> list.add("c"));
    }
}

List.of가 만든 리스트는 수정이 막혀 있어서, add를 하면 예외가 납니다. 지난 시간 불변 객체에서 방어적 복사를 할 때 살짝 봤던 동작이죠. 추측하지 말고 테스트로 확인해 두면 확실합니다.

학습 테스트의 진짜 가치는 시간이 지나서 나옵니다. 나중에 이 라이브러리를 새 버전으로 올렸는데 동작이 바뀌었다면, 이 테스트가 가장 먼저 빨개져서 "어? 외부 동작이 달라졌어!"라고 알려 줍니다. 우리 코드가 운영 중에 조용히 깨지기 전에 말이죠. 경계로 외부를 감싸고(Step 5), 그 외부의 동작을 학습 테스트로 고정하면(Step 6), 외부에 기대면서도 외부에 휘둘리지 않는 코드가 됩니다.

⚠️ 언제 깨나 — 학습 테스트도 한번 쓰면 계속 유지해야 하는 비용입니다. 외부 라이브러리의 모든 메서드를 다 테스트하려 들면, 결국 외부 코드를 우리가 떠안는 꼴이 돼요. 우리가 실제로 의존하는 동작, 그리고 BigDecimal.equals처럼 헷갈려서 사고 나기 쉬운 동작에만 집중하세요. 학습 테스트는 "전부 검증"이 아니라 "위험한 곳만 핀으로 고정"하는 도구입니다.

💡 한 줄 정리

학습 테스트는 외부 라이브러리의 동작을 추측 대신 우리 테스트로 확인해 고정한다. 라이브러리가 업그레이드돼 동작이 바뀌면 이 테스트가 먼저 알려 준다. 단, 위험한 곳만 골라서.

마무리

오늘은 코드의 "없음"과 "실패", 그리고 외부와의 "경계"를 다뤘습니다. A 카테고리의 마지막 모듈이었어요. 이름·함수·객체에 이어, 이제 에러 처리까지 코드 레벨의 기본기를 한 바퀴 다 돌았습니다.

오늘 배운 핵심 세 가지

• 💡 에러 코드와 null은 문제를 숨긴다. 에러 코드 대신 이름 있는 예외로, null 대신 빈 컬렉션·특수 케이스 객체·Optional로 "없음"과 "실패"를 또렷하게 드러내자. 그래야 호출부가 깨끗해지고 NPE 지옥이 끊긴다.
• 💡 예외는 꼭 필요할 때만. 예외로 호출부를 깨끗하게 만들되, 정상적인 흐름 제어에까지 예외를 쓰지는 말자. 저수준 예외는 경계에서 우리 도메인 예외로 감싼다.
• 💡 외부는 감싸고 고정한다. 외부 라이브러리는 우리 인터페이스 뒤에 감춰 변화를 한 곳에 가두고(경계), 그 동작을 학습 테스트로 고정해 업그레이드 회귀를 잡는다. 단, 다 감싸지도 다 테스트하지도 말 것.

다음 시간 예고

지금까지 A 카테고리에서는 한 줄, 함수 하나, 객체 하나, 에러 처리까지 "코드 레벨"을 다듬었습니다. 이제 시야를 한 단계 넓힐 차례예요. 다음 시간부터는 B 카테고리, 클래스 사이의 구조로 갑니다.

다음 시간(B-1)엔 좋은 설계의 두 축인 응집도와 결합도를 먼저 잡고, 거기서 SRP·OCP·LSP라는 설계 원칙으로 들어갑니다. "이 클래스, 바꿀 이유가 다섯 개나 되네요" 같은 지적을 그때 풀어 봐요. 오늘 배운 에러 처리·경계는 그 설계 원칙들의 든든한 바탕이 됩니다. 경계를 인터페이스로 감쌌던 오늘의 감각이, 다음 시간 "추상화에 의존하라"로 자연스럽게 이어질 거예요.

과제

오늘 배운 원리를 직접 손으로 고쳐 보며 익히는 과제입니다. 지저분한 Before를 깨끗한 After로 바꾸는 게 핵심이에요.

[기초] null 반환을 안전한 형태로 고치기

아래는 장바구니에서 특정 카테고리의 상품을 찾아 돌려주는 메서드입니다. 결과가 없으면 null을 돌려줘서, 호출부가 순회 전에 매번 null을 검사해야 합니다.

public List<Product> findByCategory(String category) {
    List<Product> found = new ArrayList<>();
    for (Product product : products) {
        if (product.category().equals(category)) {
            found.add(product);
        }
    }
    if (found.isEmpty()) {
        return null;
    }
    return found;
}

이 메서드를 호출부가 null 검사 없이 바로 순회할 수 있도록 고쳐 보세요. 그리고 "회원 한 명을 이메일로 찾되 없을 수 있는" 메서드도 하나 만들어, 반환 타입을 Optional로 표현해 보세요.

[응용] 에러 코드 반환을 예외로 리팩토링

아래는 주문을 검증하는 메서드입니다. 성공이면 0, 재고가 없으면 -1, 금액이 0 이하면 -2를 돌려줍니다. 호출부는 이 숫자를 if로 분기하고 있어요.

public int validateOrder(Long productId, int quantity, int price) {
    if (!stock.has(productId, quantity)) {
        return -1;
    }
    if (price <= 0) {
        return -2;
    }
    return 0;
}

이 메서드를 예외 기반으로 리팩토링하세요. 상황에 맞는 이름의 예외 클래스(OutOfStockException, InvalidPriceException 등)를 만들고, 호출부가 정상 흐름만 적도록 바꿔 보세요. 예외에는 무엇이 잘못됐는지 알 수 있는 맥락(요청 수량, 잘못된 금액 등)을 담아 보세요.

[심화] 외부 SDK를 경계로 감싸기

아래는 외부 환율 SDK를 서비스에서 직접 쓰는 코드입니다. SDK가 raw Map을 돌려주고, 그 파싱이 서비스 안에 노출돼 있어요.

public class DirectExchangeService {

    private final AcmeExchangeSdk sdk = new AcmeExchangeSdk();

    public int toKrw(String currency, int amount) {
        Map<String, Object> raw = sdk.fetch(currency);
        double rate = (double) raw.get("rate");
        return (int) (amount * rate);
    }
}

이 코드를 경계로 감싸 보세요. 우리 도메인 인터페이스(ExchangeClient)와 깨끗한 결과 타입을 정의하고, SDK를 다루는 코드는 어댑터 한 곳에만 가두세요. 서비스가 SDK 대신 우리 인터페이스에만 의존하도록 바꾸고, 테스트에서 가짜 ExchangeClient를 끼울 수 있게 만들면 성공입니다.

생각해볼 주제

규칙을 외우는 게 아니라 "언제 어떻게 쓸지"를 판단하는 게 이 과목의 목표입니다. 정답이 하나가 아닌 주제들이에요. 혼자 고민해도 좋고, 동료와 논쟁해도 좋습니다.

1. "없음"을 표현하는 세 가지 방법 — 예외 vs 빈 값 vs Optional, 언제 무엇을?

오늘 "없음"과 "실패"를 표현하는 방법을 여럿 봤습니다. 빈 컬렉션, 특수 케이스 객체, Optional, 그리고 예외까지요. 그런데 같은 "회원을 못 찾았다"도 상황에 따라 답이 달라집니다. 어떤 때는 예외가 맞고, 어떤 때는 Optional이 맞고, 어떤 때는 빈 값이 맞아요. 각각을 언제 써야 할지, 그 판단 기준을 정리해 보세요.

2. Optional을 어디까지 써야 할까?

Optional은 "반환값에만 쓰라"고 배웠습니다. 필드나 파라미터, 컬렉션 원소에 쓰는 건 남용이라고요. 그런데 왜 그럴까요? 만약 모든 곳에 Optional을 쓰면 어떤 문제가 생기는지, 반대로 Optional을 너무 아껴 써서 null이 다시 새어 나오면 어떤 문제가 생기는지, 양쪽의 균형을 고민해 보세요.

3. 모든 외부 라이브러리를 다 감싸야 할까?

경계를 감싸면 외부 변화로부터 우리 코드를 보호할 수 있습니다. 그렇다면 안전을 위해 모든 외부 라이브러리를 다 감싸면 더 좋은 코드일까요? 감싸는 데도 비용이 듭니다. 껍데기 클래스가 늘고, 코드를 따라가기 위해 거쳐야 할 단계가 많아져요. 무엇은 감싸고 무엇은 그냥 써도 되는지, 그 경계를 어떻게 그을지 생각해 보세요.