[Spring] DI에서 외부 설정 주입하기: @ConfigurationProperties 활용

🌱 Spring DI에서 외부 설정 주입하기: @ConfigurationProperties 활용 가이드

안녕하세요! Spring (특히 Spring Boot) 애플리케이션을 개발하다 보면, 데이터베이스 접속 정보, API 키, 서버 도메인 등 다양한 설정 값들을 코드와 분리하여 관리해야 할 필요성을 느끼게 됩니다. 개발, 테스트, 운영 환경마다 다른 설정을 사용해야 하거나, 민감한 정보를 코드에 직접 노출시키지 않기 위해서죠.

Spring은 이러한 요구사항을 만족시키기 위해 application.properties 또는 application.yml 같은 외부 설정 파일을 활용하는 강력하고 편리한 방법을 제공합니다. 오늘은 그중에서도 타입-세이프(Type-Safe) 하게 외부 설정 값을 자바 객체로 바인딩하여 사용하는 @ConfigurationProperties 어노테이션에 대해 예제 코드와 함께 자세히 알아보겠습니다.

왜 외부 설정 파일을 사용할까요?

코드 안에 설정 값을 직접 하드코딩하면 다음과 같은 문제들이 발생할 수 있습니다.

• 환경별 설정 변경의 어려움: 개발 환경과 운영 환경의 DB 정보나 서버 주소가 다른 경우, 매번 코드를 수정하고 다시 빌드/배포해야 합니다.
• 보안 문제: API 키나 비밀번호 같은 민감한 정보가 코드에 그대로 노출될 수 있습니다.
• 유지보수 어려움: 설정 값이 코드 곳곳에 흩어져 있으면 관리하기 어렵고 변경 시 누락될 가능성이 있습니다.

외부 설정 파일을 사용하면 이러한 문제들을 해결하고, 설정을 중앙에서 관리하며 애플리케이션의 유연성과 보안성을 높일 수 있습니다.

 

Spring의 해결책: @ConfigurationProperties

Spring Boot는 application.properties 나 application.yml 파일을 클래스패스 루트(src/main/resources)에 두면 자동으로 로드하여 사용합니다. 하지만 단순히 @Value 어노테이션을 사용하여 개별 속성을 하나씩 주입받는 방식은 속성이 많아질수록 번거롭고 타입 안정성이 떨어질 수 있습니다.

@ConfigurationProperties는 관련 있는 설정 값들을 하나의 자바 객체(POJO) 로 묶어서 관리하게 해주는 훨씬 세련된 방법입니다.

핵심 단계:

1. 외부 설정 파일 정의 (application.properties)
2. 설정 값을 담을 자바 클래스 생성 및 @ConfigurationProperties 적용 (MyProperties.java)
3. 해당 Properties 클래스를 빈으로 등록하고 바인딩 활성화 (@EnableConfigurationProperties in Main.java)
4. 설정 객체를 주입받아 사용 (@Autowired in Main.java)

이제 예제 코드를 통해 각 단계를 자세히 살펴보겠습니다.

 

📌  예시 코드로 배우는 설정 주입 방법

🔸 (1) application.properties 파일 작성

먼저, src/main/resources 폴더 아래에 application.properties 파일을 만들고 설정 값들을 정의합니다. 여기서 중요한 것은 관련 있는 속성들을 공통된 접두사(prefix) 로 시작하게 만드는 것입니다. 예제에서는 mysite를 접두사로 사용했습니다.

 

# src/main/resources/application.properties

mysite.domain=www.ABC.com
mysite.email=admin@ABC.com

 

🔸 (2) 설정 정보를 담을 클래스 작성  (MyProperties.java)

 

다음으로, application.properties 파일의 mysite 접두사를 가진 속성들을 담을 자바 클래스(MyProperties)를 생성합니다.

package com.yourpackage; // 패키지 경로는 실제 프로젝트에 맞게 수정하세요.

import org.springframework.boot.context.properties.ConfigurationProperties;

// @ConfigurationProperties(prefix="mysite"): "mysite" 접두사를 가진 속성들을 이 클래스의 필드에 바인딩합니다.
@ConfigurationProperties(prefix = "mysite")
public class MyProperties {
    private String domain; // mysite.domain 값과 매핑됩니다.
    private String email;  // mysite.email 값과 매핑됩니다.

    // Spring이 값을 바인딩하기 위해 Getter와 Setter가 필요합니다.
    public String getDomain() {
        return domain;
    }

    public void setDomain(String domain) {
        this.domain = domain;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }

    // (toString() 메서드 등은 필요에 따라 추가)
}

• @ConfigurationProperties(prefix = "mysite"): 이 어노테이션이 핵심입니다! Spring Boot에게 "application.properties (또는 다른 외부 설정 소스)에서 mysite. 으로 시작하는 속성들을 찾아서 이 클래스의 필드에 자동으로 채워 넣어줘!" 라고 지시합니다.
• 필드 이름 매핑: Spring Boot는 유연한 바인딩 규칙을 따릅니다. 일반적으로 mysite.some-property 또는 mysite.someProperty는 someProperty 필드와 매핑됩니다. (예: mysite.domain -> domain 필드)
• Getter/Setter 필수: Spring이 리플렉션을 통해 값을 주입하려면 해당 필드에 대한 public Getter와 Setter가 필요합니다. (Lombok의 @Getter, @Setter 또는 @Data를 사용해도 됩니다.)

🔸 (3) 메인 애플리케이션 작성

@ConfigurationProperties 어노테이션을 붙인 클래스가 실제로 동작(속성 값 바인딩)하고 스프링 빈으로 등록되게 하려면, 이 기능을 활성화하는 과정이 필요합니다. @EnableConfigurationProperties 어노테이션을 사용하여 이 작업을 수행합니다. 보통 @Configuration 어노테이션이 붙은 설정 클래스나 메인 애플리케이션 클래스에 추가합니다.

 

package com.yourpackage;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.ApplicationContext;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;

import java.util.Arrays;

// @EnableConfigurationProperties({MyProperties.class}): MyProperties 클래스에 대한 @ConfigurationProperties 처리를 활성화하고,
// MyProperties를 스프링 빈으로 등록합니다.
@EnableConfigurationProperties({MyProperties.class})
@Configuration // 이 클래스가 설정 정보를 포함함을 알림
@ComponentScan // @Component 등을 스캔하여 빈으로 등록 (예제에서는 MyProperties 외 다른 빈은 없지만 일반적으로 사용)
public class Main implements CommandLineRunner { // CommandLineRunner: 애플리케이션 시작 후 특정 코드 실행

    @Autowired
    MyProperties prop; // 4단계: 설정 객체 주입

    @Autowired
    ApplicationContext ac; // ApplicationContext 주입 (빈 목록 확인용)

    // CommandLineRunner의 run 메서드: 애플리케이션이 시작되고 DI가 완료된 후 실행됨
    @Override
    public void run(String... args) throws Exception {
        // 등록된 빈 목록 확인 (디버깅 목적)
        String[] beanDefinitionNames = ac.getBeanDefinitionNames();
        Arrays.sort(beanDefinitionNames);
        Arrays.stream(beanDefinitionNames)
                .filter(b -> !b.startsWith("org")) // Spring 내부 빈 제외
                .forEach(System.out::println); // 빈 이름 출력

        // 주입받은 MyProperties 객체를 통해 설정 값 사용
        System.out.println("prop.getDomain() = " + prop.getDomain());
        System.out.println("prop.getEmail() = " + prop.getEmail());
    }

    public static void main(String[] args) {
        // Spring Boot 애플리케이션 실행
        ApplicationContext context = SpringApplication.run(Main.class, args);
    }
}

• @EnableConfigurationProperties({MyProperties.class}): 이 어노테이션이 매우 중요합니다. Spring에게 MyProperties 클래스에 정의된 @ConfigurationProperties 설정을 처리하도록 지시하고, 동시에 MyProperties 자체를 스프링 컨테이너에 빈으로 등록해줍니다. 이제 다른 컴포넌트에서 @Autowired를 통해 주입받을 수 있게 됩니다.

🔸 (4) 설정 객체 주입 및 사용 

이제 @EnableConfigurationProperties 덕분에 빈으로 등록되고 외부 설정 값으로 채워진 MyProperties 객체를 필요한 곳에서 주입받아 사용하면 됩니다.

Java

 

    // ... Main 클래스 내부 ...

    @Autowired // 스프링 컨테이너가 관리하는 MyProperties 빈을 자동으로 주입받음
    MyProperties prop;

    @Override
    public void run(String... args) throws Exception {
        // 주입받은 prop 객체의 getter 메서드를 통해 설정 값에 접근
        System.out.println("prop.getDomain() = " + prop.getDomain()); // 출력: prop.getDomain() = www.fastcampus.com
        System.out.println("prop.getEmail() = " + prop.getEmail());   // 출력: prop.getEmail() = admin@fascampus.com
    }

• @Autowired MyProperties prop;: Spring이 관리하는 MyProperties 빈을 찾아 prop 필드에 주입해줍니다. 이 시점의 prop 객체는 이미 application.properties 파일의 값들로 채워져 있습니다.
• CommandLineRunner 사용 이유: main 메서드는 static 메서드이므로 @Autowired 필드(prop)를 직접 사용할 수 없습니다. CommandLineRunner 인터페이스를 구현하고 run 메서드를 오버라이드하면, Spring 애플리케이션이 시작되고 모든 빈의 생성과 의존성 주입이 완료된 후에 run 메서드가 호출됩니다. 따라서 run 메서드 내에서는 안전하게 @Autowired된 인스턴스 변수(prop)에 접근할 수 있습니다.

@ConfigurationProperties의 장점

• 타입 안전성 (Type Safety): 문자열 기반의 @Value와 달리, 정의된 클래스의 타입(String, int, List 등)으로 값을 받아오므로 타입 오류를 컴파일 시점 또는 IDE에서 미리 발견하기 쉽습니다.
• 코드 가독성 및 구조화: 관련된 설정 값들이 하나의 클래스로 묶여있어 관리가 용이하고 코드가 깔끔해집니다.
• IDE 지원: @ConfigurationProperties 클래스는 IDE의 자동 완성 및 검증 기능을 활용하기 좋습니다. (application.properties에서 키 자동완성 등)
• 유효성 검사 (Validation): JSR-303(Bean Validation) 어노테이션(@NotNull, @Email, @Max 등)을 Properties 클래스 필드에 추가하여 설정 값의 유효성을 검증할 수 있습니다. (예제에는 없지만 매우 유용한 기능)
• 유연한 바인딩: some-property, someProperty, SOME_PROPERTY 등 다양한 형식의 프로퍼티 키를 동일한 필드(someProperty)에 바인딩할 수 있습니다.

결론

Spring (특히 Spring Boot)에서 외부 설정 값을 관리하는 가장 권장되는 방법 중 하나는 @ConfigurationProperties를 사용하는 것입니다. 이를 통해 설정 값들을 타입-세이프한 자바 객체로 쉽게 바인딩하고, 코드와 설정을 명확하게 분리하여 애플리케이션의 유연성, 가독성, 유지보수성을 크게 향상시킬 수 있습니다.