[JPA] @Embedded 사용 시 주의할 점, 레거시 코드 리팩터링하기

🌱 들어가기 전

너무 오랜만에 작성하는 블로그 글...! 최근에 사내에서 매우 많이 쓰이는 도메인에 대해서 리팩터링을 진행했었는데, 거기서 만났던 이슈들과 간단한 생각 기록을 블로그에 남기면 좋을 것 같아서 작성하고자 한다. 이미 팀 내에서 공유도 했었고, 동기들에게도 공유한 내용이기도 하고, 사실 별거 아닌 거라 그냥 간단하게만 정리할 예정이다.
 

---

 
 

🌱 문제 상황

리팩터링을 진행하고자 한 도메인은 우리 팀에서 매우 중요한 비즈니스 도메인 객체 중 하나였고, 이미 안정적으로 잘 운영되고 있지만 굉장히 옛날부터 레거시로 내려오고 있던 객체였기 때문에 신규 입사자가 보기에 좋은 코드가 아니라는 생각이 들었다.
사내 도메인인 만큼 그대로 가져올 수는 없지만, 비슷한 느낌으로 아래와 같이 세팅을 진행해보았다.

CREATE TABLE `student_group` (
  `id` bigint NOT NULL AUTO_INCREMENT,
  `name` varchar(255) DEFAULT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=2 DEFAULT CHARSET=utf8mb3


CREATE TABLE `student` (
   `id` bigint NOT NULL AUTO_INCREMENT,
   `city` varchar(255) DEFAULT NULL,
   `county` varchar(255) DEFAULT NULL,
   `district` varchar(255) DEFAULT NULL,
   `age` int NOT NULL,
   `name` varchar(255) DEFAULT NULL,
   `group_id` bigint NOT NULL,
   PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb3

간단하게 생각하면 학생의 그룹과 학생에 대한 테이블이고, 이에 대한 엔티티 매핑은 아래와 같았다.

@Entity
class Student(
    val name: String,
    val age: Int,
    group: StudentGroup
) {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    val id: Long = 0L

    @ManyToOne
    @JoinColumn(name = "group_id", insertable = false, updatable = false)
    val group: StudentGroup = group

    @Column(name = "group_id")
    val groupId: Long = group.id

    @Column
    val city: String? = null

    @Column
    val county: String? = null

    @Column
    val district: String? = null
}

실제 도메인에서는 30개가 넘는 필드들이 있었으며, 굉장히 많은 일들을 하고 있는 객체였기 때문에 파악하기 쉽지 않은 객체였다.
나는 위의 엔티티를 보고, 다음과 같은 2가지 포인트에 집중하였다.

1. group이라는 엔티티를 이미 의존하고 있는데, 꼭 groupId라는 필드를 따로 두어야 할까?
2. 맥락상으로 연관이 있는 필드들은 @Embedded로 묶어두면 가독성이 올라가지 않을까?

먼저, 1번의 경우 JPA에 대한 의존성을 최대한 낮추고 싶었다. 이미 @JoinColumn으로 엔티티 직접 참조를 통해 의존성을 가지고 있음에도, @Column을 통해 간접 참조까지 가지고 있는 게 처음 본 사람의 입장에서는 인지 오류를 줄 수 있는 포인트라고 생각했었다. (또한, 현재는 group_id만 있지만 실질적으로 엔티티 참조를 가지고 있던 객체들이 모두 위와 같이 별도로 Id를 위한 필드들이 존재하고 있었다.) 언뜻 보면 group_id라는 컬럼이 2번 있는 것인가? 라는 오류를 줄 수 있을 것 같았다.
 
2번의 경우, 현재 위의 엔티티를 실질적으로 도메인 객체로 사용하고 있다 보니 굉장히 많은 비즈니스 로직에서 사용되는 객체였다. 그러나 수많은 필드 및 메서드들이 주석 없이 단순 필드명으로, 혹은 테이블 스키마에 작성된 커멘트 내용을 보고 파악을 진행하는 게 까다로웠다. (사실 Persistence Layer에 있는 엔티티가 여러 곳에서 도메인 객체로 쓰이는 것부터가 굉장히 어색하지만, 레거시라는 게 생각처럼 쉽게 리팩터링이 되는 부분이 아니었기에 우선 해당 부분에 대해서는 다음 기회에 고쳐나가고자 했다.)

아무튼, 2가지 포인트를 바탕으로 아래와 같이 리팩터링을 진행하고자 했다.

@Entity
class Student(
    val name: String,
    val age: Int,
    group: StudentGroup
) {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    val id: Long = 0L

    @ManyToOne
    @JoinColumn(name = "group_id", insertable = false, updatable = false)
    val group: StudentGroup = group
    
    @Embedded
    val address: Address = Address.init()
}

@Embeddable
class Address protected constructor() {

  @Column
  val city: String? = null

  @Column
  val county: String? = null

  @Column
  val district: String? = null

  companion object {
    fun init(): Address {
      return Address()
    }
  }
}

단순 코드상으로는 정말 간단하다. 엔티티를 참조하고 있는 경우 간접 참조를 위한 논리적 FK 값을 제거하고, '주소'라는 도메인에 맞춰 Address라는 새로운 클래스를 정의하여 @Embedded, @Embeddable를 통해 리팩터링을 진행하였다.
 
처음에는 비즈니스 로직의 수정 없이, 단순히 클래스를 추가한 부분이기 때문에 아무 문제가 없을 것이라고 생각했었다.
그러나, 실제로는 매우 큰 2가지의 문제점이 존재했었는데, 이는 테스트 케이스로 한 번 살펴보자.
 

---

 

🌱 Case 1 - JPA 사용 시 옵션을 제대로 보자

먼저, 정말 간단하게 저장 및 조회하는 서비스 코드가 아래와 같이 존재한다고 생각해보자.

@Service
class StudentService(
    private val studentRepository: StudentRepository,
    private val groupRepository: StudentGroupRepository
) {

    fun saveGroup(name: String) {
        val group = StudentGroup(name)
        groupRepository.save(group)
    }

    fun saveStudent(group: StudentGroup, name: String, age: Int): Student {
      val student = Student(name, age, group)
      return studentRepository.save(student)
    }
}

그리고, 그룹을 저장하고 해당 그룹에 대해 학생을 저장하는 코드를 테스트 코드로 작성해보자.

@SpringBootTest
@TestConstructor(autowireMode = TestConstructor.AutowireMode.ALL)
@ActiveProfiles("test")
class StudentServiceTest(
    private val studentService: StudentService
) {

    @Test
    fun test() {
      val group = studentService.saveGroup("그룹")
      studentService.saveStudent(group, "학생", 20)
    }
}

위의 테스트 결과는 어떻게 나올까? 언뜻 보면 성공할 것 같다. 

하지만, 실제로는 위와 같이 Field 'group_id' doesn't have a default value 라는 오류가 발생한다.
현재 재현할 때는 위 사진처럼 어떤 쿼리가 발생했는지 오류 메시지로 함께 나왔지만, 당시에는 default value가 없다는 오류만 발생했었기 때문에 바로 인지하지 못했다. (또한, 위 테스트 코드의 경우 비즈니스 로직이 없기 때문에 당연히 이런 흐름이 잘 보이지만, 내가 부딪혔던 상황에서는 그 사이에 비즈니스 로직이 너무 많아서 파악하기가 어려웠다.)
 
그래서 나는 처음에는 student를 저장할 때 student group이 영속화 되지 않은 객체가 넘어와서 (혹은 객체가 아예 null로 넘어와서) group id가 null로 나오는 것인지 고민했었다. 그래서 디버깅을 통해 student가 저장되는 시점의 group을 체크하였다.

하지만, 사진을 보면 당연하게도 group 정보와 id 값이 잘 있는 것을 확인할 수 있다. 
그렇다면 뭐가 문제였을까 한참을 고민하다가, 선언되어 있는 Entity를 주의 깊게 살펴보니 바로 알아챌 수 있었다.
 

@JoinColumn(name = "group_id", insertable = false, updatable = false)

바로, insertable = false 옵션으로 인해 오류가 발생했던 것이었다.
정확하게 말하면, 스키마 상으로는 group_id가 NOT NULL로 지정되어 있던 상태에서, insertable = false로 인해 insert 시에 해당 컬럼을 제외하고 쿼리가 발생했기 때문에 오류가 발생했던 것이다.
 
여기서 내가 초래했던 실수는 다음과 같다고 생각한다.

1. 개발자가 작성한 Entity가 테이블 형상과 그대로 일치할 것이라 생각하고 테이블 스키마를 주의깊게 살펴보지 않은 점
2. 기존 레거시 코드를 그대로 옮겨야 잘 동작한다고 생각하고, 옵션에 대해 주의 깊게 살펴보지 않은 점.

1번의 경우, 다르게 생각하면 Persistence Layer인 Entity가 DB의 형상과 다르게 유지되면서 (사내에서는 flyway 같은 마이그레이션 툴을 사용하지 않는다.) 발생된 인지 오류였다. 필드가 당연히 nullable 하게 선언되어 있을 것이라고 생각했다.
2번의 경우, 사실 개인적으로 리팩터링을 진행하면서 조금만 수정해도 예상과 다르게 동작했던 점이 여러 번 있다 보니 '최대한 기존 코드를 유지해야겠다!'라는 마음 가짐에서 했던 행동이었다. 주의깊게 봤더라면 처음부터 이상한 점을 알아챌 수 있었을 텐데 부끄러울 정도로 명확한 내 실수 그 자체였다.

그렇다면, 지금까지는 어떻게 insert가 되었던 것일까?

@ManyToOne
@JoinColumn(name = "group_id", insertable = false, updatable = false)
val group: StudentGroup = group

@Column(name = "group_id")
val groupId: Long = group.id

 
내가 리팩터링을 하려고 했던 그 groupId라는 필드를 통해서 insert가 정상적으로 진행이 되고 있던 상태였다.
아마 코드를 처음 작성하신 분의 의도로는 (확실하지는 않지만) Spring data JPA를 사용할 때 메서드명을 통해 select를 많이 하는데, group이라는 도메인 대신에 id를 통해서 바로 값을 가져올 수 있도록 하기 위해 따로 분리하신 게 아닐까 싶다. 
 

Unable to build Hibernate SessionFactory; nested exception is org.hibernate.MappingException: Column 'group_id' is duplicated in mapping for entity

또한, 둘 다 insert가 가능한 상태라면 위와 같이 오류가 발생하기 때문에 엔티티에 대해서는 insertable=false로 막아두신 걸로 추측된다.
 
이전에 작성했던 엔티티를 다시 롤백한 다음 테스트 코드를 돌려보자.

바인딩 파라미터 옵션을 켜고 확인해보면, group_id에 아이디 값이 제대로 들어간 것을 확인할 수 있었다.
위 문제를 해결하기 위해서는 엔티티 직접 참조 유지 + insertable = false를 사용하거나, 기존 형상을 유지하면 된다.
 

---

🌱 Case 2 - 알 수 없는 하이버네이트

사실 위 문제의 경우 비즈니스 로직 수행 후 금방 잡힐 수 있는 케이스였지만, 이번 케이스는 조금 신기한 경우이다.

fun findStudent(id: Long): Student {
    return studentRepository.findById(id).orElseThrow()
}

위와 같이 조회를 위한 비즈니스가 추가되었고, 실질적으로 아래와 같은 로직이었다고 생각해보자.

@Test
fun test2() {
    val group = studentService.saveGroup("그룹")
    val student = studentService.saveStudent(group, "학생", 20)
    val findStudent = studentService.findStudent(student.id)
    // 학생의 address 정보를 다른 api로 전달한다고 가정
    callExternalApi(findStudent.address)
}

fun callExternalApi(address: Address) {
    // 대충 address의 각 요소에 대해서 접근하여 호출한다고 가정
    println("address.city = ${address.city}")
    println("address.county = ${address.county}")
    println("address.district = ${address.district}")
}

이때, 위 코드는 어떤 문제가 발생할까?
당시 내가 이해했던 흐름으로는, address의 경우 기본값으로 Address.init()을 통해 빈 객체를 할당해주었기 때문에 실질적으로 city, county, district 값이 null인 address가 할당이 되었을 것이라고 생각했었다.

하지만, 실제로 위 코드의 경우 NPE가 발생하게 된다.
코틀린 같은 언어에서 NPE가 발생한다는 건 굉장히 주의깊게 살펴봐야 하는 부분이라서, 처음에는 매우 당황했었다.
또한, 비즈니스 로직에서 무조건 발생하는 게 아니라 분기에 따라서 발생한 로직이었어서 잘못하면 인지하지 못하고 배포를 나갔을 수도 있던 부분이라서 한 편으로는 지금 잡혀서 다행이라고 생각했었다... ㅎㅎ
 

아무튼, 실제로 디버깅을 통해 확인해보아도 위와 같이 address에 null이 들어간 것을 확인할 수 있었다.
Address 객체 자체를 non-nullable한 타입으로 설정하였는데 어떻게 NPE가 발생한 것일까?
처음에는 디컴파일을 통해, 뭔가 JPA의 내가 모르는 기능으로 인해 nullable한 타입으로 선언된다고 생각했었다.
 

하지만, 필드와 getter에 대해 모두 @NotNull 어노테이션이 붙어있는 것을 확인할 수 있었다.
 

처음 오류를 봤을 때 나의 심정...

 
처음에는 내가 코틀린을 잘못 알고 있는 건가 싶어서 막 구글링을 하다가 아래와 같은 이슈를 발견하였다.

[HHH-7610] - Hibernate JIRA

When all of the values in an @Embedded object are NULL, Hibernate sets the field in the parent object to null. 
This can lead to NullPointerExceptions if not handled correctly.

요약: Embedded 객체의 모든 필드가 null이면 해당 객체도 null로 하이버네이트가 세팅을 한다.

가만히 생각해보면 JPA의 경우 리플랙션을 통해 객체를 세팅하니까, NotNull로 세팅하더라도 충분히 null로 세팅이 가능할 것 같다는 생각이 들었다. (사실 이부분을 직접 재현해보려고 했는데 생각보다 공수가 더 들어가서 우선 패스...)
 
아무튼, 이를 해결하기 위해 hibernate의 릴리즈 노트를 봤는데 해결책이 있었다! (5.1 version)

spring.jpa.properties.hibernate.create_empty_composites.enabled=true

바로, 위의 옵션을 true로 지정해주면 되는 것이었다.
궁금해서 하이버네이트 쪽을 살짝 찾아봤는데 다음과 같이 구현되어 있다.

public ComponentMetamodel(Component component, MetadataBuildingOptions metadataBuildingOptions) {
    ...
    
    final ConfigurationService cs = component.getMetadata().getMetadataBuildingOptions().getServiceRegistry()
            .getService(ConfigurationService.class);

    this.createEmptyCompositesEnabled = ConfigurationHelper.getBoolean(
            Environment.CREATE_EMPTY_COMPOSITES_ENABLED,
            cs.getSettings(),
            false
    );
}

public ComponentType(TypeFactory.TypeScope typeScope, ComponentMetamodel metamodel) {
	...
    this.createEmptyCompositesEnabled = metamodel.isCreateEmptyCompositesEnabled();
}

이렇게 create_empty_composites.enabled에 대한 옵션 정보를 통해서 플래그를 지정해주고...!

// 객체의 값 비교 로직 중 일부
// null value and empty component are considered equivalent
Object[] xvalues = getPropertyValues( x, entityMode );
Object[] yvalues = getPropertyValues( y, entityMode );

 
잘은 모르겠지만 null value and empty component are considered equivalent 라는 주석도 있었다.
(내부적으로 null 과 빈 객체가 동일하다고 판단하기 위함인 것 같다)

// 프로퍼티 가져올 때
public Object getPropertyValue(Object component, int i)throws HibernateException {
    if (component == null) {
        component = new Object[propertySpan];
    }
    ...
}

// resolve 할 때
@Override
public Object resolve(Object value, SessionImplementor session, Object owner) throws HibernateException {

    if ( value != null ) {
        Object result = instantiate( owner, session );
        Object[] values = (Object[]) value;
        Object[] resolvedValues = new Object[values.length]; //only really need new array during semiresolve!
        for ( int i = 0; i < values.length; i++ ) {
            resolvedValues[i] = propertyTypes[i].resolve( values[i], session, owner );
        }
        setPropertyValues( result, resolvedValues, entityMode );
        return result;
    }
    
    // 여기서 아까 옵션이 활성화 되어 있는 경우 정상적으로 초기화하도록!
    else if ( isCreateEmptyCompositesEnabled() ) {
        return instantiate( owner, session );
    }
    else {
        return null;
    }
}

그리고 빈 객체에 대해서 초기화가 가능하도록 되어 있다. (else if 분기)
원래였으면 else 문으로 인해서 null이 반환되었을 텐데, 저 분기 덕분에 빈 객체로 초기화가 가능하게 된 것이다.

아무튼, 위의 옵션을 적용해보고 돌려보면 다음과 같이 빈 객체가 잘 할당되는 것을 확인할 수 있다!
 

---

 

🌱 간단 회고

사실 주요 도메인인 만큼 신중하게 리팩터링을 진행했어야 했는데, 간단한 작업이라 큰 영향이 없을 것이라고 생각한 것이 문제였던 것 같다.

1. 무조건 엔티티에 작성된 것만 보고 의존하지 말자.

지금까지 개인 프로젝트를 했을 때는 테이블 세팅부터 내가 진행했다 보니까 자연스럽게 JPA 엔티티가 테이블의 형상을 그대로 따라간다고 생각했던 것 같다. 하지만, 현업에서는 이미 테이블이 세팅되어 있고, 테이블의 스키마가 변함에도 불구하고 엔티티가 업데이트 되지 않는 경우가 많다. 앞으로는 테이블 스키마부터 먼저 체크를 해봐야겠다.
 

2. 레거시라고 무조건 따라가지 말기

앞서 신중하자고 했지만, 무엇보다 레거시 코드를 그대로 믿고 따라가는 건 다른 레거시를 또 낳는 행동인 것 같다.
신중하게 영향 범위를 잘 파악해서 조금씩 리팩터링을 진행하는 게 가장 중요한 것 같다.
사실 이번 리팩터링은 규모가 커서 다시 롤백했지만... 🥲 1월에 다시 한 번 시도해볼 예정이다.
 

3. JPA의 러닝커브 고민해보기

사실 우리 팀의 경우 JPA의 기능을 제대로 활용하지 않는다. 정말 CRUD를 편하게 해주는 도구 그 이상, 그 이하도 아니게 사용하는 느낌?
예전에는 JPA가 무조건 좋다고 생각했는데, 회사를 입사하고 든 가장 큰 생각은 모두가 생각하는 지향점과 러닝 커브가 새로운 기술을 도입하고 어떠한 것을 사용할 때 가장 중요하다는 생각이 들었다. 사용할 거면 제대로 알아보고, 팀원 모두가 해당 지식에 대해 완벽하게 싱크가 되어 있을 때 사용하는 것이 좋을 것 같다.
 
JPA의 러닝커브를 생각해보았을 때, @ManyToOne 같은 JPA 종속적인 어노테이션을 많이 사용해야 하는가? 라는 의문점도 들고... 아마 다음 리팩터링 때는 @ManyToOne 같은 어노테이션을 제거하는 방향도 한 번 고려해볼 것 같다.
이번 @Embedded 케이스도 사실 팀 내에서 가장 익숙한 사람이 나였어서, 다시 사용하지 않는 방향으로 나아가는 걸 고민 중이다. (모두가 편하게 사용하는 게 가장 중요하니까)

오랜만에 블로그 글을 작성하다 보니 생각보다 시간도 많이 쓰였지만, 발표까지 했던 주제(...) 였던 것 만큼 개인적으로 정리해보고 싶었다. 내년부터는 다시 조금씩 블로그 글도 열심히 작성해야겠다... 파이팅!