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

22 KiB
Raw Permalink 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
feature-capability-provider-selection-contract
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 공식 근거
raw/branch-notes/feature-capability-provider-selection-contract capability 활성화 property 를 단일 prefix 로 통일하는 결정의 근거 — relaxed binding 이 dash/capitalized 환경변수를 동일 property 로 취급하는 메커니즘, placeholder canonical form(kebab-case) 권장, @ConfigurationProperties prefix→bean 명명 규칙, type-safe binding 이점, OS 환경변수가 application.yml(config data)보다 나중에 평가되는(우선하는) PropertySource 순서 — 현재 ca-skeleton.*/app.* 이중 prefix 와 APP_* 환경변수 registry 통일 필요성의 공식 근거

출처 / 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."

추가 인용 (2026-07-28, feature-capability-provider-selection-contract 근거 수집, 6개)

셀프그렙 검증 원본: /tmp/source-fetch-20260728-155300.txt (WebFetch 결과 저장, self-grep 통과)

[§Relaxed Binding — 환경변수 특수문자 치환, self-grep L7] "If you use environment variables rather than system properties, most operating systems disallow period-separated key names, but you can use underscores instead (for example, SPRING_CONFIG_NAME instead of spring.config.name)."

[§Relaxed Binding — 일반 규칙 + 예시, self-grep L11] "Spring Boot uses some relaxed rules for binding Environment properties to @ConfigurationProperties beans, so there does not need to be an exact match between the Environment property name and the bean property name. Common examples where this is useful include dash-separated environment properties (for example, context-path binds to contextPath), and capitalized environment properties (for example, PORT binds to port)."

[§Placeholder canonical form 권장, self-grep L17] "You should always refer to property names in the placeholder using their canonical form (kebab-case using only lowercase letters). This will allow Spring Boot to use the same logic as it does when relaxed binding @ConfigurationProperties."

[§@ConfigurationProperties bean 명명 규칙 (prefix), self-grep L29] "When the @ConfigurationProperties bean is registered using configuration property scanning or through @EnableConfigurationProperties, the bean has a conventional name: <prefix>-<fqn>, where <prefix> is the environment key prefix specified in the @ConfigurationProperties annotation and <fqn> is the fully qualified name of the bean."

[§Type-safe Configuration Properties 이점, self-grep L33] "Using the @Value("${property}") annotation to inject configuration properties can sometimes be cumbersome, especially if you are working with multiple properties or your data is hierarchical in nature. Spring Boot provides an alternative method of working with properties that lets strongly typed beans govern and validate the configuration of your application."

[§PropertySource 순서 목록 (item 3, 5) + 순서 방향 확인 문장, self-grep L45/L47/L61] "3. Config data (such as application.properties files)" ... "5. OS environment variables" ... "As mentioned previously, command line properties always take precedence over file-based property sources."

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 일반 동작
SPRING-EXTCONFIG-C6 Spring Boot relaxed binding 은 dash-separated 환경변수(context-path→contextPath)와 capitalized 환경변수(PORT→port)를 각각 bean property 이름으로 매핑한다 [§Relaxed Binding, self-grep L11] "Common examples where this is useful include dash-separated environment properties (for example, context-path binds to contextPath), and capitalized environment properties (for example, PORT binds to port)." official-vendor-doc @ConfigurationProperties 바인딩 전체 (환경변수 소스) 어떤 표기가 "정식" 표기인지는 말하지 않음 — canonical form 권장은 별도 claim(C8)
SPRING-EXTCONFIG-C7 대부분의 OS 는 마침표(.)로 구분된 키 이름을 환경변수로 쓸 수 없어서, Spring Boot 는 언더스코어(_) 치환을 허용한다(예: spring.config.name → SPRING_CONFIG_NAME) [§Relaxed Binding — 환경변수 특수문자 치환, self-grep L7] "...most operating systems disallow period-separated key names, but you can use underscores instead (for example, SPRING_CONFIG_NAME instead of spring.config.name)." official-vendor-doc 환경변수로 property 를 지정하는 모든 경우 대문자화가 반드시 함께 요구되는지는 이 문장만으로는 규정하지 않음(대문자 규칙은 C6/C9 예시들이 뒷받침)
SPRING-EXTCONFIG-C8 ${...} placeholder 에서 property 이름을 참조할 때는 항상 canonical form(소문자 kebab-case)을 쓰는 것이 권장된다 — 그래야 relaxed binding 과 동일 로직이 적용된다 [§Placeholder canonical form 권장, self-grep L17] "You should always refer to property names in the placeholder using their canonical form (kebab-case using only lowercase letters)." official-vendor-doc ${demo.item-price} 류의 placeholder 참조 표기 property 소스 파일(application.yml) 자체의 키 표기 관례까지 강제한다고 명시하진 않음 — placeholder 참조 표기에 대한 권장
SPRING-EXTCONFIG-C9 @ConfigurationProperties bean 이 configuration property scanning 또는 @EnableConfigurationProperties 로 등록되면, bean 이름은 <prefix>-<fqn> 관례를 따르며 <prefix> 는 애노테이션에 지정된 environment key prefix 다 [§@ConfigurationProperties bean 명명 규칙, self-grep L29] "...the bean has a conventional name: <prefix>-<fqn>, where <prefix> is the environment key prefix specified in the @ConfigurationProperties annotation..." official-vendor-doc scanning 또는 @EnableConfigurationProperties 로 등록된 @ConfigurationProperties bean 이 문장은 bean 이름 관례를 설명할 뿐, "단일 prefix 를 써야 한다"는 정책을 직접 규정하지 않음 — prefix 는 클래스마다 자유롭게 지정 가능하다는 사실만 확인됨
SPRING-EXTCONFIG-C10 @Value("${property}") 로 설정을 주입하는 방식은 다수 property 나 계층 구조 데이터를 다룰 때 번거로울 수 있으며, Spring Boot 는 strongly-typed bean 이 설정을 관리·검증하게 하는 대안(type-safe @ConfigurationProperties)을 제공한다 [§Type-safe Configuration Properties 이점, self-grep L33] "Using the @Value("${property}") annotation to inject configuration properties can sometimes be cumbersome... Spring Boot provides an alternative method of working with properties that lets strongly typed beans govern and validate the configuration of your application." official-vendor-doc @Value vs @ConfigurationProperties 선택 비교 특정 property 개수·계층 깊이 기준으로 @ConfigurationProperties 전환을 강제하지 않음 — "cumbersome 할 수 있다"는 정성적 진술
SPRING-EXTCONFIG-C11 공식 문서는 PropertySource 를 15개 항목의 순서 목록으로 제공하며, Config data(application.properties 류 파일)는 3번째, OS 환경변수는 5번째로 나열된다. 별도로 커맨드라인 인자(11번째)가 파일 기반 소스보다 항상 우선한다고 명시하여, 목록에서 더 나중에 나열된 소스가 우선한다는 방향을 확인해준다 [§PropertySource 순서, self-grep L45/L47/L61] "3. Config data (such as application.properties files)" ... "5. OS environment variables" ... "As mentioned previously, command line properties always take precedence over file-based property sources." official-vendor-doc Spring Boot 의 전체 PropertySource 우선순위 체계 (config data 파일 vs OS 환경변수 포함) "OS 환경변수가 config data 파일보다 우선한다"는 문장이 이 발췌에 축자적으로 존재하지는 않음 — 목록 순서 + 커맨드라인/파일 우선순위 진술의 결합 추론. SPRING_PROFILES_ACTIVE 같은 특정 키의 실제 override 동작은 별도 통합 테스트 필요

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 공식 근거)
    • SPRING-EXTCONFIG-C6: relaxed binding 이 dash/capitalized 환경변수 표기를 property 이름으로 매핑 (capability-provider-selection 근거)
    • SPRING-EXTCONFIG-C7: 마침표 구분 키를 언더스코어 환경변수로 대체 허용
    • SPRING-EXTCONFIG-C8: placeholder 참조는 canonical form(kebab-case) 사용을 권장
    • SPRING-EXTCONFIG-C9: @ConfigurationProperties bean 이름이 <prefix>-<fqn> 관례를 따름 — prefix 는 애노테이션에 클래스마다 지정하는 값
    • SPRING-EXTCONFIG-C10: @Value 대비 type-safe @ConfigurationProperties 의 이점(다수/계층적 property 관리·검증)
    • SPRING-EXTCONFIG-C11: PropertySource 순서 목록 + "커맨드라인이 파일 기반보다 우선" 진술로 뒷받침되는 우선순위 방향
  • 이 자료가 증명하지 않는 것:
    • 30s 형식이 PT30S 보다 더 권장됨 (C1은 "동등하다"고만 말함 — 규약 선택은 팀 결정)
    • SPRING_PROFILES_ACTIVE 와 APP_PROFILE 이 불일치할 때 startup 이 자동으로 fail-fast 되는 동작 (별도 EnvironmentPostProcessor 구현 필요)
    • @Validated 실패가 반드시 startup 중단을 일으킨다는 명시 (Spring context 초기화 실패가 JVM exit 을 일으키는 것은 Spring Boot 런처 일반 동작이나 이 문서에 명시 없음)
    • SPRING_PROFILES_ACTIVE 라는 정확한 환경 변수 이름이 문서에 명시적으로 나타남 (규칙 귀결)
    • "capability 활성화 property 를 단일 prefix 로 통일해야 한다"는 정책을 이 문서가 직접 규정하지 않음 — C9 는 prefix 가 클래스마다 자유롭게 지정 가능한 애노테이션 속성임을 보여줄 뿐, "prefix 를 하나로 통일하라"는 권고는 없음. 단일 prefix 결정은 ca-skeleton.*/app.* 이중 prefix 가 relaxed binding·canonical form 규칙 위에서 일관성을 해친다는 branch 자체의 판단이며, 이 raw 자료는 그 판단이 딛고 서는 메커니즘(관례상 규칙 자체는 일관 표기를 전제로 설계됨)만 뒷받침한다
    • SPRING_PROFILES_ACTIVE/APP_* 같은 특정 키가 config data 보다 실제로 override 하는지의 런타임 동작 확인(C11 은 목록 순서 + 별도 진술의 결합 추론이며, 이 문서 발췌에 "환경변수가 config data 보다 우선한다"는 축자 문장은 없음)
  • 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
    • APP_PROFILE 과 SPRING_PROFILES_ACTIVE 불일치 시 startup fail 동작 — EnvironmentPostProcessor 또는 @PostConstruct validator 구현 후 통합 테스트로 검증
    • @Validated 실패 시 Spring Boot launcher 가 exit code 1 로 종료되는지 — contract test StartupFailFastTest 로 검증
    • ca-skeleton.*/app.* 이중 prefix를 APP_* 단일 registry 로 통일할 때, relaxed binding 이 실제로 기존 ca-skeleton.* YAML 키와 새 APP_* 환경변수를 충돌 없이 매핑하는지 — 통합 테스트로 검증 필요

메모 / 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.

2026-07-28 추가 메모 (feature-capability-provider-selection-contract 근거 수집)

  • capability 활성화 property 단일 prefix 통일 결정: relaxed binding(C6/C7)과 canonical form 권장(C8)은 "표기가 달라도 같은 property 로 매핑된다"는 사실을 확인해주지만, 반대로 이는 현재 ca-skeleton.* 와 app.* 두 prefix 가 서로 다른 property 트리로 남아 relaxed binding 으로도 통합되지 않는다는 점을 부각시킨다 — relaxed binding 은 표기 변형(대소문자/구분자)만 흡수하고, 서로 다른 prefix 자체를 통합하지는 않음. C9(prefix→bean 명명 규칙)는 prefix 가 클래스 단위로 자유롭게 지정된다는 사실만 보여주므로 "두 prefix 혼재가 Spring 표준 관행이 아니다"라는 직접 근거는 아니다 — 단일 prefix 채택은 이 문서가 아니라 팀의 일관성 정책 판단.
  • 버전 드리프트 주의: 2026-06-05 원 메모(D6 resolution)는 "OS env = 우선순위 10번째"라고 기록했으나, 2026-07-28 재확인한 동일 URL 발췌(Spring Boot 4.1.0 기준, javadoc 링크로 확인)에서는 OS 환경변수가 15개 항목 중 5번째, config data(application.properties)가 3번째로 나열됨. 항목 개수·순서가 문서 버전에 따라 달라졌을 가능성이 있음 — 두 메모 모두 "OS env 가 config data 파일보다 나중(=우선)"이라는 상대적 방향은 일치하나, 절대 순번은 재검증 시점의 문서 버전에 의존하므로 절대 순번을 claim 근거로 인용하지 말 것.
  • 추가로 봐야 할 것: ca-skeleton.*/app.* 두 prefix 를 하나의 APP_* registry 로 합칠 때, 기존 YAML 계층 구조(ca-skeleton.foo.bar)를 app.foo.bar 로 옮기는 마이그레이션 경로가 relaxed binding 만으로 자동 해결되지 않음(수동 rename 필요) — 이 문서 범위 밖.

Related / 관련

Reference in New Issue View Git Blame Copy Permalink