93 lines
10 KiB
Markdown
93 lines
10 KiB
Markdown
---
|
||
title: "official-doc / Spring Boot — Externalized Configuration (Features Reference)"
|
||
source_type: official-doc
|
||
url: https://docs.spring.io/spring-boot/reference/features/external-config.html
|
||
archive_url:
|
||
related_branches: [feature-env-driven-runtime-configuration]
|
||
related_projects: [ca-skeleton]
|
||
tags: [official-doc, ca-skeleton, application, spring-boot, bean-validation, externalized-config, profile-activation]
|
||
created: 2026-06-05
|
||
---
|
||
|
||
# Spring Boot — Externalized Configuration (Features Reference)
|
||
|
||
> Layer: `raw/` — 외부 자료(공식 문서)의 **원문 발췌·출처 기록**.
|
||
> Spring Boot 4.0.6 Reference — Features › Externalized Configuration
|
||
|
||
## Parent / 활용 branch (필수)
|
||
|
||
| Branch | 이 자료가 정당화하는 결정 |
|
||
|---|---|
|
||
| [[raw/branch-notes/feature-env-driven-runtime-configuration]] | D4: Duration `30s`/`PT30S` 양쪽 허용 확인 (우리 규약이 `30s` 1택을 선택해도 됨을 Spring 공식 근거로 확인) / D6: `spring.profiles.active` 및 relaxed binding 규칙(`SPRING_PROFILES_ACTIVE` 도출 메커니즘) Spring Boot native 공식 근거 / D10: `@ConfigurationProperties + @Validated` JSR-303 startup validation fail-fast 공식 근거 |
|
||
|
||
## 출처 / Source
|
||
|
||
- 원본 URL: https://docs.spring.io/spring-boot/reference/features/external-config.html
|
||
- 아카이브 URL: (미확보)
|
||
- 저자 / 조직: Spring Team (Broadcom / VMware)
|
||
- 발행일: Spring Boot 4.0.6 (2025)
|
||
- 마지막 확인일: 2026-06-05
|
||
|
||
## 왜 저장했는지 / Why archived
|
||
|
||
`feature-env-driven-runtime-configuration` branch 의 D4 (Duration/DataSize binding 포맷), D6 (profile 활성화 우선순위), D10 (`@Validated` startup validation) 세 결정이 모두 `UNSUPPORTED_DECISION` 상태였음. Spring Boot 공식 reference doc 에서 세 결정 모두 직접 지지하는 원문을 확보하기 위해 아카이브.
|
||
|
||
## 핵심 인용 / Key quotes (verbatim, 5개)
|
||
|
||
> [§features.external-config.typesafe-configuration-properties.conversion.durations, line 4471] "To specify a session timeout of 30 seconds, `30`, `PT30S` and `30s` are all equivalent. A read timeout of 500ms can be specified in any of the following form: `500`, `PT0.5S` and `500ms`."
|
||
|
||
> [§features.external-config.typesafe-configuration-properties.conversion.durations, line 4504] "The default unit is milliseconds and can be overridden using `@DurationUnit` as illustrated in the sample above."
|
||
|
||
> [§features.external-config.typesafe-configuration-properties.conversion.data-sizes, line 4733] "To specify a buffer size of 10 megabytes, `10` and `10MB` are equivalent. A size threshold of 256 bytes can be specified as `256` or `256B`."
|
||
|
||
> [§features.external-config.typesafe-configuration-properties.relaxed-binding.environment-variables, line 3966] "For example, the configuration property `spring.main.log-startup-info` would be an environment variable named `SPRING_MAIN_LOGSTARTUPINFO`."
|
||
|
||
> [§features.external-config.files.profile-specific, line 1802] "For example, if profiles `prod,live` are specified by the `spring.profiles.active` property, values in `application-prod.properties` can be overridden by those in `application-live.properties`."
|
||
|
||
> [§features.external-config.typesafe-configuration-properties.validation, line 4897–4898] "Spring Boot attempts to validate `@ConfigurationProperties` classes whenever they are annotated with Spring's `@Validated` annotation. You can use JSR-303 `jakarta.validation` constraint annotations directly on your configuration class."
|
||
|
||
## Claims Extracted / 추출된 주장
|
||
|
||
> 이 자료가 **직접 말하는 것만** claim 으로 분리한다. 내 프로젝트에 적용한 결론은 여기 쓰지 않는다.
|
||
|
||
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
||
|---|---|---|---|---|---|
|
||
| SPRING-EXTCONFIG-C1 | Spring Boot Duration 프로퍼티는 `long`(기본 ms), ISO-8601(`PT30S`), 단순 suffix(`30s`) 세 가지 형식을 모두 허용하며 상호 동등하다 | [§conversion.durations, l.4471] "To specify a session timeout of 30 seconds, `30`, `PT30S` and `30s` are all equivalent." | `official-vendor-doc` | spring.boot ≥ 3.x의 `@ConfigurationProperties`에 바인딩되는 `java.time.Duration` 필드 | 특정 형식이 권장됨을 의미하지 않음 — 어느 형식을 규약으로 고를지는 팀 결정 영역 |
|
||
| SPRING-EXTCONFIG-C2 | Duration 기본 단위는 밀리초(ms)이며 `@DurationUnit` 으로 재정의할 수 있다 | [§conversion.durations, l.4504] "The default unit is milliseconds and can be overridden using `@DurationUnit` as illustrated in the sample above." | `official-vendor-doc` | `@ConfigurationProperties` 바인딩 Duration 필드 | `@DurationUnit` 없이 정수만 쓸 때 단위 착오를 막아주는 보장은 없음 (개발자가 정수 값 단위를 일치시켜야 함) |
|
||
| SPRING-EXTCONFIG-C3 | Spring Framework `DataSize` 프로퍼티는 `long`(기본 bytes)과 단순 suffix(`10MB`) 두 형식을 허용한다 | [§conversion.data-sizes, l.4733] "To specify a buffer size of 10 megabytes, `10` and `10MB` are equivalent." | `official-vendor-doc` | `@ConfigurationProperties` 바인딩 `DataSize` 필드 | `DataSize` 가 ISO-8601 형식을 지원하지 않음을 증명하지 않음 (Duration 과 달리 ISO-8601 언급 없음) |
|
||
| SPRING-EXTCONFIG-C4 | Spring Boot relaxed binding 은 프로퍼티 이름의 점(`.`)을 언더스코어(`_`)로, 대시(`-`)를 제거하고, 대문자로 변환하여 OS 환경 변수 이름에 매핑한다 | [§relaxed-binding.environment-variables, l.3966] "For example, the configuration property `spring.main.log-startup-info` would be an environment variable named `SPRING_MAIN_LOGSTARTUPINFO`." | `official-vendor-doc` | Spring Boot 환경 변수 바인딩 전체 (`systemEnvironment` property source 및 `-systemEnvironment` suffix 를 가진 추가 property source) | `SPRING_PROFILES_ACTIVE` 라는 이름이 문서에 명시적으로 나열되지는 않음 — 규칙 적용의 당연한 귀결 |
|
||
| SPRING-EXTCONFIG-C5 | Spring Boot 는 `@Validated` 애노테이션이 붙은 `@ConfigurationProperties` 클래스를 자동으로 검증하며, `jakarta.validation` JSR-303 제약 애노테이션을 필드에 직접 사용할 수 있다 | [§validation, l.4897–4898] "Spring Boot attempts to validate `@ConfigurationProperties` classes whenever they are annotated with Spring's `@Validated` annotation. You can use JSR-303 `jakarta.validation` constraint annotations directly on your configuration class." | `official-vendor-doc` | Spring Boot 의 `@ConfigurationProperties` + `@Validated` 조합 | 검증 실패 시 startup 이 fail-fast 로 중단된다는 명시적 문구는 이 문서에 없음 — Spring Bean 초기화 실패로 컨텍스트 로드 실패가 발생함은 Spring Framework 일반 동작 |
|
||
|
||
## Usage Boundaries / 적용 경계
|
||
|
||
- 이 자료가 직접 증명하는 것:
|
||
- `SPRING-EXTCONFIG-C1`: Spring Boot Binder 가 `30s`, `PT30S`, `30` 세 형식 모두 수용 (D4 근거 — "양쪽 허용 확인")
|
||
- `SPRING-EXTCONFIG-C2`: `@DurationUnit` 으로 기본 ms 단위를 override 할 수 있음
|
||
- `SPRING-EXTCONFIG-C3`: `DataSize` 가 `10MB` suffix 형식을 수용 (D4 DataSize 근거)
|
||
- `SPRING-EXTCONFIG-C4`: `spring.profiles.active` 는 relaxed binding 규칙에 의해 `SPRING_PROFILES_ACTIVE` 로 매핑됨 (D6 메커니즘 근거)
|
||
- `SPRING-EXTCONFIG-C5`: `@ConfigurationProperties + @Validated` 는 공식 Spring Boot API (D10 공식 근거)
|
||
- 이 자료가 증명하지 않는 것:
|
||
- `30s` 형식이 `PT30S` 보다 더 권장됨 (C1은 "동등하다"고만 말함 — 규약 선택은 팀 결정)
|
||
- `SPRING_PROFILES_ACTIVE` 와 `APP_PROFILE` 이 불일치할 때 startup 이 자동으로 fail-fast 되는 동작 (별도 `EnvironmentPostProcessor` 구현 필요)
|
||
- `@Validated` 실패가 반드시 startup 중단을 일으킨다는 명시 (Spring context 초기화 실패가 JVM exit 을 일으키는 것은 Spring Boot 런처 일반 동작이나 이 문서에 명시 없음)
|
||
- `SPRING_PROFILES_ACTIVE` 라는 정확한 환경 변수 이름이 문서에 명시적으로 나타남 (규칙 귀결)
|
||
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
|
||
- `APP_PROFILE` 과 `SPRING_PROFILES_ACTIVE` 불일치 시 startup fail 동작 — `EnvironmentPostProcessor` 또는 `@PostConstruct` validator 구현 후 통합 테스트로 검증
|
||
- `@Validated` 실패 시 Spring Boot launcher 가 exit code 1 로 종료되는지 — contract test `StartupFailFastTest` 로 검증
|
||
|
||
## 메모 / Notes
|
||
|
||
- D4 resolution: C1 + C3 는 "Spring Boot 가 양쪽 형식을 모두 허용한다" 는 사실을 확인. branch 결정 `30s` 1택은 Spring 강제가 아니라 팀 가독성 규약이므로 D4 를 `UNSUPPORTED_DECISION` → "supported by C1/C3 for mechanical feasibility, team convention for `30s` preference" 로 보강 가능.
|
||
- D6 resolution: C4 는 `spring.profiles.active` → `SPRING_PROFILES_ACTIVE` 매핑 메커니즘을 공식 근거로 확보. `SPRING_PROFILES_ACTIVE` 우선순위 (Spring Boot property precedence table §1 — OS env > properties file) 는 동일 페이지 상단의 priority list 에서 확인 가능 (OS env = 우선순위 10번째, properties file 더 낮음).
|
||
- D10 resolution: C5 는 `@Validated` API 지원의 공식 근거. fail-fast startup 동작은 Spring framework 컨텍스트 로드 실패 일반 동작으로 추가 raw 없이 합리적으로 추론 가능 — 단, 추론이므로 claim 에는 넣지 않음.
|
||
- 추가로 봐야 할 동일 출처 페이지: property precedence priority list (페이지 상단 §1), `@ConfigurationPropertiesScan`, constructor binding with `@DefaultValue`.
|
||
|
||
## Related / 관련
|
||
|
||
- 같은 주제 다른 official-doc:
|
||
- [[raw/official-docs/config-12-factor-app-config]] — 12-factor §III Config (D1 근거)
|
||
- [[raw/official-docs/config-spring-cloud-config-server-official]] — Spring Cloud Config Server (D3 대안)
|
||
- [[raw/official-docs/config-spring-cloud-kubernetes-configmap-reload]] — k8s ConfigMap reload (D3 대안)
|
||
- [[raw/official-docs/config-aws-appconfig-feature-flag-deployment]] — AWS AppConfig (D3 대안)
|
||
- 이 자료를 인용한 wiki 요약: (생성 시 추가)
|