Files

T

DongHyeonka 58515ab0f3 feat: 공식 문서 근거자료, 브랜치 기능 문서 작성

2026-07-29 18:05:17 +09:00

11 KiB

Raw Permalink Blame History

title, source_type, status, confidence, url, archive_url, related_branches, related_projects, tags, created, last_reviewed

title

source_type

status

confidence

url

archive_url

related_branches

related_projects

Spring Boot Javadoc — ConditionalOnProperty (matchIfMissing default, havingValue, name, prefix)

Layer: raw/official-docs/ — Spring Boot 4.1.0 Javadoc API 페이지(org.springframework.boot.autoconfigure.condition.ConditionalOnProperty) 발췌. 기존 [[raw/official-docs/spring-boot-condition-annotations]] (reference 문서, matchIfMissing 을 1회만 언급하고 semantics 를 설명하지 않음 — SB-COND-C2)가 남긴 공백을 메우기 위해 별도 수집.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-capability-provider-selection-contract	D4("production capability 에 `matchIfMissing = true` 금지")의 메커니즘 근거 승급 — `matchIfMissing` 의 선언된 기본값이 `false` 이고, property 가 `Environment` 에 전혀 없을 때 기본적으로 조건이 match 되지 않는다는 사실이 공식 Javadoc 에 명시되어 있는지 확인

출처

원본 URL: https://docs.spring.io/spring-boot/api/java/org/springframework/boot/autoconfigure/condition/ConditionalOnProperty.html
아카이브 URL: (미수집)
저자 / 조직: Spring Team — Maciej Walkowiak, Stephane Nicoll, Phillip Webb (Javadoc @author 태그 명시) / Broadcom
발행일: 미상 — living Javadoc. 페이지 타이틀 기준 Spring Boot 4.1.0 API, @since 1.1.0
마지막 확인일: 2026-07-28

왜 저장했는지

[[raw/branch-notes/feature-capability-provider-selection-contract]] 의 D4("production capability 에 matchIfMissing = true 를 쓰지 않는다")는 기존에 UNSUPPORTED_DECISION 으로 라벨돼 있었다 — 이미 수집한 reference 문서(spring-boot-condition-annotations.md)는 matchIfMissing 을 36,781자 중 1회만 언급하고 기본값·semantics 를 설명하지 않기 때문이다(SB-COND-C2 의 Does not prove 참조). 이 Javadoc 페이지는 그 annotation element 자체의 공식 API 문서이며, matchIfMissing 의 선언된 기본값과 "property 부재 시 기본 동작"을 직접 서술한다. 이 자료로 D4 의 메커니즘 축(공식 문서가 증명하는 것)과 정책 축(내부 결정)을 분리할 수 있는지 확인하는 것이 수집 목적이다.

핵심 인용

[class-level description] "If the property is not contained in the Environment at all, the matchIfMissing() attribute is consulted. By default missing attributes do not match."

[Element Details § matchIfMissing] "Specify if the condition should match if the property is not set. Defaults to false." — Default: false

[Optional Element Summary / Element Details § havingValue] "The string representation of the expected value for the properties. If not specified, the property must not be equal to false."

[Element Details § prefix] "A prefix that should be applied to each property. The prefix automatically ends with a dot if not specified. A valid prefix is defined by one or more words separated with dots (e.g. "acme.system.feature")."

[Element Details § name] "The name of the properties to test. If a prefix has been defined, it is applied to compute the full key of each property. For instance if the prefix is app.config and one value is my-value, the full key would be app.config.my-value"

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
SB-COND-JD-C1	`matchIfMissing` attribute 의 선언된 기본값은 `false` 다	[Element Details § matchIfMissing] "Specify if the condition should match if the property is not set. Defaults to false." (+ `Default: false`)	`official-reference`	`@ConditionalOnProperty(matchIfMissing=...)` 를 명시적으로 지정하지 않았을 때 annotation element 자체의 기본값	`matchIfMissing=true` 를 명시적으로 설정하는 것이 안티패턴이거나 금지해야 한다는 정책적 권고 — 이 문서는 그런 진술을 포함하지 않는다
SB-COND-JD-C2	property 가 `Environment` 에 전혀 존재하지 않을 때, `matchIfMissing` 이 참조되며 기본적으로(=미지정 시) 조건은 match 되지 않는다 — "property 미설정 = 조건 불일치"가 annotation class-level description 이 직접 서술하는 기본 동작이다	[class-level description] "If the property is not contained in the Environment at all, the matchIfMissing() attribute is consulted. By default missing attributes do not match."	`official-reference`	property 완전 부재 상황에서 `@ConditionalOnProperty` 의 기본(=matchIfMissing 미지정) 동작. D4 의 메커니즘 축 근거	특정 capability(예: gRPC 서버, filesystem object storage)가 코드에서 이미 `matchIfMissing=true` 를 명시적으로 override 한 경우의 실제 동작까지 바꾸지 않는다 — 그 6곳의 실제 설정 여부는 `internal-code-fact` 로 개별 확인해야 한다
SB-COND-JD-C3	`havingValue` 의 기본값은 빈 문자열(`""`)이며, 명시하지 않으면 property 값이 `"false"` 와 같지 않아야 match 된다	[Element Details § havingValue] "The string representation of the expected value for the properties. If not specified, the property must not be equal to false."	`official-reference`	`havingValue` 미지정 시 매칭 규칙 (class-level description 의 "존재+값≠false" 규칙과 동일 규칙을 attribute 레벨에서 재확인)	`havingValue` 를 특정 문자열로 지정했을 때 세부 매칭 표(원문에 있으나 이 claim 의 인용 범위 밖)
SB-COND-JD-C4	`prefix` 는 각 property 에 적용되는 접두어이며, 명시하지 않으면 자동으로 점(`.`)으로 끝나고, 점으로 구분된 하나 이상의 단어로 정의된 유효 prefix 를 갖는다(예: `"acme.system.feature"`)	[Element Details § prefix] "A prefix that should be applied to each property. The prefix automatically ends with a dot if not specified. A valid prefix is defined by one or more words separated with dots (e.g. "acme.system.feature")."	`official-reference`	`@ConditionalOnProperty(prefix=...)` 의 문법·기본 동작	prefix 를 생략했을 때(기본값 `""`) 전체 키가 어떻게 계산되는지의 구체 규칙 자체(그건 `name` 설명이 규정, SB-COND-JD-C5)
SB-COND-JD-C5	`name` 은 검사할 property 이름이며, `prefix` 가 정의돼 있으면 각 property 의 full key 계산에 적용된다(예: `prefix=app.config`, value=`my-value` → full key `app.config.my-value`)	[Element Details § name] "The name of the properties to test. If a prefix has been defined, it is applied to compute the full key of each property. For instance if the prefix is app.config and one value is my-value, the full key would be app.config.my-value"	`official-reference`	`name`/`prefix` 조합의 full key 계산 규칙	dashed notation 강제(`my-long-property`)를 어기면 실제 binding 이 실패하는지 여부 — 원문은 "use" 를 권고할 뿐 강제 실패를 서술하지 않음

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- SB-COND-JD-C1: matchIfMissing 의 선언된 기본값은 false
- SB-COND-JD-C2: property 가 Environment 에 전혀 없을 때 (matchIfMissing 미지정 시) 기본적으로 조건은 match 되지 않는다
- SB-COND-JD-C3~C5: havingValue/prefix/name 각 attribute 의 정의와 기본값
이 자료가 증명하지 않는 것:
- "production capability 에 matchIfMissing=true 를 쓰지 않는다"는 정책이 Spring 공식 best practice 라는 것 — Javadoc 은 mechanism(기본값·매칭 규칙)만 서술하고, 이 attribute 를 언제 쓰거나 쓰지 말아야 하는지에 대한 권고 문장을 포함하지 않는다
- @Conditional 계열 조건의 평가 시점·bean definition 순서 의존성 — 그 범위는 sibling [[raw/official-docs/spring-boot-condition-annotations]] 의 SB-COND-C3/C4 가 다룬다
- @ConditionalOnProperty 와 @ConditionalOnBooleanProperty 의 세부 차이 — "See Also" 링크만 존재하고 본문 비교 서술은 없음
내 프로젝트(ca-skeleton) 에 적용하려면 추가 확인이 필요한 것:
- D4 Open Risk 로 남아 있는 6곳(GrpcServerConfig.java:18-22, ObjectStorageConfig.java:32-37 등)이 실제로 matchIfMissing=true 를 명시했는지, 그것이 §Audit A5 판정대로 "속성 부재로 활성화되는 운영 표면"인지는 internal-code-fact 로 개별 확인해야 한다 — 이 Javadoc 은 그 판정에 필요한 기본값 규칙만 제공한다

메모

검증되지 않은 내 해석. 인용 아님.

D4 는 이 수집으로 2축 승급 가능: (1) 메커니즘 — "matchIfMissing 기본값은 false, property 부재 시 기본 동작은 조건 불일치"는 이제 official-reference(Javadoc) 근거를 갖는다(SB-COND-JD-C1/C2). (2) 정책 — "그래서 production capability 에는 이 attribute 를 명시적으로 true 로 켜지 않는다"는 여전히 internal-policy다. Javadoc 은 attribute 를 어떻게 쓰라는 권고를 하지 않기 때문. 두 축을 하나의 official-vendor-doc/official-reference 라벨로 뭉치지 말 것.
역설적으로 이 발견은 D4 의 위험 서술을 더 날카롭게 만든다: 기본값(matchIfMissing 미지정)이 이미 "property 부재 = 비활성"이므로, ca-tmpl 6곳이 실제로 위험한 이유는 "matchIfMissing 을 안 써서"가 아니라 "명시적으로 override 해서"다. §Audit A5(GrpcServerConfig/ObjectStorageConfig)가 실제로 matchIfMissing=true 를 썼는지 코드에서 재확인 필요 — 이 raw 문서만으로는 그 코드 사실을 증명하지 못한다.
self-grep 결과 이 Javadoc 페이지 전체에서 matchIfMissing(식별자)은 6회 등장 — 목차(1) + class description(2) + Optional Element Summary(1) + Element Details 제목/시그니처(2)이며, 그중 semantics 를 서술하는 문장은 class description 1곳 + Element Details 1곳 총 2곳뿐이다.

11 KiB Raw Permalink Blame History