외부 설정과 프로필 우선순위

포트, 시간대, 외부 서비스 주소처럼 배포 환경마다 달라지는 값은 코드에서 분리해야 합니다. 그러나 문자열 키를 필요한 곳마다 직접 읽으면 이름 오타와 타입 변환 오류를 실행 중에야 발견하게 됩니다.

@ConfigurationProperties는 같은 접두사의 값을 하나의 타입으로 묶고 애플리케이션 시작 시 검증합니다. 기본값은 공통 설정에 두고, 프로필은 환경별 묶음을 선택하며, 환경 변수는 배포 시점의 최종 값을 덮어쓰는 데 사용합니다.

설정 값도 검증 가능한 모델이어야 한다

설정 우선순위는 "무엇이 더 중요하다"가 아니라 같은 키가 여러 출처에 있을 때 어느 값을 최종 선택할지 정하는 규칙입니다. 공통 application.yaml 위에 활성 프로필의 문서가 적용되고, 운영 환경이 제공한 환경 변수는 파일 값을 다시 덮어쓸 수 있습니다.

환경 변수 이름 STUDY_LOG_DAILY_LIMIT_MINUTES가 study-log.daily-limit-minutes에 연결되는 것은 relaxed binding 덕분입니다. 표기법은 달라도 같은 속성으로 인식하지만, 타입과 @Min·@Max 제약까지 우회하는 것은 아닙니다.

타입 안전한 StudyLog 설정 만들기

시간대와 하루 학습 상한을 하나의 record로 묶습니다. 설정이 빠졌거나 범위를 벗어나면 요청을 받은 뒤가 아니라 애플리케이션 시작 단계에서 실패하게 만드는 것이 목표입니다.

src/main/java/com/andongmin/studylog/StudyLogProperties.java

package com.andongmin.studylog;

import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;

@Validated
@ConfigurationProperties("study-log")
public record StudyLogProperties(
        @NotBlank String zone,
        @Min(1) @Max(1440) int dailyLimitMinutes) {
}

src/main/java/com/andongmin/studylog/StudyLogApplication.java

package com.andongmin.studylog;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.EnableConfigurationProperties;

@SpringBootApplication
@EnableConfigurationProperties(StudyLogProperties.class)
public class StudyLogApplication {
    public static void main(String[] args) {
        SpringApplication.run(StudyLogApplication.class, args);
    }
}

src/main/resources/application.yaml

study-log:
  zone: Asia/Seoul
  daily-limit-minutes: 480

src/main/resources/application-local.yaml

study-log:
  daily-limit-minutes: 540

local 프로필은 공통 시간대를 그대로 두고 학습 상한만 540분으로 바꿉니다. 프로필 파일은 전체 설정을 복사하는 문서가 아니라 공통값과 다른 부분만 적는 덮어쓰기 문서로 유지하는 편이 안전합니다.

프로필과 환경 변수의 최종 값을 비교한다

먼저 프로필만 활성화해 540이 선택되는지 확인하고, 이어서 환경 변수로 같은 키를 600으로 바꿉니다. 실제 값을 출력하는 짧은 ApplicationRunner나 설정을 사용하는 서비스에 breakpoint를 두면 최종 바인딩 결과를 확인할 수 있습니다.

터미널 — 프로필과 환경 변수 적용

STUDY_LOG_DAILY_LIMIT_MINUTES=600 \
  ./mvnw -q spring-boot:run -Dspring-boot.run.profiles=local

Environment 확인 결과

환경 변수의 600이 YAML 기본값 480보다 우선하며 설정 검증 오류 없이 시작되어야 합니다.

값을 0으로 바꾸면 @Min(1) 검증 때문에 서버가 시작되지 않아야 합니다. 이 실패는 나쁜 입력을 받기 전에 잘못된 배포 설정을 차단했다는 뜻이므로, 정상 시작만큼 중요한 확인 결과입니다.

외부 값을 안전하게 모델링했으니 다음 장에서는 그 설정과 서비스를 컨테이너가 어떤 순서로 만들고 연결하는지 살펴봅니다.

외부 설정과 프로필 우선순위

설정 값도 검증 가능한 모델이어야 한다

타입 안전한 StudyLog 설정 만들기

프로필과 환경 변수의 최종 값을 비교한다

이 페이지의 목차