@ConfigurationProperties

@ConfigurationProperties는 Spring Framework에서 외부 설정을 Java 객체에 매핑하기 위해 사용하는 어노테이션입니다. 이 어노테이션을 사용하면 프로퍼티 파일(application.properties, application.yml 등) 또는 환경 변수에서 값을 읽어와 자동으로 Java 객체에 매핑할 수 있습니다. 이를 통해 설정값을 객체지향적으로 다룰 수 있게 되어, 설정값의 변경이나 추가가 간편해집니다.

1. @ConfigurationProperties 기본 개념

@ConfigurationProperties는 주로 외부 설정을 객체에 바인딩하기 위해 사용됩니다. 이 어노테이션을 사용하면, 프로퍼티 파일(application.properties 또는 application.yml)에 설정된 값들이 자동으로 Java 객체에 주입됩니다. 이 방식은 설정 값들이 많을 때 유용하며, 코드 내에서 설정을 타입 안전하게 다룰 수 있습니다.

2. 사용 예시

application.properties 파일

app.name=MyApplication
app.version=1.0.0
app.description=This is an application.

Java 클래스에 @ConfigurationProperties 적용

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

@Component
@ConfigurationProperties(prefix = "app")
public class AppConfig {
    private String name;
    private String version;
    private String description;

    // Getters and Setters
    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getVersion() {
        return version;
    }

    public void setVersion(String version) {
        this.version = version;
    }

    public String getDescription() {
        return description;
    }

    public void setDescription(String description) {
        this.description = description;
    }
}

@ConfigurationProperties 동작 설명

• @ConfigurationProperties(prefix = "app"): application.properties 파일에 있는 app.*로 시작하는 설정 값들을 AppConfig 클래스의 필드에 자동으로 매핑합니다.
• 이 클래스는 @Component로 등록되어, Spring의 IoC 컨테이너에 의해 자동으로 관리됩니다. (또는 @Configuration을 사용하여 명시적으로 설정할 수도 있습니다.)

사용법

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class AppController {

    @Autowired
    private AppConfig appConfig;

    @GetMapping("/app-info")
    public String getAppInfo() {
        return "App Name: " + appConfig.getName() +
               ", Version: " + appConfig.getVersion() +
               ", Description: " + appConfig.getDescription();
    }
}

위 코드를 통해 application.properties에 설정된 값들이 자동으로 AppConfig 클래스의 필드에 매핑되어, AppController에서 해당 값을 반환할 수 있습니다.

3. YAML 파일 예시

YAML 파일에서 설정을 읽는 경우에도 동일하게 @ConfigurationProperties가 동작합니다.

application.yml 파일

app:
  name: MyApplication
  version: 1.0.0
  description: This is an application.

Java 클래스

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

@Component
@ConfigurationProperties(prefix = "app")
public class AppConfig {
    private String name;
    private String version;
    private String description;

    // Getters and Setters
}

4. @ConfigurationProperties와 @Value의 차이점

	@Value	@ConfigurationProperties
주요 용도	단일 프로퍼티 값을 주입	여러 프로퍼티를 객체에 바인딩
매핑 범위	한 번에 하나의 프로퍼티 값	여러 프로퍼티 값
타입 안전성	불가능 (String으로만 주입됨)	가능 (타입 안전한 매핑)
사용 방법	@Value("${property.name}")	@ConfigurationProperties(prefix = "property")
적용 대상	간단한 설정 값	복잡한 설정 객체

@Value는 간단한 값들을 주입할 때 유용하지만, 여러 값을 다루거나 복잡한 객체를 매핑할 때는 @ConfigurationProperties가 더 효율적입니다.

5. @EnableConfigurationProperties를 통한 명시적 활성화

• @EnableConfigurationProperties 어노테이션을 사용하여, @ConfigurationProperties를 사용할 클래스를 명시적으로 활성화할 수 있습니다.
• 이 어노테이션을 사용하면, Spring Boot 애플리케이션에서 외부 설정 값을 Java Bean으로 관리할 수 있게 됩니다.

예시

import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableConfigurationProperties(AppConfig.class)
public class AppConfigConfig {
    // AppConfig를 활성화
}

6. 리스트 및 맵 처리

@ConfigurationProperties는 리스트나 맵 같은 복잡한 자료형도 지원합니다.

YAML 예시 (리스트와 맵)

app:
  servers:
    - server1.example.com
    - server2.example.com
  properties:
    version: "1.0.0"
    name: "MyApp"

Java 클래스 (리스트와 맵 처리)

import java.util.List;
import java.util.Map;

@Component
@ConfigurationProperties(prefix = "app")
public class AppConfig {
    private List<String> servers;
    private Map<String, String> properties;

    // Getters and Setters
}

7. 결론

@ConfigurationProperties는 외부 설정 파일(application.properties, application.yml 등)에서 Java 객체로 값을 바인딩할 수 있도록 도와주는 Spring Boot 어노테이션입니다. 여러 설정 값을 객체로 매핑하고, 객체지향적으로 다룰 수 있게 해주는 기능을 제공하며, 타입 안전성과 유지 관리 용이성을 개선할 수 있습니다.