donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
074931bea4161597a96aa3973fe6dfc95df61141
llm-wiki/raw/official-docs/config-spring-boot-externalized-configuration.md
T

10 KiB
Raw Blame History

title, source_type, url, archive_url, related_branches, related_projects, tags, created
title source_type url archive_url related_branches related_projects tags created
official-doc / Spring Boot — Externalized Configuration (Features Reference) official-doc https://docs.spring.io/spring-boot/reference/features/external-config.html
feature-env-driven-runtime-configuration
ca-skeleton
official-doc
ca-skeleton
application
spring-boot
bean-validation
externalized-config
profile-activation
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

왜 저장했는지 / 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 / 관련

Reference in New Issue View Git Blame Copy Permalink