llm-wiki/raw/blog-topics/spring-boot-3-configprops-record-multi-constructor-binding-2026-06-12.md

title, source_type, status, created, related_branches, related_projects, tags, status_label, target_audience, inspiration_url, archive_url

title	source_type	status	created	related_branches	related_projects	tags	status_label	target_audience	inspiration_url	archive_url
Spring Boot 3 @ConfigurationProperties record 에 보조 생성자를 추가하면 바인딩이 깨지는 이유	blog-topic	raw	2026-06-12	feature-domain-event-outbox-contract	ca-tmpl	blog-topic ca-tmpl spring-boot configuration-properties record constructor-binding java21	ready-for-canonical	backend-engineer

Spring Boot 3 @ConfigurationProperties record 에 보조 생성자를 추가하면 바인딩이 깨지는 이유

Parent

raw/branch-notes/feature-domain-event-outbox-contract

---

글감 씨앗

OutboundHttpSettings record 에 기존 호출부 호환을 위한 보조 6-arg 생성자를 추가했을 때, ApplicationContextRunner 로 바인딩을 테스트하자 No default constructor found 로 실패한 경험. 해결책은 @ConstructorBinding 을 canonical compact constructor 에 추가하는 것이었다.

---

블로그 글 아이디어

제목 후보

• "Spring Boot 3 @ConfigurationProperties 레코드에 보조 생성자를 추가하면 생기는 일"
• "왜 Java record 에 생성자를 하나 더 추가했더니 Spring Boot 설정 바인딩이 깨졌나"

핵심 메시지

Spring Boot 3.x 는 record 에 생성자가 딱 하나일 때만 자동으로 constructor binding 경로를 선택한다. 생성자가 둘 이상이면 일반 JavaBean 경로(no-arg constructor 탐색)로 fallback 하기 때문에, 보조 생성자를 추가하는 순간 기존에 잘 돌던 바인딩이 깨진다.

커버할 내용

1. Spring Boot @ConfigurationProperties 에서 record 바인딩이 동작하는 원리 (single-constructor auto-detect)
2. 보조 생성자 추가 시 발생하는 예외 메시지와 스택 트레이스 분석
3. 해결책: @ConstructorBinding (from org.springframework.boot.context.properties.bind) 을 canonical compact constructor 에 명시
4. Spring Boot 2.x vs 3.x import 경로 차이 (@ConstructorBinding deprecated 위치 변경)
5. 실전 패턴: 기존 호출부 호환을 유지하면서 record 필드를 확장하는 방법 (보조 생성자 + @ConstructorBinding)

코드 예시

@ConfigurationProperties(prefix = "app.outbound.http")
public record MySettings(
        Duration connectTimeout,
        Retry retry) {

    @ConstructorBinding  // 다중 생성자 record 필수!
    public MySettings { /* validation */ }

    /** 보조 생성자: 기존 호출부 호환 */
    public MySettings(Duration connectTimeout) {
        this(connectTimeout, null);
    }
}

독자 대상

Java 21 + Spring Boot 3.x 를 사용하며 @ConfigurationProperties 를 record 로 작성하는 개발자.

---

Claims To Verify

• Spring Boot 3.4 릴리즈 노트에 이 동작의 공식 문서 여부 확인 필요.
• @ConstructorBinding import 경로 변경 이력 (2.x → 3.x) 공식 마이그레이션 가이드 인용 필요.

트리거 / Trigger

• 트리거 유형: troubleshooting
• 트리거 날짜: 2026-06-12
• 트리거 연결 노트: raw/branch-notes/feature-domain-event-outbox-contract

글감 / Topic seed

• 한 문장 요지: Spring Boot 3 record @ConfigurationProperties에 보조 생성자를 추가하면 constructor binding auto-detect가 깨질 수 있어 canonical constructor에 @ConstructorBinding을 명시해야 한다.
• 예상 제목 후보:
  • Spring Boot 3 record configuration binding이 깨지는 이유
  • 보조 생성자와 @ConstructorBinding의 함정

핵심 주장 후보 / Claim candidates

• 사실 후보:
  • multi-constructor record는 single-constructor auto-detect 경로를 벗어날 수 있다.
• 의견/해석 후보:
  • backward-compatible constructor를 추가할 때 binding entrypoint를 명시하는 테스트가 필요하다.

Outline seed

1. record binding auto-detect와 multi-constructor fallback을 설명한다.
2. ApplicationContextRunner failure로 원인을 좁힌다.
3. @ConstructorBinding import 경로와 canonical constructor 명시 패턴을 정리한다.

Canonical 전환 후보 / Canonical extraction candidates

• wiki/projects/ca-tmpl/config-and-adapter-templates.md 후보:
  • configuration properties record binding troubleshooting 글감.
• 필요한 추가 검증:
  • 공식 문서/마이그레이션 가이드 source 보강.

Sources / 근거 후보

• raw/branch-notes/feature-domain-event-outbox-contract

미해결 / Unknown

• 아직 확인해야 할 사실: Spring Boot 3.x 공식 문서의 정확한 constructor binding 문구.
• 과장하면 안 되는 부분: 모든 record multi-constructor가 동일하게 실패한다고 단정하지 않는다.

Decision / 처리 결정

• 액션: promote-to-canonical
• 이유: wiki/projects/ca-tmpl/config-and-adapter-templates.md 에 Spring Boot 3 record configuration binding 글감으로 반영한다.
• 다음 단계: blogify 전 official doc 근거를 보강한다.

Related / 관련

• 관련 branch: raw/branch-notes/feature-domain-event-outbox-contract