feat: 공식 문서 근거자료, 브랜치 기능 문서 작성
This commit is contained in:
DongHyeonka
@@ -0,0 +1,87 @@
|
||||
---
|
||||
title: official-doc / Spring Boot Condition Annotations — @ConditionalOnProperty, matchIfMissing, Evaluation Order
|
||||
source_type: official-doc
|
||||
status: raw
|
||||
confidence: high
|
||||
url: https://docs.spring.io/spring-boot/reference/features/developing-auto-configuration.html
|
||||
archive_url:
|
||||
related_branches: [feature-capability-provider-selection-contract]
|
||||
related_projects: [ca-skeleton]
|
||||
tags: [official-doc, ca-skeleton, architecture, spring-boot]
|
||||
created: 2026-07-28
|
||||
last_reviewed: 2026-07-28
|
||||
---
|
||||
|
||||
# Spring Boot Condition Annotations — @ConditionalOnProperty / matchIfMissing / Evaluation Order
|
||||
|
||||
> Layer: `raw/official-docs/` — Spring Boot 4.1.0 reference "Creating Your Own Auto-configuration" 발췌. `feature-capability-provider-selection-contract` 브랜치의 "`matchIfMissing=true` 금지" 결정과 "조건 평가 시점의 한계"를 뒷받침하는 근거.
|
||||
|
||||
## Parent / 활용 branch (필수)
|
||||
|
||||
| Branch | 이 자료가 정당화하는 결정 |
|
||||
|---|---|
|
||||
| [[raw/branch-notes/feature-capability-provider-selection-contract]] | production capability 활성화를 `@ConditionalOnProperty` 로 게이트할 때 `matchIfMissing=true` 를 금지하는 결정, 그리고 조건 평가 시점/순서 의존성의 한계 근거 |
|
||||
|
||||
## 출처
|
||||
|
||||
- 원본 URL: https://docs.spring.io/spring-boot/reference/features/developing-auto-configuration.html
|
||||
- 아카이브 URL: (미수집)
|
||||
- 저자 / 조직: Spring Team (spring-projects / Broadcom)
|
||||
- 발행일: 미상 — living reference 문서. 페이지 내 버전 배지 기준 **Spring Boot 4.1.0** (Stable)
|
||||
- 마지막 확인일: 2026-07-28
|
||||
|
||||
## 왜 저장했는지
|
||||
|
||||
`feature-capability-provider-selection-contract` 는 production capability 활성화 게이트에 `@ConditionalOnProperty` 를 쓰되 `matchIfMissing=true` 를 금지한다 (속성 미설정 = 비활성 유지). 이 raw 자료는 (1) `@ConditionalOnProperty` 의 공식 정의와 `matchIfMissing` 이 실제로 존재하는 옵션 attribute 라는 근거, (2) `@Conditional` 계열 annotation 전반의 평가 시점·순서 의존성 한계(원문은 이를 근거로 bean 존재 기반 조건을 auto-configuration class 로 한정 권고)를 보존한다. 후자는 project 가 이미 내린 "활성화는 bean 이름이 아니라 typed descriptor 기반 provider 선택으로만" 결정과도 연결된다.
|
||||
|
||||
## 핵심 인용
|
||||
|
||||
> [§Understanding Auto-configured Beans] "Additional @Conditional annotations are used to constrain when the auto-configuration should apply. Usually, auto-configuration classes use @ConditionalOnClass and @ConditionalOnMissingBean annotations."
|
||||
|
||||
> [§Property Conditions] "The @ConditionalOnProperty annotation lets configuration be included based on a Spring Environment property. Use the prefix and name attributes to specify the property that should be checked. By default, any property that exists and is not equal to false is matched."
|
||||
|
||||
> [§Property Conditions] "There is also a dedicated @ConditionalOnBooleanProperty annotation specifically made for boolean properties. With both annotations you can also create more advanced checks by using the havingValue and matchIfMissing attributes."
|
||||
|
||||
> [§Bean Conditions] "You need to be very careful about the order in which bean definitions are added, as these conditions are evaluated based on what has been processed so far."
|
||||
|
||||
> [§Bean Conditions] "For this reason, we recommend using only @ConditionalOnBean and @ConditionalOnMissingBean annotations on auto-configuration classes (since these are guaranteed to load after any user-defined bean definitions have been added)."
|
||||
|
||||
## Claims Extracted / 추출된 주장
|
||||
|
||||
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
||||
|---|---|---|---|---|---|
|
||||
| SB-COND-C1 | `@ConditionalOnProperty` 는 Spring `Environment` 의 property 존재 여부·값을 기준으로 configuration 포함 여부를 결정하며, `prefix`/`name` 으로 지정한 property 가 **존재하고 값이 `"false"` 가 아니면** 기본적으로 match 된다 | [§Property Conditions] "The @ConditionalOnProperty annotation... By default, any property that exists and is not equal to false is matched." | `official-vendor-doc` | `@ConditionalOnProperty` 의 기본(=`havingValue`/`matchIfMissing` 미지정) 매칭 규칙 | property 가 **부재**할 때의 기본 동작(=matchIfMissing 미지정 시 기본값)은 이 문장이 다루지 않음 — 이 문장은 "존재 시" 규칙만 정의 |
|
||||
| SB-COND-C2 | `matchIfMissing` 은 `havingValue` 와 함께 "more advanced checks" 를 만들 때 쓰는 실존하는 attribute 다 | [§Property Conditions] "With both annotations you can also create more advanced checks by using the havingValue and matchIfMissing attributes." | `official-vendor-doc` | `matchIfMissing` 이라는 옵션이 Spring Boot 공식 API 에 실재한다는 사실 | **이 페이지는 `matchIfMissing` 의 기본값이나 매칭 semantics(속성 부재 시 true/false 중 무엇으로 처리되는지)를 설명하지 않는다** — self-grep 결과 이 페이지 전체에서 `matchIfMissing` 단어는 이 한 문장에서만 등장(1회). 따라서 이 자료만으로 "matchIfMissing=true 를 금지해야 한다"는 명제를 공식 권고로 증명할 수 없음 — 이는 project/branch 의 자체 설계 판단이다 |
|
||||
| SB-COND-C3 | `@Conditional` 계열 annotation(특히 `@ConditionalOnBean`/`@ConditionalOnMissingBean`) 은 "지금까지 처리된 것"을 기준으로 평가되므로 bean definition 이 추가되는 **순서**에 매우 주의해야 한다 | [§Bean Conditions] "You need to be very careful about the order in which bean definitions are added, as these conditions are evaluated based on what has been processed so far." | `official-vendor-doc` | bean 존재/부재 기반 조건(`@ConditionalOnBean`/`@ConditionalOnMissingBean`)의 순서 의존성 일반 | 이 경고는 원문에서 "Bean Conditions" 섹션에 위치 — "Property Conditions" 섹션(`@ConditionalOnProperty`)에는 동일한 순서 의존 경고 문장이 없다. Property 기반 조건에도 동일한 순서 취약성이 있다고 이 인용만으로 단정할 수 없음 |
|
||||
| SB-COND-C4 | 순서 의존 위험 때문에 공식 문서는 `@ConditionalOnBean`/`@ConditionalOnMissingBean` 을 **auto-configuration 클래스에서만** 사용하라고 권고한다 — auto-configuration 클래스는 사용자 정의 bean definition 이 모두 추가된 후에 로드되는 것이 보장되기 때문 | [§Bean Conditions] "For this reason, we recommend using only @ConditionalOnBean and @ConditionalOnMissingBean annotations on auto-configuration classes (since these are guaranteed to load after any user-defined bean definitions have been added)." | `official-vendor-doc` | bean 존재/이름 기반 판정의 순서 취약성 근거 — "bean 이름 기반 판정 제거" 결정을 뒷받침하는 데 사용 가능 | `@ConditionalOnProperty` 같은 property 기반 조건에도 이 권고가 확장 적용된다는 뜻은 아님(범위는 명시적으로 bean 존재 기반 조건) |
|
||||
| SB-COND-C5 | auto-configuration class 는 `@AutoConfiguration`(= meta-annotated `@Configuration`) + 추가 `@Conditional` 로 적용 조건을 제한하며, 보통은 `@ConditionalOnClass` + `@ConditionalOnMissingBean` 조합을 쓴다 | [§Understanding Auto-configured Beans] "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` | 이 문서가 다루는 condition annotation 의 전형적 사용 범위(=auto-configuration class 의 적용 여부 제약) | `@ConditionalOnProperty` 가 이 "usual" 조합에 포함된다는 뜻은 아님(원문이 명시한 usual 조합은 OnClass+OnMissingBean) — capability provider 선택처럼 property 기반 게이트를 쓰는 것이 이 문서의 표준 패턴이라는 주장의 근거로는 쓸 수 없음 |
|
||||
|
||||
## Usage Boundaries / 적용 경계
|
||||
|
||||
- **이 자료가 직접 증명하는 것**:
|
||||
- `SB-COND-C1`: `@ConditionalOnProperty` 의 "존재 + 값≠false" 기본 매칭 규칙
|
||||
- `SB-COND-C2`: `matchIfMissing` 이 실존하는 공식 attribute 라는 사실 (semantics 는 아님)
|
||||
- `SB-COND-C3`: bean 존재 기반 조건은 bean definition 추가 순서에 의존하는 평가 시점 한계가 있음
|
||||
- `SB-COND-C4`: 그 한계 때문에 `@ConditionalOnBean`/`@ConditionalOnMissingBean` 은 auto-configuration class 사용으로 한정 권고됨
|
||||
- `SB-COND-C5`: condition annotation 의 usual 조합은 `@ConditionalOnClass`+`@ConditionalOnMissingBean`
|
||||
- **이 자료가 증명하지 않는 것**:
|
||||
- `matchIfMissing` 의 기본값(true/false) 자체 — 이 reference 페이지는 명시하지 않음(별도로 Javadoc 확인 필요, 본 URL 범위 밖)
|
||||
- "`matchIfMissing=true` 를 금지해야 한다"는 명제가 Spring 공식 best practice 라는 것 — 이 자료는 그런 권고 문장을 포함하지 않는다. 금지 결정은 project/branch 의 안전-기본값(fail-closed) 설계 판단으로 별도 명시해야 함
|
||||
- Bean 조건의 순서 의존 경고가 Property 조건(`@ConditionalOnProperty`)에도 문자 그대로 적용된다는 것 — 원문 절 구분상 별개 섹션
|
||||
- **내 프로젝트(ca-skeleton) 에 적용하려면 추가 확인이 필요한 것**:
|
||||
- `matchIfMissing` 의 실제 기본값과, 값을 명시하지 않았을 때(=옵션 자체를 안 쓸 때) capability descriptor 활성화가 어떻게 평가되는지 — Javadoc(`org.springframework.boot.autoconfigure.condition.ConditionalOnProperty`) 별도 조사 필요
|
||||
- property 기반 조건이 실제로 순서 독립적인지(=Environment 기반이라 bean 등록 순서와 무관한지)를 이 문서만으로 확정할 수 없음 — 필요하면 Spring 소스 또는 별도 실험으로 검증
|
||||
|
||||
## 메모
|
||||
|
||||
> 검증되지 않은 내 해석. 인용 아님.
|
||||
|
||||
- 이 페이지가 `matchIfMissing` semantics를 설명하지 않는다는 사실 자체가 중요한 발견 — branch 결정문에 "공식 문서가 matchIfMissing=false 를 기본값으로 명시한다"처럼 쓰면 과장. 정확히는 "matchIfMissing 은 옵션으로 실재하지만 그 기본값·의미는 이 reference 페이지 밖(Javadoc)에서 확인해야 한다"로 표현할 것.
|
||||
- `SB-COND-C3`/`SB-COND-C4` (bean 조건의 순서 의존성)는 matchIfMissing 자체보다는, project 가 이미 정한 "bean 이름 기반 판정 금지 → typed descriptor 기반 provider 선택" 결정을 보강하는 배경 근거로 더 적합해 보임.
|
||||
- 동일 URL을 이미 인용한 `[[raw/official-docs/adapter-spring-boot-autoconfig-custom-starter]]` (ca-tmpl 프로젝트, `AutoConfiguration.imports`/custom starter naming 위주)와는 발췌 절이 다름 — 이 문서는 Property/Bean Conditions 절에 집중.
|
||||
|
||||
## 관련
|
||||
|
||||
- 같은 URL, 다른 발췌·다른 프로젝트: `[[raw/official-docs/adapter-spring-boot-autoconfig-custom-starter]]` (ca-tmpl, `AutoConfiguration.imports` + custom starter naming + `@ConditionalOnBooleanProperty` 위주)
|
||||
- 인접 주제: `[[raw/official-docs/archunit-conditional-on-property-3-layer-pattern]]` (`@ConditionalOnProperty` 기반 adapter on/off 의 ArchUnit 정적 검사 한계)
|
||||
- 이 자료를 인용한 wiki 요약: (생성 시 추가)
|
||||
Reference in New Issue
Block a user