LLM을 활용해 Java, Rust, TypeScript, Python, Go 등 여러 언어로 동시에 작업하다 보면 언어별 스타일 가이드만으로는 부족하다는 것을 느끼게 된다. AI가 코드를 생성할 때 “중첩을 줄여라”, “이름을 명확히 해라” 수준이 아니라, 왜 그렇게 해야 하는지 근거가 있는 원칙이 필요하다. 이 원칙은 Domain-Driven Design(DDD), Clean Code, Code Complete, Refactoring의 핵심 내용을 통합하여, 비즈니스 도메인을 최우선으로 삼으면서도 읽기 쉽고 유지보수성이 높으며 결함이 적은 코드를 만드는 것을 목표로 한다. AI가 코드를 생성하고 수정하는 빈도가 높아질수록, 코드가 얼마나 명확하고 의도적으로 작성되었는지가 AI의 추론 품질과 직결되기 때문에 이 원칙들은 AI 시대에 더욱 중요해진다. 이 글은 내가 여러 프로젝트에서 공통 규칙으로 쓰는 문서를 옮긴 것이라, 본문의 “팀”은 이 문서를 채택한 팀을 가리킨다. 대상 독자는 AI 코딩 도구에 넘길 공통 규칙을 정리하려는 개발자와 팀이다.
1. 목적과 철학 (Philosophy)
코드는 기술적 산출물이기 이전에, 도메인 지식을 안전하게 보존하고 발전시키는 그릇 이다. 소프트웨어의 본질은 문법의 우아함이나 프레임워크 활용 능력, 또는 기술적 기교에 있지 않다. 비즈니스와 도메인의 행동을 명확하게 인코딩하여, 지금의 개발자뿐 아니라 미래의 개발자가 안전하게 이해하고, 수정하고, 확장할 수 있게 하는 것이 소프트웨어가 존재하는 목적이다.
따라서 이 문서가 추구하는 코드 품질의 기준은 단순히 “동작하는 코드”가 아니라, 사람이 읽고 신뢰할 수 있는 코드 다. 좋은 코드는 작성하는 순간보다 읽히는 순간이 훨씬 많다. 코드는 컴파일러가 아니라 사람에게 먼저 말을 걸어야 한다.
팀이 추구하는 우선순위
코드를 작성할 때 상충하는 가치가 생기는 경우, 팀은 아래의 우선순위를 기준으로 판단한다. 각 항목은 독립된 규칙이 아니라 서로를 강화하는 하나의 철학적 체계로 이해해야 한다.
첫째, 도메인 명확성(Domain Clarity)을 최우선으로 삼는다
코드는 비즈니스와 도메인의 행동을 있는 그대로 표현해야 한다. 변수명, 함수명, 모듈 구조 모두 도메인 언어를 중심으로 결정하며, 비즈니스 로직은 해당 도메인 객체 안에 위치시켜 코드를 읽는 사람이 기술적 세부사항보다 도메인의 의도를 먼저 파악할 수 있어야 한다. 도메인 언어가 코드 전반에 일관되게 흐를 때, 코드는 비로소 팀 공통의 언어가 된다.
둘째, 명시적 의도(Explicit Intent)를 암시적 관례보다 항상 우선한다
코드는 컴파일러가 아니라 사람에게 먼저 말을 걸어야 한다. 작성한 사람만 아는 관례나 맥락에 의존하는 표현보다, 읽는 사람 누구에게나 의도가 드러나는 표현을 선택한다. “왜 이렇게 했는가”가 코드 자체에서 읽혀야 하며, 주석으로만 설명되는 코드는 명시성이 부족한 코드다.
셋째, 변경 안전성(Change Safety)을 설계의 기준으로 삼는다
코드는 한 번 작성되고 수십 번 수정된다. 변경이 발생했을 때 파급 범위가 작고 예측 가능해야 하며, 수정이 필요한 지점이 직관적으로 드러나야 한다. 변경에 취약한 설계는 아무리 우아해 보여도 좋은 설계가 아니다. 안정성과 예측 가능성은 변경 안전성의 다른 이름이며, 예외 상황과 경계 조건도 암묵적 전제가 아닌 명시적 처리로 표현한다.
넷째, 인지 부하 감소(Cognitive Load Reduction)를 가독성의 실질적 기준으로 삼는다
좋은 코드는 읽는 사람이 머릿속에 동시에 담아야 할 정보의 양을 줄인다. 코드 라인 수를 줄이거나 압축적으로 표현하는 것이 목표가 아니라, 읽는 순간의 인지 부담을 줄이는 것이 목표다. 복잡한 로직은 의미 있는 단위로 나누고, 흐름이 위에서 아래로 자연스럽게 읽히도록 구성한다.
다섯째, 진화 가능한 설계(Evolutionary Design)를 추구하되, 조급한 확장은 경계한다
좋은 설계는 처음부터 완벽할 필요가 없다. 지금의 요구사항을 명확하게 해결하면서, 미래의 변경이 자연스럽게 수용될 수 있는 구조를 지향한다. 추상화와 재사용은 반드시 필요한 시점에, 반드시 필요한 수준만큼만 도입한다. 아직 오지 않은 요구사항을 위한 유연성은 유연성이 아니라 복잡성이다.
여섯째, 성능 최적화는 측정된 병목에만 적용한다
확인되지 않은 성능 문제를 위한 최적화는 조기 최적화(Premature Optimization)로 간주한다. 최적화는 반드시 측정 결과를 근거로 하며, 위의 우선순위를 희생하는 최적화는 충분한 이유와 명시적인 주석을 동반해야 한다.
의식적으로 배제하는 것들
좋은 코드를 만들기 위해 추구할 것만큼이나, 의식적으로 배제해야 할 것도 중요하다.
1) 영리하지만 불필요하게 복잡한 추상화(Clever Abstractions)는 지양한다 (KISS)
추상화가 코드를 단순하게 만드는 것이 아니라 이해를 어렵게 만든다면, 그 추상화는 오히려 부채다. 코드 라인 수를 과도하게 줄이려는 시도도 마찬가지다. 간결함과 압축은 다르다. 읽는 사람의 인지 부하를 줄이는 것이 목표이지, 타이핑의 양을 줄이는 것이 목표가 아니다.
2) 프레임워크 순수성(Framework Purity)을 맹목적으로 우선시하는 설계는 경계한다
프레임워크는 도구이지 목적이 아니다. 도메인 로직이 프레임워크의 구조에 종속되어서는 안 된다. 프레임워크의 관례가 도메인의 명확성과 충돌할 때, 도메인이 우선한다.
3) 조급한 재사용(Premature Reuse)은 지양한다
중복이 나쁜 것은 사실이지만, 섣부른 공통화는 불필요한 결합을 만들고 변경을 어렵게 한다. 재사용의 필요성은 패턴이 충분히 반복된 이후에 판단한다.
4) 이론적 우아함(Theoretical Elegance)을 실용성보다 우선하지 않는다
실제 팀이 이해하고 운용할 수 있는 코드가, 패턴 교과서에 나올 법한 완벽한 설계보다 항상 낫다. 설계의 아름다움은 팀이 그것을 자신 있게 수정할 수 있을 때 완성된다.
AI/LLM 코드 생성과 인간 협업에 대한 원칙
AI는 코드 작성의 조력자이지, 코드 품질의 책임자가 아니다. AI가 생성한 코드도 이 문서의 기준과 동일하게 검토되어야 하며, 생성된 코드를 그대로 수용하는 것은 리뷰를 생략하는 것과 같다.
AI를 활용한 코딩, 리팩토링, 코드 리뷰 시, 이 문서와 언어별 상세 가이드는 AI에게 부여되는 명시적 지침으로 기능한다. AI는 이 철학을 이해하고 일관되게 적용하는 방향으로 코드를 생성하거나 평가해야 한다. 특히 도메인 명확성, 명시적 의도, 변경 안전성을 최우선으로 반영하고, 불필요한 추상화나 측정되지 않은 최적화를 스스로 제안하지 않아야 한다.
인간 개발자는 AI의 결과물에 대해 최종 판단과 책임을 가진다. AI가 생성한 코드라도 팀의 우선순위와 도메인 지식에 비추어 반드시 검토하고, 필요하다면 주저 없이 수정한다. AI의 자신감은 코드의 정확성을 보장하지 않는다. 검토하지 않은 코드는 작성하지 않은 코드와 같다.
2. 코드 조직 구조 (Project Structure)
구조는 도메인을 반영해야 한다. 코드를 어떻게 배치하고 나누느냐는 단순한 파일 정리의 문제가 아니다. 디렉토리 구조와 모듈 경계는 팀이 도메인을 어떻게 이해하고 있는지를 드러내는 설계 결정이다. 기술 스택이나 프레임워크의 관례가 아니라, 비즈니스 도메인의 개념과 변화 축(change axis) 을 기준으로 코드를 조직한다. 구조를 보는 것만으로 이 시스템이 어떤 문제를 풀고 있는지 파악할 수 있어야 한다.
디렉토리 구조 원칙
1) Feature-First 구조를 기본으로 한다
디렉토리를 구성할 때 기술 계층(controller, service, repository)을 최상위 기준으로 삼는 Layer-First 방식보다, 도메인 기능(order, payment, member)을 최상위 기준으로 삼는 Feature-First 방식을 기본으로 채택한다.
Layer-First 구조는 기술적 역할이 명확히 드러나지만, 하나의 기능을 수정하려면 여러 디렉토리를 동시에 탐색해야 하고 도메인 개념이 구조에서 사라진다. 반면 Feature-First 구조는 하나의 기능 단위로 응집된 코드가 한 곳에 모여 있어, 변경의 파급 범위를 예측하기 쉽고 도메인 의도가 디렉토리 이름 자체에 드러난다.
2) 패키지 구성 원칙
각 기능 패키지 내부는 계층(layer) 기준으로 다시 나눈다. 계층 구분은 의존성 방향을 강제하고 Domain Layer를 보호하기 위한 수단이다. 계층 내 세부 구조는 언어별 상세 가이드를 따른다.
모듈을 분리할 때는 다음 기준을 적용한다. 변화의 이유가 다른가, 배포 단위가 다른가, 팀의 소유권이 다른가. 이 세 가지 중 하나라도 해당한다면 분리를 검토한다. 반대로, 단순히 코드량이 많다거나 기술적 역할이 다르다는 이유만으로 모듈을 나누는 것은 조급한 분리다.
계층 아키텍처와 의존성 방향 (SoC)
1) Domain Layer는 최우선으로 보호된다
시스템은 다음 네 계층으로 구성되며, 의존성은 항상 바깥에서 안쪽 방향 으로만 흐른다. 안쪽 계층은 바깥 계층을 알지 못하고, 알아서도 안 된다.
- Domain Layer 는 비즈니스 규칙과 도메인 지식이 살아있는 핵심이다. 이 계층은 프레임워크, 데이터베이스, 외부 API, 라이브러리로부터 철저히 격리되어야 한다. Domain Model이 ORM 어노테이션이나 프레임워크 어노테이션, HTTP 응답 구조, 외부 라이브러리의 타입에 오염되는 순간, 도메인 지식은 기술 세부사항에 잠식된다.
- Infrastructure Layer 는 외부 의존성을 Adapter/Port 패턴으로 격리한다. DB, 외부 API, 메시징 시스템 등 기술적 세부사항은 Domain Layer가 정의한 계약(Port)을 구현하는 형태로 존재한다. 안쪽 계층이 바깥 구현이 아니라 자신이 정의한 추상에 의존하게 만드는 이 배치가 의존성 역전 원칙(DIP, Dependency Inversion Principle)이다. 덕분에 기술 스택이 바뀌어도 Domain Layer는 변경되지 않는다.
- Application Layer 는 도메인 객체들의 협력을 조율하는 얇은 계층이다. 비즈니스 규칙을 직접 보유하지 않고, Domain Layer에 위임한다. 트랜잭션 경계와 Use Case의 흐름을 관리하는 것이 이 계층의 책임이다.
- Presentation Layer(Interface Layer) 는 HTTP 핸들러, CLI, 메시지 컨슈머처럼 외부와 맞닿는 입출력을 담당한다. 요청을 Application Layer가 이해하는 형태로 바꾸고 결과를 되돌려줄 뿐, 비즈니스 규칙을 갖지 않는다.
비즈니스 규칙은 반드시 Domain Model 내부에 명시적으로 표현 되어야 한다. 중요한 규칙이 Controller, SQL 쿼리, UI 검증, 프레임워크 어노테이션, 설정 파일 등에 흩어져 있으면, 코드를 읽는 것만으로 비즈니스 의도를 파악할 수 없게 된다.
2) 순환 참조는 절대 허용하지 않는다
모듈 간 의존성은 반드시 단방향이어야 한다. A가 B를 참조하면 B는 A를 참조할 수 없다. 순환 참조는 결합도의 가장 위험한 형태로, 변경의 파급 범위를 예측할 수 없게 만들고 독립적인 테스트와 배포를 불가능하게 한다. 순환 참조가 발생했다면, 그것은 책임 분리가 잘못되었다는 신호이므로 설계를 재검토해야 한다.
3) 상속보다 합성(Composition over Inheritance)을 선호한다
코드 재사용과 확장성을 높이기 위한 수단으로 상속보다 합성을 우선 검토한다. 상속은 부모와 자식 사이에 강한 결합을 만든다. 부모 클래스의 내부 구현이 변경되면 자식 클래스가 영향을 받고, 상속 계층이 깊어질수록 변경의 파급 범위를 예측하기 어렵다. 합성은 필요한 기능을 가진 객체를 내부에 보유하고 그 객체에 일을 위임하는 방식으로, 결합도가 낮고 런타임에 대상을 교체하는 것도 가능하다. “IS-A” 관계가 명확히 성립하는 경우에만 상속을 사용하고, “HAS-A” 또는 기능 재사용이 목적이라면 합성을 선택한다.
4) 개방/폐쇄 원칙(OCP)을 의식한다
소프트웨어 엔티티(클래스, 모듈, 함수)는 확장에 대해 열려 있고 수정에 대해 닫혀 있어야 한다. 새로운 요구사항이 생겼을 때 기존 코드를 직접 수정하지 않고 새 코드를 추가하는 방식으로 대응할 수 있어야 한다. 이를 위해 변경 가능성이 높은 부분(외부 API 연계, 비즈니스 규칙, 데이터 포맷)을 인터페이스나 추상 클래스로 격리하고, 구체 구현은 주입되도록 설계한다. 앞서 언급한 DIP와 맞닿아 있으며, 두 원칙이 함께 적용될 때 변경에 강한 구조가 만들어진다.
5) 의존성은 생성자나 함수 인자로 명시적으로 전달한다
DI 컨테이너가 필드에 직접 의존성을 주입하는 방식은 편리하지만, 그 객체가 실제로 무엇에 의존하는지 코드를 실행하지 않고는 파악하기 어렵게 만든다. 의존성을 생성자나 함수 인자로 전달하면 시그니처만으로 의존 관계가 드러나고, 테스트에서 대역으로 교체하기도 쉬워진다. 특히 비즈니스 규칙을 계산하는 Domain Layer의 함수는 DI 컨테이너의 존재를 전혀 알지 못한 채로 작성하는 것이 이상적이다. 컨테이너는 Application Layer나 Infrastructure Layer가 구성 요소를 조립하는 지점에서만 사용하고, Domain Layer의 시그니처에는 컨테이너의 흔적이 드러나지 않게 한다. 이는 1장에서 다룬 명시적 의도(Explicit Intent) 원칙을 의존성 관리에 적용한 것이다.
공개 API 경계
1) 공개 범위는 최소화한다
모듈의 공개 API(public interface)는 외부에 드러낼 필요가 있는 것만 노출한다. 내부 구현 세부사항은 철저히 은닉한다. 공개 범위가 넓을수록 변경 시 영향받는 범위가 넓어지고, 외부에서 내부 구현에 의존하는 코드가 생겨 유지보수가 어려워진다.
내부 구현이 외부로 노출된 코드는 리팩토링의 자유를 잃는다. 외부에 공개된 것은 계약(contract)이 되고, 그 계약은 변경 비용을 높인다.
2) 안정적인 API와 내부 구현을 구분한다
공개 API는 한 번 외부에 노출되면 변경이 어렵다. 따라서 안정성이 높고 변화가 적은 것만 공개 API로 승격한다. 아직 설계가 확정되지 않았거나 변경 가능성이 높은 것은 내부로 유지하고, 필요한 시 점에 점진적으로 공개한다.
모듈이 외부에 제공하는 진입점(entry point)을 명확히 정의하고, 그 경계 밖에서는 내부 구조를 직접 참조하지 않는다. 경계를 넘는 모든 통신은 공개 인터페이스를 통해서만 이루어진다.
Bounded Context 간 관계
지금까지 다룬 구조 원칙은 하나의 코드베이스 안에서 모듈을 어떻게 나누는지를 다뤘다. 하지만 여러 팀이나 여러 서비스로 시스템이 커지면, 코드베이스 경계를 넘어서는 관계도 명시적으로 설계해야 한다. 두 팀이 같은 용어를 서로 다른 의미로 쓰고 있다면, 그 자체가 경계가 잘못 그어졌다는 신호다. “주문”이라는 단어가 물류 팀에서는 배송 대상을, 결제 팀에서는 청구 대상을 가리킨다면 두 팀은 같은 도메인 모델을 공유해서는 안 되며 별도의 Bounded Context로 분리해야 한다.
Bounded Context 사이의 관계는 팀 사이의 협력 방식과 기술적 통합 방식을 함께 결정한다. 관계를 명시적으로 정하지 않으면, 상류(upstream) 팀의 임의 변경이 하류(downstream) 팀을 예고 없이 무너뜨리는 일이 반복된다.
| 관계 | 설명 | 적용 상황 |
| Partnership | 두 팀이 성공과 실패를 함께 책임지며 긴밀히 동기화한다 | 두 컨텍스트가 사실상 하나의 목표를 공유할 때 |
| Shared Kernel | 작은 공통 모델을 두 컨텍스트가 함께 소유하고 함께 변경한다 | 중복 제거의 이득이 결합 비용보다 클 때만 |
| Customer-Supplier | 상류가 하류의 요구사항을 반영해 API를 제공한다 | 상류 팀이 하류의 요청에 협조적일 때 |
| Conformist | 하류가 상류의 모델을 그대로 따른다 | 상류를 바꿀 권한이나 협상력이 없을 때 |
| Anticorruption Layer(ACL) | 하류가 번역 계층을 두어 상류 모델의 변경으로부 터 자신을 보호한다 | 상류 모델이 자신의 도메인 언어와 맞지 않거나 신뢰할 수 없을 때 |
| Open Host Service(OHS) | 상류가 여러 소비자를 위한 공개 API를 제공한다 | 다수의 하류 컨텍스트가 동일한 데이터를 필요로 할 때 |
| Separate Ways | 통합하지 않고 각자 독립적으로 구현한다 | 통합 비용이 얻는 이득보다 클 때 |
이 중 실무에서 가장 자주 필요한 것은 Anticorruption Layer다. 외부 시스템이나 레거시 컨텍스트의 모델을 Domain Layer로 직접 끌어들이면, 그 컨텍스트의 언어와 변경 주기가 우리 도메인을 그대로 오염시킨다. ACL은 앞서 다룬 Adapter/Port 패턴을 컨텍스트 경계 수준으로 확장한 것으로, 외부 모델을 번역하는 책임을 명확한 경계 안에 가둔다.
관계 유형을 고를 때는 팀 사이의 협상력과 조직 구조를 먼저 인정해야 한다. 기술적으로는 Partnership이 이상적으로 보여도, 상류 팀이 협조하지 않는 조직 구조에서 그 관계를 강제할 수는 없다. 그런 상황이라면 Conformist나 ACL을 선택하는 것이 현실적인 판단이다. Context Map은 기술 문서이기 이전에 팀 사이의 관계를 드러내는 문서이며, 조직 구조를 무시하고 이상적인 관계만 그려 넣은 문서는 실제로 지켜지지 않는다.
구조 설계 시 피해야 할 것들
좋은 구조만큼이나, 잘못된 구조의 패턴을 인식하는 것도 중요하다.
1) 과도한 레이어링은 복잡성을 증가시킨다
모든 요청이 의미 없이 다섯 개 이상의 계층을 통과하도록 설계된 구조는, 이해와 탐색 비용을 높이고 실제 도메인 로직이 어디에 있는지 찾기 어렵게 만든다. 계층은 목적이 있을 때만 도입한다.
3. 네이밍 규칙 (Naming)
이름은 설계 행위다. 이름을 짓는 것은 단순한 표기 선택이 아니라 설계 행위다. 좋은 이름은 코드를 읽는 사람에게 의도, 역할, 제약, 부수효과 가능성까지 전달한다. 반대로 나쁜 이름은 코드의 동작을 숨기고, 읽는 사람이 코드를 실행하거나 주석을 뒤져야만 의도를 파악할 수 있게 만든다.
이름은 코드에서 가장 많이 읽히는 요소다. 작성 비용은 한 번이지만 독해 비용은 수십 번 반복된다. 좋은 이름 하나가 주석 열 줄보다 낫고, 나쁜 이름 하나가 버그의 온상이 된다.
일반 원칙
1) 의도와 도메인을 드러내는 이름을 사용한다
이름은 무엇(what) 인지와 왜(why) 존재하는지를 드러내야 한다. 기술적 구현 방식이 아니라 도메인 개념과 비즈니스 행동을 기준으로 이름을 결정한다. 도메인 전문가와 개발자가 일상적으로 사용하는 동일한 언어(Ubiquitous Language)를 코드, 테스트, 문서, 커밋 메시지 전반에 일관되게 사용한다. 코드에서 쓰는 용어와 기획서나 회의에서 쓰는 용어가 다르다면, 그 간극이 오해와 버그의 출발점이 된다.
2) 축약은 최소화한다
축약어는 작성자의 타이핑 시간을 줄이지만, 읽는 사람의 해독 시간을 늘린다. 팀 전체가 명백히 공유하는 약어(예: id, url, dto)가 아닌 이상 축약하지 않는다. 길더라도 명확한 이름이 짧지만 모호한 이름보다 항상 낫다.
3) 이름은 검색 가능해야 한다
이름은 코드베이스 전체에서 검색했을 때 의미 있는 결과를 돌려줄 수 있어야 한다. 단일 문자 변수나 숫자 리터럴은 검색이 불가능하다. 범위가 작은 루프 인덱스를 제외하면, 단일 문자 이름은 사용하지 않는다.
타입별 네이밍 기준
1) 클래스 (Class)
클래스 이름은 명사 또는 명사구로 짓는다. 클래스가 표현하는 도메인 개념이 이름에 직접 드러나야 한다. 클래스가 무슨 일을 하는지가 아니라, 무엇을 나타내는지를 이름으로 표현한다. 클래스 이름에 Manager, Handler, Processor, Helper 같은 모호한 접미사가 붙기 시작하면, 그 클래스가 너무 많은 책임을 갖고 있다는 신호다. 이름이 명확히 붙지 않는다면 설계를 먼저 재검토한다.
2) 함수 / 메서드 (Function / Method)
함수 이름은 동사 또는 동사구 로 짓는다. 함수가 수행하는 행동을 명확히 드러내야 하며, 부수효과(side effect)가 있다면 이름에서 예상 가능해야 한다. 반환값이 boolean인 함수는 is, has, can, should 등의 접두사를 붙여 질문 형태로 표현한다.
변수 (Variable)
변수는 저장하는 값의 도메인 의미를 드러내야 한다. 같은 타입의 변수가 둘 이상 있을 때 타입 이름을 그대로 변수명으로 쓰면 역할이 구분되지 않으므로, 도메인 역할을 이름에 담는다. 컬렉션 변수는 복수형 으로 명명한다. 단수형 컬렉션 이름은 단일 객체와 혼동을 유발한다.
1) 상수 (Constant)
상수는 코드에 등장하는 이유와 비즈니스 의미를 이름으로 드러낸다. 값 자체를 이름에 포함시키지 않는다. 상수명은 언어별 컨벤션에 따르되, 의미를 최우선으로 한다. 매직 넘버와 매직 스트링은 절대 코드에 직접 사용하지 않는다. 의미 없는 리터럴 값은 코드의 의도를 숨기고, 변경 시 누락의 원인이 된다.
2) 인터페이스 (Interface)
인터페이스는 능력(capability) 또는 역할(role) 을 표현하는 이름을 사용한다. 구현 세부사항이 아닌 계약(contract)의 의미를 담아야 한다. 언어에 따라 I 접두사 또는 able 접미사 등의 컨벤션은 언어별 상세 가이드를 따른다. 인터페이스 이름이 구현체와 지나치게 유사하거나(IOrderService / OrderServiceImpl), 의미가 중첩된다면, 인터페이스의 추상화 수준을 다시 검토한다.
3) 커맨드 (Command)
커맨드는 시스템에 특정 행동을 요청하는 의도를 표현하므로, 명령형 동사로 명명한 다(CreateOrder, CancelBooking, ApprovePayment). 커맨드 이름과 그 커맨드가 성공했을 때 발행되는 이벤트 이름은 짝을 이루도록 설계한다(CreateOrder가 성공하면 OrderCreated). 이 짝을 의식적으로 맞추면, 코드를 읽는 사람이 무엇을 요청했고 그 결과 무엇이 일어났는지를 이름만으로 추적할 수 있다. 커맨드는 유효성 검증 실패나 권한 부족으로 거부될 수 있으므로, 항상 성공을 전제하는 이름은 피한다.
4) 이벤트 (Event)
이벤트는 이미 발생한 사실 을 표현하므로, 과거형으로 명명한다. 이벤트 이름은 도메인 전문가가 사용하는 비즈니스 언어를 그대로 반영한다. 이벤트를 처리하는 핸들러는 on 접두사를 붙여 이벤트에 반응하는 역할임을 명확히 한다.
5) 비동기 함수 (Async Function)
비동기 함수임을 이름에서 명시적으로 드러내는 것이 원칙이다. 언어 수준에서 비동기 여부가 타입이나 키워드로 충분히 표현되는 경우(예: TypeScript의 Promise<T>, Kotlin의 suspend)에는 별도 접미사 없이도 괜찮지만, 팀 컨벤션을 일관되게 유지한다. 비동기 함수와 동기 함수를 같은 이름으로 혼용하지 않는다. 혼용은 호출하는 쪽에서 비동기 여부를 코드를 읽지 않으면 알 수 없게 만든다.
6) 테스트명 (Test Name)
테스트 이름은 어떤 상황에서, 어떤 동작을 했을 때, 어떤 결과가 나오는지 를 명확히 드러내야 한다. 테스트는 문서의 역할도 겸하기 때문에, 이름만 읽고도 무엇을 검증하는지 이해할 수 있어야 한다. 테스트 이름에 도메인 언어를 사용하면, 테스트 목록이 곧 비즈니스 명세가 된다.
금지 패턴
1) util / helper / common 남용
utils, helpers, common 같은 이름의 모듈이나 클래스는 관련 없는 로직의 쓰레기통이 되기 쉽다. 이런 이름이 붙은 순간, 그 안에 무엇이 있는지 이름만으로 알 수 없게 된다. 공통 코드가 필요하다면, 그 코드가 속한 도메인 개념을 먼저 찾는다. 명확한 도메인 개념이 없다면 각자의 맥락에 두는 것이 낫다. 억지로 공통화하면 불필요한 결합만 생긴다.
2) Manager / God Object
하나의 클래스가 너무 많은 책임을 가질 때 흔히 Manager, Controller(도메인 수준), Coordinator, Orchestrator 같은 이름이 붙는다. 이런 이름은 설계가 무너지고 있다는 경고 신호다. 클래스가 표현하는 도메인 개념을 이름으로 특정할 수 없다면, 책임이 과도하게 집중되어 있다는 신호다. 이 경우 이름을 고치기 전에 설계를 먼저 분리해야 한다.
3) data / info / temp 등 의미 없는 이름
data, info, result, temp, obj, value 같은 이름은 아무것도 설명하지 않는다. 모든 변수는 데이터이고, 모든 반환값은 결과이며, 모든 객체는 객체다. 이런 이름은 읽는 사람에게 맥락과 의미를 전혀 전달하지 못한다.
4) 기술 용어가 도메인 용어를 압도하는 경우 (Technical Naming Dominance)
기술적 구현 방식이 도메인 개념보다 이름에서 더 크게 드러나는 것을 경계한다. 코드는 기술 시스템이기 전에 도메인 시스템이다. 도메인 전문가가 코드의 이름을 보고 낯설게 느낀다면, 그 이름은 재검토 대상이다.
4. 코드 스타일 (Code Style)
스타일은 일관성이 목적이다. 코드 스타일 규칙의 목적은 특정 방식이 다른 방식보다 절대적으로 우월해서가 아니다. 팀 전체가 동일한 방식으로 코드를 작성하면, 읽는 사람이 형식에 소비하는 인지 자원을 줄이고 내용에 집중할 수 있게 된다. 일관성은 이해 속도, 리뷰 품질, 유지보수성을 동시에 높인다.
포맷팅처럼 기계적으로 검사 가능한 것은 자동화한다. formatter와 linter가 강제할 수 있는 규칙 은 도구에 위임하고, 사람은 도메인 이해와 설계 판단에 집중한다. 스타일 논쟁은 자동화로 종결한다.
포맷팅 (Formatting)
1) 들여쓰기와 줄 길이
들여쓰기 방식(스페이스/탭)과 단위는 언어별 상세 가이드에서 정의하며, 프로젝트 내에서 혼용하지 않는다. 들여쓰기 깊이가 깊어질수록 코드의 복잡도가 높아지고 있다는 신호이므로, 깊은 들여쓰기는 로직 분리의 기회로 인식한다. 줄 길이는 한 줄에 담 을 수 있는 정보의 양을 제한하여 가로 스크롤 없이 코드를 읽을 수 있게 한다. 구체적인 최대 길이는 언어별 상세 가이드를 따른다. 줄이 길어진다면 표현식이 너무 많은 일을 하고 있다는 신호일 수 있으며, 의미 있는 단위로 분리를 검토한다.
2) 공백
공백은 코드의 논리적 단위를 시각적으로 구분하는 수단이다. 관련 있는 코드는 가까이, 관련 없는 코드는 공백 한 줄로 구분한다. 공백 없이 모든 로직을 붙여 쓰는 것은 문단 구분 없는 글과 같다.
3) Import 정렬
import 구문은 자동 정렬 도구에 위임한다. 그룹 구분과 순서 기준은 언어별 상세 가이드에서 정의하며, 미사용 import는 항상 제거한다. 와일드카드 import(import *)는 어떤 심볼이 어디서 오는지 숨기므로 원칙적으로 사용하지 않는다.
4) Trailing Comma
컬렉션, 파라미터, 인수 목록의 마지막 항목에 trailing comma를 허용하는 언어에서는 일관되게 사용한다. Trailing comma는 항목을 추가하거나 순서를 변경할 때 diff를 깔끔하게 유지하고, 코드 리뷰 시 불필요한 변경 노이즈를 줄인다.
5) 대칭 원리(Symmetry Principle)를 지킨다
쌍을 이루는 연산(open/close, lock/unlock, acquire/release, init/cleanup)은 반드시 짝이 맞게 처리한다. 한쪽을 수행했으면 예외가 발생하더라도 반드시 반대쪽도 수행해야 하며, 이를 지키지 않으면 리소스 누수, 데드락, 불완전한 초기화 같은 버그가 발생한다. 언어가 제공하는 자동 해제 메커니즘(try-with-resources, using, RAII)을 활용하면 컴파일러와 런타임이 대칭을 보장하므로 적극 사용한다.
표현식 스타일 (Expression Style)
1) Early Return과 Guard Clause로 중첩을 최소화한다
중첩(nesting)이 깊어질수록 코드를 이해하기 위해 머릿속에 유지해야 하는 문맥이 늘어난다. 중첩은 복잡성의 가장 직접적인 지표이며, 읽는 사람의 인지 부하를 높인다.
- Guard Clause 는 함수의 진입 조건을 초반에 빠르게 검사하고 조기에 반환하여, 이후 코드가 항상 유효한 상태에서 실행됨을 보장한다. 조건을 충족하지 못하는 경우를 먼저 처리하고, 핵심 로직은 들여쓰기 없이 평탄하게 유지한다.
- Early Return 은 함수 내에서 조건이 충족된 시점에 즉시 반환하여, 이후 로직이 불필요한 분기를 타지 않도록 한다. “정상 흐름(happy path)“이 코드의 메인 흐름으로 읽히도록 유지한다.
2) 조건식을 단순하고 명시적으로 유지한다
복잡한 boolean 표현식은 의도를 드러내는 이름의 변수나 메서드로 추출한다. 조건식을 읽는 것만으로 무엇을 검사하는지 알 수 있어야 하며, 조건의 의미를 해독하기 위해 코드를 거슬러 올라가야 한다면 추출을 고려한다. 삼항 연산자는 단순하고 명확한 경우에만 사용한다. 중첩 삼항 연산자는 어떤 경우에도 사용하지 않는다. 읽는 데 한 번 이상 눈이 멈춘다면, 일반 조건문으로 풀어낸다. 복잡성을 줄이는 순서는 6장에서 다루듯 상태, 결합도, 분기, 코드량 순이다. 분기를 줄이는 가장 좋은 방법은 애초에 잘못된 상태가 만들어지지 않도록 모델을 설계하는 데 있다.
함수 스타일 (Function Style)
1) 함수는 하나의 일만 한다 (SRP)
함수는 한 가지 일을 하고, 그 일을 잘 해야 한다. 함수의 추상화 수준은 일관되어야 하며, 하나의 함수 안에서 고수준 오케스트레이션과 저수준 구현 세부사항이 섞이면 안 된다(SLAP). 함수 길이에 절대적인 기준은 없지만, 한 화면(약 20~30줄)을 넘기 시작하면 책임이 과도하게 집중되고 있다는 신호로 인식한다. 함수가 길어지는 이유는 대부분 한 가지 이상의 일을 하기 때문이다. 명확한 의미 단위로 분리하고, 분리된 함수에 도메인 의미가 담긴 이름을 붙인다.
2) 파라미터 개수를 제한한다
파라미터가 많아질수록 함수의 책임이 불명확해지고, 호출하는 쪽에서 인수의 순서와 의미를 기억해야 하는 부담이 늘어난다. 파라미터는 원칙적으로 3개 이하를 권장하며, 그 이상이 필요하다면 관련 파라미터를 묶는 도메인 객체(Value Object, DTO)로 추출한다. boolean 파라미터는 함수가 두 가지 일을 하고 있다는 신호다. 가능하면 두 개의 명확한 함수로 분리한다.
3) 부수효과(Side Effect)를 명시적으로 관리한다
함수가 외부 상태를 변경하거나, 외부 시스템에 영향을 미치거나, I/O를 수행한다면 그 함수는 부수효과를 가진다. 부수효과는 나쁜 것이 아니지만, 예측 불가능한 부수효과 는 버그의 가장 흔한 원인이다. 부수효과가 있는 함수와 없는 함수를 명확히 구분하고, 부수효과는 이름에서 예상 가능하도록 한다. 값을 계산하는 함수가 예상치 못하게 외부 상태를 변경하거나, 데이터베이스에 쓰는 행위를 숨기는 것은 가장 위험한 패턴이다.
4) 순수 함수(Pure Function)를 우선적으로 선호한다
순수 함수는 동일한 입력에 항상 동일한 결과를 반환하며, 외부 상태를 변경하지 않는다. 순수 함수는 테스트가 쉽고, 이해하기 쉬우며, 예측 가능하다. 이 세 가지는 모두 변경 안전성과 직결된다. 모든 함수를 순수 함수로 만들 수는 없다. 데이터베이스 저장, 외부 API 호출, 로깅은 본질적으로 부수효과를 동반한다. 그러나 비즈니스 규칙을 표현하는 로직은 최대한 순수 함수로 구성하고, 부수효과를 동반하는 부분은 함수의 바깥 경계로 밀어내는 구조를 지향한다.
5. 타입 시스템 활용 (Type System)
타입은 도메인 지식을 인코딩하는 수단이다. 타입 시스템은 컴파일러가 오류를 잡아주는 도구이기 이전에, 도메인 개념을 코드로 표현하는 설계 수단 이다. 좋은 타입 설계는 잘못된 상태를 런타임 이전에 차단하고, 코드를 읽는 사람에게 도메인의 제약과 의도를 타입 자체로 전달한다.
타입을 단순히 데이터의 저장 형식으로만 사용하면 타입 시스템의 나머지 절반을 놓친다. 타입이 도메인 개념을 온전히 표현할 때, 컴파일러는 비즈니스 규칙의 첫 번째 수호자가 된다. 이 섹션은 언어별 차이가 크므로 언어 공 통 원칙 만 정의한다. 구체적인 문법과 구현 방식은 언어별 상세 가이드를 따른다.
강한 타입을 선호한다
가능한 한 강한 타입(strong type)을 사용한다. 타입이 약하거나 모호할수록, 컴파일러가 잡아낼 수 있었던 오류가 런타임으로 밀려난다. Any, Object, unknown, dynamic 같은 최상위 타입은 타입 시스템을 사실상 무력화하며, 코드의 의도를 숨긴다.
타입 캐스팅은 런타임 검사를 동반해야 한다. 컴파일러가 허용했다고 안전하지는 않다. 명시적인 타입 검사 없는 강제 캐스팅은 타입 시스템을 우회하는 행위이며, 런타임 오류의 원인이 된다.
Primitive Obsession을 방지한다
String, int, boolean 같은 기본 타입만으로 도메인 개념을 표현하는 것을 Primitive Obsession 이라 한다. 이는 코드에서 반복적으로 나타나는 가장 흔한 안티패턴 중 하나다.
기본 타입은 도메인 제약을 표현하지 못한다. String으로 선언된 email은 형식이 올바른지 보장하지 않고, int로 선언된 price는 음수가 될 수 없다는 규칙을 담지 못한다. 기본 타입을 그대로 사용하면 동일한 타입의 값을 혼용하는 버그(예: customerId와 orderId를 바꿔 전달)를 컴파일러가 잡을 수 없다.
도메인 개념을 표현하는 값은 Value Object 로 감싼다. Value Object는 유효성 검증을 생성 시점에 수행하며, 해당 도메인 개념에 속하는 행동을 함께 보유한다.
Nullable 처리 원칙
null은 “값이 없음”을 표현하는 가장 오래된 방법이지만, 가장 위험한 방법이기도 하다. null은 타입 시스템 밖에 있어 컴파일러가 추적하지 못하고, 런타임에서야 NullPointerException 으로 드러난다. 또한 null의 의미가 “아직 모름”, “존재하지 않음”, “선택적 값” 중 무엇인지 코드만으로 구분할 수 없다.
1) null 대신 명시적인 Optionality를 사용한다
언어가 제공하는 명시적인 Optional 타입(Option<T>, Optional<T>, Maybe<T>, T?)을 사용하여 “값이 없을 수 있다”는 사실을 타입으로 표현한다. 이렇게 하면 호출하는 쪽에서 null 여부를 반드시 처리하도록 타입 시스템이 강제하고, 예상치 못한 null 전파를 방지한다.
2) null 전파를 허용하지 않는다
null을 반환받은 쪽에서 null 여부를 확인하지 않고 다음 레이어로 전달하는 것은 null 전파 지옥을 만드는 지름길이다. null 여부는 발생 지점 가장 가까운 곳에서 처리하며, null을 다음 레이어로 흘려보내지 않는다. if (x != null) 체크를 단순히 추가하는 것은 근본 원인을 숨기는 임시방편이다. null이 발생한다면 그 지점의 설계를 재검 토해야 한다.
Enum 사용 기준
열거된 상태와 선택지를 표현할 때는 String이나 int 상수 대신 Enum 을 사용한다. Enum은 허용되는 값의 범위를 타입으로 제한하며, 새로운 값이 추가될 때 컴파일러가 처리되지 않은 케이스를 감지할 수 있게 한다.
Enum은 단순한 상수 집합을 넘어 도메인 행동을 보유할 수 있다. 상태에 따라 다른 행동이 필요하다면, switch/when 문 대신 Enum 자체에 행동을 정의하는 것을 검토한다.
switch/match 문은 모든 Enum 값을 명시적으로 처리한다. 언어가 exhaustive check를 지원하면 default나 else를 두지 않는다. default가 있으면 새 Enum 값이 추가되어도 컴파일러가 누락을 알려주지 못하고 조용히 default로 흘러간다. exhaustive check가 없는 언어에서만 default를 두되, 그 안에서는 예상치 못한 값임을 즉시 실패로 드러낸다.
Value Object 사용 기준
Value Object는 도메인 개념을 타입으로 표현하면서, 유효성 규칙과 도메인 행동을 함께 보유하는 불변 객체다. 다음 기준 중 하나 이상에 해당하면 Value Object 도입을 검토한다.
- 기본 타입에 유효성 제약 이 있는 경우 (예: 이메일 형식, 양수만 허용하는 금액)
- 같은 타입의 값이 다른 도메인 의미 를 가지는 경우 (예:
latitude와longitude는 모두Double이지만 혼용하면 좌표가 뒤집힘) - 특정 값에 속하는 도메인 행동 이 존재하는 경우 (예:
Money.add(),Email.getDomain()) - 유효성 검증 로직이 여러 곳에서 중복 되는 경우
Value Object는 불변(immutable) 으로 설계한다. 상태가 변경되어야 한다면 새로운 Value Object를 반환한다. 불변성은 공유해도 안전하고, 동시성 문제에서 자유롭다.
Generic 사용 기준
Generic은 타입 안전성을 유지하면서 재사용 가능한 코드를 작성하기 위한 수단이다. Generic을 사용할 때는 타입 파라미터의 의미가 명확해야 하며, 타입 파라미터 이름은 단일 문자(T, E) 보다 의미를 드러내는 이름을 사용한다.
단, Generic의 복잡도가 코드를 이해하기 어렵게 만들 정도라면 과도한 추상화일 수 있다. Generic이 인지 부하를 줄이는 것이 아니라 오히려 높인다면, 명시적인 타입을 사용하는 것이 낫다. “이 Generic을 이해하려면 타입 파라미터가 어떻게 사용되는지 모두 추적해야 한다”면 설계를 재검토한다.
Type Alias 사용 기준
Type Alias(타입 별칭)는 기존 타입에 도메인 의미를 부여하는 가벼운 방법이다. Value Object를 도입할 정도는 아니지만, 타입의 의미를 명확히 하고 싶을 때 사용한다.
단, Type Alias는 컴파일러 수준에서 타입 안전성을 보장하지 못하는 언어도 있다. 언어에 따라 Type Alias가 단순한 문서화 수단에 그치는 경우, 유효성 검증이 필요하다면 Value Object를 선택한다.
잘못된 상태 자체를 불가능하게 설계한다
타입 시스템의 궁극적인 목표는 잘못된 상태를 표현할 수 없게 만드는 것 이다. 런타임에 방어 코드를 여러 겹 쌓는 것보다, 그런 상태 자체가 생성되지 않도록 모델링하는 것이 근본적인 해결책이다.
상태 전이(state transition)가 있는 도메인 개념은 허용되는 전이만 타입 수준에서 표현한다. “주문은 취소된 이후에 배송될 수 없다”는 규칙이 조건문이 아닌 타입 구조로 강제될 때, 그 규칙은 코드 어디에서도 우회될 수 없다.
비즈니스 불변 조건(Business Invariant)은 도메인 모델이 직접 보호한다. 불변 조건이란 시스템이 어떤 상태에 있든 반드시 참이어야 하는 규칙이다. “계좌 잔액은 음수가 될 수 없다”, “주문 항목은 최소 하나 이상이어야 한다”처럼 도메인 규칙 자체가 불변 조건이다. 이 조건을 Service 계층의 조건문으로 분산시키면, 조건이 누락되거나 우회되는 경로가 생긴다. 불변 조건 위반은 도메인 모델 내부에서 즉시 감지하고 의미 있는 도메인 예외로 반환한다.
여러 Aggregate에 걸친 불변 조건은 단일 트랜잭션으로 강제할 수 없다. 이 경우 결과적 일관성(eventual consistency)을 의식적으로 선택하고, 불변 조건 위반이 발생했을 때의 보상 로직을 설계 시점에 명시한다. “지금 당장 일관성을 보장할 수 없다”는 사실을 암묵적으로 숨기지 않고, 시스템이 언제, 어떻게 일관성을 회복하는지를 코드 수준에서 표현한다.
워크플로우의 단계를 타입으로 표현한다
앞서 다룬 원칙이 하나의 값이 가질 수 있는 상태를 타입으로 제한하는 것이었다면, 이 원칙은 값이 여러 단계를 거치며 처리되는 워크플로우 전체에 같은 발상을 적용한다. 하나의 요청이 검증, 계산, 확정 같은 단계를 통과할 때마다 그 값에 대해 보장할 수 있는 사실이 늘어난다. 이 신뢰 수준의 상승을 주석이나 함수 이름만으로 표현하면, 어떤 함수가 어느 단계의 값을 기대하는지는 코드를 실행해봐야 알 수 있다.
신뢰 수준이 바뀔 때마다 별도의 타입을 만들고, 각 단계를 그 타입 사이를 잇는 함수로 표현하면 이 정보가 컴파일 타임에 강제된다.
UnvalidatedOrder → ValidatedOrder → PricedOrder → AcknowledgedOrder각 타입은 그 값을 받은 코드가 무엇을 믿어도 되는지를 표현한다. ValidatedOrder는 상품 코드와 배송지가 실재함을 보장하지만 아직 가격은 계산되지 않은 상태이고, PricedOrder는 각 항목의 가격과 합계가 확정된 상태다. validateOrder(order: UnvalidatedOrder): Result<ValidatedOrder, ValidationError>처럼 함수 시그니처만 보 고도 이 함수가 무엇을 검증 완료 상태로 만드는지 알 수 있고, 검증되지 않은 값을 가격 계산 함수에 실수로 전달하는 것은 컴파일 오류가 된다.
이 패턴을 적용할 때는 다음을 함께 지킨다.
- 외부 I/O는 파이프라인의 양 끝에 둔다. 각 단계를 잇는 변환 함수는 가능한 한 순수 함수로 유지하고, 데이터베이스 조회나 외부 API 호출 같은 부수효과는 파이프라인의 입력 직전과 출력 직후로 밀어낸다. 중간 단계에 I/O가 섞이면 그 단계는 더 이상 순수 함수로 테스트할 수 없다.
- 불필요하게 단계를 쪼개지 않는다. 모든 검증 항목마다 별도의 타입을 만들면 타입 수가 늘어나 오히려 인지 부하가 커진다. 새 단계는 이후의 코드가 실제로 의존하는 새로운 보장이 생길 때만 추가한다.
- 각 단계에서 발생 가능한 실패는 그 단계의 반환 타입에 드러낸다. 7장에서 다루는 Result 타입 원칙을 각 단계에 그대로 적용하며, 단계별 에러는 하나의 에러 타입으로 뭉뚱그리지 않고 검증 에러, 가격 계산 에러처럼 원인별로 구분한다.
이 기법은 특정 프레임워크나 함수형 언어에 국한되지 않는다. 객체지향 언어에서도 각 단계를 별도의 불변 클래스로 표현하고 팩토리 메서드로 다음 단계를 생성하면 동일한 효과를 얻는다. 핵심은 “아직 검증되지 않음”과 “검증됨”을 같은 타입으로 뭉뚱그리지 않는 데 있다.
6. 데이터와 상태 관리 (State & Data)
상태는 복잡성의 근원이다. 소프트웨어의 복잡성은 상태(state) → 결합도(coupling) → 분기(branching) → 코드량 (code volume) 순으로 증가한다. 상태가 가장 먼저 나오는 것은 우연이 아니다. 상태는 복잡성의 가장 근본적인 원천이며, 상태를 잘 관리하는 것이 시스템의 예측 가능성과 변경 안전성을 결정한다.
상태 관리의 목표는 상태를 완전히 없애는 데 있지 않다. 상태는 소프트웨어의 본질적인 구성 요소다. 목표는 상태의 범위를 최소화하고, 상태 변경이 발생하는 지점을 예측 가능하게 만들며, 잘못된 상태가 존재할 수 없도록 설계하는 데 있다.
상태 관리 (State Management)
1) 가변 상태(Mutable State)를 최소화한다
변경 가능한 상태는 그것이 어디서, 언제, 누구에 의해 변경되었는지 추적해야 하는 부담을 만든다. 가변 상태가 많을수록 코드를 이해하기 위해 실행 흐름 전체를 머릿속에 유지해야 하며, 테스트의 신뢰성도 떨어진다. 변수와 필드는 기본적으로 불변(immutable) 으로 선언하고, 변경이 반드시 필요한 경우에만 가변으로 선언한다. 불변으로 선언된 것이 많을수록, 가변으로 선언된 것이 더 눈에 띄고 주의가 집중된다.
2) 불변 객체(Immutable Object)를 우선적으로 설계한다
불변 객체는 생성된 이후 상태가 변경되지 않는다. 불변 객체는 공유해도 안전하고, 동시성 환경에서 별도의 동기화 없이 사용할 수 있으며, 디버깅 시 상태 변경 경로를 추적할 필요가 없다. 특히 Value Object, 도메인 이벤트, DTO는 불변으로 설계하는 것을 기본으로 한다. 도메인 엔티티처럼 상태 변경이 본질적인 경우에도, 변경 메서드를 통해서만 상태가 바뀌도록 캡슐화하고 외부에서 직접 필드를 수정할 수 없게 한다.
3) 공유 가변 상태(Shared Mutable State)는 가장 위험하다
여러 곳에서 동시에 접근하고 변경할 수 있는 상태는 소프트웨어에서 가장 위험한 형태의 복잡성이다. 공유 가변 상태는 실행 순서에 따라 결과가 달라지는 레이스 컨디션(race condition) 의 직접적인 원인이며, 테스트 환경에서 재현하기 어려운 버그를 만들어낸다. 공유 가변 상태는 다음 세 가지 방향으로 해소한다.
- 불변으로 만들기: 공유하되 변경하지 않는다.
- 공유하지 않기: 변경하되 공유하지 않는다. 상태를 필요한 범위 안으로 가두고, 외부로 노출하지 않는다.
- 변경을 직렬화하기: 공유와 변경이 모두 필요하다면, 변경이 한 번에 하나씩만 발생하도록 보장한다.
전역 상태(global state)와 싱글톤의 가변 필드는 공유 가변 상태의 전형이다. 특별한 이유가 없는 한 전역 가변 상태는 사용하지 않는다.
데이터 모델 (Data Model)
1) DTO와 Domain Model을 명확히 분리한다
DTO(Data Transfer Object)와 Domain Model은 목적과 책임이 근본적으로 다르다. 이 두 가지를 하나의 객체로 혼용하면 도메인 모델이 외부 기술 요소에 오염되고, 계층 간 결합도가 높아진다.
| 구분 | Domain Model | DTO |
| 목적 | 비즈니스 규칙과 도메인 행동 표현 | 계층 간 또는 시스템 간 데이터 전달 |
| 행동 | 도메인 행동을 보유함 | 데이터 운반만 담당 (행동 없음) |
| 유효성 | 생성 시점에 도메인 규칙으로 검증 | 입력/출력 형식 검증 |
| 변경 원인 | 비즈니스 요구사항 변경 | API 스펙, 외부 시스템 변경 |
| 불변성 | 원칙적으로 불변 또는 제어된 가변 | 일반적으로 가변 허용 |
Domain Model이 직렬화 어노테이션, HTTP 응답 구조, 데이터베이스 컬럼 매핑에 직접 오염되는 것을 막는다. Domain Model은 기술 세부사항을 알지 못해야 하고, DTO가 그 변환을 담당한다.
2) Serialization 정책
직렬화/역직렬화는 Infrastructure Layer의 책임이 다. Domain Model이 직렬화 방식을 알아서는 안 된다. 직렬화 형식(JSON, Protobuf, Avro 등)이 변경되어도 Domain Model은 영향받지 않아야 한다. 역직렬화 시 외부에서 들어오는 데이터는 신뢰하지 않는다. 외부 경계(Trust Boundary)에서 입력 검증을 수행하고, 검증된 데이터만 Domain Model로 변환한다. 역직렬화된 객체를 검증 없이 Domain Model로 직접 매핑하는 것은 외부 입력을 도메인 내부로 그대로 통과시키는 행위다.
3) Schema Evolution (스키마 진화)
시스템은 시간이 지남에 따라 데이터 구조가 변경된다. 스키마 변경은 하위 호환성을 의식적으로 관리해야 한다. 특히 이벤트 소싱, 메시지 큐, 외부 API를 사용하는 환경에서는 스키마 변경이 기존 데이터와 소비자에게 미치는 영향을 항상 먼저 검토한다.
스키마를 진화시킬 때는 다음 원칙을 따른다.
- 추가는 안전하다: 새로운 필드 추가는 일반적으로 하위 호환이 가능하다.
- 삭제 와 이름 변경은 위험하다: 기존 소비자가 해당 필드에 의존할 수 있다. Deprecated 단계를 거쳐 점진적으로 제거한다.
- 타입 변경은 가장 위험하다: 기존 데이터와 새로운 스키마가 충돌할 수 있다. 타입 변경은 새로운 필드를 추가하고 기존 필드를 단계적으로 마이그레이션하는 방식을 사용한다.
- 버전 관리: API 스펙이나 이벤트 스키마가 변경될 때는 버전을 명시적으로 관리한다.
Aggregate 경계 설계
여러 Entity와 Value Object가 하나의 트랜잭션 단위로 묶여야 한다면, 그 묶음을 Aggregate로 설계한다. Aggregate의 경계를 어디로 잡느냐는 트랜잭션 범위, 동시 요청끼리의 충돌 가능성, 나아가 시스템의 확장성까지 결정하는 설계 결정이다. 다음 네 가지 규칙을 기준으로 삼는다.
1) Aggregate 경계 안에서 비즈니스 불변조건을 보호한다
트랜잭션이 끝나는 시점에 Aggregate 내부의 모든 구성요소가 비즈니스 규칙에 맞게 정합해야 한다. “이 데이터가 바뀔 때 반드시 동시에 정합해야 하는 데이터는 무엇인가”라는 질문에 대한 답이 곧 Aggregate의 경계다.
2) Aggregate는 작게 설계한다
Aggregate Root와 그 불변조건을 지키는 데 꼭 필요한 최소한의 Entity, Value Object만 포함한 다. Aggregate가 커질수록 하나의 트랜잭션이 잠그는 범위가 넓어져 동시 요청끼리 충돌할 가능성이 높아지고, 조회할 때마다 불필요한 데이터까지 함께 로드하게 된다. 이 Aggregate에서 분리할 수 있는 개념이 있는지, 그 개념이 정말로 즉시 정합해야 하는지를 항상 되묻는다.
3) 다른 Aggregate는 ID로만 참조한다
한 Aggregate가 다른 Aggregate의 인스턴스를 직접 보유하면, 두 Aggregate의 트랜잭션 경계가 사실상 하나로 합쳐진다. 다른 Aggregate에 대한 참조는 객체 참조가 아니라 식별자(Value Object로 감싼 ID)로만 유지하고, 필요한 데이터는 그 ID로 별도 조회한다.
4) 다른 Aggregate의 갱신은 결과적 일관성으로 처리한다
하나의 트랜잭션은 하나의 Aggregate만 변경한다. 다른 Aggregate에 영향을 줘야 한다면 Domain Event를 발행하고, 그 이벤트를 구독한 쪽이 자신의 트랜잭션 안에서 별도로 갱신하도록 한다. 두 Aggregate를 하나의 트랜잭션으로 묶고 싶어지는 순간은, 애초에 하나의 Aggregate로 설계했어야 하는 것은 아닌지 점검할 시점이다.
상태만 있고 행동이 없는 Aggregate는 흔한 설계 실패 신호다. 이 실패 패턴은 이 장 끝의 금지 패턴에서 Anemic Domain Model로 다룬다.
동시성 (Concurrency)
1) Thread Safety를 설계 단계에서 결정한다
Thread safety는 나중에 추가하기 어렵다. 클래스나 함수를 설계할 때 동시성 환경에서의 사용 여부를 먼저 명확히 결정하고, 그 결정을 문서화한다. “이 객체는 단일 스레드에서만 사용된다”, “이 메서드는 thread-safe하다” 같은 사실은 코드를 읽는 사람이 추론하게 두지 말고 명시한다. Thread safety를 확보하는 가장 효과적인 방법은 공유 가변 상태를 없애는 것 이다. 불변 객체는 별도의 동기화 없이 thread-safe하다.
2) Lock 정책
Lock은 동시성 문제를 해결하는 수단이지만, 잘못 사용하면 데드락(deadlock), 성능 저하, 기아 상태(starvation)를 유발한다. Lock을 사용해야 할 때는 다음 원칙을 따른다.
- Lock의 범위를 최소화한다: Lock을 유지하는 시간이 길수록 병목이 된다. Lock 범위 안에서는 도메인 연산만 수행하고, 외부 I/O(DB, 네트워크 호출)는 Lock 범위 밖으로 꺼낸다.
- Lock 순서를 일관되게 유지한다: 여러 Lock을 동시에 획득해야 할 때 항상 동일한 순서로 획득한다. 순서가 다르면 데드락이 발생할 수 있다.
- Lock보다 더 나은 대안을 먼저 검토한다: 불변 객체, 스레드 로컬 상태, 원자적 연산(atomic operation), 락프리(lock-free) 자료구조를 먼저 고려한다.
3) Actor / Message Passing 모델
공유 메모리 기반 동시성의 대안으로, Actor 모델 또는 Message Passing 방식을 활용할 수 있다. 이 방식은 상태를 각 Actor가 독립적으로 소유하고, Actor 간 통신은 메시지를 통해서만 이루어지므로 공유 가변 상태 자체가 발생하지 않는다. 분산 시스템이나 높은 동시성이 요구되는 환경에서는 이 모델이 Lock 기반 동시성보다 더 안전하고 예측 가능한 설계를 가능하게 한다. 단, 도입 시 팀의 운용 경험과 시스템의 실제 복잡도를 먼저 검토한다. 단순한 시스템에 Actor 모델을 도입하는 것은 과도한 아키텍처(Over Engineering)가 될 수 있다.
트랜잭션 보장 (Transaction Guarantee)
트랜잭션 범위는 최소화한다. 트랜잭션이 길수록 Lock을 오래 유지하고, 동시 처리 성능이 저하되며, 데드락 가능성이 높아진다. 트랜잭션은 비즈니스 규칙상 원자적으로 처리되어야 하는 최소 단위에만 적용한다.
트랜잭션 내부에서 외부 I/O를 실행하지 않는다. 트랜잭션 내에서 외부 API 호출, 메시지 발행, 이메일 전송을 실행하면 외부 시스템의 응답 시간만 큼 Lock이 유지된다. 외부 I/O는 트랜잭션 커밋 이후에 실행한다. 트랜잭션 커밋 직후 외부 API 호출이 실패하는 경우를 위해, 외부 발행 전 Outbox 패턴(DB에 발행 예정 이벤트를 기록하고 별도 프로세스가 발행)을 고려한다.
Application Layer가 트랜잭션 경계를 결정한다. 트랜잭션 경계는 도메인 규칙이 아니라 Use Case의 원자성 요구사항이 결정한다. Domain Layer는 트랜잭션을 모른다. Domain Model 내부에서 트랜잭션을 시작하거나 커밋하는 것은 계층 위반이다.
분산 트랜잭션이 필요한 설계는 재검토한다. 여러 서비스나 DB에 걸친 ACID 트랜잭션은 구현과 운용 복잡도가 매우 높다. 분산 트랜잭션이 필요한 상황이라면 먼저 Aggregate 경계가 올바른지 점검한다. 불가피하게 여러 서비스를 조율해야 한다면 Saga 패턴 을 사용한다. Saga는 각 서비스가 로컬 트랜잭션을 실행하고, 실패 시 이전 단계를 취소하는 보상 트랜잭션(compensating transaction) 을 순차적으로 실행한다.
데이터 일관성 (Data Consistency)
일관성 수준을 의식적으로 선택한다. 모든 데이터가 항상 강한 일관성(strong consistency)을 가져야 하지는 않는다. 강한 일관성은 성능과 가용성을 희생한다. 결과적 일관성(eventual consistency)은 일시적인 불일치를 허용하되 최종적으로 일관성이 보장된다. 어느 쪽을 선택하든, 그 선택은 명시적이어야 한다. “이 데이터는 일시적으로 낡을 수 있다”는 사실을 암묵적으로 숨기는 것이 가장 위험하다.
결과적 일관성을 선택했다면 불일치 기간을 설계한다. 결과적 일관성은 “언젠가는 일관성이 맞춰진다”는 막연한 기대가 아니라, 불일치가 허용되는 최대 시간과 일관성 복구 메커니즘을 코드 수준에서 명시해야 한다.
- 이벤트 기반 동기화: 상태 변경이 이벤트로 발행되고, 다른 서비스가 이를 구독해 자신의 상태를 업데이트한다. 이벤트 소비가 실패했을 때의 재처리 정책과 중복 처리 방지(멱등성)를 함께 설계한다.
- 보상 트랜잭션: 분산 환경에서 일부 단계가 실패했을 때 이미 완료된 단계를 취소하는 로직을 미리 구현한다. 보상 로직이 없는 Saga는 반쪽짜리 설계다.
- 읽기 전용 복제본의 지연: 읽기 전용 복제본(read replica)은 쓰기 원본보다 데이터가 늦게 반영된다. 방금 쓴 데이터를 읽기 복제본에서 즉시 읽어야 하는 경우(read-your-writes 일관성)에는 원본에서 읽도록 분기한다.
Optimistic Locking과 Pessimistic Locking을 구분해 사용한다. 충돌 가능성이 낮고 성능이 중요한 경우 낙관적 잠금(version 필드로 충돌 감지) 을 사용한다. 충돌이 빈번하거나 충돌 비용이 크면 비관적 잠금(선점 Lock) 을 사용한다. 낙관적 잠금 충돌 시 재시도 전략을 함께 설계한다. 충돌을 감지하고도 사용자에게 의미 있는 피드백 없이 조용히 덮어쓰는 것은 데이터 손실이다.
상태 설계의 금지 패턴
Anemic Domain Model 은 데이터만 있고 행동이 없는 객체다. 데이터 클래스만 놓고 비즈니스 로직을 Service에 모두 몰아넣으면, 도메인 규칙이 코드 전반에 흩어지고 객체의 상태가 외부에서 자유롭게 조작된다. 상태와 행동은 함께 있어야 한다.
무분별한 Setter 노출 은 캡슐화를 무너뜨린다. Setter가 모든 필드에 열려 있으면 객체의 상태를 누구든 어디서든 변경할 수 있게 되어, 상태 변경의 추적이 불가능해진다. 상태 변경은 의미 있는 도메인 행동 메서드를 통해서만 이루어져야 한다.
Silent State Mutation 은 이름에서 상태를 변경한다는 것을 알 수 없는 함수가 내부적으로 상태를 변경하는 패턴이다. 상태를 변경하는 메서드는 이름에서 그 사실이 드러나야 하며, 값을 반환하는 것처럼 보이는 함수가 부수적으로 상태를 변경하는 것은 가장 위험한 숨겨진 부수효과다.
7. 에러 처리 (Error Handling)
에러는 도메인의 일부다. 에러 처리는 코드의 부속품이 아니라 시스템 설계의 핵심이다. 어떤 에러가 발생할 수 있는지, 그것이 복구 가능한지, 누가 책임지는지를 명확히 정의하는 것은 비즈니스 규칙만큼 중요한 설계 결정이다. 에러를 잘못 다루면 두 가지 방향으로 실패한다. 에러를 침묵시키면 문제가 숨어있다가 훨씬 나중에, 훨씬 이해하기 어려운 형태로 터진다. 에러를 과도하게 전파하면 호출 스택 전체가 에러 처리 로직으로 오염되고, 정상 흐름(happy path)이 에러 처리 코드 속에 묻힌다. 목표는 에러가 발생한 지점에서 의미 있게 처리되고, 정상 흐름이 코드의 주인공으로 읽히 는 구조를 만드는 데 있다.
에러의 세 가지 분류
에러를 일관되게 다루기 위해 먼저 세 가지 유형으로 명확히 구분한다. 이 구분은 에러를 어떻게 처리할지 결정하는 기준이 된다.
1) Assertion (프로그래머 가정)
Assertion은 “이 시점에는 반드시 이 조건이 참이어야 한다”는 프로그래머의 불변식 (invariant)을 선언하는 수단이다. 외부 입 력을 검증하는 용도가 아니라, 코드 내부의 논리적 일관성을 확인하는 용도로만 사용한다. Assertion은 개발/테스트 환경에서 프로그래머의 실수를 조기에 발견하기 위한 도구다. 프로덕션 환경의 외부 입력 검증 수단으로 사용하면 안 된다. Assertion이 실패했다면 그것은 비즈니스 에러가 아니라 코드 자체의 버그를 의미한다.
2) Validation (외부 입력 검증)
Validation은 시스템 경계(Trust Boundary)에서 외부로부터 들어오는 입력이 기대하는 형식과 범위를 만족하는지 검사하는 절차다. 사용자의 입력, API 요청, 외부 시스템의 데이터가 여기에 해당한다. Validation은 예외가 아닌 명시적인 검증 결과 로 처리한다. 사용자가 잘못된 값을 입력하는 것은 예외적인 상황이 아니라 예상 가능한 시나리오이며, 사용자에게 명확한 피드백을 돌려줘야 한다.
3) Domain Error (비즈니스 실패)
Domain Error는 비즈니스 규칙이 위반되었을 때 발생하는 에러다. “재고가 부족한 상태에서 주문을 시도함”, “이미 취소된 주문을 다시 취소하려 함”처럼 도메인 규칙상 허용되지 않는 상태 전이가 이에 해당한다. Domain Error는 프로그래머의 실수도, 시스템 장애도 아니다. 비즈니스 흐름의 일부로 명시적으로 모델링하고, 호출하는 쪽이 반드시 처리하도록 강제해야 한다.
예외(Exception) 사용 기준
예외는 진짜 예외적인 상황, 즉 정상적인 프로그램 흐름에서는 발생해서는 안 되는 상황에만 사용한다. 예측 가능한 비즈니스 분기를 예외로 처리하는 것은 예외를 흐름 제어 수단으로 남용하는 것이며, 성능 저하와 가독성 저하를 동시에 초래한다.
예외를 사용하기에 적절한 상황은 다음과 같다.
- 시스템이 복구할 수 없는 상태 (메모리 부족, 필수 리소스 접근 불가)
- 프로그래머의 실수로 발생한 계약 위반 (잘못된 인자, null이 허용되지 않는 곳에 null 전달)
- 인프라 수준의 장애 (DB 연결 실패, 재시도를 소진한 외부 API 호출 실패)
반면 다음 상황은 예외가 아닌 다른 수단으로 처리한다.
- 사용자 입력 오류 → Validation 결과 반환
- 비즈니스 규칙 위반 → Domain Error 또는 Result 타입 반환
- 존재하지 않는 리소스 조회 → Optional/Result 반환
예외를 던질 때는 반드시 적절한 예외 객체를 사용한다. 단순 문자열이나 기본 타입을 throw하면 스택 트레이스가 사라져 디버깅이 극도로 어려워진다.
Result / Either 사용 기준
Result 타입(또는 Either<Error, Value>)은 실패 가능성을 타입으로 표현하는 수단이다. 함수가 성공할 수도, 실패할 수도 있다는 사실을 반환 타입 자체에 드러냄으로써, 호출하는 쪽이 반드시 실패 케이스를 처리하도록 타입 시스템이 강제한다.
Result 타입은 다음 상황에서 예외보다 적합하다.
- 예측 가능한 비즈니스 실패: 발생 가능성이 알려져 있고, 호출하는 쪽이 반드시 처리해야 하는 Domain Error
- 흐름 제어가 필요한 실패: 실패 시 대안 로직을 실행하거나 복구를 시도해야 하는 경우
- 합성 가능한 연산: 여러 실패 가능한 연산을 체이닝할 때 예외보다 선형적으로 읽힘
언어별로 Result 타입을 표현하는 방법이 다르므로 구체적인 구현은 언어별 상세 가이드를 따른다. 실패 가능성이 타입으로 드러나고 처리가 강제되는 것이 핵심이다.
복구 가능(Recoverable) / 불가능(Unrecoverable) 구분
에러를 처리하기 전에 반드시 먼저 결정해야 할 것은, 이 에러가 복구 가능한가 불가능한가이다.
- 복구 가능한 에러 는 시스템이 정상 상태를 유지하면서 대응 가능한 에러다. 비즈니스 규칙 위반, 사용자 입력 오류, 일시적인 외부 시스템 장애가 여기에 해당한다. 이런 에러는 호출 스택 어딘가에서 명시적으로 처리하고, 적절한 피드백이나 대안 흐름으로 이어져야 한다.
- 복구 불가능한 에러 는 시스템이 정상적으로 계속 동작할 수 없는 상태다. 필수 설정값 누락, 데이터 무결성 손상, 복구 불가능한 인프라 장애가 여기에 해당한다. 복구 불가능한 에러는 즉시 실패하고(fail-fast), 충분한 컨텍스트와 함께 로그를 남긴 후 시스템을 중단하거나 상위 레이어에 위임한다.
Fail-Fast 정책
Fail-Fast 는 잘못된 상태를 발견한 즉시 명시적으로 실패하는 원칙이다. 잘못된 상태를 감지했음에도 계속 진행하면, 에러가 훨씬 나중에 훨씬 이해하기 어려운 형태로 드러난다.
Fail-Fast가 적용되어야 하는 상황은 다음과 같다.
- 생성자나 팩토리 메서드에서 유효하지 않은 입력을 받았을 때
- 필수 의존성이 null이거나 초기화되지 않았을 때
- 프로그래머가 가정한 불변식이 위반되었을 때
잘못된 값을 기본값으로 대체하거나 조용히 무시하는 것은 문제를 숨기는 가장 위험한 패턴이다. 에러는 침묵하지 않는다.
Logging 기준
로그 레벨의 기준과 로그에 담을 맥락은 13장 관측성에서 정의한다. 여기서는 에러 처리와 직접 맞닿는 규칙만 둔다. 예외를 로그로 기록할 때는 예외 객체를 함께 전달해 스택 트레이스가 남게 한다. 스택 트레이스 없는 예외 로그는 발생 위치를 알 수 없어 디버깅이 불가능하다. 일시적인 외부 장애는 재시도 중에는 WARN으로, 재시도를 소진해 비즈니스 흐름이 중단될 때 ERROR로 기록한다.
같은 에러를 여러 레이어에서 중복으로 로그하지 않는다. 예외를 catch하여 로그를 남기고, 다시 throw하면 같은 에러가 스택 전체에서 중복 기록된다. 로그는 에러를 최종 처리하는 지점에서 한 번만 남긴다.
사용자 오류(User Error) vs 시스템 오류(System Error)
에러를 외부로 노출할 때 사용자 오류와 시스템 오류를 반드시 구분한다.
- 사용자 오류 는 사용자의 잘못된 입력이나 허용되지 않는 행동에서 비롯된다. 사용자 오류의 응답에는 무엇이 잘못되었는지, 어떻게 수정해야 하는지 를 명확하고 이해하기 쉬운 언어로 전달한다.
- 시스템 오류 는 인프라 장 애, 프로그래머 실수, 예상치 못한 상태에서 비롯된다. 시스템 오류의 응답에는 내부 구현 세부사항, 스택 트레이스, 시스템 경로 등 보안에 민감한 정보를 절대 노출하지 않는다. 사용자에게는 추적 가능한 에러 ID만 제공하고, 상세 정보는 내부 로그에만 기록한다.
에러 처리 금지 패턴
- Silent Failure 는 예외를 catch한 후 아무것도 하지 않거나, 의미 없는 기본값으로 대체하는 패턴이다. 문제가 발생했다는 사실을 숨기고, 에러가 훨씬 나중에 전혀 다른 곳에서 이해하기 어려운 형태로 드러나게 만든다. 에러는 어떤 경우에도 침묵해서는 안 된다.
- 예외를 흐름 제어에 사용하는 것 은 성능 저하와 가독성 저하를 동시에 초래한다. “존재 여부 확인”을 예외로 구현하는 것이 대표적인 사례다.
8. 비동기 처리 (Async & Concurrency)
비동기는 복잡성을 수반한다. 비동기 처리는 성능과 응답성을 높이는 강력한 수단이지만, 동시에 코드의 복잡성을 크게 높이는 영역이다. 실행 순서가 보장되지 않고, 에러가 예상치 못한 시점에 발생하며, 리소스 누수와 경쟁 조건(race condition)이 눈에 보이지 않게 숨어 있을 수 있다.
비동기 코드에서 발생하는 버그는 재현이 어렵고, 디버깅이 오래 걸리며, 프로덕션에서만 나타나는 경우가 많다. 비동기를 도입할 때는 “이 비동기 처리가 실패하면 어떻게 되는가”, “취소되면 어떻게 되는가”, “타임아웃이 발생하면 어떻게 되는가” 를 반드시 설계 단계에서 결정해야 한다. 재시도, 멱등성, 취소 처리를 나중에 붙이는 것은 가장 흔한 실패 패턴 중 하나다.
Async/Await 원칙
1) 비동기는 일관되게 전파한다
비동기 함수는 호출 스택 전체에 걸쳐 일관되게 비동기로 처리해야 한다. 비동기 함수 내에서 동기 블로킹 호출을 수행하면 비동기의 이점이 사라지고, 스레드 풀을 고갈시키는 원인이 된다. 비동기 컨텍스트에서 동기 블로킹을 수행하는 것은 가장 위험한 안티패턴 중 하나다.
2) 비동기 흐름은 명시적이고 선형적으로 유지한다
비동기 코드는 실행 흐름이 분기되고 뒤엉키기 쉽다. 가능한 한 async/await를 사용하여 코드를 동기 코드처럼 위에서 아래로 선형적으로 읽히게 유지한다. 콜백 중첩(callback hell)은 비동기 코드를 이해하기 어렵게 만드는 가장 직접적인 원인이므로 피한다. 비동기 함수는 3섹션에서 다룬 네이밍 원칙에 따라 비동기임을 이름에서 명확히 드러낸다. 언어와 팀 컨벤션에 따라 Async 접미사를 붙이거나, 반환 타입으로 비동기 여부를 충분히 표현한다.
3) 비동 기 에러는 반드시 처리한다
비동기 에러는 동기 코드와 달리 호출하는 쪽에 자동으로 전파되지 않는 언어와 런타임이 있다. 처리되지 않은 비동기 에러(unhandled promise rejection, unobserved task exception 등)는 조용히 사라져 디버깅을 불가능하게 만든다. 모든 비동기 작업의 에러는 반드시 명시적으로 처리하거나, 전역 에러 핸들러에서 최종적으로 포착되도록 보장한다.
취소(Cancellation)
취소는 선택 사항이 아니라 비동기 작업의 필수 설계 요소다. 사용자가 요청을 취소하거나, 타임아웃이 발생하거나, 상위 작업이 실패했을 때 진행 중인 비동기 작업은 정리되어야 한다. 취소를 고려하지 않으면 불필요한 작업이 계속 실행되고, 리소스가 낭비되며, 이미 의미가 없어진 결과가 시스템 상태를 변경하는 문제가 발생한다.
언어가 제공하는 취소 메커니즘(CancellationToken, AbortSignal, coroutine cancellation 등)을 적극 사용한다. 취소 신호를 전파받은 작업은 현재 작업을 정리하고, 보유한 리소스를 반환한 후 조용히 종료해야 한다.
취소와 실패는 다르다. 취소는 예외적인 오류가 아니라 정상적인 흐름의 일부이며, 취소로 인한 종료는 에러 로그가 아닌 적절한 수준의 로그로 처리한다.
타임아웃(Timeout)
모든 외부 시스템 호출에는 타임아웃을 설정한다. 타임아웃 없이 외부 API, DB, 네트워크 호출을 수행하면 외부 시스템의 응답 지연이 자신의 시스템 전체를 마비시킬 수 있다. 하나의 느린 외부 호출이 스레드 풀을 고갈시키고, 연쇄적으로 다른 요청들을 실패하게 만드는 것이 Cascading Failure의 가장 흔한 원인이다.
타임아웃 값은 코드에 하드코딩하지 않고 설정으로 관리한다. 서비스와 환경에 따라 적절한 타임아웃이 다르며, 실제 측정값과 SLA를 기반으로 설정한다.
타임아웃 발생 시 처리 방침을 명확히 정의한다. 단순히 에러를 반환하는 것이 적절한지, 재시도가 필요한지, 폴백(fallback) 응답을 제공해야 하는지를 설계 단계에서 결정한다.
재시도(Retry)
일시적인 장애(transient failure)는 대부분의 분산 시스템에서 피할 수 없다. 네트워크 순간 단절, 일시적인 DB 부하, 외부 API의 일시적 과부하는 재시도로 해결될 수 있다. 단, 재시도는 잘못 설계하면 장애를 악화시키는 원인이 된다.
1) 재시도 전에 반드시 멱등성을 확인한다
재시도 가능한 작업은 멱등(idempotent) 해야 한다. 같은 요청을 여러 번 실행해도 동일한 결과가 보장되지 않으면, 재시도는 중복 처리, 중복 결제, 중복 발송 같은 심각한 문제를 만든다. 멱등성이 보장되지 않는 작업에는 재시도를 적용하지 않거나, 멱등성 키를 사용하여 중복 처리를 방지한다.
2) Exponential Backoff와 Jitter를 사용한다
즉시 재시도를 반복하면 이미 부하 상태인 외부 시스템에 폭발적인 트래픽을 쏟아붓게 된다. 재시도 간격은 지수적으로 증가(Exponential Backoff) 시키고, 여러 클라이언트가 동시에 재시도하는 것을 방지하기 위해 Jitter(무작위 오차) 를 추가한다.
3) 재시도 횟수와 중단 조건을 명확히 정의한다
재시도는 무한히 반복하지 않는다. 최대 재시도 횟수를 명확히 정의하고, 모든 재시도가 실패했을 때의 처리 방침(에러 반환, 폴백, Dead Letter Queue 전송)을 설계 단계에서 결정한다. 모든 재시도가 실패한 후의 처리는 재시도 로직만큼 중요하다. 재시도해서는 안 되는 에러를 구분한다. 인증 실패(401), 권한 없음(403), 잘못된 요청(400) 같은 클라이언트 에러는 재시도로 해결되지 않는다. 재시도는 일시적인 서버/인프라 오류에만 적용한다. 429 Too Many Requests는 클라이언트 에러로 분류되지만 Retry-After 헤더를 존중해 재시도하는 예외다.
백프레셔(Backpressure)
Backpressure 는 소비자(consumer)가 처리할 수 있는 속도보다 생산자(producer)가 빠르게 데이터를 생성할 때, 소비자가 생산자의 속도를 제어하는 메커니즘이다. Backpressure 없이 무한히 데이터를 받아들이면 메모리가 고갈되고 시스템 전체가 응답 불가 상태에 빠진다.
스트리밍, 이벤트 처리, 메시지 큐 소비 등 데이터 흐름이 있는 모든 구조에서 Backpressure를 고려한다. 처리 속도를 초과하는 데이터에 대한 정책을 명확히 결정한다.
- 버퍼링(Buffering): 처리 가능할 때까지 일정량을 대기열에 보관. 버퍼 크기와 버퍼 초과 시 정책을 명시한다.
- 드로핑(Dropping): 처리 불가능한 메시지를 버린다. 어떤 메시지를 버릴지 기준이 명확해야 하며, 드롭된 메시지는 반드시 로그로 기록한다.
- 생산 속도 제한: 소비자가 처리 가능한 속도로 생산자를 직접 제한한다.
동시성 제한(Concurrency Limit)
무제한 동시 실행은 리소스를 고갈시킨다. 특히 외부 시스템 호출, DB 쿼리, 파일 I/O는 동시 실행 수를 제한하지 않으면 연결 풀 고갈, 외부 API Rate Limit 초과, 메모리 압박으로 이어진다. 동시성 제한은 시스템의 용량 설계와 직결된다. 다음 상황에서는 반드시 동시성 한도를 설정한다.
- 외부 API 호출: Rate Limit이 있는 외부 API는 동시 요청 수와 초당 요청 수를 제한한다.
- DB 쿼리: 동시 쿼리 수가 커넥션 풀 크기를 초과하면 대기가 발생하고 타임아웃으로 이어진다.
- 대용량 데이터 처리: 대량 배치 처리는 메모리와 CPU 사용량을 고려하여 동시 처리 단위를 제한한다.
동시성 한도는 설정으로 관리하고, 실제 측정값을 기반으로 조정한다. 처음부터 최적값을 알 수는 없으므로, 보수적으로 시작하고 모니터링 결과에 따라 조정한다.
Failure Semantics (실패 의미론)
메시지 전달 보장 수준을 명시한다. 비동기 통신에서 “메시지를 보냈다”와 “메시지가 처리되었다”는 다르다. 시스템이 어떤 전달 보장을 제공하는지를 설계 시점에 결정하고, 코드와 운영 정책 모두 이에 맞춰야 한다.
- At-most-once: 메시지가 유실될 수 있지만 중복 처리는 없다. 로그성 이벤트처럼 일부 유실이 허용되는 경우에 적합하다.
- At-least-once: 메시지가 반드시 처리되지만 중복 전달될 수 있다. 재시도 기반 시스템의 기본값이다. 소비자 측 멱등성이 반드시 보장되어야 한다.
- Exactly-once: 정확히 한 번 처리를 보장한다. 구현 복잡도가 가장 높고, 실제로는 at-least-once + 멱등 소비자로 대체하는 경우가 많다.
Partial Failure(부분 실패)를 명시적으로 처리한다. 분산 환경에서는 일부 단계는 성공하고 나머지는 실패하는 상황이 언제든 발생한다. 부분 실패를 무시하거나 단순히 로그만 남기는 것은 데이터 불일치로 이어진다. 각 비동기 작업에 대해 “이 단계가 실패했을 때 시스템은 어떤 상태가 되는가”를 설계 단계에서 명시하고, 복구 경로(재시도, 보상, 알림)를 코드에 구현한다.
Dead Letter Queue(DLQ)는 무시하지 않는다. 재시도를 모두 소진한 실패 메시지는 DLQ로 이동한다. DLQ는 조용한 데이터 손실을 막는 마지막 안전망이다. DLQ에 메시지가 쌓이면 알람이 울려야 하고, 담당자가 원인을 분석하고 재처리하는 프로세스가 있어야 한다. DLQ를 만들고 모니터링하지 않는 것은 쓰레기통을 만들고 비우지 않는 것과 같 다.
Fire-and-Forget을 남용하지 않는다
Fire-and-Forget은 비동기 작업을 실행하고 결과를 전혀 추적하지 않는 패턴이다. 작업이 실패해도 알 수 없고, 리소스가 누수되어도 감지할 수 없다. Fire-and-Forget이 필요한 경우에도 에러는 반드시 포착하여 로그를 남기고, 작업의 생명주기를 추적할 수 있어야 한다. 비동기 컨텍스트에서 .Result, .Wait(), Thread.Sleep() 같은 동기 블로킹 호출을 섞는 것도 같은 이유로 피한다. 스레드 풀 고갈과 데드락의 직접적인 원인이다.
9. API 설계 (API Design)
API는 계약이다. API는 호출하는 쪽과 구현하는 쪽 사이의 계약(contract) 이다. 계약은 한번 공개되면 변경 비용이 높아지고, 소비자가 많을수록 변경은 더 어려워진다. 좋은 API는 처음부터 명확한 의도를 드러내고, 잘못된 사용이 어렵게 설계되며, 변경이 필요할 때 소비자에게 최소한의 영향을 준다.
API 설계는 내부 구현을 어떻게 숨기느냐의 문제이기도 하다. 잘 설계된 API는 내부 구현이 바뀌어도 소비자가 영향받지 않도록 충분한 추상화 경계를 제공한다. API 경계 너머로 내부 구현 세부사항이 새어나오는 순간, 그 세부사항은 계약의 일부가 되어 변경을 어렵게 만든다.
함수 API
1) 입력과 출력을 명확하게 설계한다
함수의 시그니처는 그 자체로 문서여야 한다. 함수 이름, 파라미터 타입, 반환 타입만 보고도 무엇을 받아서 무엇을 돌려주는지, 실패할 수 있는지를 파악할 수 있어야 한다. 시그니처를 이해하기 위해 구현을 열어봐야 한다면 설계를 재검토한다.
- 입력 은 가능한 한 구체적인 도메인 타입을 사용한다.
String,Long같은 기본 타입보다OrderId,Email,Money같은 Value Object를 파라미터로 받으면, 호출하는 쪽이 잘못된 값을 전달하는 것을 컴파일 타임에 방지할 수 있다. - 출력 은 실패 가능성을 타입으로 드러낸다. 실패할 수 있는 함수는 예외로만 실패를 표현하는 것보다,
Result<T, E>,Optional<T>등으로 반환 타입에서 실패 가능성을 명시하여 호출하는 쪽이 반드시 처리하도록 강제한다.
2) 부수효과(Side Effect)를 명시적으로 드러낸다
함수 API에서 가장 중요한 계약 중 하나는 부수효과의 존재 여부 다. 값을 계산하는 것처럼 보이는 함수가 내부에서 DB에 쓰거나 외부 API를 호출한다면, 그것은 숨겨진 부수효과다. 명령(Command)과 조회(Query)를 명확히 분리한다. 상태를 변경하는 함수는 상태를 변경한다는 사실이 이름에서 드러나야 하며, 값을 반환하는 함수는 부수효과 없이 순수하게 값을 돌려줘야 한다. 이 원칙을 Command Query Separation(CQS) 라 하며, API를 예측 가능하게 만드는 핵심 원칙이다.
3) Optional Parameter 기준
선택적 파라미터는 신중하게 사용한다. 선택적 파라미터가 많아지면 함수가 여러 가지 모드로 동작하기 시작하고, 각 조합마다 동작이 다를 수 있어 이해와 테스트가 어려워진다. 선택적 파라미터가 3개 이상 필요하다면 파라미터 객체 패턴(Parameter Object) 을 검토한다. 관련 파라미터를 하나의 객체로 묶으면 호출 코드가 명확해지고, 향후 파라미터가 추가되어도 기존 호출 코드를 변경하지 않아도 된다. 서로 다른 동작 모드가 필요하다면, 선택적 파라미터 하나로 동작을 분기하는 대신 의미가 명확한 별도의 함수를 제공하는 것이 낫다.
네트워크 API
1) REST / gRPC 기준
네트워크 API의 방식(REST, gRPC, GraphQL 등)은 팀과 시스템의 요구사항에 따라 결정한다. 어떤 방식을 선택하든 다음 원칙은 공통으로 적용된다.
- 도메인 개념을 URI와 메서드로 표현한다: REST API에서 리소스는 도메인 개념을 반영해야 하며, HTTP 메서드는 행위의 의미를 충실히 따른다. URI에 동사를 사용하지 않고, 리소스는 명사로 표현한다.
- 도메인 행동을 명확히 표현한다: 단순 CRUD로 표현하기 어려운 도메인 행동은 의미 있는 서브리소스나 액션 엔드포인트로 표현한다.
2) Versioning
API는 한번 공개되면 소비자가 생기고, 소비자가 있는 한 함부로 변경할 수 없다. 버전 관리 전략은 API를 처음 설계할 때부터 결정하고 적용한다. 변경이 필요한 이후에 버전 전략을 세우는 것은 이미 늦다. 하위 호환되는 변경(backward compatible)과 파괴적 변경(breaking change)을 명확히 구분한다.
| 변경 유형 | 예시 | 처리 방법 |
| 하위 호환 가능 | 선택적 필드 추가, 새 엔드포인트 추가 | 기존 버전 유지, 바로 적용 |
| 파괴적 변경 | 필드 삭제/이름 변경, 타입 변경, 동작 변경 | 새 버전으로 분리, 이전 버전 Deprecation 후 단계적 제거 |
Deprecated된 API는 충분한 유예 기간을 두고 단계적으로 제거한다. 단, 기존 API를 영원히 유지하는 것도 기술 부채다. Deprecated 시점부터 제거 일정을 명시적으로 공개하고, 소비자의 마이그레이션을 적극적으로 지원한다.
3) Idempotency(멱등성)
네트워크는 신뢰할 수 없다. 클라이언트는 응답을 받지 못했을 때 요청을 재시도한다. 재시도가 중복 처리를 일으키면 중복 결제, 중복 발송, 중복 생성 같은 심각한 문제가 발생한다. 상태를 변경하는 모든 API는 멱등성을 고려해야 한다. GET, PUT, DELETE는 본질적으로 멱등하게 설계할 수 있지만, POST는 명시적인 멱등성 처리가 필요하다. Idempotency Key 를 헤더로 받아 같은 키의 요청이 재시도될 때 동일한 결과를 반환하고 중복 처리하지 않도록 설계한다. 멱등성 처리는 기능 구현 후 추가하는 것이 아니라 처음 설계할 때 반드시 고려한다. 나중에 추가하면 기존 데이터와 처리 방식을 모두 고려해야 하므로 비용이 기하급수적으로 높아진다.
4) Pagination
목록을 반환하는 API는 반드시 페이지네이션을 제공한다. 페이지네이션 없는 목록 API는 데이터가 증가할수록 응답 크기가 무한정 늘어나고, 결국 타임아웃과 메모리 고갈로 이어진다. 페이지네이션은 기능이 안정된 후 추가하는 것이 아니라, 처음 API를 설계할 때 기본으로 포함한다. 페이지네이션 방식은 사용 목적에 따라 선택한다.
- Offset 기반 페이지네이션 은 구현이 간단하고 특정 페이지로 이동이 쉽지만, 데이터가 추가되거나 삭제될 때 페이지 경계가 흔들리는 문제가 있다. 대량 데이터에서 깊은 오프셋은 DB 성능에 심각한 영향을 준다.
- Cursor 기반 페이지네이션 은 마지막으로 받은 항목의 커서를 기반으로 다음 페이지를 가져온다. 데이터 추가/삭제 시 안정적이고, 대량 데이터에서도 성능이 일관되게 유지된다. 무한 스크롤처럼 연속적인 데이터 탐색에 적합하다.
5) Error Response 형식
에러 응답은 일관된 형식 을 유지한다. API마다 에러 형식이 다르면 클라이언트가 에러 처리 로직을 중복 구현해야 하고, 에러의 원인을 파악하기 어렵다. 에러 응답에는 다음 정보를 포함한다.
- 에러 코드: 기계가 처리할 수 있는 식별자. HTTP 상태 코드만으로 원인을 특정하기 어려우므로 도메인 에러 코드를 별도로 제공한다.
- 메시지: 사람이 읽을 수 있는 설명. 사용자에게 보여줄 메시지와 내부 진단용 메시지를 구분한다.
- 추적 ID: 서버 로그와 연결할 수 있는 식별자. 내부 정보는 절대 노출하지 않는다.
- 필드 오류: 입력 검증 실패 시 어떤 필드가 왜 실패했는지 구체적으로 전달한다.
HTTP 상태 코드는 의미에 맞게 정확히 사용한다. 모든 에러에 200을 반환하고 바디에서 에러를 표현하는 것은 HTTP를 단순 전송 수단으로만 사용하는 것이며, 클라이언트의 에러 감지를 어렵게 만든다.
| 상황 | HTTP 상태 코드 |
| 성공 | 200 OK, 201 Created, 204 No Content |
| 입력 오류, 도메인 규칙 위반 | 400 Bad Request |
| 인증 필요 | 401 Unauthorized |
| 권한 없음 | 403 Forbidden |
| 리소스 없음 | 404 Not Found |
| 멱등성 충돌 | 409 Conflict |
| 서버 오류 | 500 Internal Server Error |
| 외부 의존성 장애 | 502 Bad Gateway, 503 Service Unavailable |
10. 의존성 관리(Dependencies)
의존성은 부채다. 외부 라이브러리와 프레임워크는 개발 속도를 높이고 검증된 솔루션을 제공한다. 그러나 모든 의존성은 동시에 부채 이기도 하다. 의존성을 추가하는 순간, 그 라이브러리의 버그, 보안 취약점, 파괴적 업그레이드, 라이선스 변경, 프로젝트 유지 중단 가능성을 함께 떠안는다. 좋은 의존 성 관리는 “필요한 것을 올바른 방식으로 사용하고, 그 의존성이 시스템 전체에 퍼지지 않도록 격리하는 것”이다. 의존성이 많을수록, 그것이 코드 전반에 깊게 퍼져있을수록 나중에 교체하거나 제거하는 비용은 기하급수적으로 높아진다.
외부 라이브러리 채택 기준
1) 라이브러리 도입 전에 반드시 자문한다
외부 라이브러리를 추가하기 전에 다음 질문에 답할 수 있어야 한다. 이 질문들에 명확히 답할 수 없다면 도입을 보류한다.
- 이미 잘 만들어진 것을 직접 구현하려 하지 않는다. 인증(JWT, OAuth), 로깅, 캐시, 날짜/시간 처리, 페이징, 유효성 검사, 국제화처럼 검증된 라이브러리가 존재하는 문제를 직접 구현하는 것은 시간 낭비이자 잠재적 버그의 원인이다. 바퀴를 재발명하지 않는다.
- 반대로 팀이 운용할 수 있는지 먼저 확인한다. 기술적으로 뛰어나더라도 팀이 운용 경험이 없는 라이브러리나 프레임워크를 도입하는 것은 위험하다. Kubernetes, Kafka, 이벤트 소싱 프레임워크처럼 운용 복잡도가 높은 기술은 팀의 역량과 시스템의 실제 요구사항을 먼저 냉정하게 평가한다.
2) 의존성의 범위를 최소화한다
라이브러리는 필요한 범위에서만 사용하고, 코드 전반에 퍼지지 않도록 격리한다. 특히 외부 라이브러리의 타입과 인터페이스가 Domain Layer까지 침투하면, 라이브러리를 교체하거나 제거할 때 도메인 코드 전체를 수정해야 하는 상황이 발생한다. 외부 라이브러리는 Adapter/Port 패턴으로 격리 한다. Domain Layer는 외부 라이브러리를 직접 의존하지 않고, Infrastructure Layer가 라이브러리를 사용하여 Domain이 정의한 인터페이스를 구현한다. 라이브러리가 바뀌어도 도메인 코드는 영향받지 않는다.
버전 정책
1) 버전은 명시적으로 고정한다
의존성 버전은 재현 가능하게(reproducible) 고정한다. Lockfile을 지원하는 생태계(npm, Cargo, Bundler 등)에서는 매니페스트의 범위 지정(^, ~)을 허용하되 실제 버전은 Lockfile이 고정하므로, Lockfile 없이 범위 지정만 두거나 *, latest를 쓰는 것을 금지한다. Lockfile이 없는 생태계에서는 매니페스트에 정확한 버전을 명시한다. 어느 쪽이든 “최신 버전을 자동으로 사용한다”는 정책은 외부 라이브러리의 파괴적 변경이 언제든지 빌드를 깨뜨릴 수 있다는 의미다. 버전 업그레이드는 팀이 인식하고 검토한 뒤 의도적으로 수행한다.
2) 업그레이드는 정기적으로, 작게 수행한다
버전 업그레이드를 오래 미루면 여러 버전의 변경사항이 누적되어 한 번에 업그레이드하는 비용이 기하급수적으로 높아진다. 의존성을 최신 상태에 가깝게 유지하되, 한 번에 하나씩 작은 단위로 업그레이드하고 각 업그레이드마다 테스트로 안전성을 검증한다. 메이저 버전 업그레이드는 파괴적 변경을 동반할 수 있으므로, 별도의 작업으로 분리하여 충분한 검토 후 진행한다.
전이 의존성(Transitive Dependency) 관리
Transitive Dependency 는 직접 의존하는 라이브러리가 또 다른 라이브러리에 의존하는 관계다. 직접 추가하지 않았지만 자동으로 포함되는 이 의존성들은 버전 충돌, 보안 취약점, 예상치 못한 동작의 원인이 된다. 주기적으로 의존성 트리를 확인하고, 직접 사용하지 않지만 포함되는 라이브러리 목록을 파악한다. 같은 라이브러리의 서로 다른 버전이 동시에 포함되는 버전 충돌이 발생하면 명시적으로 버전을 지정하여 해결한다.
불필요하게 포함되는 Transitive Dependency는 exclusion 설정으로 제거한다. 사용하지 않는 코드를 배포 산출물에 포함시키는 것은 공격 표면(attack surface)을 넓히고 빌드 크기를 불필요하게 늘린다.
# 의존성 트리 확인 (언어별 도구)
mvn dependency:tree # Maven
gradle dependencies # Gradle
npm ls # Node.js
pipdeptree # Python
cargo tree # RustLockfile 정책
Lockfile 은 의존성의 정확한 버전과 무결성 해시를 기록한 파일이다. Lockfile이 있으면 팀 전체와 CI/CD 환경에서 항상 동일한 버전의 의존성을 사용하는 것이 보장된다. Lockfile은 반드시 버전 관리(VCS)에 포 함한다. Lockfile을 .gitignore에 추가하거나 커밋하지 않으면 환경에 따라 다른 버전의 의존성이 설치되어 “내 로컬에서는 되는데 CI에서는 안 된다”는 문제가 발생한다.
Lockfile은 자동으로 업데이트되도록 두지 않는다. 의존성 버전 변경은 의도적인 행위이며, 코드 변경과 동일하게 리뷰 과정을 거쳐야 한다. Lockfile의 변경은 반드시 명시적인 업그레이드 커맨드 실행의 결과여야 한다.
Vendor 정책
Vendoring 은 외부 의존성의 소스 코드를 프로젝트 저장소에 직접 포함시키는 방식이다. 네트워크 없이 빌드가 가능하고, 외부 패키지 저장소의 장애나 패키지 삭제에 영향받지 않는 장점이 있다. Vendoring은 다음 상황에서 검토한다.
- 외부 네트워크 접근이 제한된 폐쇄망 환경
- 외부 패키지 저장소의 가용성을 보장할 수 없는 환경
- 패키지 공급망 보안(supply chain security)이 중요한 환경
반면 Vendoring은 저장소 크기를 크게 늘리 고, 의존성 업그레이드를 수동으로 관리해야 하는 부담이 있다. 대부분의 환경에서는 Lockfile과 패키지 저장소 캐시를 활용하는 것이 더 실용적이다. 팀의 환경과 보안 요구사항을 기준으로 Vendoring 여부를 결정하고, 결정한 정책을 일관되게 적용한다.
보안 검토 기준
1) 의존성 취약점은 코드 취약점과 동일하게 취급한다
외부 라이브러리의 보안 취약점은 직접 작성한 코드의 취약점과 동일한 위험을 초래한다. 오히려 외부 라이브러리의 취약점은 공개적으로 알려져 있어 공격자가 적극적으로 탐색하는 대상이다. 알려진 취약점(CVE)이 있는 의존성이 프로덕션에 배포되지 않도록 CI/CD에서 자동 차단하며, 도구 선택과 심각도별 대응 기준은 14장 Dependency Scanning에서 정의한다.
2) 라이선스를 반드시 확인한다
외부 라이브러리의 라이선스는 사용 조건을 정의한다. GPL 같은 카피레프트 라이선스를 상업용 프로젝트에 사용하면 법적 문제가 발생할 수 있다. 라이브러리를 도입하기 전에 라이선스를 확인하고, 팀의 라이선스 정책과 호환되는지 검토한다.
| 라이선스 유형 | 특징 | 상업적 사용 시 주의사항 |
| MIT, Apache 2.0, BSD | 자유로운 사용 허용 | 저작권 표시 필요 |
| LGPL | 라이브러리로 링크 시 사용 가능 | 라이브러리 자체 수정 시 공개 의무 |
| GPL | 소스 코드 공개 의무 | 상업적 프로젝트에 주의 필요 |
| AGPL | 네트워크를 통한 서비스에도 적용 | SaaS 제품에 특히 주의 필요 |
| 상용 라이선스 | 사용 조건이 개별적으로 정의됨 | 계약 내용 확인 필요 |
3) 공급망 보안(Supply Chain Security)에 주의한다
외부 라이브러리 자체가 악성 코드를 포함하거나, 신뢰할 수 있는 라이브러리와 이름이 유사한 악성 패키지를 설치하도록 유도하는 Typosquatting 공격이 증가하고 있다. 패키지 이름과 게시자를 신중하게 확인하고, 공식 저장소와 패키지 서명을 검증하는 습관을 갖는다. 인기 있는 라이브러리라도 관리자 계정이 탈취되거나 악성 코드가 삽입된 버전이 배포될 수 있다. 의존성 업그레이드 시 변경사항을 확인하고, 검증되지 않은 새 버전을 즉시 프로덕션에 적용하는 것을 지양한다.
11. 테스트 (Testing)
테스트는 안전망이자 설계 도구다. 테스트는 버그를 잡는 도구이기 이전에, 코드가 올바르게 설계되었는지를 반영하는 거울 이다. 테스트하기 어려운 코드는 대부분 설계가 잘못된 코드다. 반대로 테스트하기 쉬운 코드는 의존성이 명확하고, 책임이 분리되어 있으며, 도메인 로직이 제자리에 있는 코드다. AI 코 딩 도구가 일상이 된 지금, “테스트가 있다”는 사실보다 “테스트가 올바른 것을 검증하고 있다”는 신뢰 가 더 중요해졌다. AI가 생성한 테스트는 겉으로는 그럴듯해 보이지만, 구현 세부사항에 강하게 결합되거나 의미 없는 Assertion으로 가득 찬 경우가 많다. 리팩토링 한 번에 테스트 수십 개가 한꺼번에 깨진다면, 그 테스트들은 방어망이 아닌 짐이다.
테스트 철학
1) 구현이 아닌 동작을 테스트한다
테스트의 역할은 코드가 어떻게(How) 동작하는지가 아니라 무엇을(What) 하는지를 보장하는 데 있다. 메서드 이름을 바꾸고, 반복문을 재귀로 교체하고, 중간 변수를 제거하는 순수 리팩토링은 외부 동작을 바꾸지 않는다. 이런 변경에 테스트가 깨진다면, 그 테스트는 동작이 아니라 구현을 잠그고 있었다.
2) Classicist TDD를 기본으로 선택한다
- Mockist(London School) 는 협력 객체를 Mock으로 교체하고 객체 간 상호작용을 검증한다.
- Classicist(Chicago School) 는 가능한 한 실제 협력 객체를 사용하고 최종 상태와 반환값을 검증한다.
팀은 Classicist TDD를 기본으로 선택 한다. 이유는 명확하다. AI 도구는 코드를 리팩토링하 거나 재생성할 때 내부 구현을 자주 바꾼다. Mockist 방식은 구현에 결합되므로, AI가 내부를 바꿀 때마다 테스트가 따라서 깨진다. Classicist 방식의 테스트는 동작이 동일하면 내부 구현이 어떻게 바뀌든 통과한다. 단, 두 방식은 배타적이지 않다. 내부 로직은 상태로, 외부 부수효과는 상호작용으로 검증하는 것 이 원칙에 부합한다. 이메일 발송, 메시지 큐 발행, 외부 API 호출처럼 부수효과 자체가 비즈니스 요구사항인 경우는 상호작용 검증이 적합하다.
3) 테스트 레벨은 위험에 따라 선택한다
단위 테스트는 빠르지만 실제 시스템과 멀어질수록 검증력이 떨어진다. 유스케이스 하나를 실 DB와 함께 통합 테스트로 검증하면, 그 경로 위의 단위 테스트 여러 개를 대체한다. 단위 테스트는 통합 테스트로 커버하기 어려운 복잡한 도메인 로직과 엣지 케이스에만 집중한다.

