JPA - Entity 필드 작성 순서 Best Practice

배경

프로젝트에서 여러 개발자가 Entity를 작성하다 보니 각자 다른 순서로 필드를 배치하는 경우가 많았다. 코드 리뷰를 하면서 일관성 있는 Entity 작성 규칙이 필요하다고 느꼈고, 특히 데이터 마이그레이션 작업이나 테이블 비교 시에도 필드 순서가 중요하다는 것을 깨달았다. 그래서 팀 내에서 사용할 수 있는 Entity 필드 작성 순서 가이드를 정리해보게 되었다.

 

혹시 더 괜찮은 구조가 있다면 댓글에 남겨주세요!

 

Entity 필드 작성 순서

식별자 > 기본 속성 > 임베디드 값 객체 > 연관관계 > Audit 필드

1. 식별자

• 순서: 기본 키(Primary Key) > 비즈니스 식별자(Business Key)
• 기본키는 항상 가장 위에 작성한다.
• 상품코드, 주문번호와 같이 비즈니스에서 사용하는 고유 식별자를 두 번째로 배치한다.

 

2. 기본 속성

• 순서: 기본 속성 > 상태 및 플래그
• 엔티티의 주요 속성(이름, 상태, 금액 등)을 식별자 아래에 작성한다.
• 기본값이 있다면 명시적으로 지정해주자
• 상태 및 플래를 나타내는 필드(boolean이나 enum)들을 배치한다.

 

3. 임베디드 값 객체

• @Embedded 애너테이션이 붙는 필드를 기본 속성 아래에 작성한다.

 

4. 연관관계 필드

• 단방향/양방향 연관관계(@ManyToOne, @OneToMany 등) 필드를 작성한다.
• @OneToMany, @ManyToMany 등 컬렉션 필드는 연관관계 필드 중 가장 아래에 작성한다.

 

5. Auditing 필드

• 생성일, 수정일, 생성자, 수정자 등의 Auditing 정보를 마지막에 배치한다.

 

Entity 예시

@Entity
@Table(name = "orders")
@getter
@NoArgsConstruct(access = AccessLevel.PROTECTED)
@AllArgsConstruct
public class Order {

    // 1. 식별자
    @Id
    @GeneratedValue
    private Long id;

    @Column(nullable = false)
    private String orderNumber;

    // 2. 기본 속성
    @Column(nullable = false)
    private int orderPrice;

    @Enumerated(EnumType.STRING)
    private OrderStatus status;

    // 3. 임베디드 값 객체
    @Embedded
    private Address shippingAddress;

    // 4. 연관관계
    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "user_id")
    private User user;

    @OneToMany(mappedBy = "order")
    private List<OrderItem> orderItems = new ArrayList<>();

    // 5. Auditing
    @CreatedDate
    private LocalDateTime createdAt;

    @LastModifiedDate
    private LocalDateTime updatedAt;

    // ...편의 메서드 등
}

 

마무리

기능적인 측면에서 엔티티 필드의 순서가 중요하지는 않다. 하지만 가독성 측면에서는 중요하다고 생각하기 때문에 이러한 필드 작성 순서에 대한 컨벤션을 정해둔다면 팀 내에 일관성을 유지할 수 있기 때문에 효율적이고 깔끔하게 개발을 할 수 있지 않을까 생각한다.

 

참조

Perplexity AI와 함께 논의하며 작성했다.