📄 Spring 환경변수 관리: @Value vs @ConfigurationProperties

Spring 애플리케이션에서 외부 설정(properties, yml) 값은 필수적임. 이 값들을 코드에 주입하는 대표적인 방법으로 @Value와 @ConfigurationProperties가 있음. 둘의 차이를 명확히 이해하고 상황에 맞게 사용하는 것이 중요함.

💡 핵심 개념

@Value: 개별 값의 단순 주입

@Value는 SpEL(Spring Expression Language)을 이용해 프로퍼티 값을 하나씩 필드나 생성자 파라미터에 주입하는 가장 기본적인 방식임.

• 장점: 몇 개 안 되는 간단한 값을 주입할 때 가장 빠르고 직관적임.
• 단점:
  • 분산된 관리: 프로퍼티가 많아지면 @Value 어노테이션이 여러 클래스에 흩어져 추적과 관리가 어려워짐.
  • 타입 불안정성: 런타임에 값을 주입하므로, 잘못된 타입의 값이 들어와도 컴파일 시점에 알 수 없음.
  • 오타에 취약: 프로퍼티 키를 문자열("${...}")로 작성하여 오타가 발생해도 찾기 어려움.
  • 복잡한 구조 한계: List나 Map 같은 복잡한 자료구조나 계층적 데이터 바인딩이 불편함.

@ConfigurationProperties: 구조화된 설정 객체 바인딩

@ConfigurationProperties는 특정 접두사(prefix)를 가진 프로퍼티들을 하나의 객체(POJO/Record)에 통째로 바인딩하는, 현대 Spring Boot에서 가장 권장되는 방식임.

• 장점:
  • 강력한 타입 안정성: 컴파일 시점에 대상 클래스의 필드 타입으로 변환되므로 타입 오류를 미리 방지할 수 있음.
  • 구조화 및 캡슐화: 관련 설정들이 하나의 클래스로 묶여, 계층 구조를 그대로 반영하므로 가독성과 유지보수성이 극대화됨.
  • 불변성(Immutability) 확보: 생성자 바인딩을 통해 final 필드를 가진 불변 객체로 설정을 관리할 수 있음. (Setter가 필요 없어짐)
  • 강력한 유효성 검사: @Validated와 JSR-303(@NotEmpty, @Max 등) 어노테이션으로 각 프로퍼티 값의 유효성을 선언적으로 검증할 수 있음.
  • IDE 지원: spring-boot-configuration-processor 의존성을 추가하면 application.yml 작성 시 키 자동완성 및 문서보기를 지원함.

※ 등록 및 사용 방법

@ConfigurationProperties가 붙은 클래스를 Spring 컨테이너가 인식하게 하는 방법은 주로 두 가지임.

1. @Component 사용: 설정 클래스에 @Component를 붙여 컴포넌트 스캔 대상으로 만듦. 가장 간단하지만, 설정 클래스가 다른 비즈니스 로직 컴포넌트와 섞이는 단점이 있음.
2. @EnableConfigurationProperties 사용: @Configuration이 붙은 설정 클래스나 메인 애플리케이션 클래스에 @EnableConfigurationProperties(MyProperties.class)를 명시하여 등록함. 설정의 책임과 역할을 명확히 분리할 수 있어 이 방식이 더 권장됨.

📊 @Value vs @ConfigurationProperties 비교

구분	@Value	@ConfigurationProperties
바인딩 단위	개별 프로퍼티 (낱개)	프로퍼티 그룹 (객체)
컴파일 시점 타입 안정성	낮음 (런타임 주입)	높음 (객체 필드 타입으로 변환)
구조적 바인딩	부적합	적합 (계층 구조를 중첩 클래스로 매핑)
불변성(Immutability)	불가능	가능 (생성자 바인딩)
유효성 검사	직접 구현 필요	@Validated로 선언적 지원
IDE 자동완성	미지원	지원 (의존성 추가 시)
권장 사용처	단일 값, 임시/테스트 설정	애플리케이션의 핵심, 복잡/계층적 설정

🧠 코드 예시

계층적인 application.yml 예제

API 서버의 인증 정보, CORS 허용 목록 등 복합적인 설정을 관리하는 예제.

# application.yml
server:
  port: 8080

# API 관련 설정 그룹
api:
  # 중첩 구조 (auth)
  auth:
    jwt-secret-key: "a-very-long-and-secure-secret-key-for-development"
    token-expires-in: 3600 # 1시간 (초 단위)
  # List 형태의 데이터
  cors:
    allowed-origins:
      - "http://localhost:3000"
      - "https://my-frontend.com"

---
spring:
  config:
    activate:
      on-profile: prod

api:
  auth:
    # 운영 환경에서는 외부 환경변수나 Secret Manager를 통해 주입
    jwt-secret-key: ${API_JWT_SECRET_KEY}
    token-expires-in: 86400 # 24시간
  cors:
    allowed-origins:
      - "https://my-real-service.com"

@Value 사용 예시 (권장하지 않는 방식)

프로퍼티가 늘어날수록 생성자가 길어지고 관리 포인트가 분산됨.

@Service
public class SimpleAuthService {

    private final String jwtSecretKey;
    private final List<String> allowedOrigins;

    public SimpleAuthService(
            @Value("${api.auth.jwt-secret-key}") String jwtSecretKey,
            @Value("${api.cors.allowed-origins}") List<String> allowedOrigins) {
        this.jwtSecretKey = jwtSecretKey;
        this.allowedOrigins = allowedOrigins;
    }
    // ...
}

@ConfigurationProperties 사용 예시 (권장 방식)

1. 불변(Immutable) 설정 프로퍼티 클래스 작성 (with 생성자 바인딩)
Java 17 이상에서는 record를 사용하면 더 간결하게 작성할 수 있음.

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;
import javax.validation.constraints.NotEmpty;
import javax.validation.constraints.Positive;
import java.util.List;

@ConfigurationProperties(prefix = "api")
@Validated // 필드 유효성 검사를 활성화
public class ApiProperties {

    @NotEmpty // jakarta.validation.constraints.NotEmpty
    private final Auth auth;
    @NotEmpty
    private final Cors cors;

    // 생성자 바인딩: Spring Boot가 이 생성자를 통해 yml 값을 주입함 (Setter 불필요)
    public ApiProperties(Auth auth, Cors cors) {
        this.auth = auth;
        this.cors = cors;
    }

    // --- Getters ---
    public Auth getAuth() { return auth; }
    public Cors getCors() { return cors; }

    // --- 중첩된 설정을 위한 정적(static) 내부 클래스 ---
    public static class Auth {
        @NotEmpty
        private final String jwtSecretKey;
        @Positive
        private final int tokenExpiresIn;

        public Auth(String jwtSecretKey, int tokenExpiresIn) {
            this.jwtSecretKey = jwtSecretKey;
            this.tokenExpiresIn = tokenExpiresIn;
        }

        public String getJwtSecretKey() { return jwtSecretKey; }
        public int getTokenExpiresIn() { return tokenExpiresIn; }
    }
    
    public static class Cors {
        @NotEmpty
        private final List<String> allowedOrigins;
        
        public Cors(List<String> allowedOrigins) {
            this.allowedOrigins = allowedOrigins;
        }
        
        public List<String> getAllowedOrigins() { return allowedOrigins; }
    }
}

2. 메인 애플리케이션에 프로퍼티 클래스 등록

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

@SpringBootApplication
@EnableConfigurationProperties(ApiProperties.class) // 작성한 프로퍼티 클래스를 빈으로 등록
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

3. 프로퍼티 객체를 주입받아 사용

@Service
public class AdvancedAuthService {

    private final ApiProperties apiProperties;

    // 생성자를 통해 ApiProperties 객체를 통째로 주입받음
    public AdvancedAuthService(ApiProperties apiProperties) {
        this.apiProperties = apiProperties;
    }

    public void issueToken() {
        String secretKey = apiProperties.getAuth().getJwtSecretKey();
        int expirySeconds = apiProperties.getAuth().getTokenExpiresIn();
        System.out.println("Using Secret Key (first 5 chars): " + secretKey.substring(0, 5) + "...");
        System.out.println("Token expires in: " + expirySeconds + " seconds");
        System.out.println("Allowed Origins: " + apiProperties.getCors().getAllowedOrigins());
    }
}

🔍 더 깊이 파고들기

• @ConfigurationPropertiesScan: Spring Boot 2.2부터 추가된 어노테이션. @EnableConfigurationProperties 대신 메인 클래스에 @ConfigurationPropertiesScan을 붙이면 지정된 패키지 내의 @ConfigurationProperties를 자동으로 스캔하여 등록해줌. 훨씬 편리함.
• Spring Boot Configuration Processor: build.gradle에 annotationProcessor "org.springframework.boot:spring-boot-configuration-processor" 의존성을 추가하면, IDE가 yml/properties 파일에서 api.auth.jwt-secret-key 같은 키를 자동완성하고, Javadoc 주석을 툴팁으로 보여줘 개발 생산성을 극대화함.
• Externalized Configuration 우선순위: Spring Boot는 다양한 소스에서 설정을 로드하며 명확한 우선순위를 가짐. (e.g., 커맨드라인 인자 > OS 환경변수 > application.yml 외부 파일 > application.yml 내부 파일). 이 순서를 이해하면 배포 환경에서 설정 충돌 문제를 해결하는 데 큰 도움이 됨.