donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
main
llm-wiki/raw/official-docs/adapter-spring-boot-autoconfig-custom-starter.md
T

14 KiB
Raw Permalink Blame History

title, source_type, url, archive_url, status, confidence, related_branches, related_projects, tags, created, last_reviewed
title source_type url archive_url status confidence related_branches related_projects tags created last_reviewed
Spring Boot Auto-configuration + custom starter 공식 문서 official-doc https://docs.spring.io/spring-boot/reference/features/developing-auto-configuration.html raw high
feature-integration-adapter-templates
feature-architecture-enforcement-rules
feature-runtime-health-lifecycle-contract
feature-skeleton-package-blueprint-contract
ca-tmpl
ca-tmpl
adapter
spring-boot
auto-configuration
conditional-on-property
custom-starter
2026-05-22 2026-05-27

Spring Boot Auto-configuration + Custom Starter

Layer: raw/official-docs/ — Spring Boot 3.5 reference "Developing Auto-configuration" + @ConditionalOnProperty / @ConditionalOnBooleanProperty Javadoc 발췌. ca-tmpl 그룹 G-I (feature-integration-adapter-templates) 의 adapter on/off 채택안 1차 근거.

Parent / 활용 branch (필수)

Branch 이 자료가 정당화하는 결정
raw/branch-notes/feature-integration-adapter-templates optional adapter 의 @ConditionalOnProperty(name="app.adapter.{adapterName}.enabled", havingValue="true") 결정 — Layer 1 메커니즘의 정확한 공식 시맨틱
raw/branch-notes/feature-architecture-enforcement-rules ArchUnit Layer 2 검사가 Spring 공식 cover 밖이라는 분리 근거 (본 문서는 Layer 1 만 cover)
raw/branch-notes/feature-runtime-health-lifecycle-contract required vs optional dependency SSOT 의 boolean 시맨틱 (@ConditionalOnBooleanProperty 3.5.0+ 정합성)
raw/branch-notes/feature-skeleton-package-blueprint-contract adapter 후보 package 의 AutoConfiguration import 등록 위치 (META-INF/spring/...AutoConfiguration.imports) 결정

컨텍스트 / 왜 저장했는지

ca-tmpl feature-integration-adapter-templates branch의 결정 근거 (canonical reference). branch는 "optional adapter는 @ConditionalOnProperty(name="app.adapter.{adapterName}.enabled", havingValue="true") 적용"을 결정. 이 결정의 정확한 공식 시맨틱과 대안(@AutoConfiguration without ConditionalOnProperty, @Profile)과의 차이를 명확히 보존.

출처 / Source

핵심 인용 / Key quotes (verbatim)

[§Understanding Auto-configured Beans] "Classes that implement auto-configuration are annotated with @AutoConfiguration. This annotation itself is meta-annotated with @Configuration, making auto-configurations standard @Configuration classes. Additional @Conditional annotations are used to constrain when the auto-configuration should apply. Usually, auto-configuration classes use @ConditionalOnClass and @ConditionalOnMissingBean annotations. This ensures that auto-configuration applies only when relevant classes are found and when you have not declared your own @Configuration."

[§Locating Auto-configuration Candidates] "Spring Boot checks for the presence of a META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports file within your published jar. The file should list your configuration classes, with one class name per line." (additional: "Auto-configurations must be loaded only by being named in the imports file. Make sure that they are defined in a specific package space and that they are never the target of component scanning.")

[§@ConditionalOnProperty Javadoc] "@Conditional that checks if the specified properties have a specific value. By default the properties must be present in the Environment and not equal to false." (collection note: "This condition cannot be reliably used for matching collection properties... It is better to use a custom condition for such cases.")

[§@ConditionalOnBooleanProperty Javadoc, since 3.5.0] "@Conditional annotation that checks if the specified properties have a specific boolean value. By default the properties must be present in the Environment and equal to true. The havingValue() and matchIfMissing() attributes allow further customizations."

[§Naming + Configuration keys] "Do not start your module names with spring-boot, even if you use a different Maven groupId." / "If your starter provides configuration keys, use a unique namespace for them. In particular, do not include your keys in the namespaces that Spring Boot uses (such as server, management, spring, and so on)... As a rule of thumb, prefix all your keys with a namespace that you own (for example acme)."

Claims Extracted / 추출된 주장

Claim ID Claim (이 자료가 직접 말하는 것) Evidence quote Strength Applies to Does not prove
SBAC-C1 auto-configuration class 는 @AutoConfiguration (= meta-annotated @Configuration) + 추가 @Conditional (보통 @ConditionalOnClass, @ConditionalOnMissingBean) 로 적용 조건을 제한 [§Understanding Auto-configured Beans] "Classes that implement auto-configuration are annotated with @AutoConfiguration. This annotation itself is meta-annotated with @Configuration... Additional @Conditional annotations are used to constrain when the auto-configuration should apply. Usually, auto-configuration classes use @ConditionalOnClass and @ConditionalOnMissingBean annotations." official-vendor-doc Spring Boot AutoConfiguration 작성 일반 @ConditionalOnProperty 가 표준 권장 조합이라는 뜻은 아님 (문서가 명시한 표준 조합은 OnClass + OnMissingBean)
SBAC-C2 auto-configuration discovery 는 published jar 의 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 파일에 한 줄당 한 class FQN 을 나열하는 방식이며, imports file 에 등록되지 않은 class 는 auto-configuration 으로 로드되지 않음 + component scan 대상이 되면 안 됨 [§Locating Auto-configuration Candidates] "Spring Boot checks for the presence of a META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports file... The file should list your configuration classes, with one class name per line." + "Auto-configurations must be loaded only by being named in the imports file." official-vendor-doc Spring Boot 2.7+ 의 AutoConfiguration.imports 메커니즘 기존 spring.factories 가 deprecated 라는 뜻은 본 인용 범위 밖 (별도 release note)
SBAC-C3 @ConditionalOnProperty 는 default 로 property 가 Environment 에 존재 + 값이 false 가 아닐 때 매칭. matchIfMissing default 는 false. collection property 에는 신뢰성 있게 사용 불가 [§@ConditionalOnProperty Javadoc] "By default the properties must be present in the Environment and not equal to false." + "This condition cannot be reliably used for matching collection properties... It is better to use a custom condition for such cases." official-reference Spring Boot 3.x @ConditionalOnProperty 사용 havingValue 미지정 시 모든 임의 string 값에 매칭한다는 뜻은 아님 — 명시적으로 false 만 reject, 빈 string 은 표 참조
SBAC-C4 @ConditionalOnBooleanProperty (since 3.5.0) 는 boolean 시맨틱을 명시적으로 강제 — default 로 property 가 Environment 에 존재 + 값이 true 일 때 매칭, matchIfMissing default false [§@ConditionalOnBooleanProperty Javadoc, since 3.5.0] "By default the properties must be present in the Environment and equal to true. The havingValue() and matchIfMissing() attributes allow further customizations." official-reference Spring Boot 3.5.0+ 환경 3.5.0 미만 버전에서 동일 시맨틱이 가능하다는 뜻은 아님 (그 경우 @ConditionalOnProperty(havingValue="true") 명시 필요)
SBAC-C5 starter 의 configuration key 는 own namespace prefix 의무. server, management, spring 등 Spring Boot 가 사용하는 namespace 사용 금지 (향후 Spring 이 충돌 변경 가능). module 이름은 spring-boot 로 시작 금지 [§Naming + Configuration keys] "Do not start your module names with spring-boot..." + "do not include your keys in the namespaces that Spring Boot uses (such as server, management, spring, and so on)... prefix all your keys with a namespace that you own (for example acme)." official-vendor-doc custom starter 배포 "acme" 이외의 특정 prefix 가 권장된다는 뜻은 아님 — 본 문서는 예시일 뿐

Usage Boundaries / 적용 경계

  • 이 자료가 직접 증명하는 것:
    • SBAC-C1: @AutoConfiguration 의 메타 구조 + 표준 @Conditional 조합 (OnClass + OnMissingBean)
    • SBAC-C2: AutoConfiguration.imports 파일 위치·형식·discovery 의무
    • SBAC-C3: @ConditionalOnProperty 의 default 매칭 규칙 + collection 한계
    • SBAC-C4: @ConditionalOnBooleanProperty (3.5.0+) 의 명시적 boolean 시맨틱
    • SBAC-C5: custom starter 의 namespace/naming 의무
  • 이 자료가 증명하지 않는 것:
    • "ApplicationContext bean count = 0" 검증이 Spring 공식 권장 verification 패턴이라는 명제 (본 문서는 verification 메커니즘을 명시 안 함)
    • ArchUnit 기반 정적 검사가 Spring 공식 권장 패턴이라는 명제 (Spring docs 범위 밖)
    • AdapterDisabledException 같은 runtime fail-fast 패턴 (ca-tmpl 자체 contract, 공식 문서 부재)
    • @Profile 과 @ConditionalOnProperty 의 정확한 우선순위·결합 시맨틱
  • 내 프로젝트(ca-tmpl) 에 적용하려면 추가 확인이 필요한 것:
    • havingValue="true" 명시 + matchIfMissing=false 조합이 branch 의 "기본 disabled" 의도를 정확히 표현하는지 (intent 일치 확인)
    • 3.5.0 미만 baseline 인 경우 @ConditionalOnBooleanProperty 사용 불가 → fallback 필요
    • starter 의 acme 같은 prefix 를 ca-tmpl 의 app.adapter.<name>.enabled 네임스페이스로 매핑하는 결정 (본 문서는 prefix 예시만 제공)

메모 / Notes (내 프로젝트 해석 — 미검증)

본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.

  • 적용 시나리오: 선택형 adapter (Kafka / Redis / Slack / Google Email) 같은 외부 통합 모듈을 단일 codebase에 두되, application property로 on/off 전환.
  • 장점:
    • 표준 메커니즘: @ConditionalOnProperty + AutoConfiguration.imports 조합은 Spring 공식 패턴.
    • boot 시점 결정: false → bean 자체 등록 안 됨. ApplicationContext 검사로 검증 가능.
    • branch가 결정한 3-layer detection (ApplicationContext / ArchUnit / Runtime AdapterDisabledException) 중 Layer 1을 정확히 cover.
    • Spring Boot 3.5부터 @ConditionalOnBooleanProperty 추가 — boolean 시맨틱이 명시적으로 강제됨. branch의 "boolean true/false only" 결정과 정합.
  • 단점 / 함정:
    • havingValue 누락 시: property가 단순히 "존재"하면 매칭 → false 의도가 무력화될 수 있음. branch는 havingValue="true" 명시.
    • matchIfMissing은 default false. 누락된 env가 자동으로 enable로 해석되지 않도록 주의.
    • collection property에는 사용 부적합 (Javadoc 명시).
  • ca-tmpl 결정과의 매핑:
    • branch Layer 1: @ConditionalOnProperty(name="app.adapter.{name}.enabled", havingValue="true") → 본 문서 인용 그대로.
    • branch Layer 2 (ArchUnit noClasses().that().resideInAPackage("..application..").should().dependOnClassesThat().resideInAPackage("..adapters.{disabled-adapter}..")): Spring 공식 문서 범위 밖. ArchUnit 별도 source 필요.
    • branch Layer 3 (AdapterDisabledException + log code REQUIRED_ADAPTER_DISABLED): branch 자체 contract. 공식 문서가 강제하지 않는 영역.
  • 대안 비교:
    • @Profile("kafka") — boolean 시맨틱 부재, 다중 활성/비활성 표현이 어려움.
    • AutoConfiguration without ConditionalOnProperty — classpath 존재만으로 bean 등록 → 비활성 의도 표현 불가.
    • SPI/ServiceLoader — Spring DI와 별도 라이프사이클. Spring 환경에서는 over-engineering.
  • 신뢰도: official-doc 등급. Spring 공식 reference + API doc.

Related / 관련

Reference in New Issue View Git Blame Copy Permalink