Policy vs. Detail

Policy vs. Detail

소프트웨어 아키텍처에서 Policy 와 Detail 의 분리는 시스템의 핵심 비즈니스 규칙과 외부 인터페이스, 기술적 구현을 명확히 구분하는 원칙이다. 정책은 시스템의 전체적인 동작과 구조를 정의하는 중요한 비즈니스 규칙과 관련된 결정으로, 변경될 가능성이 적고 안정적이다. 반면 상세 구현은 정책을 실행하기 위한 특정 기술, 프레임워크, 데이터베이스 등과 같은 구체적인 실행 방법에 관한 것으로, 상대적으로 자주 변경된다. 이러한 분리는 의존성을 올바른 방향으로 관리하여 시스템의 유연성, 확장성, 유지보수성을 크게 향상시키는 데 핵심적인 역할을 한다. 의존성 규칙을 통해 세부사항이 정책에 의존하도 함으로써 비즈니스 로직의 안정성을 보장하고, 기술적 변경으로부터 핵심 로직을 보호할 수 있다.

배경

Policy vs. Detail 개념은 Robert C. Martin 의 Clean Architecture 에서 체계화되었으며, 다음과 같은 문제점들을 해결하기 위해 등장했다:

• 기술 중심 설계의 문제: 비즈니스 로직이 기술적 세부사항에 강하게 결합
• 변경의 파급효과: 데이터베이스나 프레임워크 변경이 비즈니스 로직에 영향
• 테스트의 어려움: 외부 의존성으로 인한 단위 테스트 복잡성
• 재사용성 부족: 특정 기술에 종속된 비즈니스 로직

Policy vs. Detail 비교

Policy 와 Detail 의 구분은 소프트웨어 시스템에서 변경의 이유와 빈도, 중요도에 따라 결정된다. 이 분리를 통해 시스템의 핵심 가치를 보호하고 기술적 변경에 대한 유연성을 확보할 수 있다.

• 정책과 상세 구현을 분리함으로써 변경에 대한 영향을 최소화하고, 시스템의 유연성과 유지보수성을 향상시킬 수 있다.
• 정책과 상세 구현을 분리하기 위해서는 명확한 경계 (Boundary) 설정이 필요하다:
  • 아키텍처 경계는 시스템의 다양한 영역 간의 명확한 구분선
  • 각 경계는 인터페이스와 어댑터를 통해 소통
  • 경계를 넘어서는 데이터는 단순하고 독립적인 구조여야 함
  • 경계 인터페이스는 내부 원 (정책) 이 소유해야 함
  • 각 영역에서 사용하는 데이터 형식은 해당 영역의 필요에 최적화되어야 함
• 로버트 C. 마틴 (Uncle Bob) 의 클린 아키텍처 (Clean Architecture) 는 정책 vs 상세 구현 원칙을 잘 구현한 아키텍처 패턴이다:
  • 동심원 형태의 계층 구조로 표현됨
  • 내부로 갈수록 더 높은 수준의 추상화 (정책) 를 포함
  • 외부 원은 메커니즘 (상세 구현) 을, 내부 원은 정책을 담당
  • 의존성 규칙을 철저히 준수하여 내부로만 향하도록 설계
  • 정책은 구체적인 기술 선택에 영향을 받지 않음

Policy 중심 설계 vs. Detail 중심 설계 강점과 약점:

의존성 규칙 (Dependency Rule):

목적 및 효과

목적

효과

개발자의 관점에서 정책 (Policy) 과 상세 구현 (Detail) 의 분리는 관심사의 분리 (Separation of Concerns, SoC) 원칙을 매우 효과적으로 실현한다.

주요 기능 및 역할

정책 vs 상세 구현 원칙은 소프트웨어 아키텍처에서 다음과 같은 주요 기능과 역할을 수행한다:

특징

정책 vs 상세 구현 원칙의 주요 특징은 다음과 같다:

정책과 구현 분리를 위한 핵심 아키텍처 설계 원칙

정책 vs 상세 구현 원칙을 구현하기 위한 핵심 원칙들은 다음과 같다:

정책 (Policy) vs. 상세 구현 (Detail) 의 아키텍처 설계 원칙 정리

flowchart TD
    %% Clean Architecture Layers
    subgraph "Clean Architecture Layers"
        D[Frameworks & Drivers<br/>프레임워크 & 드라이버]
        C[Interface Adapters<br/>인터페이스 어댑터]
        U[Use Cases<br/>유스케이스]
        E[Entities<br/>엔티티]
    end

    %% 의존성 흐름
    D --> C
    C --> U
    U --> E

    %% 시맨틱 분류: Policy vs Detail
    classDef policy fill:#4caf50,color:#fff,stroke:#2e7d32,stroke-width:2px
    classDef adapter fill:#ff9800,color:#fff,stroke:#ef6c00,stroke-width:2px
    classDef detail fill:#f44336,color:#fff,stroke:#b71c1c,stroke-width:2px

    class E,U policy
    class C adapter
    class D detail

의존성 규칙 (Dependency Rule):

1. 소스 코드 의존성은 항상 안쪽 (고수준) 을 향해야 함
2. 내부 계층은 외부 계층에 대해 아무것도 알지 말아야 함
3. 외부 계층의 변경이 내부 계층에 영향을 주지 않아야 함

분류에 따른 종류 및 유형

정책 vs 상세 구현 원칙은 다양한 아키텍처 패턴을 통해 구현될 수 있다:

동심원 계층 구조 (Concentric Layer Structure)

클린 아키텍처에서는 동심원 형태의 계층 구조로 표현된다:

• 의존성 방향은 항상 바깥 → 안쪽 (Detail → Policy) 으로 향함
• 안쪽 계층 (Entities, Use Cases) 은 외부 기술에 대해 전혀 알지 않아야 함
• 가장 바깥 계층 (Frameworks & Drivers) 은 교체 가능한 플러그인처럼 동작해야 함
• 각 계층은 자신보다 더 안쪽 계층만 참조 가능

헥사고날 아키텍처 (Hexagonal Architecture) 구조

또 다른 구현 방식인 헥사고날 아키텍처는 다음과 같은 구조를 가진다:

• 내부는 순수한 비즈니스 로직만 포함하며, 외부와의 연결은 모두 추상화된 포트를 통해 이루어짐
• 외부 시스템 (예: DB, API) 은 내부의 포트를 구현하는 어댑터를 통해 연결됨
• 포트와 어댑터는 경계 (Interface) 와 구현체 (Implementation) 관계로 분리됨
• 이 구조는 테스트 용이성, 프레임워크 독립성, 유연한 기술 교체에 유리함

클린 아키텍처 계층 구조 및 의존성 흐름

graph TB
    subgraph "Policy Layer (정책 계층)"
        E[Entities<br/>엔티티]
        UC[Use Cases<br/>유스케이스]
        DS[Domain Services<br/>도메인 서비스]
    end
    
    subgraph "Detail Layer (세부사항 계층)"
        DB[(Database<br/>데이터베이스)]
        WEB[Web Framework<br/>웹 프레임워크]
        UI[User Interface<br/>사용자 인터페이스]
        API[External API<br/>외부 API]
    end
    
    subgraph "Interface Adapters (인터페이스 어댑터)"
        REPO[Repository<br/>저장소]
        CTRL[Controller<br/>컨트롤러]
        PRES[Presenter<br/>프레젠터]
    end
    
    E --> UC
    UC --> DS
    
    UC -.-> REPO
    UC -.-> CTRL
    UC -.-> PRES
    
    REPO --> DB
    CTRL --> WEB
    PRES --> UI
    API --> CTRL
    
    classDef policy fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    classDef detail fill:#fff3e0,stroke:#e65100,stroke-width:2px
    classDef adapter fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    
    class E,UC,DS policy
    class DB,WEB,UI,API detail
    class REPO,CTRL,PRES adapter

범주별 구성 요소

의존성 방향:

• 항상 바깥에서 안쪽 (Detail → Adapter → Policy) 으로 향함
• Use Case는 Repository, Controller, Presenter에 대해 추상화만 알고 있으며, 실제 구현은 어댑터 계층에서 담당
• 이는 정책은 구현을 몰라도 되며, 구현은 정책의 인터페이스를 따르도록 강제하는 구조

장점과 단점

• 장점: 유지보수성, 테스트성, 유연성, 확장성, 협업 구조에 탁월함
• 단점: 초기 설계 비용, 팀 역량, 성능 이슈, 과도한 추상화의 위험

실무 적용 예시

다양한 환경과 상황에서 정책 vs 상세 구현 원칙을 적용하는 방법에 대한 실무 예시는 다음과 같다:

시스템 유형별 계층화 아키텍처 구현

업무 영역에 따른 Policy Vs Detail 구조 적용 사례

활용 사례

사례 1: 결제 시스템의 정책/세부사항 분리

시나리오: 결제 정책 (할인 규칙, 승인 조건 등) 이 자주 변경됨. 외부 결제 게이트웨이, DB, UI 등은 빈번히 교체/변경됨.
시스템 구성: 정책 (비즈니스 규칙) 은 도메인 계층에 집중, 외부 연동 및 데이터 저장은 인프라 계층에서 처리.
워크플로우:

1. 사용자가 결제 요청 → 결제 정책 (Policy) 검증
2. 정책 통과 시 외부 결제 게이트웨이 (Detail) 호출
3. 결제 결과 저장 및 알림 처리 (Detail)
   다이어그램

flowchart TD
    User[사용자]
    Policy["결제 정책(Policy)"]
    Gateway["결제 게이트웨이(Detail)"]
    DB["DB(Detail)"]
    User --> Policy
    Policy --> Gateway
    Gateway --> DB

사례 2: 온라인 뱅킹 시스템

시나리오: 대형 은행의 온라인 뱅킹 시스템 구축

시스템 구성

graph TB
    subgraph "Policy Layer - 은행 핵심 업무"
        AC[Account Entity<br/>계좌 엔티티]
        TR[Transfer Use Case<br/>이체 유스케이스]
        LN[Loan Service<br/>대출 서비스]
        FR[Fraud Detection<br/>부정거래 탐지]
    end
    
    subgraph "Interface Adapters - 어댑터"
        WC[Web Controller<br/>웹 컨트롤러]
        MF[Mobile Facade<br/>모바일 파사드]
        AR[Account Repository<br/>계좌 저장소]
        EG[External Gateway<br/>외부 게이트웨이]
    end
    
    subgraph "Details - 기술적 세부사항"
        WEB[Web UI<br/>웹 인터페이스]
        MOB[Mobile App<br/>모바일 앱]
        DB[(Core Banking DB<br/>핵심 은행 DB)]
        PAY[Payment Gateway<br/>결제 게이트웨이]
        KYC[KYC Service<br/>본인확인 서비스]
    end
    
    AC --> TR
    TR --> LN
    TR --> FR
    
    TR -.-> AR
    TR -.-> EG
    WC --> TR
    MF --> TR
    
    WEB --> WC
    MOB --> MF
    AR --> DB
    EG --> PAY
    EG --> KYC
    
    classDef policy fill:#e8f5e8,stroke:#2e7d32,stroke-width:3px
    classDef adapter fill:#fff3e0,stroke:#f57722,stroke-width:2px
    classDef detail fill:#ffebee,stroke:#c62828,stroke-width:2px
    
    class AC,TR,LN,FR policy
    class WC,MF,AR,EG adapter
    class WEB,MOB,DB,PAY,KYC detail

워크플로우:

1. 이체 요청 처리:
   • 사용자가 모바일 앱에서 이체 요청
   • Mobile Facade 가 요청을 받아 Transfer Use Case 로 전달
   • Transfer Use Case 가 비즈니스 규칙 검증 (잔액, 한도, 부정거래)
   • Account Repository 를 통해 계좌 정보 조회/업데이트
   • External Gateway 를 통해 타행 이체 처리
2. 부정거래 탐지:
   • Fraud Detection 서비스가 이체 패턴 분석
   • 의심 거래 발견 시 이체 중단 및 알림

각 계층의 역할:

• Policy Layer (은행 핵심 업무):
  • 계좌 관리 규칙: 최소 잔액, 이체 한도
  • 이체 업무 규칙: 본인 확인, 수수료 계산
  • 대출 심사 규칙: 신용 평가, 담보 평가
  • 부정거래 탐지: 패턴 분석, 위험도 계산
• Detail Layer (기술적 세부사항):
  • 웹/모바일 UI: 사용자 인터페이스
  • 데이터베이스: Oracle, PostgreSQL 등
  • 외부 연동: SWIFT, 카드사 API
  • 인증 시스템: ActiveDirectory, LDAP

사례 3: 전자상거래 플랫폼의 할인 정책 적용

시나리오: 전자상거래 플랫폼의 할인 정책 적용
정책 (Policy): 특정 기간 동안 특정 상품에 대해 10% 할인 적용
세부사항 (Detail): 할인 계산 로직, UI 표시, 데이터베이스 저장 방식 등
시스템 구성 다이어그램:

graph TD
  A[Discount Policy Module] --> B[Discount Calculation Service]
  B --> C[UI Component]
  B --> D[Database]

Workflow:

1. 사용자가 상품을 조회하면, 할인 정책 모듈에서 해당 상품에 대한 할인 여부를 확인
2. 할인 계산 서비스에서 할인 금액을 계산
3. UI 컴포넌트에서 할인 금액을 표시
4. 주문 시 데이터베이스에 할인 금액 저장

차이점: 할인 정책 변경 시 정책 모듈만 수정하면 되며, 계산 로직이나 UI, 데이터베이스는 변경하지 않아도 되어 유지보수가 용이

실무에서 효과적으로 적용하기 위한 고려사항 및 주의할 점

• 설계, 데이터 처리, 경계 구조, 조직 운영, 도입 방식, 성능 고려 등 다면적 요소 필요
• 기술적 아키텍처뿐 아니라 조직적/문화적 기반도 함께 설계해야 성공적으로 적용 가능
• 실무에서는 과하지 않게, 점진적으로, 현실적인 변경 가능성 기반으로 설계하는 것이 핵심

최적화하기 위한 고려사항

• 핵심 최적화 방향: " 계층 경계 최소화 “, " 불필요한 데이터/자원 최소화 “, " 병목 지점 식별 후 집중 "
• 성능보다 먼저 고려할 것: 측정 기반 최적화, 유지보수성 유지, 실제 사용 패턴 반영
• 실무에서는 캐싱 + 비동기 + 병렬 처리의 적절한 조합이 가장 실용적인 성능 향상 수단

장점과 단점

주제와 관련하여 주목할 내용

하위 주제로 분류해서 추가적으로 학습해야할 내용들

관련 분야와 함께 추가로 학습해야할 내용들

용어 정리

참고 및 출처

• Uncle Bob - Clean Architecture 설명
• Hexagonal Architecture (Alistair Cockburn)
• Martin Fowler - Inversion of Control
• Spring - Dependency Injection 가이드
• Domain-Driven Design Reference
• Clean Architecture - The Clean Code Blog - Uncle Bob
• Policy vs Detail - Roadmap.sh
• The Clean Architecture Dependency Rule | InformIT
• Dependency inversion principle - Wikipedia
• Clean Architecture by Uncle Bob: Summary and review - CleverCoder.net
• Architectural principles - .NET | Microsoft Learn
• Complete Guide to Clean Architecture | GeeksforGeeks
• Clean Architecture Reference Guide | Bitloops Docs
• Organizing App Logic with the Clean Architecture | Khalil Stemmler
• Software architecture and boundaries | Convinced Coder
• Policy vs Detail - roadmap.sh
• Architectural principles - Microsoft Learn
• The Clean Architecture - Uncle Bob’s Blog
• Clean Architecture Summary and Review
• TOGAF Architecture Principles
• Architecture Principles: An approach to effective decision making
• InfoQ Software Architecture and Design Trends Report - 2025
• Top Software Architecture Patterns for 2025
• Bitloops: Clean Architecture - The Fundamentals
• SweetProcess: Policy vs. Procedure vs. Process
• Hidayat Rizvi: Policy vs Procedure vs Standard
• Comprose: Policy, Procedure, Work Instructions, Process
• StandardFusion: Policy Management Best Practices