D-2: 레거시 개선·코드 리뷰·아키텍처 맛보기 — 규칙을 외우는 게 주니어, 언제 깰지 아는 게 미들

홍순구입니다. 드디어 이 과목의 마지막 시간이에요. 길게 달려왔습니다. 지난 시간엔 코드 스멜을 알아채고, 테스트로 안전망을 친 뒤 작은 걸음으로 리팩토링하는 한 바퀴를 돌았죠. 그런데 그때 우리가 고친 건 '내가 방금 짠 작은 예제'였어요. 오늘은 그 연습장을 덮고 현실로 나갑니다.

현실의 코드 리뷰에서 가장 자주 듣는 세 마디가 있어요. "레거시라 무서워서 손을 못 대요." "리뷰에서 뭘 봐야 할지 모르겠어요." 그리고 가장 깊은 한마디, "규칙은 아는데, 언제 깨야 할지를 모르겠어요." 오늘 이 셋을 차례로 풉니다. 테스트도 없고 의존성이 거미줄처럼 엉킨 레거시에 손댈 틈을 내는 법, 코드 리뷰에서 무엇을 보고 어떻게 말하는지, 그리고 코드를 담는 큰 그림인 아키텍처의 첫 스케치까지요.

그리고 마지막엔, 이 과목 내내 깔아 온 척추를 정면으로 세웁니다. 클린 코드는 도그마가 아니다. 규칙을 외워 모든 코드에 똑같이 들이대는 건 주니어예요. 그 규칙이 왜 생겼는지 알아 언제 적용하고 언제 깰지 판단하는 게 미들이고요. 좋은 코드를 보는 안목의 마지막 한 조각, 오늘 채웁니다.

 오늘의 여정 — 원리에서 현실로, 그리고 안목으로

 ① 레거시 다루기    테스트 없는 코드에 이음새를 내고, 멈추지 않고 교체한다
 ② 코드 리뷰        무엇을 먼저 보고, 어떻게 건설적으로 말하나
 ③ 아키텍처 맛보기   계층형·의존성 규칙·헥사고날 — 큰 그림의 첫 스케치
 ④ 도그마 경계      "규칙을 외우는 게 주니어, 언제 깰지 아는 게 미들"

💡 오늘 수업의 핵심 — "좋은 코드의 안목은 규칙 암기가 아니라, 맥락을 읽고 언제 적용하고 언제 깰지 판단하는 힘이다"

🎯 학습 목표

• 테스트 없는 레거시에 이음새(seam)를 내 의존성을 끊고, 안전하게 손댈 틈을 만든다.
• 코드 리뷰에서 무엇을 먼저 보고 어떻게 건설적으로 피드백하는지 안다.
• 계층형·헥사고날 아키텍처의 큰 그림을 잡고, 클린 코드가 도그마가 아님을 판단의 언어로 설명한다.

Step 1: "테스트 없는 코드가 레거시다"

먼저 '레거시'가 뭔지부터 짚어요. 보통은 '오래된 코드', '옛날 기술로 짠 코드'를 떠올리죠. 그런데 이 분야의 고전 『레거시 코드 활용 전략』을 쓴 마이클 페더스는 아주 도발적으로 정의합니다. "테스트 없는 코드가 레거시 코드다." 나이도, 언어도, 기술 스택도 상관없어요. 방금 짠 코드라도 테스트가 없으면 레거시고, 10년 된 코드라도 테스트가 단단하면 레거시가 아니라는 겁니다.

왜 이렇게 정의할까요? 코드를 고칠 때 가장 무서운 건 '고쳤더니 엉뚱한 데가 터지는' 상황이에요. 테스트가 있으면 고친 뒤 돌려 보고 "동작이 안 바뀌었다"를 바로 확인할 수 있죠. 테스트가 없으면 그 확인을 할 길이 없어요. 그래서 손을 못 대고, 못 대니 더 썩고, 더 썩으니 더 무서워지는 악순환에 빠집니다. 이게 "레거시라 무서워서 손을 못 대요"의 정체예요.

지난 시간에 우리는 이 두려움의 해법을 하나 배웠죠. 특성화 테스트로 현재 동작을 그물처럼 떠서 고정한 뒤 손대는 법이요. 그런데 현실의 레거시는 한 겹 더 고약합니다. 테스트를 짜려고 마음먹어도, 코드가 외부 세계에 너무 단단히 묶여 있어 테스트조차 짤 수 없는 경우가 많아요. 여기 그런 한 토막이 있습니다.

// refactoring.legacy.OrderConfirmationBefore
public class OrderConfirmationBefore {

    public String confirm(String orderId, int amount) {
        EmailSender sender = new EmailSender();
        LocalDate today = LocalDate.now();
        String message = "주문 " + orderId + " (" + amount + "원) 확정 — " + today;
        sender.send(message);
        return message;
    }
}

겉보기엔 멀쩡해요. 주문 확정 메시지를 만들어 메일로 보내죠. 그런데 "이 메서드가 올바른 메시지를 만드나"를 테스트로 확인하려고 보면, 두 군데가 발목을 잡습니다.

첫째, new EmailSender(). 메서드 안에서 의존성을 직접 만들어 버려요. 그래서 테스트를 한 번 돌리기만 해도 진짜 메일이 나갑니다. 가짜로 바꿔 끼울 틈이 없어요. 둘째, LocalDate.now(). 실행하는 '오늘'에 묶여요. 같은 입력이라도 날마다 다른 메시지가 나오니, "2026-06-24가 나와야 한다"고 단언할 수가 없습니다. 테스트가 들어갈 입구 자체가 막혀 있는 거예요.

⚠️ 언제 깨나: 모든 레거시를 다 테스트로 덮으려 들지 마세요. 하루 돌고 버릴 일회성 스크립트, 곧 통째로 걷어낼 모듈에 안전망을 까는 건 과한 투자예요. 페더스의 조언도 "전부"가 아니라 "지금 손댈 코드 주변부터"입니다. 무서운 건 코드 전체가 아니라, 오늘 내가 고쳐야 하는 그 한 부분이거든요.

💡 한 줄 정리

레거시는 나이가 아니라 테스트의 유무로 정해진다. 그리고 진짜 무서운 레거시는 의존성이 외부에 단단히 묶여 테스트조차 짤 수 없는 코드다.

Step 2: "이음새를 찾아 의존성을 끊는다"

그럼 테스트조차 못 짜는 Step 1의 코드를, 어떻게 테스트 가능하게 바꿀까요? 여기서 페더스의 또 다른 핵심 개념이 등장합니다. 이음새(seam)예요. 이음새란 "코드를 직접 고치지 않고도 동작을 바꿀 수 있는 지점"입니다. 옷의 솔기를 뜯어 다른 천을 덧대듯, 그 지점에서 구현을 갈아 끼우는 거죠.

Step 1의 코드는 이음새가 두 군데 막혀 있었어요. 의존성을 직접 만드는 new EmailSender()와, 시각에 묶이는 LocalDate.now(). 이 둘을 바깥에서 갈아 끼울 수 있게 열어 주면 됩니다. 먼저, 발송이라는 행위를 약속(인터페이스)으로 추상화해요.

// refactoring.legacy.Notifier
public interface Notifier {

    void send(String message);
}

이게 이음새예요. 코어 로직은 "메시지를 보낸다"만 알면 되고, 그게 이메일인지 SMS인지 테스트용 가짜인지는 몰라도 됩니다. 이제 이 약속에 기대도록 코드를 고쳐요.

// refactoring.legacy.OrderConfirmation
public class OrderConfirmation {

    private final Notifier notifier;

    public OrderConfirmation(Notifier notifier) {
        this.notifier = notifier;
    }

    public String confirm(String orderId, int amount, LocalDate today) {
        String message = "주문 " + orderId + " (" + amount + "원) 확정 — " + today;
        notifier.send(message);
        return message;
    }
}

두 이음새가 열렸어요. Notifier를 생성자로 주입받으니(객체 이음새), 테스트에선 진짜 발송 대신 가짜를 끼울 수 있고요. 날짜를 파라미터로 받으니(값 이음새), 고정된 날짜를 넘겨 결과를 단언할 수 있습니다. 눈여겨볼 건, 비즈니스 로직(메시지 형식·언제 보내나)은 한 글자도 안 바뀌었다는 거예요. 바꾼 건 오직 '의존성을 어디서 받느냐'뿐입니다.

이 "구체 클래스에 직접 매달리지 말고 약속에 기대라", 어디서 봤죠? 맞아요, B-2의 의존성 역전 원칙(DIP)입니다. 그때는 설계 원칙으로 배웠는데, 오늘은 그게 '레거시를 테스트 가능하게 만드는 실전 도구'로 돌아온 거예요. 이제 진짜로 테스트를 짤 수 있게 됐는지 볼까요. 발송을 기록만 하는 가짜 하나를 만들고요.

// 테스트용 가짜 Notifier — 진짜로 보내는 대신 기록만 한다
class RecordingNotifier implements Notifier {

    private final List<String> sent = new ArrayList<>();

    @Override
    public void send(String message) {
        sent.add(message);
    }
    // sentCount(), lastMessage() 로 무엇을 몇 번 보냈는지 확인한다
}

이 가짜를 코어에 끼우면, 진짜 메일을 한 통도 보내지 않고 "무엇을, 몇 번 보냈는지"를 단언으로 확인할 수 있어요. Step 1에선 꿈도 못 꾸던 일이죠.

@Test
void confirmSendsFormattedMessageThroughSeam() {
    RecordingNotifier notifier = new RecordingNotifier();
    OrderConfirmation confirmation = new OrderConfirmation(notifier);

    String message = confirmation.confirm("A100", 10000, LocalDate.of(2026, 6, 24));

    assertEquals("주문 A100 (10000원) 확정 — 2026-06-24", message);
    assertEquals(1, notifier.sentCount());
}

이음새를 연 덕분에, 고정된 날짜를 넘겨 메시지를 정확히 단언하고, 가짜가 발송을 한 번 받았는지까지 확인했어요. 안전망을 칠 수 있게 된 겁니다. 이제 이 코드는 마음 놓고 리팩토링할 수 있어요.

⚠️ 언제 깨나: 이음새를 무한정 내면, 모든 의존성이 인터페이스와 주입으로 뒤덮여 코드가 간접 참조의 미로가 됩니다. 정말 갈아 끼울 일이 없는 의존성까지 다 뽑아 추상화하는 건 과잉이에요. 이음새는 "테스트를 위해, 혹은 진짜 교체 가능성을 위해" 필요한 곳에만 냅니다. 처음부터 모든 걸 뽑지 말고, 손댈 곳 주변부터 하나씩.

💡 한 줄 정리

이음새는 코드를 고치지 않고 동작을 갈아 끼우는 지점이다. 하드코딩된 의존성을 주입·파라미터로 열면 테스트가 들어올 입구가 생기고, 그제야 안전망을 칠 수 있다.

Step 3: "Strangler Fig — 멈추지 않고 교체한다"

이음새로 한 메서드를 구해 냈어요. 그런데 더 큰 질문이 남죠. 시스템 전체가 낡았다면요? "이 낡은 모듈을 새것으로 갈아엎고 싶다"는 마음이 들 때, 가장 위험한 선택이 빅뱅 재작성입니다. 운영을 멈추고 전부 새로 짜서 한 번에 교체하는 거죠. 지난 시간에도 봤지만, 재작성은 도박이에요. 새로 짜는 동안 비즈니스는 멈추고, 옛 코드에만 있던 수많은 예외 처리를 빠뜨리기 십상이거든요.

그래서 멈추지 않고 점진적으로 교체하는 전략이 있습니다. Strangler Fig(교살 무화과) 패턴이에요. 이름이 좀 섬뜩하죠? 열대의 무화과나무는 다른 나무를 타고 올라가 천천히 감싸고, 끝내 그 숙주 나무를 대체하며 자랍니다. 소프트웨어도 똑같이 해요. 낡은 시스템 곁에 새 구현을 조금씩 키우고, 트래픽을 한 갈래씩 옮기다가, 낡은 코드는 일거리가 말라 자연히 걷어내는 겁니다.

핵심 장치는 공통 약속(인터페이스)과, 그 뒤에서 트래픽을 나눠 주는 창구예요. 배송비 계산기를 예로 들게요. 낡은 계산기와 새 계산기가 같은 약속을 구현합니다.

// refactoring.strangler.ShippingFee
public interface ShippingFee {

    int calculate(Parcel parcel);
}

그리고 창구 역할을 하는 라우터가, 어느 구현으로 보낼지 결정해요.

// refactoring.strangler.ShippingFeeRouter
public class ShippingFeeRouter implements ShippingFee {

    private final ShippingFee legacy;
    private final ShippingFee modern;

    public ShippingFeeRouter(ShippingFee legacy, ShippingFee modern) {
        this.legacy = legacy;
        this.modern = modern;
    }

    @Override
    public int calculate(Parcel parcel) {
        if (parcel.domestic()) {
            return modern.calculate(parcel);
        }
        return legacy.calculate(parcel);
    }
}

                 ┌─────────────────────┐
   배송비 요청 ─▶│  ShippingFeeRouter  │
                 └──────────┬──────────┘
                            │
                            ├─ 국내?  ─▶ NewShippingFee     (이전 완료)
                            └─ 국제?  ─▶ LegacyShippingFee  (아직 레거시)

   트래픽을 한 갈래씩 새 구현으로 옮기다, 낡은 코드는 일거리가 말라 걷어낸다

호출하는 쪽은 여전히 ShippingFee 하나만 봅니다. 그 뒤에서 라우터가 결정하죠. 국내 배송은 새 구현으로 이미 옮겼고, 국제 배송은 아직 낡은 구현이 처리해요. 국제까지 검증이 끝나면 라우터의 그 한 줄만 새 구현으로 바꾸면 됩니다.

여기서 절대 빠뜨리면 안 되는 게 있어요. 트래픽을 새 구현으로 옮기기 전에, 새 구현이 낡은 구현과 똑같은 결과를 낸다는 걸 먼저 증명해야 합니다. 어떻게요? 지난 시간의 특성화 테스트로요. 같은 입력에 두 구현이 같은 값을 내는지 확인한 뒤에야 안전하게 라우팅합니다.

@Test
void domesticIsMigratedSafely() {
    Parcel parcel = new Parcel(1500, true);

    assertEquals(5000, legacy.calculate(parcel));
    assertEquals(5000, modern.calculate(parcel));
    assertEquals(5000, router.calculate(parcel));
}

낡은 구현도 5000, 새 구현도 5000, 라우터도 5000. 결과가 같으니 국내 배송을 새 구현으로 옮겨도 동작이 바뀌지 않아요. 이 '같음'을 확인하는 순간이, 트래픽을 옮겨도 좋다는 안전 신호입니다. 참고로 이 라우터는 C-2에서 본 퍼사드와 한 핏줄이에요. 복잡한 내부(어느 구현을 쓸지)를 단순한 창구 하나로 가린다는 점에서요.

⚠️ 언제 깨나: 작은 코드를 Strangler Fig로 교체하는 건 과합니다. 라우터를 두고, 옛 구현과 새 구현을 한동안 나란히 굴리는 '이중 운영'에는 그 자체로 복잡함과 비용이 따라요. 이 전략의 진가는 멈출 수 없는 큰 시스템, 한 번에 갈아엎기엔 위험이 너무 큰 레거시에서 나옵니다. 작은 모듈이라면 그냥 이음새 내고 테스트 친 뒤 한 번에 바꾸는 게 빠르고 깔끔해요.

💡 한 줄 정리

Strangler Fig는 공통 약속 뒤에서 트래픽을 한 갈래씩 새 구현으로 옮겨, 낡은 시스템을 멈추지 않고 교체한다. 단, 옮기기 전에 새 구현이 같은 결과를 낸다는 증명이 먼저다.

Step 4: "코드 리뷰 — 무엇을 보나"

레거시를 다루는 손을 익혔으니, 이번엔 시선을 바꿔 봐요. 남의 코드를 들여다보는 일, 코드 리뷰예요. 처음 리뷰어가 되면 다들 막막해해요. "리뷰에서 뭘 봐야 할지 모르겠어요"가 그래서 나오죠. 화면 가득한 변경 코드를 앞에 두고 무엇부터 봐야 할지 모르면, 결국 눈에 띄는 사소한 것(들여쓰기, 변수명 취향)만 잔뜩 지적하게 됩니다. 정작 중요한 걸 놓치고요.

리뷰에는 우선순위가 있어요. 위에서부터 봅니다.

 코드 리뷰에서 무엇을 먼저 보나 — 위가 더 중요하다

 ① 정확성    이 코드가 진짜 의도대로 동작하나? 빠뜨린 경우(엣지)는?
 ② 설계      책임이 잘 나뉘었나? 결합도는? 이 변경이 옆을 깨뜨리나?
 ③ 가독성    6개월 뒤 남이 읽고 이해할 수 있나? 이름은 의도를 드러내나?
 ④ 스타일    들여쓰기·줄바꿈·따옴표 — 가장 덜 중요하고, 대개 도구가 처리

정확성이 맨 위예요. 아무리 깨끗해도 틀린 코드는 의미가 없으니까요. 그다음이 설계, 그다음이 가독성, 맨 아래가 스타일입니다. 초보 리뷰어가 가장 많이 하는 실수가 이 순서를 거꾸로 밟는 거예요. 스타일부터 잡느라 본질을 놓치는 거죠.

그런데 ②와 ③, 그러니까 설계와 가독성을 볼 때 무엇을 보면 되냐고요? 사실 우리는 이미 그 체크리스트를 다 배웠어요. 이 과목 전체가 코드 리뷰의 렌즈였던 겁니다.

보세요. A부터 D까지, 우리가 배운 모든 게 리뷰어의 눈이 됩니다. 리뷰란 결국 "내가 아는 좋은 코드의 기준을, 남의 코드에 비춰 보는 일"이에요. 그래서 이 과목을 끝까지 들은 여러분은, 이미 꽤 좋은 리뷰어의 렌즈를 갖춘 셈입니다.

⚠️ 언제 깨나: 체크리스트를 기계적으로 전부 들이대면, 사소한 지적이 폭탄처럼 쏟아져 작성자가 질려 버립니다. 맥락을 보세요. 마감이 코앞인 핫픽스라면 정확성만 보고 나머진 다음으로 미룰 수 있고, 주니어의 첫 PR이라면 한 번에 다섯 개만 골라 짚는 게 낫습니다. 리뷰는 흠집 내기 대회가 아니라, 함께 코드를 낫게 만드는 협업이에요.

💡 한 줄 정리

코드 리뷰는 정확성 → 설계 → 가독성 → 스타일 순으로 본다. 그리고 설계·가독성의 체크리스트는, 이 과목에서 배운 A·B·C·D 전부다.

Step 5: "건설적 피드백, 그리고 취향은 도구에 맡긴다"

무엇을 보는지 알았으니, 이제 어떻게 말하나입니다. 사실 이게 더 어려워요. 같은 지적도 어떻게 전하느냐에 따라 약이 되기도 하고 독이 되기도 하거든요. 코드 리뷰는 사람과 사람 사이의 일이라, 기술만큼이나 말투가 중요합니다. 같은 내용을 담은 두 코멘트를 비교해 볼게요.

 ❌ 나쁜 코멘트                          ✅ 좋은 코멘트

 "이거 왜 이렇게 짰어요?"              "이 변수명이 의도를 잘 안 드러내는 것
 "여기 완전 틀렸는데요."                같아요. activeMembers는 어떨까요?"
 "이 정도는 기본 아닌가요?"            "여기 입력이 비었을 때 NPE가 날 수 있을
                                       것 같은데, 한번 확인해 주실래요?"

왼쪽과 오른쪽의 차이가 보이세요? 몇 가지 원칙으로 정리됩니다.

첫째, 사람이 아니라 코드를 향해 말해요. "당신은 왜"가 아니라 "이 코드는"으로 시작합니다. 둘째, 명령보다 질문과 제안으로요. "고치세요"가 아니라 "이건 어떨까요?"가 상대의 방어를 풉니다. 셋째, 근거를 함께 줍니다. "틀렸어요"가 아니라 "비었을 때 NPE가 날 수 있어서요"처럼 왜를 붙여요. 넷째, 좋은 점도 짚어 주고요. 리뷰가 지적만 가득하면 받는 사람이 위축됩니다.

그런데 리뷰에서 가장 소모적인 싸움이 뭔지 아세요? 들여쓰기를 탭으로 할지 스페이스로 할지, 세미콜론을 붙일지 말지, 따옴표를 작은걸로 할지 큰걸로 할지 — 이런 취향 논쟁이에요. 정답이 없는데 사람마다 고집이 있어서, 여기에 리뷰 시간을 다 쓰면 정작 정확성과 설계는 못 봅니다.

해법은 간단해요. 이런 취향은 사람이 싸우지 말고 도구에 맡깁니다. A-1에서 자동 포매터를 잠깐 봤죠. 코드 스타일을 자동으로 통일해 주는 도구요. 거기에 더해 린터(linter)라는 도구가 있어요. 코드에서 흔한 실수 패턴(쓰지 않는 변수, 위험한 비교 등)을 자동으로 잡아 줍니다. 포매터와 린터를 팀의 자동 검사에 걸어 두면, 스타일과 단순 실수는 사람이 보기 전에 도구가 처리해요. 그럼 사람은 도구가 못 보는 것, 즉 로직과 설계에만 집중할 수 있습니다. 이게 리뷰를 건강하게 유지하는 핵심이에요.

⚠️ 언제 깨나: 정중한 질문형이 늘 옳은 건 아니에요. 한밤중 장애가 터져 핫픽스를 다투는 순간엔, 부드러운 돌려 말하기가 오히려 사치입니다. "여기 이 조건이 반대예요, 지금 바로 고쳐야 해요"처럼 짧고 명확한 게 나아요. 또 모든 지적을 칭찬으로 감싸려다 핵심 문제가 흐려지면 안 됩니다. 부드러움은 수단이지, 명확함을 희생하면서까지 지킬 목적이 아니에요.

💡 한 줄 정리

건설적 피드백은 사람이 아니라 코드를 향해, 질문과 근거로 말한다. 그리고 취향 논쟁(스타일)은 사람이 싸우지 말고 린터·포매터에 맡겨, 리뷰는 로직과 설계에 집중한다.

Step 6: "아키텍처 맛보기 ① 계층형과 의존성 규칙"

지금까지 우리는 코드 한 줄(A), 클래스 하나(B), 패턴 하나(C), 리팩토링 한 걸음(D)을 봤어요. 이제 한 발 더 물러나, 코드를 담는 큰 그릇을 봅니다. 아키텍처예요. 파일이 수백 개로 불어나면 "이 코드는 어디에 둬야 하지?"가 매일의 고민이 되거든요. 그 답의 첫 스케치를 잡아 봅시다. (큰 그림을 본격적으로 짓는 건 후속 spring-boot의 몫이고, 오늘은 개념의 첫 맛만 봐요.)

가장 기본이 되는 게 계층형 아키텍처입니다. 코드를 관심사에 따라 위에서 아래로 층층이 나눠요.

   ┌────────────────┐
   │  Presentation  │ ── 화면·API, 사용자와 만나는 곳
   └───────┬────────┘
           │ 의존
           ▼
   ┌────────────────┐
   │  Business      │ ── 핵심 규칙, 진짜 알맹이(도메인)
   └───────┬────────┘
           │ 의존
           ▼
   ┌────────────────┐
   │  Data          │ ── DB·파일, 데이터를 담는 곳
   └────────────────┘

화면을 그리는 층, 비즈니스 규칙을 담는 층, 데이터를 저장하는 층. 각 층이 한 가지 관심사만 맡으니, B-1에서 배운 단일 책임이 클래스를 넘어 시스템 규모로 커진 모습이에요.

그런데 여기 함정이 있어요. 화살표를 보면 의존성이 위에서 아래로, Business가 Data를 향해 흐르죠. 이러면 핵심 알맹이인 Business가 구체적인 데이터베이스에 매달리게 됩니다. DB를 다른 걸로 바꾸면 도메인 규칙까지 흔들려요. 진짜 중요한 알맹이가, 갈아 끼울 수 있어야 할 바깥(DB)에 끌려다니는 거죠.

그래서 나온 게 의존성 규칙이에요. "의존성은 안쪽(핵심 도메인)을 향해야 한다"는 원칙입니다. 어떻게요? B-2의 의존성 역전(DIP)으로 화살표를 뒤집습니다. 도메인이 "나는 이런 저장소가 필요해"라는 약속(인터페이스)을 스스로 정의하고, 바깥의 Data 층이 그 약속을 구현하게 하는 거예요. 그럼 화살표가 Data → Business 방향으로 뒤집혀, 도메인이 더는 DB에 매달리지 않습니다. 이 "의존성을 안쪽으로 뒤집는다"가 다음 Step에서 볼 헥사고날 아키텍처의 씨앗이에요.

⚠️ 언제 깨나: 작은 앱에 계층을 과하게 나누면, 기능 하나 고치려고 네 개의 파일을 열어 같은 데이터를 네 번 변환해야 하는 일이 벌어집니다. 계층은 규모가 정당화할 때 가치가 있어요. 화면-비즈니스-데이터가 뒤엉켜도 괜찮을 만큼 작은 도구라면, 굳이 삼층으로 가르지 않는 게 맞습니다.

💡 한 줄 정리

계층형 아키텍처는 코드를 관심사별 층으로 나눈다. 핵심은 의존성 규칙 — 의존성이 핵심 도메인을 향하도록, DIP로 화살표를 뒤집어 도메인을 바깥에서 떼어 낸다.

Step 7: "아키텍처 맛보기 ② 헥사고날(포트 & 어댑터)"

Step 6의 "의존성을 안쪽으로 뒤집는다"를 끝까지 밀고 가면 도착하는 그림이 있어요. 헥사고날 아키텍처, 다른 이름으로 포트 & 어댑터(Ports & Adapters)입니다. 핵심 아이디어는 이래요. 코어(도메인)를 한가운데 두고, 바깥 세상과의 모든 소통을 '포트'라는 약속으로만 한다. 그럼 코어는 바깥이 어떤 기술인지 전혀 모른 채, 자기 규칙에만 집중할 수 있어요.

용어 둘만 짚을게요. 포트(Port)는 코어가 바깥에 요구하는 약속, 즉 인터페이스예요. 코어 안에 삽니다. 어댑터(Adapter)는 그 포트를 실제 기술로 구현한 부품이고, 바깥에 살아요. C-2에서 본 어댑터 패턴이, 여기선 아키텍처 전체의 뼈대로 커진 겁니다. 결제를 예로 코어부터 볼게요.

// refactoring.hexagonal.PaymentPort — 포트(코어 안의 약속)
public interface PaymentPort {

    boolean pay(int amount);
}

// refactoring.hexagonal.OrderService — 코어(도메인)
public class OrderService {

    private final PaymentPort paymentPort;

    public OrderService(PaymentPort paymentPort) {
        this.paymentPort = paymentPort;
    }

    public String placeOrder(int amount) {
        if (amount <= 0) {
            return "거부: 금액이 올바르지 않습니다";
        }
        boolean paid = paymentPort.pay(amount);
        return paid ? "주문 완료" : "주문 실패: 결제가 거절되었습니다";
    }
}

OrderService는 결제가 카드인지, 계좌이체인지, 어떤 회사 서비스인지 전혀 모릅니다. 오직 PaymentPort라는 약속에만 기대요. 그래서 결제 수단이 무엇으로 바뀌든 이 코어 코드는 손대지 않습니다. 바깥은 이 포트를 구현한 어댑터로 채워요.

   바깥 세상              경계             코어(도메인)
   (어댑터)              (포트)

   HTTP 요청 ─▶ [입력 어댑터] ─▶  OrderService
                                      │
                                      ▼  PaymentPort (약속)
                                 [출력 어댑터] ─▶ 결제 게이트웨이
                                  · FakePaymentAdapter  (테스트)
                                  · 실제 결제 어댑터       (운영)

포트가 같은 모양이라, 테스트할 땐 가짜 어댑터를, 운영할 땐 진짜 어댑터를 꽂으면 됩니다. 코어는 그 차이를 몰라요. 그래서 외부 결제 서비스 없이도 주문 로직을 통째로 검증할 수 있습니다.

@Test
void orderCompletesWhenAdapterApproves() {
    FakePaymentAdapter adapter = new FakePaymentAdapter(true);
    OrderService service = new OrderService(adapter);

    String result = service.placeOrder(10000);

    assertEquals("주문 완료", result);
    assertEquals(10000, adapter.paidAmount());
}

가짜 어댑터를 끼우니, 진짜 결제 한 번 없이 "주문이 완료되고, 코어가 만 원을 결제하려 했다"까지 확인됐어요. 눈치채셨겠지만, 이건 B-2의 DIP와 C-2의 어댑터 패턴을 아키텍처 규모로 키운 것에 다름 아니에요. 작은 원리를 큰 구조로 넓힌 거죠. 코어에 어떤 어댑터를 꽂아 줄지를 자동으로 관리해 주는 장치가 바로 후속 spring-boot의 의존성 주입 컨테이너인데, 그 본격적인 적용은 그 과목에서 만나요. 오늘은 "코어를 포트로 감싸 바깥에서 떼어 낸다"는 그림 하나만 가져가면 충분합니다.

⚠️ 언제 깨나: 작은 CRUD 앱(데이터를 넣고 빼기만 하는)에 헥사고날을 씌우면, 포트와 어댑터와 변환 계층이 잔뜩 늘어 오히려 코드가 불어납니다. 도메인이 얇은데 격식만 갖추는 꼴이에요. 이 구조의 진가는 도메인 규칙이 두텁고, 외부 연동(결제·메시지·외부 API)이 많아 갈아 끼울 일이 잦은 시스템에서 나옵니다. 규모와 복잡함이 정당화할 때 꺼내는 카드예요.

💡 한 줄 정리

헥사고날(포트 & 어댑터)은 코어를 포트(약속)로 감싸 바깥 기술에서 떼어 낸다. DIP와 어댑터 패턴을 아키텍처로 키운 것 — 가짜·진짜 어댑터를 갈아 끼워 코어를 외부 없이 검증한다.

Step 8: "클린 코드는 도그마가 아니다 — 언제 깰지가 미들의 실력"

자, 마지막 Step이에요. 이 과목 내내 각 원칙과 패턴 끝에 ⚠️ 언제 깨나를 붙여 온 거, 눈치채셨죠? 그게 우연이 아니었어요. 오늘 그 모든 경고를 하나로 모아, 이 과목의 진짜 결론을 세웁니다. "규칙은 아는데 언제 깨야 할지를 모르겠어요." 이 마지막 질문에 답하는 시간이에요.

가장 먼저 경계할 건 카고컬트(cargo cult)입니다. 원리를 모르고 형식만 흉내 내는 걸 뜻해요. "함수는 무조건 20줄 이하", "주석은 무조건 나쁨", "패턴을 많이 쓸수록 좋은 코드" 같은 맹목적 규칙 추종이 그거예요. 규칙을 외워 모든 코드에 똑같이 들이대면, 오히려 코드를 망칩니다. 지난 시간 마지막에 못 박았죠. 깨끗함은 수단이지 목적이 아니다. 규칙은 좋은 코드라는 목적지로 가는 길일 뿐, 규칙 자체가 목적이 되는 순간 길을 잃어요.

대표적인 논쟁 하나를 볼게요. 성능 대 가독성입니다. 우리는 함수를 잘게 쪼개면 읽기 좋다고 배웠어요. 그런데 함수 호출에도 아주 작은 비용이 들어서, 초당 수백만 번 도는 극한의 경로에선 그 비용이 쌓여 느려질 수 있어요. 실제로 현장엔 "클린 코드의 작은 함수 권장이 성능을 해친다"는 강한 비판이 있습니다. 같은 계산을 두 모습으로 짜 볼게요.

// refactoring.tradeoff.ReadableSum — 가독성 우선
public long sumOfEvenSquares(int[] numbers) {
    long total = 0;
    for (int n : numbers) {
        if (isEven(n)) {
            total += square(n);
        }
    }
    return total;
}
// isEven(n), square(n) 같은 작은 도우미로 의도가 또렷하다

// refactoring.tradeoff.InlinedSum — 성능 핫패스
public long sumOfEvenSquares(int[] numbers) {
    long total = 0;
    for (int n : numbers) {
        if ((n & 1) == 0) {
            total += (long) n * n;
        }
    }
    return total;
}

두 코드의 결과는 한 치도 다르지 않아요. 오른쪽은 도우미를 인라인으로 풀고 비트 연산을 써서, 극한 경로라면 조금 더 빠를 수 있습니다. 그런데 여기서 함정이 두 개예요. 하나, 대부분의 코드는 그런 극한 경로가 아니에요. 일 년에 몇 번 도는 코드를 비트 연산으로 비틀어 봤자, 읽기 어려워진 대가만 치를 뿐 아무도 그 속도 차이를 못 느낍니다. 둘, 측정도 안 하고 "이게 빠를 것 같아서" 가독성을 버리는 건 그냥 미신이에요. 진짜 핫패스인지는 재 보고 정해야 합니다. (얼마나 빠른지를 깊이 따지는 건 다른 과목의 몫이고, 우리에겐 "언제 이 트레이드오프를 꺼내나"라는 판단이 핵심이에요.)

그래서 결론은 이래요. 기본값은 가독성이다. 그러다 측정으로 진짜 병목이 확인된 그 좁은 구간에서만, 의식적으로 가독성을 양보한다. 이렇게 "언제 깨는지"를 아는 게 핵심입니다.

이 모든 걸 하나로 묶는 게 맥락이에요. 하루 쓰고 버릴 프로토타입과 10년 갈 코드, 혼자 짜는 스크립트와 50명이 고칠 시스템 — 같은 규칙도 맥락에 따라 답이 달라집니다. 프로토타입에 헥사고날을 씌우는 건 과잉이고, 결제 시스템에 테스트를 생략하는 건 자살골이에요. 좋은 개발자는 규칙을 맥락에 비춰 적용합니다.

 주니어 → 미들, 진짜 분기점

 주니어   규칙을 외운다 → 모든 코드에 똑같이 들이댄다 → "함수는 무조건 짧게!"
 미들     규칙의 이유를 안다 → 맥락을 읽는다 → "여기선 짧게, 여기선 펼치는 게 맞다"

그러니까 이 과목에서 배운 모든 것 — 이름(A), 함수, 객체, 에러 처리, SOLID(B), 디자인 패턴(C), 리팩토링(D) — 은 법전이 아니라 연장통이에요. 망치가 좋다고 모든 걸 망치로 두드리지 않듯, 각 도구를 언제 꺼내고 언제 내려놓을지 아는 게 안목입니다. 그게 규칙을 외운 주니어와, 맥락을 읽는 미들을 가르는 진짜 분기점이고요.

⚠️ 언제 깨나: 가장 중요한 경고를 마지막에 둘게요. "도그마가 아니다"를 "아무렇게나 짜도 된다"로 오해하면 절대 안 됩니다. 규칙을 깨려면 먼저 그 규칙을 깊이 알아야 해요. 왜 생겼고 무엇을 지키려는지 아는 사람이 "이 맥락에선 안 맞는다"고 판단해 깨는 것과, 몰라서 그냥 못 지키는 것은 하늘과 땅 차이예요. 앞엣것은 미들의 판단이고, 뒤엣것은 그냥 못 짜는 겁니다. 깰 자격은, 규칙을 통달한 사람에게만 주어져요.

💡 한 줄 정리

클린 코드는 법전이 아니라 연장통이다. 카고컬트(규칙 맹신)를 경계하고, 맥락에 비춰 적용한다. 규칙을 외우는 게 주니어, 이유를 알아 언제 깰지 판단하는 게 미들이다. 단, 깨려면 먼저 통달해야 한다.

마무리

긴 여정의 마지막 페이지예요. 오늘은 원리를 현실로 가져왔습니다. 테스트 없는 레거시에 이음새를 내 손댈 틈을 만들고, 멈추지 않고 교체하는 Strangler Fig를 봤어요. 코드 리뷰에서 무엇을 먼저 보고 어떻게 건설적으로 말하는지, 코드를 담는 큰 그릇인 계층형과 헥사고날 아키텍처의 첫 스케치도 잡았고요. 그리고 무엇보다, 이 과목의 진짜 결론을 세웠습니다.

오늘 배운 핵심 세 가지

💡 하나 — 레거시엔 이음새부터. 테스트 없는 코드가 레거시다. 하드코딩된 의존성을 주입·파라미터로 열어 이음새를 내면, 테스트가 들어올 입구가 생긴다. 그 안전망 위에서야 큰 시스템도 Strangler Fig로 멈추지 않고 교체할 수 있다.

💡 둘 — 리뷰는 우선순위와 말투, 취향은 도구에. 정확성 → 설계 → 가독성 → 스타일 순으로 본다. 사람이 아니라 코드를 향해, 질문과 근거로 말한다. 스타일 논쟁은 린터·포매터에 맡겨, 사람은 로직과 설계에 집중한다.

💡 셋 — 규칙은 연장통이지 법전이 아니다. 아키텍처도 클린 코드도 맥락에 비춰 꺼낸다. 카고컬트를 경계하고, 언제 적용하고 언제 깰지 판단한다. 규칙을 외우는 게 주니어, 이유를 알아 깰 때를 아는 게 미들 — 단, 깨려면 먼저 통달해야 한다.

다음 무대로 — 그리고 이 과목을 마치며

이 모듈이 마지막이라, 예고할 '다음 시간'은 없어요. 대신 여러분이 오늘 채운 안목이 어디로 이어지는지를 짚고 인사할게요.

이 과목에서 우리는 원리와 패턴 그 자체를 익혔습니다. 그 원리들이 진짜 프레임워크라는 실전 무대에서 어떻게 살아 움직이는지는 후속 spring-boot에서 만나요. 거기서 보면 깜짝 놀랄 거예요. 의존성 주입 컨테이너가 바로 B-2의 DIP를 실현한 것이거든요. 서비스와 저장소로 계층을 나누는 건 B-1의 단일 책임이고, 관점 지향(AOP)이라 부르는 기능은 C-2의 프록시 패턴이에요. 모듈러 모놀리스와 Strangler Fig는 오늘 배운 그 전략의 실전 적용이고요. 오늘 원리로 잡아 둔 그림들이, 그 과목에서 거대한 실제 코드베이스 위에 그대로 펼쳐집니다.

그러니 이 과목은 끝이 아니라 출발선이에요. 좋은 이름과 작은 함수로 읽기 좋은 코드를 쓰고, 응집도·결합도와 SOLID로 구조를 설계하고, 검증된 패턴을 그 한계까지 알아 적재적소에 씁니다. 코드 스멜은 안전망 위에서 리팩토링하고, 무엇보다 규칙을 맹목적으로 따르지 않고 맥락에 맞게 언제 깰지 판단하는 눈을 길렀어요. 주니어에서 미들로 가는 그 분기점에, 여러분은 이제 서 있습니다. 긴 시간 함께해 줘서 고마웠어요. 좋은 코드를 보는 여러분의 안목이, 앞으로 짤 모든 코드에서 빛나길 바랍니다.

과제

오늘은 이 과목의 마지막 과제예요. 레거시에 손대고, 코어를 격리하고, 무엇보다 '판단'하는 연습입니다.

[기초] 이음새 내기

아래는 테스트를 짤 수 없는 레거시 한 토막입니다. 인사말을 만들어 콘솔에 직접 출력하는데, 두 군데가 이음새를 막고 있어요.

public class GreetingBefore {

    public String greet(String name) {
        ConsolePrinter printer = new ConsolePrinter();   // 직접 생성
        LocalTime now = LocalTime.now();                 // 실행 시각에 묶임
        String hour = now.getHour() < 12 ? "좋은 아침" : "안녕하세요";
        String message = hour + ", " + name + "님!";
        printer.print(message);
        return message;
    }
}

이 코드의 막힌 이음새 두 개를 열어, 테스트 가능한 Greeting으로 바꾸세요. 출력 행위를 약속(인터페이스)으로 추상화해 주입받고, 시각을 파라미터로 받으면 됩니다. 그런 다음, 발송을 기록만 하는 가짜를 끼우고 고정된 시각을 넘겨, "오전 11시에 'jaehoon'으로 인사하면 '좋은 아침, jaehoon님!'이 나온다"를 단언하는 테스트를 한 개 작성하세요. 비즈니스 로직(인사말 형식)은 바꾸지 않는 게 핵심입니다.

[응용] 포트 & 어댑터로 코어 격리하기

주문을 받으면 재고를 확인하고 알림을 보내는 도메인이 있다고 합시다. 그런데 알림 보내는 부분이 외부 푸시 서비스에 직접 묶여 있어, 코어를 테스트하려면 진짜 푸시가 나갑니다.

알림을 보내는 행위를 포트(예: AlertPort)로 정의하고, 코어(OrderService 같은)가 그 포트에만 의존하도록 바꾸세요. 그런 다음 가짜 어댑터를 만들어, 외부 푸시 서비스 없이 "주문이 성공하면 알림이 한 번 발송된다"와 "재고가 없으면 알림이 발송되지 않는다"를 테스트로 검증하세요. 코어가 '알림이 어떻게 가는지'를 전혀 몰라야 한다는 점에 집중합니다.

[심화] 리뷰 코멘트 가려내기 + 도그마 판단

판단하는 눈을 기르는 과제예요. 코드를 짜기보다 분별하는 연습입니다.

(가) 아래 다섯 개의 리뷰 코멘트가 있습니다. 각각이 건설적인지, 아니면 무례하거나 도그마적인지 가려내고, 문제 있는 코멘트는 건설적으로 다시 쓰세요.

① "이거 왜 이렇게 짰어요? 기본도 안 됐네요."
② "여기 입력이 비면 NPE가 날 것 같은데, 확인해 주실래요?"
③ "함수가 25줄이에요. 클린 코드는 20줄 이하랬으니 무조건 쪼개세요."
④ "이 변수명이 의도를 잘 안 드러내는 것 같아요. activeCount는 어떨까요? (nit)"
⑤ "이 패턴은 제가 싫어해서요. 그냥 빼세요."

(나) 한 동료가 "우리 프로젝트의 모든 도메인에 헥사고날 아키텍처를 적용하자"고 제안합니다. 그 프로젝트는 사내에서 쓰는 작은 데이터 조회 도구예요. 여러분이라면 이 제안에 어떻게 답하겠어요? "좋다/나쁘다"가 아니라, 무엇을 근거로 판단할지를 써 보세요. (이 과목에서 배운 "언제 깨나"를 떠올리며.)

생각해볼 주제

1. "테스트 없는 코드가 레거시다"라는 정의가 우리에게 시사하는 것

마이클 페더스는 레거시를 나이가 아니라 테스트의 유무로 정의했어요. 이 정의를 따르면, 오늘 아침에 짠 코드도 테스트가 없으면 레거시고, 10년 된 코드도 테스트가 단단하면 레거시가 아닙니다. 왜 그는 굳이 이렇게 도발적으로 정의했을까요? 이 정의가 '레거시는 남의 문제'라는 흔한 생각을 어떻게 바꾸나요? 그리고 만약 이 정의를 받아들인다면, 우리가 새 코드를 짜는 방식은 어떻게 달라져야 할까요?

2. "클린 코드가 성능을 해친다"는 비판을 어떻게 받아들일까

현장에는 클린 코드의 작은 함수 권장이 성능을 떨어뜨린다는 강한 비판이 있어요. 함수 호출에 비용이 들고, 잘게 쪼갤수록 그 비용이 쌓인다는 거죠. 이 비판은 옳을까요, 틀릴까요? 어떤 코드에서는 옳고 어떤 코드에서는 과장일까요? "측정 없이 빠를 것 같아서 가독성을 버리는 것"과 "측정으로 병목을 확인하고 가독성을 양보하는 것"의 차이는 무엇인가요? 둘을 가르는 기준을 여러분의 말로 세워 보세요.

3. "규칙을 깨려면 먼저 규칙을 통달해야 한다"는 말의 무게

이 과목은 "클린 코드는 도그마가 아니다", "언제 깰지 아는 게 미들"이라고 결론지었어요. 그런데 똑같이 "이건 상황이 달라서 규칙을 안 지켜도 돼요"라는 말을, 갓 입사한 주니어가 할 때와 10년 차 미들이 할 때, 그 무게가 전혀 다릅니다. 무엇이 그 차이를 만드나요? "규칙을 몰라서 못 지키는 것"과 "알면서 의식적으로 깨는 것"을 어떻게 구별할 수 있을까요? 그리고 아직 통달하지 못한 주니어는, 그 사이 기간을 어떤 태도로 보내야 할까요?