software-design

코드 품질 개선 기법 29편: 고르디우스 변수 (새 탭에서 열림)

코드 내 데이터의 의존성이 복잡하게 얽혀 로직을 파악하기 어려운 상태를 '고르디우스의 매듭'에 비유하며, 이를 해결하기 위한 설계 기법을 제시합니다. 복잡한 조건문과 데이터 가공이 반복되는 경우, 최종 로직에 필요한 이상적인 중간 데이터 구조를 먼저 정의하고 이를 생성하는 방식으로 코드를 재구성하면 가독성과 유지보수성을 동시에 높일 수 있습니다. **데이터 의존성 과다로 인한 가독성 저하** * 원격과 로컬 데이터를 동기화할 때 추가, 업데이트, 삭제 대상을 구분하는 과정에서 데이터 의존성이 복잡해지기 쉽습니다. * 단순히 ID 목록을 비교해 차집합을 구하는 방식은 실제 데이터를 처리할 때 다시 원본 리스트에서 객체를 찾아야 하거나, 맵(Map)에서 데이터를 꺼낼 때 발생할 수 없는 예외 상황을 처리해야 하는 번거로움을 유발합니다. * 이로 인해 비즈니스 로직의 핵심인 '동기화 액션'보다 데이터를 분류하고 가공하는 '준비 과정'이 코드의 흐름을 방해하게 됩니다. **이상적인 중간 데이터 설계를 통한 역설계** * 복잡한 매듭을 풀기 위해서는 최종적으로 필요한 데이터의 형태를 먼저 상상하고, 그 지점부터 함수의 구성을 역으로 설계하는 것이 효과적입니다. * 이번 사례에서는 추가(`created`), 업데이트(`updated`), 삭제(`deleted`)될 대상들을 명확히 분리한 세 가지 리스트를 중간 데이터로 정의했습니다. * 로컬과 원격의 모든 ID 집합을 기준으로 `Pair<RemoteData?, LocalData?>` 형태의 시퀀스를 만들고, 이를 상태에 따라 분류하는 것이 핵심입니다. **`partitionByNullity`를 활용한 로직 단순화** * `partitionByNullity`라는 유틸리티 함수를 도입하여 데이터의 존재 여부에 따라 세 그룹(Remote만 존재, 둘 다 존재, Local만 존재)으로 깔끔하게 분리합니다. * 이 함수를 사용하면 메인 함수인 `synchronizeWithRemoteEntries`에서는 복잡한 필터링이나 조건문 없이 각각의 리스트에 대해 `forEach`를 돌며 추가, 업데이트, 삭제 로직만 수행하면 됩니다. * 결과적으로 런타임 에러를 방지하기 위한 불필요한 null 체크가 사라지고, 전체적인 실행 흐름이 일관성 있게 정돈됩니다. **실용적인 제언** 코드의 흐름을 따라가기 벅차다면 데이터의 흐름이 꼬여있지 않은지 점검해야 합니다. 구현에 매몰되기보다 "어떤 모양의 데이터가 있으면 이 로직이 가장 깔끔해질까?"를 먼저 고민하고, 그 중간 구조를 만들어내는 로직을 별도로 분리하면 코드 품질을 획기적으로 개선할 수 있습니다.

당근페이 백엔드 아키텍처가 걸어온 여정. Money라는 하나의 작은 프로젝트부터 수십 개의 서비스를 하나의… | by Jeremy | 당근 테크 블로그 | Jan, 2026 | Medium (새 탭에서 열림)

당근페이 백엔드 아키텍처는 서비스의 급격한 성장과 조직의 확장에 발맞춰 계층형, 헥사고날, 그리고 클린 아키텍처 기반의 모노레포 형태로 끊임없이 진화해 왔습니다. 초기에는 빠른 기능 출시를 위해 단순한 구조를 채택했으나, 비즈니스 복잡도가 증가함에 따라 의존성 관리와 코드 응집도를 높이기 위해 구조적 제약을 강화하는 방향으로 발전했습니다. 결과적으로 아키텍처는 기술적 부채를 해결하는 수단을 넘어, 대규모 팀이 협업하며 지속 가능한 성장을 이뤄낼 수 있는 기반이 되었습니다. ### 초기 성장을 견인한 계층형 아키텍처 (Layered Architecture) * **빠른 실행력 중심:** 2021년 당근페이 출시 초기, 송금 서비스의 신속한 시장 진입을 위해 `Controller-Service-Repository`로 이어지는 직관적인 3계층 구조를 사용했습니다. * **성장통의 발생:** 서비스가 커지면서 송금, 프로모션, FDS 등 다양한 기능이 하나의 계층에 뒤섞였고, 서비스 간 순환 참조와 강한 결합이 발생해 코드 변경의 영향 범위를 예측하기 어려워졌습니다. * **기술 부채의 축적:** 모든 비즈니스 로직에 프레임워크 기술(Spring)이 깊숙이 침투하면서 테스트 작성이 까다로워지고, 순수 도메인 로직만 분리해 관리하기 어려운 구조적 한계에 직면했습니다. ### 구조적 제약을 통한 응집도 향상 (Hexagonal Architecture) * **외부 구현과의 분리:** 도메인 규칙을 중심에 두고 UI, DB, 외부 API 등 인프라 영역을 포트와 어댑터를 통해 분리하여 프레임워크에 의존하지 않는 POJO 중심의 설계를 지향했습니다. * **모듈 역할의 세분화:** 프로젝트를 핵심 규칙을 담은 `domain`, 사용자 시나리오 단위의 `usecase`, 실제 입출력을 담당하는 `adapter` 모듈로 재구성하여 의존성 방향을 한곳으로 모았습니다. * **재사용성과 테스트 용이성:** 유스케이스 단위로 로직이 응집되면서 REST API뿐만 아니라 이벤트 컨슈머, 배치 잡 등 다양한 진입점에서 동일한 비즈니스 로직을 안전하게 재사용할 수 있게 되었습니다. ### 규모 확장에 대응하는 클린 아키텍처와 모노레포 * **모노레포 도입의 배경:** 머니, 포인트, 빌링 등 도메인이 늘어남에 따라 여러 저장소를 관리하는 비용이 증가했고, 이를 효율적으로 통합 관리하기 위해 하나의 저장소에서 여러 서비스를 운영하는 모노레포 구조를 채택했습니다. * **계약 기반의 모듈 분리:** 각 도메인을 `contract(인터페이스)`와 `impl(구현체)` 모듈로 쪼개어 의존성 규칙을 강제했습니다. 다른 모듈은 `contract`만 참조하게 하여 불필요한 내부 구현 노출을 차단했습니다. * **빌드 성능 및 생산성 최적화:** Gradle의 `api`와 `implementation` 구성을 활용해 컴파일 시점의 의존성을 제어함으로써, 대규모 프로젝트임에도 불구하고 빌드 시간을 단축하고 변경 영향도를 최소화했습니다. 아키텍처에는 정답이 없으며, 조직의 규모와 비즈니스의 현재 단계에 가장 적합한 형태를 선택하는 것이 중요합니다. 당근페이의 사례처럼 초기에 과도한 설계를 지양하되, 서비스 성장 속도에 맞춰 구조적 제약을 단계적으로 도입함으로써 기술 부채를 통제하고 개발 생산성을 유지하는 전략을 권장합니다.

코드 품질 개선 기법 28편: 제약 조건에도 상속세가 발생한다 (새 탭에서 열림)

코드의 불변성을 보장하기 위해 설계된 클래스가 상속을 허용할 경우, 자식 클래스에서 해당 제약을 위반함으로써 시스템 전체의 안정성을 해칠 수 있습니다. 특히 `Immutable`이라는 이름을 가진 클래스가 가변적인 자식 클래스를 가질 수 있게 되면 개발자의 의도와 다른 런타임 동작이 발생할 위험이 큽니다. 따라서 특정 제약 조건을 강제하고 싶다면 클래스를 상속 불가능하게 설계하거나, 공통의 '읽기 전용' 인터페이스를 활용하는 구조적 접근이 필요합니다. ### 불변성 보장을 방해하는 상속 구조 * Kotlin의 `IntArray`를 래핑하여 성능과 불변성을 동시에 잡으려는 `ImmutableIntList` 예시를 통해 상속의 위험성을 설명합니다. * 클래스를 상속 가능(`open`)하게 설정하면, `Immutable`이라는 명칭에도 불구하고 이를 상속받아 내부 상태를 변경하는 `MutableIntList`와 같은 자식 클래스가 생성될 수 있습니다. * 외부에서는 `ImmutableIntList` 타입으로 참조하더라도 실제 인덱스 값이 변할 수 있는 객체를 다루게 되어, 불변성을 전제로 한 로직에서 오류가 발생합니다. ### 멤버 오버라이딩을 통한 제약 조건 우회 * 내부 데이터 구조를 `private`이나 `protected`로 보호하더라도, 메서드 오버라이딩을 통해 불변성 제약을 우회할 수 있습니다. * 예를 들어 `get` 연산자를 오버라이딩하여 내부 배열이 아닌 가변적인 외부 필드 값을 반환하도록 재정의하면, 클래스의 핵심 규약인 '불변 데이터 제공'이 깨지게 됩니다. * 범용적인 클래스일수록 예상치 못한 곳에서 잘못된 상속이 발생할 가능성이 높으므로, 어떤 멤버를 노출하고 오버라이딩을 허용할지 엄격하게 제한해야 합니다. ### 가변·불변 객체의 올바른 상속 관계 * 가변 객체가 불변 객체를 상속하면 불변성 제약이 깨지고, 불변 객체가 가변 객체를 상속하면 불필요한 변경 메서드(`add`, `set`)로 인해 런타임 에러가 발생할 수 있습니다. * 가장 이상적인 구조는 가변 객체와 불변 객체가 모두 '읽기 전용(Read-only)' 인터페이스나 클래스를 상속받는 형태입니다. * 가변 객체는 읽기 전용 부모의 메서드 집합을 확장하고, 불변 객체는 읽기 전용 부모의 제약 조건을 확장하는 방식(예: Kotlin의 `List` 구조)이 안전합니다. 특정 제약 조건(불변성 등)이 핵심인 클래스를 설계할 때는 기본적으로 상속을 금지(`final`)하고, 확장이 필요하다면 상속 대신 독립된 타입을 정의하거나 읽기 전용 인터페이스를 통한 계층 분리를 권장합니다.

코드 품질 개선 기법 27편: 티끌이 모여 태산이 되듯 의존성도 쌓이면 (새 탭에서 열림)

의존성 주입(Dependency Injection)은 코드의 유연성을 높이는 강력한 도구이지만, 명확한 목적 없이 모든 요소를 주입 대상으로 삼는 것은 오히려 코드 복잡도를 높이고 유지보수를 어렵게 만듭니다. 참조 투명한 유틸리티나 단순한 모델 클래스까지 외부에서 주입받기보다는, 복잡도가 낮거나 변경 가능성이 희박한 객체는 내부에서 직접 생성하는 것이 더 효율적일 수 있습니다. 따라서 의존성을 주입할 때는 객체의 라이프사이클 관리, 구현체 전환, 테스트 용이성 등 구체적인 목적이 있는지 먼저 검토해야 합니다. **불필요한 의존성 주입의 사례와 개선** * **과도한 주입의 예시**: 뉴스 기사 스니펫을 생성하는 `LatestNewsSnippetUseCase` 클래스에서 데이터 모델인 `NewsSnippet`의 팩토리 함수나, 단순한 문자열 포매터인 `StringTruncator`까지 생성자로 주입받는 경우입니다. * **개선 방향**: 상태를 갖지 않는 단순한 유틸리티 구현체나 데이터 모델의 생성자는 클래스 내부에서 직접 호출하도록 변경합니다. * **단순화 결과**: 환경에 따라 달라지는 값(Locale)이나 네트워크 통신 등 복잡한 로직을 가진 리포지터리만 주입 대상으로 남겨 코드를 더 간결하게 유지할 수 있습니다. **의존성 주입이 필요한 명확한 목적** * **라이프사이클 및 범위 관리**: 객체의 상태를 공유해야 하거나, 사용하는 객체보다 더 긴 수명을 가진 객체를 활용해야 할 때 주입을 사용합니다. * **의존성 역전(DIP)**: 모듈 간의 순환 의존성을 해결하거나 아키텍처에서 정의한 계층 간 의존 방향을 준수하기 위해 필요합니다. * **구현체 전환 및 분리**: 테스트나 디버깅을 위해 Mock 객체로 교체해야 하는 경우, 혹은 빌드 속도 향상을 위해 독점 라이브러리를 분리해야 할 때 유용합니다. **무분별한 주입이 초래하는 문제점** * **추적의 어려움**: 인터페이스와 주입이 남발되면 특정 로직의 실제 동작을 확인하기 위해 생성자의 호출자를 거꾸로 추적해야 하는 수고가 발생합니다. * **호출자 책임 전가**: 하위 클래스의 모든 의존성을 상위 호출자가 해결해야 하므로, 의존성 해결이 연쇄적으로 전달되어 메인 클래스에 과도한 책임이 집중됩니다. * **연관 데이터의 일관성 파괴**: 예를 들어 동일한 `Locale` 값을 사용해야 하는 여러 객체를 각각 주입받을 경우, 실수로 서로 다른 로케일이 전달되어도 컴파일 타임에 이를 감지하기 어렵고 테스트 작성이 까다로워집니다. 의존성 주입은 '할 수 있기 때문'이 아니라 '필요하기 때문'에 수행해야 합니다. 복잡한 비즈니스 로직이나 외부 시스템 의존성은 주입을 통해 유연성을 확보하되, 단순한 값 객체(Value Object)나 유틸리티는 직접 인스턴스화하여 코드의 명확성을 높이는 것을 권장합니다.

배달의민족 주문접수 채널에 Flutter를 도입하며 고민한 것 | 우아한형제들 기술블로그 (새 탭에서 열림)

배달의민족 주문접수 채널은 다양한 디바이스 환경에 대응하고 개발 생산성을 극대화하기 위해 Flutter와 클린 아키텍처를 도입했습니다. 단일 코드베이스를 통해 Android, macOS 등 멀티 플랫폼 지원을 효율화하는 한편, 플랫폼별 차이는 추상화 계층으로 격리하여 유지보수성을 확보했습니다. 나아가 비즈니스 로직의 빠른 변화에 대응하기 위해 Flutter 기반 앱 셸(App Shell)에 웹뷰를 결합한 하이브리드 구조로 진화하며 일관된 사용자 경험을 제공하고 있습니다. ### 멀티 플랫폼 대응을 위한 Flutter 도입과 전략 * Windows, Android, iOS를 넘어 macOS 및 POS 환경까지 확장되는 파트너 요구사항에 대응하기 위해 단일 코드베이스인 Flutter를 선택했습니다. * "Write Once, Run Everywhere"의 이상보다는 플랫폼별 차이(업데이트 방식, 권한 관리 등)를 인정하고 공통 인터페이스로 대응하는 "Write Once, Adapt Everywhere" 접근법을 취했습니다. * 플랫폼별 구현이 다르거나 외부 라이브러리 의존성이 높은 경우, 혹은 테스트를 위해 Mock이 필요한 지점에만 선택적으로 추상화를 적용하여 불필요한 코드 복잡도를 제어했습니다. * 최근 실시간 통신 방식을 MQTT에서 SSE(Server-Sent Events)로 변경할 때, 인터페이스 기반 설계 덕분에 비즈니스 로직 수정 없이 구현체만 교체하여 작업을 완료할 수 있었습니다. ### 클린 아키텍처와 BLoC을 활용한 안정적인 상태 관리 * 계층 간 관심사를 명확히 분리하기 위해 데이터(Data), 도메인(Domain), 프레젠테이션(Presentation), 인프라(Infrastructure) 계층으로 구성된 클린 아키텍처를 적용했습니다. * 상태 관리 도구로는 BLoC(Business Logic Component) 패턴을 채택하여, 이벤트와 상태 변화를 명시적으로 로깅하고 추적함으로써 복잡한 주문 흐름의 디버깅 효율을 높였습니다. * 기능(Feature) 단위로 모듈을 분리하여 각 기능이 독립적으로 동작하고 확장될 수 있는 구조를 마련했습니다. ### 웹뷰 기반 앱 셸(App Shell)로의 전환과 유연성 확보 * 잦은 비즈니스 요구사항 변경에 실시간으로 대응하기 위해, 핵심 로직은 웹(WebView)으로 구현하고 기기 제어 기능은 Flutter(Native)가 담당하는 하이브리드 구조를 도입 중입니다. * Flutter는 프린터 제어, 오디오 출력, 푸시 알림, 로컬 DB 관리 등 하드웨어 및 OS 밀착형 기능을 '앱 셸'로서 제공합니다. * 웹과 Flutter 간의 통신은 JavaScript Bridge를 통해 이루어지며, 이를 통해 앱 스토어 심사 없이도 웹 업데이트만으로 새로운 비즈니스 기능을 즉시 반영할 수 있는 체계를 구축했습니다. 성공적인 멀티 플랫폼 서비스를 위해서는 단일 프레임워크 도입에 그치지 않고, 플랫폼별 차이를 수용할 수 있는 인터페이스 설계와 비즈니스 변화 속도에 맞춘 아키텍처(하이브리드 구조 등)를 전략적으로 선택하는 것이 중요합니다. 특히 클린 아키텍처를 통한 계층 분리는 기술적 부채를 최소화하면서도 급변하는 요구사항에 유연하게 대응할 수 있는 기반이 됩니다.

코드 품질 개선 기법 24편: 유산의 가치 (새 탭에서 열림)

코드에서 로직은 동일하고 단순히 값만 달라지는 경우, 인터페이스와 상속을 사용하는 대신 데이터 클래스와 인스턴스 생성을 활용하는 것이 더 효율적입니다. 상속은 동적 디스패치나 의존성 역전과 같은 특정한 목적이 있을 때 강력한 도구가 되지만, 단순한 값의 차이를 표현하기 위해 사용하면 불필요한 복잡성을 초래할 수 있습니다. 따라서 객체의 속성 값만 변경되는 상황이라면 상속 불가능한 클래스를 정의하고 값만 다른 인스턴스를 만들어 사용하는 것이 코드의 가독성과 예측 가능성을 높이는 지름길입니다. **상속이 과용되는 사례와 문제점** * UI 테마(색상, 아이콘 등)를 적용할 때 인터페이스를 정의하고 각 테마(Light, Dark)별로 클래스를 상속받아 구현하는 방식은 흔히 발견되는 과잉 설계의 예시입니다. * 바인딩 로직이 모든 테마에서 동일함에도 불구하고 상속을 사용하면, 각 하위 클래스가 자신만의 고유한 로직을 가질 수 있다는 가능성을 열어두게 되어 코드 추적을 어렵게 만듭니다. * 특히 단순히 속성 값을 반환하는 목적일 때는 인터페이스를 통한 동적 디스패치가 성능상 미미한 오버헤드를 발생시킬 뿐만 아니라 구조를 복잡하게 만듭니다. **상속을 사용해야 하는 정당한 경우** * **로직의 동적 변경:** 상황에 따라 실행 시점에 로직 자체를 갈아끼워야 하는 동적 디스패치가 필요할 때 사용합니다. * **합 타입(Sum Types) 구현:** Kotlin의 `sealed class`처럼 정해진 하위 타입들의 집합을 정의해야 할 때 유용합니다. * **추상화와 구현의 분리:** 프레임워크의 제약 조건 대응, 의존성 주입(DI), 또는 빌드 속도 향상을 위해 인터페이스가 필요할 때 활용합니다. * **의존성 역전 법칙(DIP) 적용:** 순환 의존성을 해결하거나 의존성 방향을 단방향으로 유지해야 할 때 상속과 인터페이스를 사용합니다. **인스턴스 기반 모델링의 이점** * 인터페이스 대신 모든 속성을 포함하는 단일 클래스(Model)를 정의하고, 각 테마를 이 클래스의 인스턴스로 생성하면 구조가 훨씬 간결해집니다. * Kotlin의 기본 클래스처럼 상속이 불가능한(`final`) 클래스로 정의할 경우, 해당 인스턴스에 고유한 로직이 포함되지 않았음을 보장할 수 있습니다. * 속성 값이 변하지 않는다면 각 인스턴스는 데이터의 묶음으로서만 존재하게 되어, 상태 변화나 로직의 부수 효과를 걱정할 필요 없이 안전하게 재사용할 수 있습니다. 단순히 값만 다른 여러 타입을 구현해야 한다면 먼저 "상속이 반드시 필요한 로직의 차이가 있는가?"를 자문해 보시기 바랍니다. 로직이 같다면 클래스 상속보다는 데이터 모델의 인스턴스를 생성하는 방식이 유지보수하기 훨씬 쉬운 코드를 만들어줍니다.

코드 품질 개선 기법 22편: To equal, or not to equal (새 탭에서 열림)

Java와 Kotlin에서 객체의 등가성을 정의하는 `equals` 메서드는 반드시 객체의 동일성(Identity)이나 모든 속성이 일치하는 등가성(Equivalence) 중 하나를 명확히 표현해야 합니다. 식별자(ID)와 같은 일부 속성만 비교하도록 `equals`를 잘못 구현하면, 상태 변경을 감지하는 옵저버블 패턴에서 데이터 업데이트가 무시되는 심각한 버그를 초래할 수 있습니다. 따라서 특정 속성만 비교해야 하는 상황이라면 `equals`를 오버라이딩하는 대신 별도의 명시적인 함수를 정의하여 사용하는 것이 안전합니다. ### 부분 비교 `equals` 구현의 위험성 * 객체의 식별자(ID) 등 일부 필드만 사용하여 `equals`를 구현하면, 객체가 논리적으로는 변경되었음에도 기술적으로는 '같은 객체'로 판정되는 모순이 발생합니다. * `StateFlow`, `LiveData`, `Observable` 등의 프레임워크는 이전 데이터와 새 데이터를 `equals`로 비교하여 변경 사항이 있을 때만 UI를 업데이트합니다. * 만약 사용자의 식별자는 같지만 닉네임이나 상태 메시지가 변경된 경우, 부분 비교 `equals`는 `true`를 반환하므로 화면에 변경 사항이 반영되지 않는 버그가 발생합니다. ### 올바른 등가성 정의와 대안 * **동일성(Identity):** 두 객체의 참조가 같은지를 의미하며, 특별한 구현이 필요 없다면 Java/Kotlin의 기본 `equals`를 그대로 사용합니다. * **등가성(Equivalence):** 모든 속성과 필드가 같을 때 `true`를 반환하도록 설계해야 합니다. Kotlin에서는 `data class`를 사용하면 생성자에 선언된 모든 필드를 비교하는 `equals`가 자동으로 생성됩니다. * **명시적 비교 함수:** 특정 식별자만 비교해야 하는 로직이 필요하다면 `hasSameIdWith(other)`와 같이 의도가 명확히 드러나는 별도의 함수를 정의하여 사용하는 것이 좋습니다. ### 구현 시 주의해야 할 예외와 맥락 * **Kotlin data class의 제약:** `data class`는 생성자 파라미터에 정의된 속성만 `equals` 비교에 사용합니다. 클래스 본문에 선언된 변수(`var`)는 비교 대상에서 제외되므로 주의가 필요합니다. * **캐시 필드의 제외:** 계산 결과의 캐시값처럼 객체의 논리적 상태에 영향을 주지 않고 성능 최적화를 위해 존재하는 필드는 등가성 비교에서 제외해도 무방합니다. * **도메인 맥락에 따른 설계:** 유리수(1/2과 2/4)의 예시처럼, 모델이 단순한 '표시용'인지 '수학적 계산용'인지에 따라 등가성의 기준이 달라질 수 있으므로 개발 목적에 맞는 신중한 정의가 필요합니다. 객체의 등가성을 설계할 때는 해당 객체가 시스템 내에서 어떻게 관찰되고 비교될지를 먼저 고려해야 합니다. 특히 데이터 바인딩이나 상태 관리를 사용하는 환경에서는 `equals`가 객체의 전체 상태를 대변하도록 엄격하게 구현하고, 식별자 비교는 명시적인 명칭의 메서드로 분리하는 것이 코드의 예측 가능성을 높이는 방법입니다.

코드 품질 개선 기법 19편: 차일드 록 (새 탭에서 열림)

상속 구조에서 자식 클래스가 부모 클래스의 함수를 오버라이딩할 때 발생할 수 있는 결함을 방지하기 위해, 오버라이딩 가능한 범위를 최대한 제한해야 합니다. 부모 클래스의 공통 로직과 자식 클래스의 확장 로직을 분리하지 않으면 `super` 호출 누락이나 책임 범위의 혼선과 같은 버그가 발생하기 쉽습니다. 따라서 부모 클래스에서 전체적인 흐름을 제어하고 자식 클래스는 특정 지점의 로직만 구현하도록 설계하는 '차일드 록(child lock)' 기법이 필요합니다. **기존 오버라이딩 방식의 문제점** * **super 호출 누락의 위험:** 자식 클래스에서 부모의 기능을 실행하기 위해 `super.bind()`를 명시적으로 호출해야 하는 구조는 실수를 유발하기 쉽습니다. 호출을 잊더라도 컴파일 에러가 발생하지 않아 헤더나 푸터가 업데이트되지 않는 등의 버그가 방치될 수 있습니다. * **구현 강제성 부족:** 오버라이딩이 필수적인 상황임에도 불구하고 주석으로만 안내되어 있다면, 개발자가 실수로 구현을 누락할 가능성이 큽니다. * **책임 범위의 모호함:** 하나의 함수(`bind`)가 공통 로직과 개별 로직을 모두 포함하고 있으면 오버라이딩의 책임 범위를 오해하기 쉽고, 결과적으로 자식 클래스에 부적절한 코드가 포함될 수 있습니다. **차일드 록을 통한 구조 개선** * **공통 흐름의 고정:** 부모 클래스의 메인 함수(예: `bind`)에서 `open` 키워드를 제거하여 자식 클래스가 전체 흐름을 수정할 수 없도록 '록'을 겁니다. * **추상 메서드 분리:** 자식 클래스마다 달라져야 하는 로직만 별도의 `abstract` 메서드(예: `updateMessageList`)로 추출합니다. * **템플릿 메서드 패턴 적용:** 부모 클래스의 `bind` 함수에서 공통 로직(헤더/푸터 업데이트)을 실행한 후, 자식 클래스가 구현한 추상 메서드를 호출하는 방식으로 설계합니다. 이를 통해 자식 클래스는 부모의 로직을 신경 쓰지 않고 자신의 역할에만 집중할 수 있습니다. **견고한 상속 설계를 위한 가이드라인** * **super 호출 지양:** 라이프사이클 관리나 플랫폼 API의 제약이 있는 특수한 경우를 제외하고는, 자식 클래스에서 `super`를 호출해야만 기능이 완성되는 구조를 피해야 합니다. * **제어 흐름의 중앙 집중화:** 자식 클래스들이 공통으로 사용하는 함수의 실행 순서나 흐름은 반드시 부모 클래스에서 정의하고 관리해야 합니다. * **캡슐화 강화:** C++의 `private virtual` 기법처럼, 부모 클래스에서만 호출 가능하면서 자식 클래스에서 동작을 재정의할 수 있는 구조를 활용하여 오버라이딩 범위를 엄격하게 제한하는 것이 좋습니다. 상속을 설계할 때는 자식 클래스에게 과도한 자유를 주기보다, 필요한 부분만 안전하게 확장할 수 있도록 제약 장치를 마련하는 것이 시스템의 안정성을 높이는 핵심입니다. 이는 코드 리뷰 과정에서 발견하기 어려운 논리적 오류를 컴파일 단계나 구조적 제약으로 사전에 차단하는 효과를 줍니다.

DDD를 Merchant 시스템 구축에 활용한 사례를 소개합니다 (새 탭에서 열림)

기존의 음식 배달 중심 시스템에서 벗어나 소매 상품 판매에 최적화된 새로운 Merchant 시스템을 구축하기 위해 도메인 주도 설계(DDD)를 도입했습니다. 이번 프로젝트는 DDD가 단순히 코드 구현 기술이 아니라, 도메인의 역할과 책임을 명확히 정의하고 이를 바탕으로 조직 구조와 협업 방식을 설계하는 방법론임을 보여줍니다. 클린 아키텍처와 비동기 이벤트 기반의 모듈 구성을 통해 시스템의 확장성을 확보하고, 글로벌 팀 간의 원활한 협업 체계를 마련하며 성공적으로 시스템을 론칭했습니다. **소매 플랫폼으로의 전환과 도메인 정의** * 기존 시스템의 '음식점 기반 소매 판매' 한계를 극복하기 위해 독립적인 Merchant 시스템을 설계했습니다. * Merchant 시스템은 점포, 상품, 재고 등의 정보를 제공하고, 실제 판매는 '소비자 플랫폼'에서 담당하는 구조로 역할을 분리했습니다. * 핵심 도메인을 점포(shop), 상품(item), 카테고리(category), 재고(inventory), 주문(order)의 다섯 가지로 정의하여 복잡도를 낮추었습니다. **클린 아키텍처를 활용한 시스템 설계** * 도메인 엔티티가 외부 환경의 변화에 영향을 받지 않도록 클린 아키텍처를 채택했습니다. * 모든 팀원이 쉽게 이해하고 따를 수 있는 명확한 계층 구조를 통해 유지보수 편의성을 높였습니다. * 의존성 방향을 내부(도메인)로만 허용하여 비즈니스 로직의 순수성을 유지했습니다. **비동기 기반의 모듈 및 통신 구조** * 시스템을 외부 요청을 받는 'API' 모듈과 비즈니스 로직을 처리하는 '엔진' 모듈로 분리하여 가용성을 높였습니다. * gRPC를 통한 API 제공과 Apache Kafka 기반의 내부 통신을 결합했으며, Decaton 라이브러리를 사용해 파티션 대비 높은 처리량을 확보했습니다. * 플랫폼 특성을 고려하여 즉각적인 응답보다는 최종 일관성(Eventual Consistency)과 빠른 API 응답 능력에 초점을 맞춘 비동기 구조를 설계했습니다. **글로벌 협업과 조직의 일치(Conway's Law)** * 한국 팀은 핵심 도메인(Core)을, 일본 팀은 현지 시스템 연계(Link, BFF)를 담당하도록 조직을 구성해 콘웨이의 법칙을 실천했습니다. * 의사결정 과정과 논의 배경을 기록하는 ADR(Architectural Decision Record)을 활용해 조직 간의 공감대를 형성하고 불필요한 재논의를 방지했습니다. * 추상화된 연계 계층을 통해 새로운 소비자 플랫폼이 추가되더라도 핵심 도메인의 변화는 최소화되는 유연한 구조를 만들었습니다. 성공적인 DDD 적용을 위해서는 헥사고날 아키텍처와 같은 기술적인 구현에만 매몰되지 않는 것이 중요합니다. 도메인의 역할과 책임을 먼저 명확히 정의하고, 그 경계에 맞춰 팀 조직과 소통 구조를 설계할 때 진정한 설계의 이점을 얻을 수 있습니다. 시스템의 아키텍처가 조직의 소통 구조를 반영한다는 점을 인지하고, 기술과 조직 관리의 균형을 맞추는 접근이 권장됩니다.

코드 품질 개선 기법 14편: 책임을 부여하는 오직 하나의 책임 (새 탭에서 열림)

단일 책임 원칙(SRP)을 기계적으로 적용하여 클래스를 과도하게 분리하면, 오히려 시스템 전체의 복잡도가 증가하고 사양의 제약 조건을 파악하기 어려워질 수 있습니다. 코드 품질을 높이기 위해서는 개별 클래스의 응집도뿐만 아니라, 분리된 클래스들이 맺는 의존 관계와 호출자가 짊어져야 할 관리 부담을 종합적으로 고려해야 합니다. 결국 핵심적인 제약 조건을 한곳에서 관리할 수 있다면, 약간의 책임이 섞여 있더라도 초기 구현의 단순함을 유지하는 것이 더 나은 선택일 수 있습니다. **과도한 책임 분리가 초래하는 문제** * 동적으로 실행 로직이 변하는 '론치 버튼'을 구현할 때, 버튼 바인딩 책임과 로직 선택 책임을 별도 클래스로 분리하면 각 클래스는 단순해지지만 시스템 구조는 복잡해집니다. * 로직별로 별도의 바인더 인스턴스를 생성하고 `isEnabled` 상태를 통해 실행 여부를 제어하게 되면, 버튼 하나에 여러 개의 리스너가 등록되는 등 내부 동작을 추적하기 어려워집니다. * 결과적으로 "단 하나의 로직만 실행되어야 한다"는 비즈니스 제약 조건을 확인하기 위해 여러 클래스와 루프 문을 모두 훑어야 하는 비용이 발생합니다. **제약 조건의 분산과 상태 중복** * 책임을 분리하면 특정 사양이 코드 전체로 흩어지는 '책임 떠넘기기' 현상이 발생할 수 있습니다. * 예를 들어 어떤 로직이 활성화되었는지 나타내는 상태를 상위 클래스(Selector)에 추가하면, 하위 클래스(Binder)의 `isEnabled` 속성과 데이터가 중복되어 상태 불일치 문제가 생길 위험이 있습니다. * 이러한 중복은 코드의 신뢰성을 떨어뜨리며, 사양 변경 시 수정해야 할 포인트가 늘어나는 결과를 초래합니다. **의존성 비대화와 라비올리 코드(Ravioli Code)** * 세부 사항을 은닉하기 위해 의존 관계를 더 잘게 쪼개면, 이를 조합해야 하는 호출자(Caller)의 코드가 비대해지는 '갓 클래스(God Class)' 현상이 나타날 수 있습니다. * 너무 작은 단위로 쪼개진 클래스들이 서로 얽히면 전체 흐름을 파악하기 위해 수많은 파일을 오가야 하는 '라비올리 코드'가 되어 유지보수성이 저하됩니다. * 객체 지향의 핵심은 캡슐화인데, 제약 조건을 보장하는 로직을 분리해버리면 오히려 캡슐화가 깨지고 외부 의존성만 강해지는 부작용이 생깁니다. **실용적인 설계를 위한 제언** 클래스를 분할할 때는 응집도라는 단일 지표에만 매몰되지 말고, 분할 후의 의존성 그래프와 호출자의 편의성을 반드시 확인해야 합니다. 만약 특정 클래스가 내부에서 핵심 제약 조건을 깔끔하게 관리하고 있다면, 억지로 책임을 나누기보다 그 응집된 구조를 유지하는 것이 시스템 전체의 결합도를 낮추고 코드의 가독성을 높이는 길입니다.

코드 품질 개선 기법 12편: 세트 할인 (새 탭에서 열림)

여러 속성을 개별적으로 변경할 수 있게 허용하는 구조는 상태 간의 불일치를 초래하고 예기치 못한 버그를 유발할 수 있습니다. 이를 해결하기 위해 서로 연관된 상태들을 하나의 객체로 묶어 한 번에 업데이트하도록 인터페이스를 제한하면 시스템의 예측 가능성을 높일 수 있습니다. 결과적으로 코드의 의도가 명확해지고 스레드 안전성 확보와 디버깅이 훨씬 용이해집니다. **개별 속성 변경의 위험성** * **실행 순서 의존성:** 활성화 상태(`isActive`)와 세부 설정(`minImportanceToRecord` 등)이 분리되어 있으면, 설정을 변경하기 전에 활성화를 먼저 시도할 경우 의도치 않게 이전 설정값이 적용되는 문제가 발생합니다. * **상태 초기화의 불일치:** 특정 속성이 변경될 때 내부 카운터가 초기화되어야 함에도 불구하고, 어떤 속성은 초기화를 수행하고 어떤 속성은 누락하는 등의 관리 포인트가 파편화되어 로직이 복잡해집니다. * **경쟁 상태(Race Condition):** 비동기 환경에서 여러 속성을 순차적으로 변경하면, 변경 중간에 다른 로직이 개입하여 불완전한 상태의 데이터를 읽게 될 위험이 있습니다. **데이터 묶음과 인터페이스 제한을 통한 개선** * **객체 캡슐화:** 연관된 설정값들을 `SamplingPolicy`와 같은 별도의 불변(Immutable) 클래스로 묶어 관리함으로써 속성들이 항상 한 세트로 업데이트되도록 강제합니다. * **상태 표현의 최적화:** 별도의 불리언 플래그 대신 상태 객체의 `null` 여부로 활성화 상태를 표현하여, 활성 상태일 때는 반드시 유효한 설정값이 존재함을 보장합니다. * **원자적 업데이트:** `startRecording`과 같이 명시적인 메서드를 통해서만 상태를 변경하게 함으로써 내부 카운터 초기화와 설정 변경이 한 번에(Atomic) 이루어지도록 제어합니다. **실용적인 결론** 단순히 모든 필드에 세터(setter)를 열어두는 것보다, 비즈니스 로직상 함께 움직여야 하는 데이터는 하나의 '상태 객체'로 정의하는 것이 좋습니다. 특히 한 속성의 변화가 다른 속성의 의미나 동작에 영향을 주는 경우에는 인터페이스를 엄격하게 제한하여 잘못된 상태 조합이 발생하는 것을 원천적으로 차단해야 합니다.

코드 품질 개선 기법 11편: 반복되는 호출에 함수도 지친다 (새 탭에서 열림)

객체의 상태를 확인하고 그 결과에 따라 상태를 변경하는 로직은 호출자가 아닌 해당 객체 내부로 캡슐화하는 것이 코드 품질을 높이는 핵심입니다. 이를 통해 외부로 드러나는 상태 전이 로직을 단순화하고, 조건 확인 누락으로 인해 발생할 수 있는 잠재적인 버그를 효과적으로 방지할 수 있습니다. 특히 상태 변경 여부에 따른 후속 작업이 필요할 때는 복잡한 콜백보다 명확한 반환값을 활용하는 것이 코드의 가독성과 유지보수 측면에서 유리합니다. **상태 확인 로직의 내재화** * `if (receiver.a()) { receiver.b() }`와 같이 외부에서 객체의 상태를 묻고 동작을 결정하는 구조는 중복 호출의 번거로움과 확인 누락의 위험을 수반합니다. * 상태를 변경하는 함수(예: `markAsFriend`) 내부에서 직접 조건을 검사(예: `isFriend`)하도록 설계하면, 호출자는 객체의 내부 상태를 일일이 신경 쓰지 않고도 안전하게 기능을 수행할 수 있습니다. * 이러한 방식은 객체 내부의 상태 전이를 단순화하며, '이미 해당 상태인 경우 아무것도 하지 않는다'는 동작을 자연스럽게 보장합니다. * 만약 조건부 동작임을 명시적으로 드러내야 한다면 `markAsFriendIfNotYet`과 같이 함수 이름을 명확하게 짓거나 주석으로 보완하는 방법이 권장됩니다. **콜백 대신 반환값으로 결과 전달** * 상태 변경 성공 여부에 따라 팝업 노출과 같은 후속 작업이 필요할 때, 고차 함수를 통한 콜백(onSucceeded) 방식은 피하는 것이 좋습니다. * 콜백 방식은 의존성 순환을 일으킬 수 있고, 해당 로직이 동기적으로 실행되는지 비동기적으로 실행되는지 호출부에서 파악하기 어렵게 만듭니다. * 대신 `Boolean` 등의 반환값을 활용하면 호출자가 결과에 따라 후속 로직을 직접 제어할 수 있어 코드의 실행 흐름이 명확해집니다. * 이때 함수 이름에서 반환값의 의미가 명확히 드러나지 않는다면 문서화를 통해 보완하고, 호출자가 반환값을 반드시 확인하도록 강제하는 기법을 함께 사용할 수 있습니다. 객체 설계 시 "묻지 말고 시키라(Tell, Don't Ask)"는 원칙을 적용해 보시기 바랍니다. 객체 외부에서 상태를 묻고 판단하기보다, 객체가 스스로 자신의 상태를 확인하고 동작하게 함으로써 더 견고하고 읽기 쉬운 코드를 작성할 수 있습니다.

코드 품질 개선 기법 10편: 적절한 거리 유지에 신경 쓰자 (새 탭에서 열림)

코드 품질을 높이기 위해서는 각 레이어나 컴포넌트가 서로의 세부 구현을 알지 못하도록 적절한 거리를 유지하는 것이 중요합니다. 특히 UI와 데이터 레이어가 암묵적인 규칙을 공유하며 의존할 경우, 사양 변경 시 예측하지 못한 버그가 발생하기 쉬우므로 명확한 상태 값과 인터페이스를 통해 책임을 분리해야 합니다. **암묵적 정보 공유의 문제점** * 리포지터리 레이어에서 UI의 표시 형식을 고려해 '최대 개수 + 1'의 데이터를 조회하는 식의 구현은 레이어 간의 경계를 무너뜨립니다. * UI 레이어가 리포지터리의 특정 동작(예: 100개 초과 시 리스트 크기가 101임)에 의존해 비즈니스 로직을 판단하면 코드의 가독성과 유지보수성이 떨어집니다. * 이러한 방식은 주석으로만 의도를 설명할 수 있을 뿐, 코드 구조 자체로는 데이터의 의미를 명확히 전달하지 못하는 한계가 있습니다. **명시적인 속성을 활용한 책임 분리** * 모델 클래스에 `hasMoreItems`와 같은 명시적인 불리언 속성을 추가하여 데이터의 상태를 직접적으로 표현하는 것이 좋습니다. * 리포지터리는 모델 인스턴스를 생성할 때 추가 데이터 존재 여부를 판단하는 로직을 수행하고, UI에는 정제된 데이터만 전달합니다. * UI 레이어는 더 이상 특정 상수값이나 리포지터리의 조회 규칙을 알 필요 없이, 모델이 제공하는 속성에만 기반하여 화면을 구성할 수 있게 됩니다. **로직과 상수의 적절한 위치 선정** * 데이터 개수를 제한하는 상수(`ITEM_LIST_MAX_COUNT`)는 서비스의 성격에 따라 비즈니스 로직 레이어(도메인, 유스 케이스 등)에서 정의하는 것이 이상적입니다. * 비즈니스 레이어를 별도로 두기 어려운 규모라면 모델 클래스 내부에 정의할 수도 있으나, 이때는 데이터 구조와 알고리즘 간의 의존 방향이 모호해지지 않도록 주의해야 합니다. * 특정 기능에 국한된 로직이 범용적인 데이터 모델에 포함되어 재사용성을 해치지 않는지 검토하는 과정이 필요합니다. **실용적인 제언** 코드 작성 시 "이 컴포넌트가 다른 컴포넌트의 내부 사정을 너무 자세히 알고 있지는 않은가?"를 자문해 보시기 바랍니다. 다른 레이어의 세부 동작에 암묵적으로 의존하는 코드를 피하고, 인터페이스를 통해 명확한 정보를 주고받도록 설계하는 것이 변경에 유연한 소프트웨어를 만드는 핵심입니다.