JPA Entity와 schema.sql의 불일치로 인한 잠재적 위험 (jOOQ DSL codegen으로 인한 순환 참조 문제)

[LeeHanEum]

Describe

배경

기존에는 schema.sql 기반으로 jOOQ DSL을 생성했지만, 이 방식으로 인해 JPA Entity와 DSL 간 불일치가 발생하고,
개발자가 schema.sql을 직접 관리하는 데 리소스가 중복으로 투입되는 문제가 있었습니다.
이를 개선하기 위해 JPA Entity 기반 DSL 생성으로 전환을 고려하게 되었습니다.

기존 방식의 문제점

• schema.sql을 기반으로 jOOQ DSL을 생성 → JPA Entity와 불일치 발생 → 런타임 에러 위험 증가
• 개발자가 수동으로 schema.sql을 관리해야 함 → 생산성 저하 및 유지보수 비용 증가

jOOQ 공식 문서에서의 제약

"You cannot put your JPA entities in the same module as the one that runs the jOOQ code generator."

즉, 모놀리식 아키텍처에서 JPA 엔티티와 Codegen을 같은 모듈에 두면 안 됨

• Codegen → Entity 참조 필요
• Entity → DSL 참조 필요 → 잠재적인 순환 참조 문제 발생

따라서 Codegen Plugin과 애플리케이션은 분리가 필요합니다.

단순히 Codegen을 분리하는 것을 넘어, 레이어드 기반의 멀티 모듈 구조를 도입할 것을 제안합니다

1. 관심사 분리

• DSL은 persistence 모듈에서만 사용
• 도메인 계층은 인프라 세부사항에 의존하지 않도록 유지
• 클린 아키텍처 원칙 준수

2. 순수 도메인 유지

• Domain 모듈에서 비즈니스 규칙과 유즈케이스 관리
• 쿼리, DSL, DB 설정 등 인프라 관련 요소를 격리

3. 의존성 흐름 강제

• Query Command 모델이 잘못된 계층에 주입되는 문제 방지
• 비즈니스 로직, 예외, 도메인 규칙의 분리를 강제

4. 테스트 용이성 확보

• 순수 도메인을 단위 테스트하기 쉬워짐
• infra 의존성이 제거된 상태에서 테스트 가능

Tasks

선행 작업

• 도메인 모델에서 애플리케이션 의존성 제거 #165
• Query Command 모델이 infra 까지 의존성이 주입되지 않도록 수정

본 작업

• 멀티 모듈 구조 도입
• JPA Entity와 DSL 간의 불일치 해결

ETC

CI 과정에서 검증할 수는 없는가?
./gradlew build 시 일반적인 빌드 순서는 다음과 같습니다:

1. compileKotlin – Kotlin/Java 소스 코드 컴파일
2. generateJooq – jOOQ DSL 생성
3. 나머지 빌드 – 테스트, jar 생성 등

DSL과 JPA Entity 간의 불일치 검증은 Codegen task가 완료된 이후에 수행되어야 합니다.
하지만 문제는 불일치로 인한 순환 참조가 이미 검증 이전 단계에서 발생할 수 있다는 것입니다.

즉, CI에서 검증을 시도하더라도 Codegen 실행 전이나 실행 중 발생하는 순환 참조를 막을 수 없기 때문에,
근본적인 문제를 예방하려면 멀티 모듈 구조와 JPA Entity 기반 DSL 생성과 같은 구조적 해결이 필요합니다.

[wjdwnsdnjs13]

사전에 논의했던 내용처럼 '멀티 모듈을 도입해야 하는 이유'가 조금 더 설명이 필요해 보여요!

JPA와 Jooq가 Schema.sql 불일치 문제로 서로 다른 상태를 가리킬 수 있다는 점은 반박의 여지가 없지만, 그걸 해결할 수 있는 방법은 다양하니까요 :)

가장 간단하게는 Entity를 통한 DDL과 Schema.sql이 일치하는지 확인하는 테스트 케이스를 추가하거나, 팀 룰로 Entity 변경 시 Schema가 항상 같은 커밋에 위치하도록 하거나 하는 등의 작업을 통해서도 해결이 가능해요.

현재 상태에서는 멀티 모듈을 도입함으로 인해서 잃을 수 있는 점들이 많기에 조금 더 설득이 필요해 보여요 :)
e.g) 기존 Jooq 코드 중 계층과 상관 없이 사용되던 모델들에 대한 코드 수정 등

또한, 멀티 모듈을 단순하게 도입하기에는 아쉬움이 남는 이유가 멀티 모듈 단독으로는 의미가 없는 아키텍쳐일 수 있다고 생각해요.
부가적으로 계층을 완전히 분리해서 사용한다거나 하는 등의 작업이 들어가야 멀티 모듈의 장점을 사용한다고 생각하기 때문에 명확한 이유가 있으면 좋을 것 같네요.

[LeeHanEum]

@wjdwnsdnjs13

좋은 피드백 감사드립니다 :)
말씀 주신 것처럼 schema.sql 테스트 케이스를 추가하거나 팀 룰로 관리하는 것도 충분히 고려할 수 있는 대안이라고 생각합니다.
다만 그럼에도 불구하고 멀티 모듈 도입을 제안드리는 이유는 정리해보면~

우선 테스트나 팀 룰은 어디까지나 사람이 지켜야 하는 규칙이기 때문에, 인수인계 과정이나 신규 인원 합류 시 지켜지지 않을 가능성이 있습니다. 반면 멀티 모듈은 구조적으로 계층 간 의존성을 강제 차단하기 때문에, 실수를 원천적으로 줄일 수 있다는 장점이 있습니다.

또한 멀티 모듈을 도입하면 JPA나 jOOQ와 같은 인프라 의존성을 도메인/애플리케이션 계층에서 완전히 분리할 수 있습니다. 이렇게 하면 도메인은 순수한 도메인 규칙만 담을 수 있고, 인프라 의존성 없이 단위 테스트를 진행할 수 있습니다.

사실 저도 말씀해주신 것처럼 단순히 schema.sql 불일치 문제만 해결하기에는 멀티 모듈이 과한 선택일 수 있다는 점에 동의합니다. 하지만 프로젝트가 장기적으로 성장하면서 DSL, Entity, Infra 관련 코드가 점점 복잡해질 경우, 모듈 경계가 곧 유지보수성과 확장성을 지켜주는 안전장치가 될 수 있다고 생각합니다.

무엇보다 코어 서비스는 앞으로 여러 기수에 걸쳐 장기간 사용되고 지속적으로 발전할 프로젝트이기 때문에, 장기적인 유지보수성과 안정성을 확보한다는 관점에서 멀티 모듈 도입이 필요하다고 생각합니다