본문으로 건너뛰기
Advertisement

2.9 설정 바인딩 (@ConfigurationProperties)

application.yml의 값을 타입에 맞게 바인딩하고 검증하려면 @ConfigurationProperties를 사용합니다. @Value 여러 개보다 구조가 명확하고, IDE 자동완성·검증에 유리합니다.

작성 기준: Spring Boot 3.2.x

1. 기본 사용​

# application.yml
app:
  mail:
    host: smtp.example.com
    port: 587
  security:
    jwt-secret: my-secret
    token-validity: 3600
@Configuration
@ConfigurationProperties(prefix = "app")
@Validated
@Getter
@Setter
public class AppProperties {

    private final Mail mail = new Mail();
    private final Security security = new Security();

    @Getter
    @Setter
    public static class Mail {
        private String host = "localhost";
        private int port = 25;
    }

    @Getter
    @Setter
    public static class Security {
        @NotBlank
        private String jwtSecret;
        @Min(60)
        private long tokenValidity = 3600;
    }
}
  • prefix: yaml의 최상위 키 (app)
  • @Validated + Bean Validation으로 기동 시 검증 가능 (필수 값 누락 시 빌드 실패)

2. 스캔 활성화​

@EnableConfigurationProperties(AppProperties.class) 또는 해당 클래스를 @Component로 두면 빈으로 등록됩니다.
Spring Boot는 @ConfigurationProperties가 붙은 클래스를 자동 스캔하므로, 보통은 @Configuration만 있어도 됩니다.

3. 프로파일별 값​

# application-dev.yml
app:
  mail:
    host: mailhog
    port: 1025
---
# application-prod.yml
app:
  mail:
    host: ${MAIL_HOST}
    port: ${MAIL_PORT:587}
  • ${ENV_VAR}: 환경 변수
  • ${ENV_VAR:default}: 기본값

4. 생성자 바인딩 (불변)​

Spring Boot 2.2+에서는 생성자로 바인딩할 수 있어, final 필드로 불변 설정을 만들 수 있습니다.

@ConfigurationProperties(prefix = "app.mail")
@ConstructorBinding  // Boot 3.x에서는 단일 생성자 시 생략 가능
@Getter
public class MailProperties {

    private final String host;
    private final int port;

    public MailProperties(String host, int port) {
        this.host = host;
        this.port = port;
    }
}

5. Spring Boot 설정 파일 로딩 순서와 우선순위​

애플리케이션 설정(application.properties / application.yml)은 여러 위치에서 로드되고, 나중에 로드된 값이 먼저 로드된 값을 덮어씁니다. 같은 키가 여러 곳에 있으면 우선순위가 높은 쪽이 최종 적용됩니다.

5.1 설정 파일 검색 경로 (위에서 아래로 우선순위 낮음)​

Spring Boot는 아래 순서로 application.properties / application.yml (및 application-{profile}.properties 등)을 찾습니다. 숫자가 작을수록 우선순위가 높습니다.

순위경로비고
1현재 디렉터리의 /config 하위./config/application.yml
2현재 디렉터리./application.yml
3클래스패스의 /config 패키지classpath:/config/application.yml
4클래스패스 루트classpath:/application.yml (일반적으로 src/main/resources)
  • jar 실행 시: 현재 디렉터리·./config 가 classpath보다 우선하므로, 배포 경로에 application.yml 또는 config/application.yml을 두면 jar 안의 기본 설정을 덮어쓸 수 있습니다.

5.2 프로파일별 파일과 공통 파일​

  • application.yml: 공통. 프로파일 없이 로드.
  • application-{profile}.yml: 해당 프로파일이 활성화될 때 추가 로드. 예: application-dev.yml, application-prod.yml.

덮어쓰기 순서 (같은 키일 때 뒤에 나온 쪽이 이김):

  1. application.yml (공통)
  2. application-{profile}.yml (활성 프로파일)

즉 application-prod.yml의 값이 application.yml보다 우선합니다.

5.3 외부 설정 우선순위 (요약)​

Spring Boot 문서 기준, 동일 키에 대해 아래 순서로 우선순위가 높아집니다 (높은 것이 최종 적용).

  1. 커맨드 라인 인자 — --server.port=8081
  2. SPRING_APPLICATION_JSON (환경 변수/시스템 프로퍼티에 JSON)
  3. ServletConfig / ServletContext (웹 환경)
  4. JNDI
  5. Java 시스템 프로퍼티 — -Dserver.port=8081
  6. OS 환경 변수
  7. RandomValuePropertySource (random.*)
  8. jar 외부의 application-{profile}.yml (패키징된 jar 기준)
  9. jar 내부의 application-{profile}.yml
  10. jar 외부의 application.yml
  11. jar 내부의 application.yml
  12. @PropertySource
  13. 기본값 (SpringBootApplication 기본 등)

실무에서는 기본값은 jar 내부 application.yml, 환경별 덮어쓰기는 application-{profile}.yml 또는 환경 변수·커맨드 라인으로 두는 패턴이 많습니다.

5.4 정리​

  • 설정 경로: ./config/ > ./ > classpath:/config/ > classpath:/
  • 파일 종류: **application-{profile}.yml**이 **application.yml**보다 같은 키에 대해 우선.
  • 외부 덮어쓰기: 커맨드 라인·환경 변수가 파일보다 우선하므로, 비밀번호·포트 등은 배포 시 외부에서 주입할 수 있습니다.

6. List / Map​

app:
  allowed-hosts:
    - api.example.com
    - admin.example.com
  features:
    new-ui: true
    beta: false
private List<String> allowedHosts = new ArrayList<>();
private Map<String, Boolean> features = new HashMap<>();
팁

민감 정보는 환경 변수나 Vault로 주입하고, @ConfigurationProperties에서는 ${VAR}로 참조하는 방식을 권장합니다. 어떤 값이 최종 적용되는지 확인할 때는 위 5. 설정 파일 로딩 순서와 우선순위를 참고하세요.

Advertisement
Advertisement