[RFC] 엔티티 설계 전략 및 테스트 편의성에 관한 고찰

[milk-stone]

1. 배경

현재 공지사항(Notice) 도메인 개발을 진행하면서 엔티티 코드를 작성하고 있는 중입니다. 엔티티 코드를 작성하는 것은 단순하지만, 이러한 코드부터 모두가 공통된 규칙을 가지고 코드를 작성하면 추후 유지보수 하기에 용이할 것 같아 글을 작성하게 되었습니다.

---

2. 주요 논의 포인트

A. 객체 참조 vs ID 참조

1. 객체 참조

• 설명 & 예시 코드: 엔티티 클래스 내에 연관된 엔티티 객체를 직접 포함하는 방식입니다.

ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "member_id")
private Member member;

• 장점
  • notice.getMember().getName()과 같이 .연산자를 통해 연관 객체 정보를 직관적으로 가져올 수 있음.
  • 지연 로딩, 영속성 전이 등 JPA 프레임워크가 제공하는 기능을 활용할 수 있음.
• 단점
  • 설계를 잘못할 경우 N+1 문제가 발생할 수 있으며, 의도치 않은 객체 로딩으로 인한 성능 저하가 발생할 수 있음.
  • 순환 참조 발생 가능성 있음.

2. ID 참조

• 설명 & 예시 코드: 연관된 엔티티의 식별자(ID)값만 필드로 가지는 방식입니다.

@Column(name = "member_id")
private Long memberId;

• 장점
  • 도메인 간 물리적 의존성을 제거하여 각 도메인을 독립적으로 관리할 수 있음.
  • 필요한 시점에 필요한 데이터만 리포지토리를 통해 조회하므로, 예상치 못한 쿼리가 실행되는 것을 방지할 수 있음.
• 단점
  • 연관 객체의 정보가 필요할 때마다 서비스 레이어에서 별도의 리포지토리 조회가 필요하여 코드가 길어질 수 있음.
  • JPA가 제공하는 연관관계 자동화 기능을 사용할 수 없음.

💡 질문

필요에 따라 객체 참조, ID 참조 방식을 혼용해도 된다고 생각합니다만, 혼용을 하게 된다면 어떤 기준을 가지고 두 방식을 나눌지 의견 제시해주시면 감사하겠습니다!

B. Lombok 어노테이션을 어느정도 사용할 것인지에 대해서

• 엔티티 클래스 상단

@Entity
@Getter
@NoArgsConstructor(access = AccessLevel.PROTECTED)
@Table(name = "notice")
public class Notice

• 엔티티 클래스 내 생성자 @Builder 설정

@Builder
public Notice(String title, String content, NoticeType type, Member member) {
    this.title = title;
    this.content = content;
    this.type = type;
    this.member = member;
}

• Enum 클래스

@Getter
@RequiredArgsConstructor
public enum NoticeType {
    GENERAL("일반 공지"),
    LOST_FOUND("분실물 공지");

    private final String description;
}

• 상세 설명
  1. 게터 메서드를 작성하는 대신 @Getter 어노테이션을 사용.
  2. @NoArgsConstructor(access = AccessLevel.PROTECTED)를 통해 JPA 프록시 생성은 허용하되, 외부에서의 무분별한 new 호출은 차단.
  3. 테이블 이름을 @Table 어노테이션을 이용해 명시
  4. 엔티티 클래스 생성자 레벨에 @Builder를 적용.
     • id 필드의 포함 여부에 대하여 아래에 자세히 작성해 두었습니다.
  5. final 필드 기반의 @RequiredArgsConstructor 활용
     • Controller, Service 등의 의존성 객체와 Enum의 모든 필드를 final로 선언하고, Lombok의 @RequiredArgsConstructor를 사용하여 생성자를 자동 생성함.
     • 이점
       • 객체의 불변성을 확보
       • 의존성 주입 누락을 컴파일 단계에서 방지하여 런타임 에러 가능성을 원천 차단.
       • 생성자 코드를 직접 작성하는 번거로움을 줄임. (보일러 플레이트 제거)

💡 질문

위 사례 이외에도 어노테이션을 사용함에 있어서 규칙으로 정하면 좋아보이는 것들이 있다면 의견 주시면 감사하겠습니다!

C. 테스트를 위한 ID 필드 노출 전략

• 제안 내용: @Builder에 id 필드를 포함하여, 테스트 코드 작성 시 DB 저장 없이도 특정 ID를 가진 Mock 객체를 생성할 수 있도록 설계를 제안합니다.
  • 장점: ReflectionTestUtils와 같은 도구 없이도 깔끔한 테스트 코드 작성이 가능해짐.
  • 단점: 서비스 레이어에서 실수로 ID를 직접 주입하거나 수정할 가능성이 존재함.

💡 질문

@Builder에 ID 필드를 포함한 후 개발자 간의 컨벤션으로 관리할 것인지, 아니면 더 엄격한 캡슐화를 위해 ID를 빌더에서 제외할 것인지 논의하고 싶습니다.

D. 정적 팩토리 메서드(Static Factory Method) 도입

• 빌더를 직접 노출하기보다 createNotice()와 같은 의미 있는 이름을 가진 정적 메서드를 통해 객체 생성을 유도.
• 예시 코드

public static Notice createNotice(String title, String content, NoticeType type, Member member) {
    return Notice.builder()
            .title(title)
            .content(content)
            .type(type)
            .member(member)
            .build(); // 여기서 id는 호출하지 않음
}

💡 질문

위 내용 처럼 정적 팩터리 메서드를 도입하여, 개발자의 실수를 원천 차단하는 방식을 사용하는 것은 어떤지 의견 드립니다!

---

3. 의견 요청

위 내용 외에도 엔티티 설계 혹은 코드 작성 시 반드시 지키는 코드 작성 컨벤션이 있다면 공유 부탁드립니다!

---

작성자: 유우석 (Backend Developer)

[wlgns12370]

우석님 초기 전략에 대해서 잘 정리해주셔서 감사합니다.

의견에 앞서 현재 저희팀은 Spring Boot와 Java를 간결합한 구조를 선택했습니다. 이는 현 시점에서 우리 팀이 가장 잘 다룰 수 있는 기술 스택에 집중하여 생산성을 높이기 위한 결정이며, 이에 따라 Domain Layer에 JPA Entity와 Repository를 배치하고 있습니다.

저는 우석님 C의견에 동의하고 B의견을 변형해야한다고 생각합니다.

저희 서비스는 DDD를 지향하며, 주막 운영 시간 검증이나 게임 점수 계산 등 복잡한 비즈니스 로직이 엔티티 내부 행위 메서드로 많이 포함될 예정입니다.(풍부한 도메인이 될 것 이라고 생각 합니다!) 이 경우 단순 CRUD 테스트보다 엔티티 내부의 비즈니스 로직을 검증하는 테스트의 비중과 중요도가 높아질 것 입니다.

그러나 B의견 코드대로 구현한다면, id 필드에 대해서는 ReflectionTestUtils 또는 Spy 를 사용해서 테스트를 진행해야하기 때문에 가독성이 떨어지고, 반복되는 코드가 많아질 것 입니다.

해결 방안

그래서 저는 풍부한 도메인 모델로의 확장을 대비한 테스트 전략을 제안하고 싶습니다. B의견에 나오는 코드와 달리 테스트 코드에서만큼은 ID를 직접 제어할 수 있도록 열어두는 방식입니다.

@Entity
@Getter
@Builder
@NoArgsConstructor(access = AccessLevel.PROTECTED)
@AllArgsConstructor(access = AccessLevel.PRIVATE)
@Table(name = "notice")
public class Notice

장단점

장점

• 테스트 가독성: ReflectionTestUtils나 Spy 같은 모킹 도구 없이도 ID가 포함된 객체를 직관적으로 생성할 수 있어 테스트가 편리합니다.
• 영속성 독립성: DB나 JPA의 생명주기에 의존하지 않고도, 이미 저장된 상태의 객체를 시뮬레이션하며 비즈니스 로직을 빠르게 검증할 수 있습니다.

단점

• 실수 가능성: 메인 코드에서 실수로 ID를 수동 할당할 위험이 있습니다.

하지만 이 단점도 추가적인 AI 리뷰 시스템이나 ArchUnit 같은 도구를 활용해, src/main 아래에서 빌더의 .id() 메서드가 호출되는 것을 차단하는 규칙을 도입하면 안정성을 확보할 수 있다고 생각합니다!

[jhssong]

A. 설계의 편의성 측면에서 객체 참조 방식이 좋다고 생각합니다. 단점을 보완하기 위해 PR 리뷰 단계에서 엔티티 추가 시 문제가 없는지 함께 고민해보고 머지하면 좋을 것 같습니다.

B. 간결한 코드 유지를 위해 말씀해주신 5개 사항 모두 동의합니다.

C. 테스트 코드 작성을 위해서 Builder에 id를 포함시키는게 좋다고 생각합니다. 인적 오류를 최소화하기 위해 테스트를 위한 엔티티 빌더에 createNoticeForTest와 같이 명시적으로 테스트를 위한 빌더임을 명시하면 좋을 것 같습니다.

D. 앞서 언급한 C 내용과 더불어 정적 팩토리 메서드 도입 동의합니다.

[GyunHeee]

A. 연관관계는 도메인 경계와 책임을 기준으로 객체 참조와 ID 참조를 구분하고 하는것이 바람직하다고 생각하지만 초기 단계에서 설계의 편의성과 도메인 모델의 의미를 명확히 구분해서 표현하기 위해 '객체 참조 방식'으로 구현하는 것이 좋을 것 같습니다.

B. 제시해주신 Lombok 사용 방식은 전반적으로 합리적이며, 말씀해주신 방향으로 규칙을 정리하는 것이 바람직하다고 판단합니다.

C. 저는 테스트 생산성과 가독성 측면에서 @builder에 ID 필드를 포함하는 방향에 찬성합니다. 하지만 운영 코드에서 id 주입 사고를 막는 가드레일이 필요합니다. ID 세팅은 테스트 전용 빌더로만 열어두는 방법으로 id를 세팅할 수 있는 빌더 API가 production 코드에서 보이지 않도록 분리하는 방식으로 예방책이 필요합니다.

D. 정적 팩토리 메서드 도입은 개발자의 실수를 예방하고, 도메인 규칙을 강제하는 측면에서 매우 긍정적인 설계라고 생각합니다.

[milk-stone]

주요 논의 포인트 정리

A. 객체 참조 vs ID 참조

초기 단계에서 설계의 편의성과 도메인 모델의 의미를 명확히 표현하기 위해 객체 참조 방식을 채택함.

B. Lombok 어노테이션 활용 범위

• final 필드 클래스 (Controller, Service, Enum): @RequiredArgsConstructor 어노테이션으로 생성자 대체함.

@Getter
@RequiredArgsConstructor
public enum NoticeType {
    GENERAL("일반 공지"),
    LOST_FOUND("분실물 공지");
    private final String description;
}

• 엔티티 클래스 표준: 생성자 코드 대체 및 캡슐화를 위해 아래 조합을 적용함.

@Entity
@Getter
@Builder
@NoArgsConstructor(access = AccessLevel.PROTECTED)
@AllArgsConstructor(access = AccessLevel.PRIVATE)
@Table(name = "notice")
public class Notice

C. 테스트를 위한 ID 필드 노출 전략

@Builder 및 @AllArgsConstructor(access = AccessLevel.PRIVATE)를 통해 테스트 코드 내에서 ID 노출 및 주입이 가능하도록 설정함.

D. 정적 팩토리 메서드(Static Factory Method) 도입

개발자의 실수를 예방하고 도메인 규칙을 강제하기 위해 적용하는 것으로 확정함.

향후 계획

ArchUnit이나 AI 리뷰 시스템 등의 도구를 활용해, src/main 아래 프로덕션 코드에서 빌더의 .id() 메서드가 호출되는 것을 차단하는 규칙을 도입하여 설계 안정성을 확보할 예정임.

---

제시해주신 의견을 모두 종합하여 작성했습니다! 한 번 씩 확인 부탁드립니다.

[wlgns12370]

저는 객체 참조를 사용한다면, 연관 관계 주인쪽은 필드로 가지고, 주인이 아닌쪽은 연관 관계 편의 메서드를 정의하면서까지 아는 것은 불필요하다고 생각합니다.

예를 들어보겠습니다. 팀은 여러 멤버를 가지는 요구사항이라고 가정합니다.

@Entity
class Member {
    @ManyToOne
    @JoinColumn(name = "team_id")
    private Team team;
}

@Entity
class Team {
    // 연관관계 아예 없음
}

Spring Data JPA를 사용하는 이유는 객체–관계 매핑의 복잡도를 줄이고, 도메인 중심으로 빠르게 개발하기 위함입니다.
그런데 외래 키를 실제로 관리하지 않는 Team 엔티티에까지 연관관계를 정의하고, 더 나아가 연관관계 편의 메서드까지 작성하는 것은 목적과 어긋난다고 생각합니다.

도메인과 JPA를 결합해서 사용하는 상황에 행위 메서드가 많이 추가될 것인데, 편의 메서드는 도메인의 행위라고 볼 수 없고 RDB에 의존적인(인프라틱한) 코드라고 생각합니다.

따라서 객체 참조 방식을 사용하면, 단방향 연관관계를 우선으로 가져가고, 도메인 적으로 부분–전체 관계를 이룰 때에만 팀원들과 회의 후 양방향 연관관계를 도입하는 방식을 제안합니다.

[GyunHeee]

동의합니다. 단방향 연관관계를 우선으로 필요 시 회의 결과에 따라 양방향 연관관계 도입여부를 정하는 방식 좋아보입니다.