헥사고날 아키텍처: 포트와 어댑터 실용 가이드

끊임없이 진화하는 소프트웨어 개발 환경에서 견고하고, 유지보수 가능하며, 테스트하기 쉬운 애플리케이션을 구축하는 것은 무엇보다 중요합니다. 헥사고날 아키텍처(Hexagonal Architecture), 일명 포트와 어댑터(Ports and Adapters)는 애플리케이션의 핵심 비즈니스 로직을 외부 의존성으로부터 분리하여 이러한 문제를 해결하는 아키텍처 패턴입니다. 이 가이드는 전 세계 개발자들을 위해 헥사고날 아키텍처에 대한 포괄적인 이해와 그 이점, 그리고 실용적인 구현 전략을 제공하는 것을 목표로 합니다.

헥사고날 아키텍처란 무엇인가?

알리스테어 콕번(Alistair Cockburn)이 창안한 헥사고날 아키텍처는 애플리케이션의 핵심 비즈니스 로직을 외부 세계로부터 격리하는 아이디어를 중심으로 합니다. 이러한 격리는 포트(ports)와 어댑터(adapters)를 사용하여 달성됩니다.

• 코어(애플리케이션): 비즈니스 로직과 도메인 모델을 포함하는 애플리케이션의 심장부를 나타냅니다. 이는 특정 기술이나 프레임워크에 독립적이어야 합니다.
• 포트: 코어 애플리케이션이 외부 세계와 상호작용하기 위해 사용하는 인터페이스를 정의합니다. 이는 데이터베이스, 사용자 인터페이스 또는 메시징 큐와 같은 외부 시스템과 애플리케이션이 상호작용하는 방법에 대한 추상적인 정의입니다. 포트는 두 가지 유형으로 나눌 수 있습니다:
  • 드라이빙(기본) 포트: 외부 액터(예: 사용자, 다른 애플리케이션)가 코어 애플리케이션 내에서 작업을 시작할 수 있도록 하는 인터페이스를 정의합니다.
  • 드리븐(보조) 포트: 코어 애플리케이션이 외부 시스템(예: 데이터베이스, 메시지 큐)과 상호작용하기 위해 사용하는 인터페이스를 정의합니다.
• 어댑터: 포트에 의해 정의된 인터페이스를 구현합니다. 이들은 코어 애플리케이션과 외부 시스템 간의 번역기 역할을 합니다. 어댑터에는 두 가지 유형이 있습니다:
  • 드라이빙(기본) 어댑터: 드라이빙 포트를 구현하여 외부 요청을 코어 애플리케이션이 이해할 수 있는 명령이나 쿼리로 변환합니다. 예로는 사용자 인터페이스 컴포넌트(예: 웹 컨트롤러), 명령줄 인터페이스 또는 메시지 큐 리스너가 있습니다.
  • 드리븐(보조) 어댑터: 드리븐 포트를 구현하여 코어 애플리케이션의 요청을 외부 시스템과의 특정 상호작용으로 변환합니다. 예로는 데이터베이스 접근 객체, 메시지 큐 생산자 또는 API 클라이언트가 있습니다.

이렇게 생각해보세요: 코어 애플리케이션이 중앙에 있고, 육각형의 껍질로 둘러싸여 있습니다. 포트는 이 껍질의 입구와 출구이며, 어댑터는 이 포트에 연결되어 코어를 외부 세계와 연결합니다.

헥사고날 아키텍처의 핵심 원칙

몇 가지 핵심 원칙이 헥사고날 아키텍처의 효과를 뒷받침합니다:

• 의존성 역전: 코어 애플리케이션은 구체적인 구현(어댑터)이 아닌 추상화(포트)에 의존합니다. 이는 SOLID 디자인의 핵심 원칙입니다.
• 명시적 인터페이스: 포트는 코어와 외부 세계 간의 경계를 명확하게 정의하여 계약 기반의 통합 방식을 촉진합니다.
• 테스트 용이성: 코어를 외부 의존성으로부터 분리함으로써, 포트의 모의(mock) 구현을 사용하여 비즈니스 로직을 격리된 상태에서 테스트하기가 더 쉬워집니다.
• 유연성: 어댑터는 코어 애플리케이션에 영향을 주지 않고 교체할 수 있어, 변화하는 기술이나 요구사항에 쉽게 적응할 수 있습니다. MySQL에서 PostgreSQL로 전환해야 하는 경우를 상상해보세요. 데이터베이스 어댑터만 변경하면 됩니다.

헥사고날 아키텍처 사용의 이점

헥사고날 아키텍처를 채택하면 수많은 이점이 있습니다:

• 향상된 테스트 용이성: 관심사의 분리는 핵심 비즈니스 로직에 대한 단위 테스트 작성을 훨씬 쉽게 만듭니다. 포트를 모의(mocking) 처리함으로써 코어를 격리하고 외부 시스템에 의존하지 않고 철저하게 테스트할 수 있습니다. 예를 들어, 결제 게이트웨이 포트를 모의 처리하여 실제 게이트웨이에 연결하지 않고도 성공 및 실패 트랜잭션을 시뮬레이션함으로써 결제 처리 모듈을 테스트할 수 있습니다.
• 증가된 유지보수성: 외부 시스템이나 기술의 변경이 코어 애플리케이션에 미치는 영향이 최소화됩니다. 어댑터는 절연층 역할을 하여 외부의 변동성으로부터 코어를 보호합니다. SMS 알림 발송에 사용되는 서드파티 API의 형식이나 인증 방법이 변경되는 시나리오를 생각해보세요. 코어 애플리케이션은 그대로 두고 SMS 어댑터만 업데이트하면 됩니다.
• 강화된 유연성: 어댑터를 쉽게 교체할 수 있어, 대규모 리팩토링 없이 새로운 기술이나 요구사항에 적응할 수 있습니다. 이는 실험과 혁신을 촉진합니다. 회사가 데이터 저장소를 기존의 관계형 데이터베이스에서 NoSQL 데이터베이스로 마이그레이션하기로 결정할 수 있습니다. 헥사고날 아키텍처를 사용하면 데이터베이스 어댑터만 교체하면 되므로 코어 애플리케이션에 대한 중단을 최소화할 수 있습니다.
• 결합도 감소: 코어 애플리케이션은 외부 의존성으로부터 분리되어 더 모듈화되고 응집력 있는 설계를 이끌어냅니다. 이는 코드베이스를 이해하고, 수정하고, 확장하기 쉽게 만듭니다.
• 독립적인 개발: 다른 팀이 코어 애플리케이션과 어댑터를 독립적으로 작업할 수 있어 병렬 개발과 더 빠른 시장 출시를 촉진합니다. 예를 들어, 한 팀은 핵심 주문 처리 로직 개발에 집중하고 다른 팀은 사용자 인터페이스와 데이터베이스 어댑터를 구축할 수 있습니다.

헥사고날 아키텍처 구현: 실용 예제

사용자 등록 시스템의 간단한 예제를 통해 헥사고날 아키텍처의 구현을 설명해 보겠습니다. 명확성을 위해 가상의 프로그래밍 언어(Java 또는 C#과 유사한)를 사용하겠습니다.

1. 코어(애플리케이션) 정의

코어 애플리케이션은 새 사용자 등록을 위한 비즈니스 로직을 포함합니다.

// Core/UserService.java (또는 UserService.cs)
public class UserService {
    private final UserRepository userRepository;
    private final PasswordHasher passwordHasher;
    private final UserValidator userValidator;

    public UserService(UserRepository userRepository, PasswordHasher passwordHasher, UserValidator userValidator) {
        this.userRepository = userRepository;
        this.passwordHasher = passwordHasher;
        this.userValidator = userValidator;
    }

    public Result<User, String> registerUser(String username, String password, String email) {
        // 사용자 입력 유효성 검사
        ValidationResult validationResult = userValidator.validate(username, password, email);
        if (!validationResult.isValid()) {
            return Result.failure(validationResult.getErrorMessage());
        }

        // 사용자가 이미 존재하는지 확인
        if (userRepository.findByUsername(username).isPresent()) {
            return Result.failure("사용자 이름이 이미 존재합니다");
        }

        // 비밀번호 해싱
        String hashedPassword = passwordHasher.hash(password);

        // 새 사용자 생성
        User user = new User(username, hashedPassword, email);

        // 사용자를 리포지토리에 저장
        userRepository.save(user);

        return Result.success(user);
    }
}

2. 포트 정의

코어 애플리케이션이 외부 세계와 상호작용하기 위해 사용하는 포트를 정의합니다.

// Ports/UserRepository.java (또는 UserRepository.cs)
public interface UserRepository {
    Optional<User> findByUsername(String username);
    void save(User user);
}

// Ports/PasswordHasher.java (또는 PasswordHasher.cs)
public interface PasswordHasher {
    String hash(String password);
}

//Ports/UserValidator.java (또는 UserValidator.cs)
public interface UserValidator{
  ValidationResult validate(String username, String password, String email);
}

//Ports/ValidationResult.java (또는 ValidationResult.cs)
public interface ValidationResult{
  boolean isValid();
  String getErrorMessage();
}

3. 어댑터 정의

코어 애플리케이션을 특정 기술에 연결하는 어댑터를 구현합니다.

// Adapters/DatabaseUserRepository.java (또는 DatabaseUserRepository.cs)
public class DatabaseUserRepository implements UserRepository {
    private final DatabaseConnection databaseConnection;

    public DatabaseUserRepository(DatabaseConnection databaseConnection) {
        this.databaseConnection = databaseConnection;
    }

    @Override
    public Optional<User> findByUsername(String username) {
        // JDBC, JPA 또는 다른 데이터베이스 접근 기술을 사용한 구현
        // ...
        return Optional.empty(); // 플레이스홀더
    }

    @Override
    public void save(User user) {
        // JDBC, JPA 또는 다른 데이터베이스 접근 기술을 사용한 구현
        // ...
    }
}

// Adapters/BCryptPasswordHasher.java (또는 BCryptPasswordHasher.cs)
public class BCryptPasswordHasher implements PasswordHasher {
    @Override
    public String hash(String password) {
        // BCrypt 라이브러리를 사용한 구현
        // ...
        return "hashedPassword"; //플레이스홀더
    }
}

//Adapters/SimpleUserValidator.java (또는 SimpleUserValidator.cs)
public class SimpleUserValidator implements UserValidator {
  @Override
  public ValidationResult validate(String username, String password, String email){
    // 간단한 유효성 검사 로직
     if (username == null || username.isEmpty()) {
            return new SimpleValidationResult(false, "사용자 이름은 비워둘 수 없습니다");
        }
        if (password == null || password.length() < 8) {
            return new SimpleValidationResult(false, "비밀번호는 8자 이상이어야 합니다");
        }
        if (email == null || !email.contains("@")) {
            return new SimpleValidationResult(false, "잘못된 이메일 형식입니다");
        }

        return new SimpleValidationResult(true, null);
  }
}

//Adapters/SimpleValidationResult.java (또는 SimpleValidationResult.cs)
public class SimpleValidationResult implements ValidationResult {
  private final boolean valid;
  private final String errorMessage;

    public SimpleValidationResult(boolean valid, String errorMessage) {
        this.valid = valid;
        this.errorMessage = errorMessage;
    }
  @Override
  public boolean isValid(){
    return valid;
  }

  @Override
  public String getErrorMessage(){
    return errorMessage;
  }
}



//Adapters/WebUserController.java (또는 WebUserController.cs)
// 드라이빙 어댑터 - 웹으로부터의 요청을 처리
public class WebUserController {
    private final UserService userService;

    public WebUserController(UserService userService) {
        this.userService = userService;
    }

    public String registerUser(String username, String password, String email) {
        Result<User, String> result = userService.registerUser(username, password, email);
        if (result.isSuccess()) {
            return "등록 성공!";
        } else {
            return "등록 실패: " + result.getFailure();
        }
    }
}

4. 구성(Composition)

모든 것을 함께 연결합니다. 이러한 구성(의존성 주입)은 일반적으로 애플리케이션의 진입점이나 의존성 주입 컨테이너 내에서 발생합니다.

// Main 클래스 또는 의존성 주입 설정
public class Main {
    public static void main(String[] args) {
        // 어댑터 인스턴스 생성
        DatabaseConnection databaseConnection = new DatabaseConnection("jdbc:mydb://localhost:5432/users", "user", "password");
        DatabaseUserRepository userRepository = new DatabaseUserRepository(databaseConnection);
        BCryptPasswordHasher passwordHasher = new BCryptPasswordHasher();
        SimpleUserValidator userValidator = new SimpleUserValidator();

        // 어댑터를 주입하여 코어 애플리케이션 인스턴스 생성
        UserService userService = new UserService(userRepository, passwordHasher, userValidator);

        // 드라이빙 어댑터를 생성하고 서비스에 연결
        WebUserController userController = new WebUserController(userService);

        // 이제 userController를 통해 사용자 등록 요청을 처리할 수 있음
        String result = userController.registerUser("john.doe", "P@sswOrd123", "john.doe@example.com");
        System.out.println(result);
    }
}



// DatabaseConnection은 시연 목적으로만 사용되는 간단한 클래스
class DatabaseConnection {
    private String url;
    private String username;
    private String password;

    public DatabaseConnection(String url, String username, String password) {
        this.url = url;
        this.username = username;
        this.password = password;
    }

    // ... 데이터베이스 연결 메서드 (간결성을 위해 구현되지 않음)
}

// Result 클래스 (함수형 프로그래밍의 Either와 유사)
class Result<T, E> {
    private final T success;
    private final E failure;
    private final boolean isSuccess;

    private Result(T success, E failure, boolean isSuccess) {
        this.success = success;
        this.failure = failure;
        this.isSuccess = isSuccess;
    }

    public static <T, E> Result<T, E> success(T value) {
        return new Result<>(value, null, true);
    }

    public static <T, E> Result<T, E> failure(E error) {
        return new Result<>(null, error, false);
    }

    public boolean isSuccess() {
        return isSuccess;
    }

    public T getSuccess() {
        if (!isSuccess) {
            throw new IllegalStateException("결과가 실패입니다");
        }
        return success;
    }

    public E getFailure() {
        if (isSuccess) {
            throw new IllegalStateException("결과가 성공입니다");
        }
        return failure;
    }
}

class User {
    private String username;
    private String password;
    private String email;

    public User(String username, String password, String email) {
        this.username = username;
        this.password = password;
        this.email = email;
    }

    // getter 및 setter (간결성을 위해 생략)

}

설명:

• UserService는 핵심 비즈니스 로직을 나타냅니다. 이것은 UserRepository, PasswordHasher, UserValidator 인터페이스(포트)에 의존합니다.
• DatabaseUserRepository, BCryptPasswordHasher, SimpleUserValidator는 각각의 포트를 구체적인 기술(데이터베이스, BCrypt, 기본 유효성 검사 로직)을 사용하여 구현하는 어댑터입니다.
• WebUserController는 웹 요청을 처리하고 UserService와 상호작용하는 드라이빙 어댑터입니다.
• main 메서드는 어댑터의 인스턴스를 생성하고 이를 코어 애플리케이션에 주입하여 애플리케이션을 구성합니다.

고급 고려사항 및 모범 사례

헥사고날 아키텍처의 기본 원칙은 간단하지만, 염두에 두어야 할 몇 가지 고급 고려사항이 있습니다:

• 포트에 적합한 세분성 선택: 포트에 대한 적절한 추상화 수준을 결정하는 것이 중요합니다. 너무 세분화된 포트는 불필요한 복잡성을 초래할 수 있고, 너무 광범위한 포트는 유연성을 제한할 수 있습니다. 포트를 정의할 때 단순성과 적응성 사이의 절충점을 고려하십시오.
• 트랜잭션 관리: 여러 외부 시스템을 다룰 때 트랜잭션 일관성을 보장하는 것이 어려울 수 있습니다. 분산 트랜잭션 관리 기술을 사용하거나 보상 트랜잭션을 구현하여 데이터 무결성을 유지하는 것을 고려하십시오. 예를 들어, 사용자 등록이 별도의 청구 시스템에서 계정을 생성하는 것을 포함한다면, 두 작업이 모두 함께 성공하거나 실패하도록 보장해야 합니다.
• 오류 처리: 외부 시스템의 장애를 정상적으로 처리하기 위해 견고한 오류 처리 메커니즘을 구현하십시오. 연쇄적인 장애를 방지하기 위해 서킷 브레이커나 재시도 메커니즘을 사용하십시오. 어댑터가 데이터베이스에 연결하지 못할 때, 애플리케이션은 오류를 정상적으로 처리하고 잠재적으로 연결을 재시도하거나 사용자에게 유익한 오류 메시지를 제공해야 합니다.
• 테스트 전략: 애플리케이션의 품질을 보장하기 위해 단위 테스트, 통합 테스트, 종단 간 테스트를 조합하여 사용하십시오. 단위 테스트는 핵심 비즈니스 로직에 초점을 맞춰야 하며, 통합 테스트는 코어와 어댑터 간의 상호작용을 검증해야 합니다.
• 의존성 주입 프레임워크: 의존성 주입 프레임워크(예: Spring, Guice)를 활용하여 컴포넌트 간의 의존성을 관리하고 애플리케이션의 구성을 단순화하십시오. 이러한 프레임워크는 의존성을 생성하고 주입하는 과정을 자동화하여, 보일러플레이트 코드를 줄이고 유지보수성을 향상시킵니다.
• CQRS (Command Query Responsibility Segregation): 헥사고날 아키텍처는 애플리케이션의 읽기 및 쓰기 모델을 분리하는 CQRS와 잘 어울립니다. 이는 특히 복잡한 시스템에서 성능과 확장성을 더욱 향상시킬 수 있습니다.

헥사고날 아키텍처의 실제 사용 사례

많은 성공적인 기업과 프로젝트들이 견고하고 유지보수 가능한 시스템을 구축하기 위해 헥사고날 아키텍처를 채택했습니다:

• 전자상거래 플랫폼: 전자상거래 플랫폼은 종종 헥사고날 아키텍처를 사용하여 핵심 주문 처리 로직을 결제 게이트웨이, 배송 제공업체, 재고 관리 시스템과 같은 다양한 외부 시스템으로부터 분리합니다. 이를 통해 핵심 기능에 지장을 주지 않고 새로운 결제 방법이나 배송 옵션을 쉽게 통합할 수 있습니다.
• 금융 애플리케이션: 은행 시스템 및 거래 플랫폼과 같은 금융 애플리케이션은 헥사고날 아키텍처가 제공하는 테스트 용이성과 유지보수성의 이점을 누립니다. 핵심 금융 로직은 격리된 상태에서 철저하게 테스트할 수 있으며, 어댑터를 사용하여 시장 데이터 제공업체 및 청산소와 같은 다양한 외부 서비스에 연결할 수 있습니다.
• 마이크로서비스 아키텍처: 헥사고날 아키텍처는 각 마이크로서비스가 자체적인 핵심 비즈니스 로직과 외부 의존성을 가진 경계 컨텍스트를 나타내는 마이크로서비스 아키텍처에 자연스럽게 들어맞습니다. 포트와 어댑터는 마이크로서비스 간의 통신을 위한 명확한 계약을 제공하여 느슨한 결합과 독립적인 배포를 촉진합니다.
• 레거시 시스템 현대화: 헥사고날 아키텍처는 기존 코드를 어댑터로 감싸고 포트 뒤에 새로운 핵심 로직을 도입함으로써 레거시 시스템을 점진적으로 현대화하는 데 사용될 수 있습니다. 이를 통해 전체 애플리케이션을 다시 작성하지 않고도 레거시 시스템의 일부를 점진적으로 교체할 수 있습니다.

과제 및 절충점

헥사고날 아키텍처는 상당한 이점을 제공하지만, 관련된 과제와 절충점을 인식하는 것이 중요합니다:

• 복잡성 증가: 헥사고날 아키텍처를 구현하면 추가적인 추상화 계층이 도입되어 코드베이스의 초기 복잡성이 증가할 수 있습니다.
• 학습 곡선: 개발자들은 포트와 어댑터의 개념과 이를 효과적으로 적용하는 방법을 이해하는 데 시간이 필요할 수 있습니다.
• 과도한 엔지니어링 가능성: 불필요한 포트와 어댑터를 만들어 과도하게 엔지니어링하는 것을 피하는 것이 중요합니다. 간단한 디자인으로 시작하여 필요에 따라 점진적으로 복잡성을 추가하십시오.
• 성능 고려사항: 추가적인 추상화 계층은 잠재적으로 약간의 성능 오버헤드를 유발할 수 있지만, 대부분의 애플리케이션에서는 일반적으로 무시할 수 있는 수준입니다.

특정 프로젝트의 요구사항과 팀의 역량이라는 맥락에서 헥사고날 아키텍처의 이점과 과제를 신중하게 평가하는 것이 중요합니다. 이는 만병통치약이 아니며, 모든 프로젝트에 최선의 선택이 아닐 수도 있습니다.

결론

포트와 어댑터를 강조하는 헥사고날 아키텍처는 유지보수 가능하고, 테스트 용이하며, 유연한 애플리케이션을 구축하기 위한 강력한 접근 방식을 제공합니다. 핵심 비즈니스 로직을 외부 의존성으로부터 분리함으로써, 변화하는 기술과 요구사항에 쉽게 적응할 수 있게 해줍니다. 고려해야 할 과제와 절충점이 있지만, 헥사고날 아키텍처의 이점은 특히 복잡하고 오래 지속되는 애플리케이션의 경우 비용을 능가하는 경우가 많습니다. 의존성 역전과 명시적 인터페이스의 원칙을 수용함으로써, 더 탄력적이고 이해하기 쉬우며 현대 소프트웨어 환경의 요구를 더 잘 충족시킬 수 있는 시스템을 만들 수 있습니다.

이 가이드는 헥사고날 아키텍처의 핵심 원칙부터 실용적인 구현 전략까지 포괄적인 개요를 제공했습니다. 이러한 개념을 더 탐구하고 자신의 프로젝트에 적용해 보시기를 권장합니다. 헥사고날 아키텍처를 배우고 채택하는 데 투자하는 것은 장기적으로 확실히 보상받을 것이며, 이는 더 높은 품질의 소프트웨어와 더 만족스러운 개발 팀으로 이어질 것입니다.

궁극적으로, 올바른 아키텍처를 선택하는 것은 프로젝트의 특정 요구에 따라 달라집니다. 결정을 내릴 때 복잡성, 수명, 유지보수성 요구사항을 고려하십시오. 헥사고날 아키텍처는 견고하고 적응 가능한 애플리케이션을 구축하기 위한 견고한 기반을 제공하지만, 이는 소프트웨어 아키텍트의 도구 상자에 있는 하나의 도구일 뿐입니다.