[Spring] 엔티티를 단순 테이블 매핑이 아닌 '정책 상태 머신'으로 설계해야 하는 이유

1. 도입부 (Introduction)

전통적인 데이터베이스 중심 아키텍처에서 엔티티(Entity)는 단순히 테이블의 컬럼들을 자바 객체로 1:1 매핑해 둔 빈 껍데기(Anemic Domain Model)로 취급받기 일쑤다. 서비스 레이어에서 엔티티의 내장 Getter와 Setter를 무분별하게 호출하며 자바 필드 값을 직접 덮어쓰는 방식은 도메인 제어권을 통째로 상실하게 만든다. 비즈니스 정책이 복잡해질수록 온보딩 확정, 가입 차단, 불량 유저 제재 등과 같은 엄격한 상태 전환 규칙들이 사방으로 흩어져 유지보수 불가능한 스파게티 코드가 되기 때문이다.

이러한 문제를 해결하기 위해서는 User 엔티티를 단순한 CRUD의 데이터 뭉치가 아니라, 오직 정해진 비즈니스 조건과 제약사항에 의해서만 다음 단계로 이행하는 "사용자 상태 머신(User State Machine)"으로 재정의해야 한다. 사용자 수명 주기에 따른 상태 전이 흐름을 엔티티 내부로 격리하고 정책 무결성을 확보하는 구조를 밀도 있게 분석해 본다.

 

 

2. 주요 특징 및 핵심 로직 (Main Features & Logic)

사용자 상태 머신의 전체적인 라이프사이클은 최초 저장 시점의 기본값 설정, 가입 직후 온보딩 완료 단계, 일반적인 정보 수정, 그리고 보안 및 커뮤니티 정화 처리를 위한 제재 전이 단계로 이어진다. 이 시스템의 핵심은 서비스 레이어가 엔티티의 가변 필드를 직접 수정하는 대신, 엔티티가 안전하게 캡슐화하여 제공하는 제한된 인터페이스 메서드만을 호출하게 강제하는 구조적 설계에 있다.

각 단계별 책임 범위와 정책 연결 구조를 일목요연하게 비교하면 다음과 같다.

단계	실행 시점 / 위치	주요 정책 및 변경  필드	비즈니스 목적 및 도메인 불변식
[1] 생성 기본값	저장 직전 (@PrePersist)	role, moderationStrike, permanentlyBanned	시스템 접근 권한의 최소 기준 확정 및 NullPointerException 원천 차단
[2] 온보딩 완료	가입 후 프로필 작성 단계	gender, birthYear, nickname	필수 속성을 한 단계에서 확정하여 개인화 추천 시스템의 입력 정합성 보장
[3] 프로필 수정	마이 페이지 정보 변경	허용된 일부 필드 집합	정책적으로 수정이 허용된 한정된 속성만 안전하게 변경 처리
[4] 제재 상태 전이	신고 및 운영 관리자 제재 집행	suspendedUntil, permanentlyBanned	서비스 이용 제한 스케줄링 및 누적 제재 규칙(Strike) 일관성 원자적 관리

 

 

 

3. 상세 가이드 및 심층 분석 (Detailed Guide)

A) 생성 기본값 초기화 (@PrePersist)

사용자가 데이터베이스에 영속화되기 직전에 동작하는 JPA Lifecycle Hook을 활용하여 초기 시스템 진입 장벽을 격리한다.

import jakarta.persistence.*;
import java.time.LocalDateTime;

@Entity
@Table(name = "users")
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String nickname;
    private Integer birthYear;

    @Enumerated(EnumType.STRING)
    private Gender gender;

    @Enumerated(EnumType.STRING)
    private Role role;

    private String signature;
    private Integer moderationStrike;
    private Boolean permanentlyBanned;
    private LocalDateTime suspendedUntil;
    private LocalDateTime createdAt;

    /**
     * JPA 영속화(Persist) 직전에 호출되는 라이프사이클 훅 메서드다.
     * 외부에서 실수로 누락한 시스템 필수 정책 기본값의 최종 방어선 역할을 수행한다.
     */
    @PrePersist
    public void prePersist() {
        this.createdAt = LocalDateTime.now(); // 최초 생성 시각 각인
        
        // 시그니처 기본값 강제 주입
        if (this.signature == null) {
            this.signature = "jeonlog";
        }
        
        // 최초 가입 시 권한은 일반 유저(USER)로 제한하여 보안 격리 확보
        if (this.role == null) {
            this.role = Role.USER;
        }
        
        // 제재 카운트의 초기 상태는 무조건 0건으로 정규화
        if (this.moderationStrike == null) {
            this.moderationStrike = 0;
        }
        
        // 영구 정지 여부의 초기값은 영속화 시점에 명시적으로 false 매핑하여 Null 분기 차단
        if (this.permanentlyBanned == null) {
            this.permanentlyBanned = false;
        }
    }
}

• 심층 분석: 소셜 가입, 관리자 화면을 통한 강제 등록, 테스트 코드 등 유저 객체가 적재되는 경로는 다양하다. 만약 권한(role)이나 제재 상태 필드들이 자바의 기본 null 상태로 DB에 삽입된다면 어떻게 될까? 시
  큐리티 인증 필터 단계나 스케줄러가 돌아갈 때 NullPointerException이 연쇄적으로 터지며 인증 무력화나 정지 우회와 같은 대형 보안 장애로 이어진다. 엔티티 생명주기 자체에 이 방어벽을 걸어두면 원천적으로 불완전한 상태의 유저 유입을 막을 수 있다.

 

B) 온보딩 상태 확정

가입 완료 직후 필수 입력 정보들을 수령하여 도메인의 의미 있는 유저 상태로 격상시키는 흐름이다.

/**
 * 성별, 출생연도, 닉네임이라는 필수 가입 정보를 패키징하여 단 한 번 온보딩을 완수하는 메서드다.
 * 외부에서 개별 필드를 무작위로 셋업하는 행위를 제한한다.
 */
public void completeOnboarding(Gender gender, Integer birthYear, String nickname) {
    // 도메인 비즈니스 밸리데이션 검증
    if (gender == null || birthYear == null || nickname == null || nickname.isBlank()) {
        throw new IllegalArgumentException("온보딩 필수 파라미터가 누락되었습니다.");
    }
    
    this.gender = gender;
    this.birthYear = birthYear;
    this.nickname = nickname;
}

@Service
@RequiredArgsConstructor
@Transactional
public class UserService {

    private final UserRepository userRepository;

    /**
     * 사용자의 온보딩 완료 요청을 처리하는 서비스 레이어 흐름이다.
     */
    public void completeOnboarding(Long userId, Gender gender, Integer birthYear, String nickname) {
        // 1. 영속성 컨텍스트에서 변경 대상 유저 식별
        User user = userRepository.findById(userId)
                .orElseThrow(() -> new NoSuchElementException("존재하지 않는 사용자입니다."));

        // 2. 비즈니스 정책 방어: 중복 온보딩 실행 여부를 서비스의 수문장 로직으로 차단
        if (user.getNickname() != null) {
            throw new IllegalStateException("이미 온보딩 단계를 완료한 사용자입니다.");
        }

        // 3. 내부 정책 제어 상태 머신 메서드를 호출하여 상태 전이 가동
        user.completeOnboarding(gender, birthYear, nickname);
        
        // @Transactional에 의해 영속성 컨텍스트 쓰기 지연 저장소의 더티 체킹(Dirty Checking)으로 반영된다.
    }
}

• 심찰 분석: 이 단계는 개별 필드의 단순 Setter 조합이 아니다. 성별, 출생연도, 닉네임이라는 핵심 속성이 '동일한 트랜잭션 도메인 문맥 안에서 원자적으로(Atomic) 확정'되어야만 정식 서비스 가용 상태가 된다는 강력한 비즈니스 게이트웨이다.
  이를 분리하여 서비스 레이어가 제어하게 두면 누락 필드가 발생할 확률이 비약적으로 증가하며, 데이터 정합성이 깨진 불완전 유저가 전시 추천 시스템에 들어가 엔진을 오염시키는 참사를 유발하게 된다.

 

C) 제재 상태 전이 및 불변식 관리

가장 엄격하고 고도화된 정책 통제가 요구되는 영역이며, 도메인 불변식(Invariant)을 완벽하게 보장하는 아키텍처다.

/**
 * [제재 정책 전이 1단계] 단순 경고 처리
 * 비즈니스 규칙: 제재 종류와 무관하게 모든 규제는 누적 Strike 카운트가 1씩 증가해야 한다.
 */
public void warn() {
    increaseModerationStrike();
}

/**
 * [제재 정책 전이 2단계] 기간제 활동 정지 처리
 * @param days 정지할 일수
 */
public void suspendForDays(int days) {
    if (days <= 0) {
        throw new IllegalArgumentException("정지 기간은 1일 이상이어야 합니다.");
    }
    
    increaseModerationStrike(); // 불변식 강제
    this.suspendedUntil = LocalDateTime.now().plusDays(days); // 정지 스케줄 연산 기재
}

/**
 * [제재 정책 전이 3단계] 영구 정지 (시스템 추방)
 * 비즈니스 규칙: 영구 정지 유저는 어떠한 경우에도 정지 상태를 되돌릴 수 없다.
 */
public void banPermanently() {
    increaseModerationStrike(); // 불변식 강제
    this.permanentlyBanned = true;
}

/**
 * 외부에서 위반 연산 없이 Strike 값만 마구잡이로 수정하는 부정 행위를 막기 위해 
 * 내부 캡슐화(private)로 감싸둔 핵심 불변식 강제 메서드다.
 */
private void increaseModerationStrike() {
    if (this.permanentlyBanned != null && this.permanentlyBanned) {
        throw new IllegalStateException("이미 영구 추방된 사용자의 제재 상태는 전이할 수 없습니다.");
    }
    this.moderationStrike = this.moderationStrike + 1;
}

@Service
@RequiredArgsConstructor
@Transactional
public class ReportService {

    private final UserRepository userRepository;

    /**
     * 누적된 신고 내역을 기반으로 관리자가 유저를 징계하는 제재 진입 서비스 지점이다.
     */
    public void 중복신고_정지집행(Long reportedUserId, int suspendDays) {
        // 1. 규제 대상 엔티티 로드
        User targetUser = userRepository.findById(reportedUserId)
                .orElseThrow(() -> new NoSuchElementException("신고 대상 유저가 식별되지 않습니다."));
                
        // 2. 엔티티 내부 정책 상태 머신 작동
        // 외부 서비스는 Strike 누적 공식을 알 필요가 없다. 메시지만 던지면 엔티티가 자율적으로 처리한다.
        if (suspendDays >= 30) {
            targetUser.banPermanently(); // 30일 이상의 중죄는 영구 정지로 전이
        } else {
            targetUser.suspendForDays(suspendDays); // 일반 규제는 기간제 정지로 전이
        }
    }
}

 

 

 

4. 실무 팁 및 주의사항 (Tips & Notes)

실패 시나리오 및 디버깅 포인트

• 신규 생성된 유저의 기본 역할(role) 값이 여전히 null로 꽂히는 장애 현상: JPA 영속성 컨텍스트의 생명주기를 오해했을 가능성이 가장 높다. @PrePersist는 자바 객체를 new로 찍어낸 순간 동작하는 것이 아니라, EntityManager.persist()가 호출되거나 트랜잭션 커밋 직전 실제 데이터베이스 INSERT 쿼리가 빌드되어 밀려 나가는 시점에 발동한다. 만약 테스트 코드에서 영속화(수동 saveAndFlush() 등)를 거치지 않고 중간에 인증 로직으로 빼버리면 기본값 주입이 생략되므로 생명주기 훅의 트리거 타이밍을 정확히 진단해야 한다.
• 활동 정지 상태로 변환된 유저가 버젓이 시스템 인증을 통과하는 보안 우회: 도메인 엔티티 내부에 아무리 정책 상태 머신을 완성도 높게 짜놓아도, 게이트웨이나 Security Filter 계층에서 이를 검증하지 않으면 무용지물이다. 인증 객체를 빌드하는 시점이나 커스텀 인터셉터 단에서 유저의 접근을 판단할 때, 아래의 수식과 같은 시간비교 정책 집행 장치(PEP)가 올바르게 작동 중인지 추적해야 한다.
• 온보딩 정보가 사후에 자꾸 초기화되거나 덮어써 지는 비즈니스 결함: 서비스 레이어 초입부에서 기 가입 여부나 기존 데이터 존재 여부를 대조하는 Fail-Fast 가드 로직이 생략되었는지 점검해야 한다. 엔티티 메서드는 들어온 요청에 대해 원자적으로 상태를 변경할 뿐이므로, "이미 온보딩한 자는 재진입할 수 없다"는 흐름 제어의 수문장 역할은 서비스 초입부에서 확실히 걸러주어야 완벽한 조화를 이룬다.

 

 

5. 마무리 (Conclusion)

결국 우수한 백엔드 아키텍처와 객체지향 설계의 진정한 목적은 "데이터를 쥐고 있는 객체 스스로가 비즈니스 정책의 결정권을 직접 행사하게 만드는 것"이다. User 엔티티를 단순한 데이터를 적재하는 바구니로 보지 않고 스스로 판단하고 움직이는 하나의 '정책 상태 머신'으로 격상시키는 순간, 사방으로 파편화되어 스파게티처럼 꼬이던 서비스 레이어 코드가 극도로 단순해진다. 서비스는 단지 엔티티에 정중하게 메시지만 전달할 뿐, 정합성의 수호는 오롯이 도메인 객체 내부에서 자율적으로 완수되기 때문이다.

 

6. 복습 질문과 해답 (Review Q&A)

Q1. 생성 기본값을 서비스 레이어가 아닌 엔티티 라이프사이클(@PrePersist)에서 강제하는 장점은 무엇인가?

A1. 개발자의 부주의나 실수로 인해 특정 생성 경로(예: 소셜 OAuth2 콜백 핸들러, 운영 툴 어드민 강제 추가, 대량 마이그레이션 배치 시스템, 테스트 픽스처 코드 등)에서 초기화 설정을 누락하더라도, 데이터베이스 적재 직전 최종 수문장 계층에서 무조건 일괄 주입되도록 보장한다. 결과적으로 시스템 전반에 산재한 예외 상황에서 NullPointerException 유발 인자를 완전히 도려낼 수 있다.

 

Q2. warn(), suspendForDays(), banPermanently()를 분리된 전용 메서드로 두는 구체적인 이유는 무엇인가?

A2. 유비쿼터스 언어(Ubiquitous Language)를 코드에 투영하여 행위의 의도를 명확하게 명시하고 도메인 무결성을 유지하기 위함이다. 외부 서비스가 단순히 엔티티의 상태 값을 임의로 셋업하는 것을 막고, "어떤 징계 정책이든 내부 Strike 누적 공식이 동시에 원자적으로 동반 발동해야 한다"는 핵심 비즈니스 연쇄 제어 규칙을 내부로 안전하게 결합·격리하기 위한 장치다.

 

Q3. 상태 전이 규칙이 엔티티 밖(Service Layer 등)으로 흩어지면 어떤 유지보수 문제가 생기는가?

A3. 정책 파편화(Policy Fragmentation)가 일어난다. 만약 "제재 시 Strike가 누적되어야 한다"는 규칙이 ReportService, SanctionBatchService, AdminUserService에 각각 복사-붙여넣기 형태로 퍼지면, 기획 변경으로 정지 산정 방식이 수정될 때 연관 코드를 한곳이라도 누락하는 순간 시스템 전체 데이터의 정합성이 붕괴된다. 일부는 카운트가 오르고 일부는 오르지 않는 심각한 정합성 장애가 발생하게 된다.