🚀 Spring Boot 3.x에서 @ConfigurationProperties 활용법 완벽 가이드

🎯 서론

💡 Spring Boot 애플리케이션에서 **설정 값(Configuration Properties)**을 다루는 방법에는 여러 가지가 있지만,
✅ **타입 세이프한 바인딩(Type-safe Binding)**과 유지보수성을 높이기 위한 강력한 방법이 바로 @ConfigurationProperties입니다.

📢 기존의 @Value 방식과 비교해 더 직관적이고 재사용성이 높은 설정 관리가 가능하며,
Spring Boot 3.x에서는 더욱 개선된 기능을 제공합니다!

🔥 이번 포스팅에서는 Spring Boot 3.x에서 @ConfigurationProperties를 활용하는 방법을 초보자도 쉽게 따라 할 수 있도록 단계별로 설명합니다.

---

📌 1. @Value vs @ConfigurationProperties 차이점

🔎 Spring Boot에서 설정 값을 주입하는 기본적인 방법은 @Value를 사용하는 것입니다.
하지만 설정 값이 많아지면 유지보수가 어려워지므로 @ConfigurationProperties를 사용하는 것이 더 효율적입니다.

🔽 기존 @Value 사용 방식

@Component
public class AppConfig {
    @Value("${app.name}")
    private String appName;

    @Value("${app.version}")
    private String appVersion;
}

⚠ 문제점:

• 개별적으로 @Value를 사용해야 해서 속성이 많아지면 유지보수 어려움
• 기본값을 설정하거나 복잡한 구조(객체, 리스트) 바인딩 불가능

---

✅ @ConfigurationProperties 활용 방식

@ConfigurationProperties(prefix = "app")
public record AppConfig(String name, String version) { }

📢 장점:
✅ 객체 단위로 설정 관리 가능
✅ 설정 값이 많아져도 유지보수 용이
✅ 타입 세이프 바인딩 (유효성 검사 가능!)
✅ YAML, properties 파일 모두 지원

---

🏗 2. @ConfigurationProperties 설정하기 (실습 예제)

🔧 Spring Boot 3.x 프로젝트에서 @ConfigurationProperties를 적용하는 단계는 다음과 같습니다.

✅ 1) spring-boot-configuration-processor 의존성 추가

💻 build.gradle 파일에 아래의 플러그인을 추가하세요.

dependencies {
    annotationProcessor 'org.springframework.boot:spring-boot-configuration-processor'
}

✅ 이 플러그인은 IDE에서 자동 완성 기능을 지원하여 설정값을 쉽게 관리할 수 있도록 도와줍니다.

---

✅ 2) 설정 파일(application.yml) 작성

📌 application.yml에서 설정 값 추가

app:
  name: "My Spring Boot App"
  version: "3.1.2"

---

✅ 3) @ConfigurationProperties 클래스 생성

📌 Spring Boot 3.x에서는 @ConfigurationProperties를 record를 활용하여 더욱 간결하게 작성 가능!

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

@ConfigurationProperties(prefix = "app")
public record AppConfig(String name, String version) { }

📢 Spring Boot 3.x에서는 record를 활용하여 더 깔끔하게 설정 클래스를 정의할 수 있습니다!

---

✅ 4) @EnableConfigurationProperties 활성화

💡 @ConfigurationProperties를 활성화하려면 Spring Boot 3.x에서는 @EnableConfigurationProperties를 추가해야 합니다.

📌 MainApplication.java

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

@SpringBootApplication
@EnableConfigurationProperties(AppConfig.class)
public class MainApplication {
    public static void main(String[] args) {
        SpringApplication.run(MainApplication.class, args);
    }
}

✅ 이제 설정 파일(application.yml)에 있는 값이 AppConfig 클래스에 자동으로 주입됩니다!

---

🔥 3. @ConfigurationProperties 값 사용하기

이제 컨트롤러에서 @ConfigurationProperties 값을 활용하는 방법을 알아보겠습니다.

📌 AppController.java

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/config")
public class AppController {
    private final AppConfig appConfig;

    public AppController(AppConfig appConfig) {
        this.appConfig = appConfig;
    }

    @GetMapping
    public String getAppInfo() {
        return "🚀 " + appConfig.name() + " - Version: " + appConfig.version();
    }
}

 

✅ 결과 확인:

curl http://localhost:8080/config

 

📢 출력 예시

🚀 My Spring Boot App - Version: 3.1.2

🎉 설정값이 정상적으로 바인딩되어 컨트롤러에서 사용할 수 있습니다!

---

🛠 4. @ConfigurationProperties로 리스트(List) & 맵(Map) 바인딩

🔍 @ConfigurationProperties를 사용하면 리스트(List)나 맵(Map) 형태의 데이터를 쉽게 매핑할 수 있습니다.

✅ 1) 리스트(List) 바인딩

📌 application.yml

app:
  servers:
    - name: "Server A"
      url: "https://server-a.com"
    - name: "Server B"
      url: "https://server-b.com"

 

📌 AppConfig.java

@ConfigurationProperties(prefix = "app")
public record AppConfig(List<Server> servers) { }

public record Server(String name, String url) { }

 

✅ 컨트롤러에서 사용하기

@GetMapping("/servers")
public List<Server> getServers() {
    return appConfig.servers();
}

 

📢 출력 예시

[
  { "name": "Server A", "url": "https://server-a.com" },
  { "name": "Server B", "url": "https://server-b.com" }
]

---

📊 5. @ConfigurationProperties에서 유효성 검사 추가하기

🔍 Spring Boot 3.x에서는 유효성 검사를 쉽게 추가할 수 있습니다.
예를 들어, 앱 이름이 비어 있으면 예외를 발생시키는 설정을 추가할 수 있습니다.

📌 의존성 추가 (build.gradle)

implementation 'org.springframework.boot:spring-boot-starter-validation'

 

📌 유효성 검사 적용 (AppConfig.java)

import jakarta.validation.constraints.NotBlank;

@ConfigurationProperties(prefix = "app")
public record AppConfig(@NotBlank String name, String version) { }

 

✅ 잘못된 설정 시 예외 발생

app:
  name: ""   # ❌ 빈 값이므로 예외 발생

 

📢 오류 메시지

Validation failed for @ConfigurationProperties class: name must not be blank

🎉 유효성 검사를 추가하면 더욱 안전하게 설정 값을 관리할 수 있습니다!

---

🎯 결론

✅ @ConfigurationProperties는 Spring Boot 3.x에서 설정 값을 안전하게 관리할 수 있는 강력한 방법입니다.
✅ @Value보다 객체 단위로 바인딩이 가능하여 유지보수가 용이합니다.
✅ 리스트(List) 및 맵(Map) 데이터도 바인딩 가능하여 유연한 설정 관리가 가능합니다.
✅ 유효성 검사(Validation)도 간단히 추가 가능하여 안정성을 높일 수 있습니다.

💡 지금 바로 프로젝트에서 @ConfigurationProperties를 활용해 보세요! 🚀