운영 장애에서 오픈소스 기여까지, OpenFeign/querydsl 컨트리뷰트

1. 배경

1) 오픈소스 기여 도전 배경

이전 글에서 JPA 양방향 @OneToOne으로 인한 Q클래스 <clinit> 데드락 장애를 다뤘습니다.

[Spring] QueryDSL 특정 API 타임아웃 - JPA 양방향 @OneToOne으로 인한 클래스 초기화 데드락, Class Initializa

이 문제는 원인을 파악하기 특히 힘들었습니다.

• 예외 발생X, 스레드가 조용히 멈춤
• 에러 로그도 없음
• DB, CPU, 메모리도 정상
• 불규칙하게 재발, 에러상황 재현 어려움

문제를 파악하고 나서 QueryDSL 이슈를 찾아보니, 이미 2012년(#146)과 2018년(#2334)에 제기된 상태였습니다.

하지만 우회책을 문서화하거나, 커뮤니티에서 해결방법이 공유되는 정도로 닫혔습니다.

문제를 특정하기도 어려운 상황에서 이는 충분한 해결책이 되지 않는다고 생각했습니다.

이전 글에서 정리한 해결 방법들(양방향 끊기, 앱 시작 시 강제 초기화, 직접 인스턴스 생성 등)로 문제를 해결할 수 있지만,

세 방법 모두 이 구조가 위험하다는 걸 이미 알고 있어야 적용할 수 있습니다.

코드를 처음 작성하는 개발자 입장에서 양방향 @OneToOne을 걸었을 때 데드락이 생긴다는 걸 사전에 알기 어렵습니다.

이에 컴파일 시점에 경고 하나만 있어도 다른 사람들은 제가 한 삽질을 안해도 되지 않을까? 라고 생각했습니다.

이렇게 제 첫번째 오픈소스 기여 도전이 시작됐습니다.

 

2) querydsl/querydsl이 아닌 OpenFeign/querydsl 선정

원본 querydsl/querydsl은 사실상 관리가 중단된 상태입니다. 이에 OpenFeign에서 포크를 만들어 독립적으로 운영 중입니다.

Spring Data JPA 공식 문서에도 다음과 같이 명시되어있습니다.

이에 OpenFeign의 querydsl에 pr을 올리기로 결정했습니다.

2. 구현

1) AbstractQuerydslProcessor

QueryDSL APT는 컴파일 시점에 @Entity가 붙은 클래스를 분석해 Q클래스를 자동으로 생성하는 어노테이션 프로세서입니다.

이 프로세서의 핵심 클래스가 AbstractQuerydslProcessor이며, processAnnotations()가 실제 Q클래스 생성 로직의 진입점입니다.

 

protected void processAnnotations() {
    // ... 엔티티 수집, Q클래스 생성 준비 ...

    // 엔티티 관계 정보 완성
    typeFactory.extendTypes();

    // 코드 추가
	detectCircularQClassReferences();

	// 컨텍스트 정리
    context.clean();
}

 

모든 엔티티와 연관관계 정보가 채워진 후에 순환 QClass를 찾는 로직을 추가했습니다.

2) DFS로 사이클 탐지

엔티티가 수백개도 있을 수 있는 상황에서 브루트 포스로 탐색하는것은 리스크가 크다고 생각했습니다.

이에 DFS로 사이클을 탐지하기로 했습니다.

전체 시간복잡도는 O(V+E)로 대규모 프로젝트에서도 빌드 시간에 유의미한 영향을 주지 않도록 했습니다.

3) 컬렉션 제외

@OneToMany같은 컬렉션 관계는 탐지 대상에 포함되지 않습니다.

컬렉션 관계는 ListPath, SetPath등으로 생성되는데, 이 타입들은 <clinit> 실행 시점에 상대 Q클래스를 직접 로딩하지 않습니다.

즉, 컬렉션은 순환 구조가 있어도 <clinit> 데드락의 트리거가 되지 않습니다.

탐지 대상은 단일 엔티티 직접 참조(@OneToOne, @ManyToOne)입니다.

 

3. PR 및 Merge

개인 프로젝트에서 순환 참조를 제대로 찾는지 테스트 해보았습니다.

Payment와 Order를 @OneToOne 관계로 만들고 돌렸습니다.

제대로 나오는 것을 확인했고, PR을 올렸습니다.

PR 링크: feat(apt): detect circular Q-class references and warn at compile time #1739

feat(apt): detect circular Q-class references and warn at compile time by o54711254 · Pull Request #1739 · OpenFeign/querydsl

 

2026년 5월 25일 merge되었습니다.

이로써 첫 오픈소스 기여가 성공적으로 마무리됐습니다.

문제상황일때는 진짜 끔찍했지만, 이렇게 유의미한 성과를 얻으니 보람찹니다.

앞으로도 단순히 수정에 그치지 않고, 왜 문제가 발생했는지 파고드는 개발자가 돼야겠습니다