85 lines
11 KiB
Markdown
85 lines
11 KiB
Markdown
---
|
|
title: official-doc / Spring Boot Javadoc — ConditionalOnProperty (matchIfMissing default, havingValue, name, prefix)
|
|
source_type: official-doc
|
|
status: raw
|
|
confidence: high
|
|
url: https://docs.spring.io/spring-boot/api/java/org/springframework/boot/autoconfigure/condition/ConditionalOnProperty.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 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곳뿐이다.
|
|
|
|
## 관련
|
|
|
|
- 같은 annotation, 다른 문서 계층(reference guide, `matchIfMissing` 존재만 언급): `[[raw/official-docs/spring-boot-condition-annotations]]`
|
|
- 인접 주제 (`@ConditionalOnProperty` 기반 adapter on/off 의 ArchUnit 정적 검사 한계): `[[raw/official-docs/archunit-conditional-on-property-3-layer-pattern]]`
|
|
- 이 자료를 인용한 wiki 요약: (생성 시 추가)
|