도메인 엔티티와 영속성 엔티티

개요

소프트웨어 아키텍처에서 도메인 엔티티와 영속성 엔티티를 분리하는 것은 중요한 설계 원칙 중 하나이다. 이 원칙은 클린 아키텍처의 핵심 개념을 기반으로 하며, 도메인 로직과 영속성 계층 간의 의존성을 최소화하여 시스템의 유지 보수성과 확장성을 높이는 데 목적이 있다.

이번 게시글에서는 이러한 도메인 엔티티와 영속성 엔티티의 차이점에 대해 알아보고, 이 둘을 분리함으로써 얻을 수 있는 이점과 주의해야 할 점 그리고 언제 분리하면 좋을지에 대해 정리했다.

 

 

도메인 엔티티

먼저 도메인 엔티티의 개념부터 살펴보면 도메인 엔티티는 비즈니스 도메인 내의 개념을 나타내는 객체로, 전자상거래 시스템에서는 'Order', 'Customer', 'Product'등이 도메인 엔티티가 될 수 있다. 다음은 간단한 예시 코드이다.

import java.util.ArrayList;
import java.util.List;
import java.util.Objects;

public class Order {
    private String orderId;
    private Address shippingAddress;
    private List<OrderItem> items;
    private OrderStatus status;

    public Order(String orderId, Address shippingAddress, List<OrderItem> items) {
        this.orderId = orderId;
        this.shippingAddress = shippingAddress;
        this.items = new ArrayList<>(items);
        this.status = OrderStatus.PENDING;
    }
    
    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        Order order = (Order) o;
        return orderId.equals(order.orderId);
    }

    @Override
    public int hashCode() {
        return Objects.hash(orderId);
    }
}

import java.util.Objects;

public class Address {
    private final String street;
    private final String city;
    private final String zipcode;

    public Address(String street, String city, String zipcode) {
        this.street = street;
        this.city = city;
        this.zipcode = zipcode;
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        Address address = (Address) o;
        return Objects.equals(street, address.street) && Objects.equals(city, address.city) && Objects.equals(zipcode, address.zipcode);
    }

    @Override
    public int hashCode() {
        return Objects.hash(street, city, zipcode);
    }
}

위 코드에서 Address는 Value Object로, 엔티티와 달리 고유 식별자가 없으며 속성만으로 동일성을 판단한다. 이는 불변(immutable) 객체로 주로 값 타입을 표현하는 데 사용된다. 반면 Order는 고유한 식별자인 orderId를 가지며, 이 식별자를 통해 엔티티 간의 동일성을 보장한다. 이를 잘 보여주는 부분이 equals와 hashCode 메서드의 구현 부분인데, 엔티티는 ID만 비교하고, VO는 모든 속성을 비교하는 것을 확인할 수 있다.

또한 import 부분을 보면 순수 POJO로 구성된 것을 확인할 수 있다.

 

 

영속성 엔티티

그렇다면 영속성 엔티티는 어떨까? 영속성 엔티티는 데이터베이스에 저장되고 ORM을 통해 관리되는 객체이다. 영속성 엔티티는 데이터베이스의 테이블과 1:1로 매핑되며 주로 JPA 같은 ORM 프레임워크를 사용하여 데이터베이스와 상호작용한다. 다음은 간단한 영속성 엔티티 예시이다.

import java.util.ArrayList;
import java.util.List;
import java.util.Objects;

import jakarta.persistence.*;

@Entity
@Table(name = "orders")
public class Order {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long orderId;

    @Embedded
    private Address shippingAddress;

    @OneToMany(cascade = CascadeType.ALL, orphanRemoval = true)
    @JoinColumn(name = "order_id")
    private List<OrderItem> items;

    @Enumerated(EnumType.STRING)
    private OrderStatus status;

    protected Order(){
    }

    public Order(Address shippingAddress, List<OrderItem> items) {
        this.shippingAddress = shippingAddress;
        this.items = new ArrayList<>(items);
        this.status = OrderStatus.PENDING;
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        Order order = (Order) o;
        return orderId.equals(order.orderId);
    }

    @Override
    public int hashCode() {
        return Objects.hash(orderId);
    }
 }
 
 // 이하 Address 등 생략

영속성 엔티티는 영속성을 위한 어노테이션들이 붙어 있다는 점에서 도메인 엔티티와 다르다. Order 엔티티는 @Entity 어노테이션으로 지정되어 있으며, 데이터베이스 테이블과 매핑된다. Address는 @Embeddable 어노테이션을 사용하여 내장 타입으로 정의되었고, OrderItem은 Order와 @OneToMany 관계를 갖는다.

도메인 엔티티는 주로 비즈니스 로직을 포함하고 있어 비즈니스 규칙과 도메인 개념을 표현하는 데 중점을 둔다. 반면 영속성 엔티티는 데이터베이스와의 상호작용을 위해 설계되며, 데이터 저장과 조회에 중점을 둔다. 현재 예시에서는 도메인 엔티티와 영속성 엔티티의 필드를 전부 동일하게 작성했지만, 보통의 경우 도메인 엔티티는 비즈니스 로직을 담고 있어 필드와 메서드가 더 복잡해질 수 있다.

예를 들어 도메인 엔티티에서는 주문 상태를 변경하는 비즈니스 로직이 포함될 수 있다.

public void completeOrder() {
    if (this.status != OrderStatus.PENDING) {
        throw new IllegalStateException("Order cannot be completed");
    }
    this.status = OrderStatus.COMPLETED;
}

그러나 영속성 엔티티는 데이터베이스의 테이블 구조와 일치하는 필드와 단순한 CRUD 작업에 필요한 메서드만을 가지므로, 비즈니스 로직보다는 데이터 저장과 조회에 더 집중한다. 물론, 도메인 엔티티를 사용하지 않는 경우에는 이러한 비즈니스 로직이 영속성 엔티티에 작성될 수 있다.

 

 

왜 도메인 엔티티와 영속성 엔티티를 분리하는가?

위의 예시 코드에서 봤듯이 굳이 이 둘을 분리하지 않고 영속성 엔티티를 도메인 엔티티로 사용해도 된다. 그런데도 왜 굳이 이 둘을 분리하는 것일까?

먼저, 클린 아키텍처의 원칙을 살펴보자. 클린 아키텍처에서는 모든 의존성이 도메인 로직을 향해 안쪽 방향으로 향한다. 이 아키텍처는 동심원 구조로 계층들이 둘러싸여 있으며, 가장 중요한 규칙은 계층 간의 모든 의존성이 안쪽으로 향해야 한다는 것이다.

클린 아키텍처에서 모든 의존성은 도메인 로직을 향해 안쪽 방향으로 향한다.

클린 아키텍처의 핵심에는 도메인 엔티티가 있다. 유스케이스는 단일 책임을 갖기 위해 더 세분화된 형태의 서비스로 구성되며, 이 코어를 중심으로 비즈니스 규칙을 구현하는 애플리케이션의 다른 모든 컴포넌트들이 존재한다. 이 컴포넌트들은 영속성을 제공하거나 UI를 제공하는 역할을 하며, 바깥쪽 계층들은 서드파티 컴포넌트에 대한 어댑터 역할을 할 수도 있다.

도메인 코드에서는 어떤 영속성 프레임워크나 UI 프레임워크가 사용되는지 알 수 없기 때문에 특정 프레임워크에 특화된 코드를 가질 수 없다. 이 덕분에 오직 비즈니스 규칙에 집중할 수 있고, 도메인 코드를 자유롭게 모델링할 수 있게 된다. 그리고 이는 곧 도메인 주도 설계(DDD)를 가장 순수한 형태로 적용할 수 있게 된다.

도메인 엔티티와, 영속성 엔티티를 분리

가령, 영속성 계층에서 ORM 프레임워크를 사용한다고 해보자. 일반적으로 ORM 프레임워크는 데이터베이스 구조와 객체 필드 및 데이터베이스 칼럼 간의 매핑을 서술한 메타데이터를 담고 있는 엔티티 클래스를 필요로 한다. 도메인 계층은 영속성 계층을 알지 못하기 때문에 도메인 계층에서 사용한 엔티티 클래스를 영속성 계층에서 함께 사용할 수 없다. 따라서 두 계층에서 각각 엔티티를 만들어야 한다. 도메인 계층과 영속성 계층이 데이터를 주고받을 때, 두 엔티티를 서로 변환해야 한다. 이는 도메인 계층과 다른 계층들 사이에서도 마찬가지다.

즉, 도메인 엔티티와 영속성 엔티티를 분리하는 이유는 클린 아키텍처의 원칙에 따라 계층 간의 의존성을 최소화하고, 도메인 로직이 특정 프레임워크나 기술에 종속되지 않도록 하기 위함이다. 

 

 

꼭 분리해야 하는가?

도메인 모델은 영속성과 무관하게 순수해야 하며, 설계에서 도메인이 가장 높은 우선순위를 가지며 중심이 된다. ORM을 사용하다가 단순 쿼리 실행기(e.g., JDBC, MyBatis)로 변경해도 도메인 설계는 변경되지 않아야 한다. 즉 영속성 프레임워크의 사용 여부가 도메인 영역에 영향을 주어서는 안 된다.

하지만 잘 생각해 보자 실제 프로젝트에서 한 번 도입된 기술들이 변경된 적이 있는가? 분리하기 위해서는 어떤 점들을 고려하면 좋을까? 

1. 일반적인 규모의 프로젝트에서 ORM을 사용하다가 걷어낸 적이 있는가?
2. 도메인 모델과 ORM @Entitiy를 동일하게 사용하고 있지는 않는가?
3. JPA를 사용하는 경우, 엔티티 클래스에 jakarta.persistence(java 17 미만에는 javax)만 추가로 import 하고 있는데, 이것도 순수 POJO로 간주할 수 있지 않을까?
4. 프로젝트 초기에 기술 선택을 잘못한 경우, 나중에 이를 수정하기 위해 들여야 할 비용과 노력이 어느 정도인가?
5. 도메인 모델과 영속성 모델이 분리됨으로써 팀의 개발 속도와 코드 품질에 미치는 영향은 무엇인가?
6. 도메인 모델과 영속성 모델의 분리를 통해 얻을 수 있는 테스트의 용이성은 어느 정도인가?
7. 도메인 모델을 사용하지 않는 팀원이나 후임 개발자가 프로젝트에 참여할 경우, 도메인 모델과 영속성 모델의 분리로 인한 학습 곡선은 어떻게 되는가?

위 질문들은 도메인 모델과 영속성 모델을 분리하기 전에 한 번 고민해 보면 좋은 리스트들이다. 그리고 위 질문들을 통해 도메인 엔티티와 영속성 엔티티로 나누는 것을 결심하더라도 실제 작업에서는 다음과 같은 문제가 발생할 수 있으니 트레이드오프를 고려해야 한다.

1. 컨버팅을 위한 보일러 플레이트 코드 작성

순수 도메인 객체와 영속성 객체는 분리되어야 한다. 즉, 서비스와 리포지토리 간의 파라미터와 반환 값은 외부에 의존하지 않도록 컨버팅 작업이 필요하다. 만약 하나의 애그리거트에 매우 많은 중첩 객체가 존재하면 어떻게 될까?

일반적으로 DDD에서는 하나의 애그리거트(같은 라이프 사이클을 가지는 관련된 객체들을 모아 하나의 단위로 취급하는 개념)를 repository의 대상 엔티티로 삼는다. 예를 들어 Order라는 애그리거트가 존재할 때, 해당 애그리거트를 저장하고 로드하는 OrderRepository만 존재해야 한다. 결국, 해당 애그리거트에 포함되는 모든 엔티티와 밸류 객체들에 대해 트랜잭션 일관성을 보장해야 하며, 컨버팅 작업에 많은 시간을 소모하게 된다.

또한 코드의 양을 줄이기 위해 매핑 프레임워크를 사용하더라도, 두 모델 간 매핑을 구현하는 데는 상당한 시간이 소요된다. 특히 매핑 프레임워크가 내부 동작 방식을 제네릭 코드와 리플렉션 뒤로 숨길 경우, 매핑 로직을 디버깅하는 것은 매우 어렵고 복잡하다.

이러한 이유로 인해, 도메인 모델과 영속성 모델의 분리는 많은 보일러플레이트 코드를 작성하게 만들고, 개발자들이 컨버팅 로직에 많은 시간을 할애하게 된다. 이로 인해 개발 속도가 저하되고, 디버깅 과정에서의 어려움이 증가하여 전체적인 생산성에 부정적인 영향을 미칠 수 있다.

2. 휴먼 에러

컨버팅 문제와 직결된 문제로, 실수로 인해 문제가 발생할 수 있다.

public class Customer {
    private Long id;
    private String name;
    private String email;
    private String phoneNumber;  // New field added
    private Address address;

    public Customer(Long id, String name, String email, String phoneNumber, Address address) {
        this.id = id;
        this.name = name;
        this.email = email;
        this.phoneNumber = phoneNumber;  // Initialization of new field
        this.address = address;
    }

    // Other methods..
}

@Entity
public class CustomerEntity {
    @Id
    private Long id;
    private String name;
    private String email;
    // Missing phoneNumber field
    private Address address;

    public CustomerEntity(Long id, String name, String email, Address address) {
        this.id = id;
        this.name = name;
        this.email = email;
        this.address = address;
    }

    // Other methods..
}

위 코드에서 Customer 객체에는 phoneNumber 필드가 추가되었지만, 실수로 CustomerEntity에는 추가되지 않았다(반대의 경우도 마찬가지다). 이는 컴파일 단계에서 확인할 수 없기 때문에 안정성이 떨어질 수 있다. 물론 철저하게 테스트 코드를 작성하면 변환 과정에서 발생할 수 있는 오류를 사전에 발견할 수 있지만, 항상 완벽하지는 않다.

이러한 실수는 별로 일어나지 않을 것 같지만, 생각보다 개발하는 동안 꽤나 자주 발생하는데 새로운 필드를 추가하는 도중 말을 걸거나 커피타임으로 인해 잠깐 주의를 돌린 후 다시 작업을 재개할 때, 필드 추가를 까먹는 경우가 자주 있다.

3. 구현 기술의 강력한 기능 사용 불가

컨버팅의 연장선으로, Lazy Loading이나 Dirty Checking 같은 JPA에서 지원하는 기능은 영속성 계층에 의존하는 기능이다. 따라서 컨버팅 이후에는 이러한 기능을 사용할 수 없게 된다. 이는 성능 최적화 및 리소스 관리 측면에서 불리할 수 있다.

다만 이 부분은 애그리거트에 대해 Lazy Loading이 필요하지 않다고 보는 의견도 많다. 애그리거트에 필요한 값은 한 번에 로드되어야 하고, 필요하지 않으면 로드되지 않아야 한다. Lazy Loading이 필요하다는 것은 애그리거트의 설계가 잘못되었을 가능성을 의미한다.

그러니 신중히 고려한 뒤 분리하자

결론적으로, 도메인 모델과 영속성 모델의 분리는 신중하게 결정해야 하며, 프로젝트의 특성, 팀의 역량, 장기적인 유지보수와 확장성을 고려한 전략적인 접근이 필요하다. 이러한 분리가 항상 최선의 선택은 아니며, 실제 프로젝트 상황에 맞는 최적의 결정을 내리는 것이 중요하다.

실제로 '만들면서 배우는 클린 아키텍처' 책에서도 8장에서 이 둘의 도메인을 나누지 않는 '매핑하지 않기' 전략에 대해 다루고 있는데, 이를 통해 도메인과 영속성 모델을 반드시 분리해야 하는 것이 정답이 아니라는 것을 알 수 있다.

 

 

그럼에도 언제 분리하면 좋을까?

그렇다면 언제 ORM @Entity와 도메인 모델을 분리하는 것이 좋을까? 가장 중요한 것은 [persistence layer → domain layer] 방향으로 변경 압력이 가해져서는 안 된다는 점이다. 이를 위해 분리를 고려해야 하는 몇 가지 상황이 있다.

비효율적이고 잘못 설계된 테이블 스키마의 경우

잘못 설계된 테이블 스키마가 그대로 도메인 계층에 노출되면 문제가 될 수 있다. ORM @Entity를 도메인 모델로 직접 사용하는 경우, 이러한 잘못된 테이블 구조가 그대로 도메인 모델에 반영된다. 예를 들면 다음과 같은 경우이다.

// 잘못 설계된 테이블 스키마
@Entity
public class UserEntity {
    @Id
    private Long id;
    private String fullName; // fullName 대신 firstName과 lastName을 분리했어야 함
    private String address1; // Address가 하나의 필드로 저장됨
    private String address2;
    private String address3;
}

// 도메인 모델
public class User {
    private Long id;
    private String firstName;
    private String lastName;
    private Address address; // Address 객체로 분리
}

public class Address {
    private String street;
    private String city;
    private String state;
    private String zipCode;
}

ORM @Entity와 도메인 모델을 분리하여, 잘못 설계된 테이블의 스키마가 도메인 모델에 반영되는 것을 방지할 수 있다. 이를 통해 도메인 모델이 데이터베이스 설계의 문제점을 그대로 가져오는 것을 막을 수 있다.

갱신 이상을 피하기 위해 컬럼이 누락된 경우

데이터베이스 설계 시 갱신 이상을 피하기 위해 중복을 최소화하는 것이 일반적이다. 다만 이로 인해 ORM @Entity와 도메인 모델 간의 불일치가 발생할 수 있다. 예를 들어, @Entity는 테이블 컬럼과 동일한 필드를 가지지만, 도메인 모델에는 비즈니스 로직상 필요한 추가 필드가 존재할 수 있다.

@Entity
public class OrderEntity {
    @Id
    private Long id;
    private BigDecimal amount;
    private Long customerId; // 고객 정보가 분리되어 있음
    // 다른 필요한 필드들...
}

public class Order {
    private Long id;
    private BigDecimal amount;
    private BigDecimal tax; // 비즈니스 로직상 필요한 추가 필드
    private Customer customer; // 고객 정보 포함

    public BigDecimal getTotalAmount() {
        return amount.add(tax);
    }
}

public class Customer {
    private Long id;
    private String name;
    private String email;
}

물론 @Transient 어노테이션을 사용하여 테이블에는 없지만 비즈니스에서 필요한 필드를 도메인 모델에 추가할 수 있다. 그러나 이 방법은 도메인 모델이 영속성 계층의 세부사항에 종속되게 하여 혼란을 초래할 수 있다. 예를 들어, 비즈니스 로직에서는 필요하지만 데이터베이스에는 존재하지 않는 필드를 처리하는 과정에서 불명확한 동작이 발생할 수 있다.

이러한 혼란이 도메인 모델에 불필요한 변경 압력으로 작용하지 않도록, ORM @Entity와 도메인 모델을 분리하는 것이 좋다. 이를 통해 도메인 모델이 비즈니스 로직을 제대로 반영하고, 데이터베이스 설계와 독립적으로 유지될 수 있다.

영속성 전용 애너테이션의 과도한 사용으로 인해 도메인 모델 오염될 경우

도메인 모델은 원칙적으로 순수해야 하므로, ORM @Entity를 붙이는 것은 제한적으로 허용된다. 하지만 다양한 ORM 애너테이션이 과도하게 사용되면 도메인 모델의 본질을 해칠 수 있다. 예를 들어 다음과 같은 경우다.

@Entity
@BatchSize(size = 10)
public class ProductEntity {
    @Id
    private Long id;
    private String name;
    @Version
    private int version; // 버전 관리 필드
    @Temporal(TemporalType.TIMESTAMP)
    private Date lastUpdated; // 마지막 업데이트 시간
}

public class Product {
    private Long id;
    private String name;
    private LocalDateTime lastUpdated; // 도메인 모델에서는 LocalDateTime 사용
}

애너테이션이 과도하게 사용되는 경우, ORM @Entity와 도메인 모델을 분리하는 것이 필요할 수 있다. 이는 도메인 모델의 순수성을 유지하고, 특정 영속성 프레임워크나 기술에 종속되지 않도록 하기 위함이다.

이러한 신호들이 보인다면, 도메인 모델과 ORM @Entity를 분리하여 설계의 순수성을 유지하고, 도메인 계층이 특정 영속성 프레임워크나 기술에 종속되지 않도록 하는 것이 좋다. 이를 통해 시스템의 유지보수성과 확장성을 높일 수 있으며, 비즈니스 로직이 데이터베이스 설계와 독립적으로 관리될 수 있다.

 

 

정리

결국, 엔티티를 분리하는 이유는 도메인 중심 설계를 구현하기 위함이다. 전통적인 계층형 아키텍처에서는 데이터베이스가 토대가 된다. 웹 계층은 도메인 계층에 의존하고, 도메인 계층은 영속성 계층에 의존하므로 자연스럽게 데이터베이스에 의존하게 된다. 이로 인해 모든 것이 영속성 계층을 기반으로 만들어진다.

우리의 애플리케이션 대부분의 목적이 무엇인지 생각해 보자. 우리는 비즈니스를 관장하는 규칙이나 정책을 반영한 모델을 만들어, 사용자가 이를 편리하게 활용할 수 있도록 한다. 이때 우리는 상태(state)가 아니라 행동(behavior)을 중심으로 모델링한다. 어떤 애플리케이션이든 상태가 중요한 요소이긴 하지만, 행동이 상태를 변화시키는 주체이기 때문에 행동이 비즈니스를 이끌어간다.

따라서 도메인 모델은 이러한 비즈니스 로직과 행동을 중심으로 설계되면 좋다. 영속성 계층의 제약이나 세부사항에 의해 도메인 모델이 왜곡되지 않도록 ORM @Entity와 도메인 모델을 분리하는 것이 중요하다. 이렇게 함으로써, 도메인 모델은 비즈니스 로직을 제대로 반영하고 데이터베이스 설계와 독립적으로 유지될 수 있다. 

 

 

+ 덧붙임..

다만, 현업에서 계층형 아키텍처와 클린 아키텍처를 모두 접해본 입장에서 나는 요즘 오버엔지니어링에 대해 매우 경계하고 있다. 모든 것에는 정답이 없지만, 클린 아키텍처나 헥사고날 아키텍처를 사용한다고 해서 잘하는 개발자이고, 계층형 아키텍처로 개발한다고 해서 못하는 개발자는 아니라고 생각한다. 구현체가 하나뿐인데도 앞단에 인터페이스를 두지 않았으니 DIP를 어겼기에 나쁜 코드인가? 후에 리팩터링을 하면 안 되는 걸까? 당장 3년 안에 저장소가 변경될 일이 없고 트래픽도 적은 서비스에서 MSA나 CQRS를 적용하는 것이 정말 필요한 걸까? 팀원들의 학습 곡선을 고려하지 않아 팀의 개발 속도가 늦춰지는 것은 괜찮은 일일까? RDD(이력서 주도 개발)이 되면 안 된다고 생각한다.

우리는 개발자이기 이전에 한 회사에서 돈을 받는 직원이고, 제품을 빠르고 경쟁력 있게 만들어 고객의 만족을 높이는 일을 해야 한다. 그렇기에 중요한 것은 비즈니스 요구사항을 충족시키고 팀의 생산성을 유지하면서 적절한 아키텍처를 선택하는 것이다. '은총알은 없다(No Silver Bullet)'라는 말이 있듯이 모든 문제를 해결할 수 있는 만능의 아키텍처나 설계는 존재하지 않는다.

 

 

참고

• https://umbum.dev/2005/
• https://dev-coco.tistory.com/190
• 만들면서 배우는 클린 아키텍처
• 도메인 주도 개발 시작하기: DDD 핵심 개념 정리부터 구현까지
• 헥사고날 배우지 말자 feat. 구현 First
• 대기업들이 시장에 MSA라는 독을 풀었다
• 지속 성장 가능한 소프트웨어를 만들어 가는 방법
• DDD의 Entity와 JPA의 Entity는 같은 걸까?