5. @ConfigurationProperties 사용법

Spring/Spring Boot

5. @ConfigurationProperties 사용법

leek94 2024. 9. 22. 15:04

@ConfigurationProperties는 Spring Boot에서 사용되는 어노테이션으로, **프로퍼티 파일(application.properties 또는 application.yml)**에 정의된 설정 값을 자바 클래스의 필드에 자동으로 매핑하는 데 사용됩니다. 이를 통해 설정 파일의 값을 손쉽게 자바 객체로 관리하고, 여러 곳에서 재사용할 수 있습니다.

@ConfigurationProperties 사용법

프로퍼티 파일에 설정값 정의
Java 클래스에 @ConfigurationProperties 적용하여 프로퍼티를 매핑
Bean 등록을 통해 주입받아 사용

1. 프로퍼티 파일 설정

먼저, application.properties 또는 application.yml 파일에 설정 값을 정의합니다. 이 값들은 @ConfigurationProperties로 선언한 클래스에 매핑될 것입니다.

properties

# application.properties
myapp.server.host=localhost
myapp.server.port=8080
myapp.server.timeout=5000

혹은 application.yml 파일에서도 설정 가능합니다:

yaml

# application.yml
myapp:
  server:
    host: localhost
    port: 8080
    timeout: 5000

2. @ConfigurationProperties 어노테이션을 사용한 자바 클래스 작성

프로퍼티 파일에 설정된 값을 매핑할 클래스를 작성합니다. 이 클래스는 프로퍼티 파일에서 설정된 값을 담는 POJO(Plain Old Java Object)입니다.

prefix: @ConfigurationProperties(prefix = "myapp.server")로 시작하는 값을 필드에 매핑할 수 있습니다.
Setter 또는 Lombok 사용: Spring Boot는 @ConfigurationProperties로 필드에 값을 주입할 때, Setter 메서드 또는 Lombok을 통한 Getter/Setter를 사용합니다.

java

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

@Component
@ConfigurationProperties(prefix = "myapp.server")
public class ServerProperties {

    private String host;
    private int port;
    private int timeout;

    // Getter와 Setter 필요
    public String getHost() {
        return host;
    }

    public void setHost(String host) {
        this.host = host;
    }

    public int getPort() {
        return port;
    }

    public void setPort(int port) {
        this.port = port;
    }

    public int getTimeout() {
        return timeout;
    }

    public void setTimeout(int timeout) {
        this.timeout = timeout;
    }
}

여기서 @ConfigurationProperties(prefix = "myapp.server")는 프로퍼티 파일에서 myapp.server.host, myapp.server.port, myapp.server.timeout에 정의된 값을 각각 host, port, timeout 필드에 매핑해 줍니다.

3. 클래스를 Bean으로 등록하고 주입하여 사용

@Component 어노테이션을 통해 해당 클래스를 Spring Bean으로 등록한 후, 다른 클래스에서 이를 의존성 주입을 통해 사용합니다.

java

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class ServerService {

    private final ServerProperties serverProperties;

    @Autowired
    public ServerService(ServerProperties serverProperties) {
        this.serverProperties = serverProperties;
    }

    public void printServerConfig() {
        System.out.println("Host: " + serverProperties.getHost());
        System.out.println("Port: " + serverProperties.getPort());
        System.out.println("Timeout: " + serverProperties.getTimeout());
    }
}

위 예시에서 ServerService는 ServerProperties를 생성자 주입을 통해 받아서 사용할 수 있습니다. 이때 ServerProperties는 application.properties 또는 application.yml에 정의된 값을 자동으로 읽어와 주입됩니다.

4. 사용 시 주의 사항

Spring Boot의 버전: @ConfigurationProperties를 사용하려면 Spring Boot에서 spring-boot-configuration-processor 의존성이 필요합니다. 이 의존성은 Spring Boot 프로젝트에 기본적으로 포함되어 있으므로, 별도로 추가할 필요가 없습니다.
하지만 만약 Lombok을 사용 중이라면, @Data, @Getter, @Setter 등을 활용하기 위해 추가 설정이 필요할 수 있습니다.
Validation: Spring Boot는 @ConfigurationProperties에서 정의된 필드에 대한 검증을 지원합니다. 예를 들어, @Valid와 @NotNull 같은 검증 어노테이션을 사용하여 특정 값이 반드시 설정되어야 한다는 제약을 추가할 수 있습니다.

java

import javax.validation.constraints.NotNull;

@Component
@ConfigurationProperties(prefix = "myapp.server")
public class ServerProperties {

    @NotNull
    private String host;

    private int port;

    @NotNull
    private Integer timeout;

    // Getter와 Setter
}

이를 통해 설정 값에 대해 런타임 시점에서 오류를 감지하고 처리할 수 있습니다.

@ConfigurationProperties의 장점

구성 관리의 편리성: 여러 구성 요소를 명시적으로 관리할 필요 없이, 프로퍼티 파일에서 설정한 값을 하나의 자바 객체로 쉽게 매핑할 수 있습니다.
유연성: 설정 파일을 통해 외부에서 값을 조정할 수 있으므로, 코드 수정 없이 다양한 환경 설정에 대응할 수 있습니다. 예를 들어, 개발 환경과 운영 환경을 각각 다르게 설정할 수 있습니다.
타입 안정성: 프로퍼티 값을 자바 클래스에 매핑함으로써, 설정 값에 대해 **타입 안정성(type safety)**을 확보할 수 있습니다. 즉, 프로퍼티 값이 잘못된 타입일 경우 컴파일 시점에서 오류를 감지할 수 있습니다.
재사용성: 자바 클래스로 설정 값을 관리하기 때문에, 여러 클래스나 서비스에서 의존성 주입을 통해 해당 설정을 쉽게 재사용할 수 있습니다.

결론

@ConfigurationProperties는 Spring Boot에서 프로퍼티 파일에 정의된 설정 값을 자바 클래스의 필드로 자동 매핑해 주는 매우 강력한 도구입니다.
이를 사용하면 프로퍼티 파일에 분산된 설정 값들을 쉽게 관리하고, 코드에서 설정 값을 안전하게 사용할 수 있습니다.
재사용성, 타입 안정성, 유연한 구성 관리 등의 장점을 제공하므로, 복잡한 설정 관리가 필요한 애플리케이션에서 유용하게 활용할 수 있습니다.