SpringBoot 커스텀 프로퍼티에 대한 문서와 자동완성 ※ Spring Configuration Processor

외부설정 문서화

 

 

yml 혹은 properties 파일에 프로퍼티 설정시 SpringBoot에 이미 정의되어 있는 document랑 자동완성을 확인할 수 있다.

 

개발자가 커스텀한 값들에 대해서도 문서랑 자동완성ㅇ을 지원하는 방법에 대해 알아보자.

 

Spring Configuration Processor란?

application.properties, application.yml 파일 등에 넣는 커스텀 설정의 자동 완성, 도움말 등을 지원해주는 도구이다.

 

실습

환경

Spring Boot 3.2.0

Gradle 8.2

 

라이브러리 의존성 추가

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

 

Properties 객체 정의

@Getter
@ConfigurationProperties(prefix = "database")
@RequiredArgsConstructor
public class DatabaseProperties {
    /** 제 키 예요. */
    private final Integer height;
}

 

@Configuration
public class DatabaseConfig {

    private final KwcProperties kwcProperties;

    @Autowired
    public DatabaseConfig(KwcProperties kwcProperties) {
        this.kwcProperties = kwcProperties;
    }

 

프로퍼티 객체와 해당 프로퍼티를 실제로 사용하는 설정 클래스를 따로 작성하는데, 

프로퍼티 객체에는 @ConfigurationProperties만들 달아주고 설정 클래스에는 @Configuration만 달아주어야 한다. 자세한 내용은 바로 아래에 있는 'Properties 객체 생성시 주의할점'을 확인하면 된다.

 

gradle의 clean -> build후 커스텀 프로퍼티를 확인해보면 document를 확인할 수 있다.

 

Properties 객체 생성시 주의할점

@Configuration
@ConfigurationProperties(prefix = "database")
@RequiredArgsConstructor
public class DatabaseProperties {
    /** 제 키 예요. */
    private final Integer height;
}

위와 같이 정의하면 아래와 같은 오류가 발생한다. (빌드는 돌아간다.)

 

Annotated with @ConstructorBinding but defined as Spring component

 

이유는 다음과 같다.

1. @ConfigurationProperties를 사용하면 기본적으로 @ConstructorBinding을 사용하게 된다 (생성자 바인딩)

2. @ConstructorBinding과 @Configuration이 같이 붙어 있을 경우 에러가 발생한다.

 

스프링에서 @Configuration이 붙어 있는 클래스를 빈으로 관리한다.

그러나 @ConstructorBinding이 붙어 있는 경우, 클래스는 생성자를 통해 외부 property를 바인딩 해줘야 한다.

즉, 외부 바인딩의 경우는 빈으로 등록하지 않아도 되는데 빈으로 등록하라고 하니 스프링 입장에선 어떻게 클래스를 다뤄야 할지 모호해진다.

 

 

Properties 객체 생성시 주의할점2

Description:

Failed to bind properties under 'kwc' to com.tech.Interview.KwcProperties:

    Reason: java.lang.IllegalStateException: Unable to create instance for com.tech.Interview.KwcProperties

Action:

Update your application's configuration

 

아무리 해도 안되서 찾아보니 SpringBoot 3.2부터 발생하는 에러였다.

https://github.com/spring-projects/spring-framework/wiki/Upgrading-to-Spring-Framework-6.x#parameter-name-retention

 

SpringBoot 3.2 전까지는 바이트코드를 파싱해서 매개변수 이름을 추론하려고 시도했다. 하지만 스프링 부트 3.2 부터는 이런 시도를 하지 않는다고 한다.

 

Build, Execution, Deployment -> Build Tools -> Gradle에서 IntelliJ IDEA -> Gradle로 변경한다.

Gradle이 컴파일 시점에 해당 옵션을 자동으로 적용해준다.

 

Properties 스캔

// @EnableConfigurationProperties({KwcProperties.class})
@ConfigurationPropertiesScan
@SpringBootApplication
public class SampleApplication {

    public static void main(String[] args) {
        SpringApplication.run(SampleApplication.class, args);
    }

}

 

@EnableConfigurationProperties({KwcProperties.class}) 혹은 @ConfigurationPropertiesScan를 @SpringBootApplication이 달린 클래스에 달아주면 된다.

자동완성

 

커스텀 프로퍼티에 추천값을 세팅할 수 있다.

 

resources - META-INF 하위에 additional-spring-configuration-metadata.json를 만들어 준다.

 

{
  "properties": [
    {
      "name": "kwc.height",
      "type": "java.lang.Integer"
    }
  ],
  "hints": [
    {
      "name": "kwc.height",
      "values": [
        {
          "value": 160,
          "description": "작은 키"
        },
        {
          "value": 170,
          "description": "중간 키"
        },
        {
          "value": 180,
          "description": "큰 키"
        }
      ]
    }
  ]
}

 

json 파일의 내용을 위와 같이 채워준다.

 

tasks.named('compileJava') {
    inputs.files(tasks.named('processResources'))
}

additional-spring-configuration-metadata.json 파일을 사용하는 경우 gradle에 옵션을 추가해야 한다.

 

gradle 새로 고침 후 clean - build를 해보자.

 

document 와 자동 추천이 완성되었다.

 

결론

팀원들에게 커스텀 프로퍼티에 대한 가이드를 제공해야 할때 활용하면 좋을 것 같다.

 

 

참고

https://fastcampus.co.kr/

한 번에 끝내는 Spring 완.전.판 초격차 패키지 Online. 김은호 강사님

 

https://velog.io/@bahar-j/Annotated-with-ConstructorBinding-but-defined-as-Spring-component-%ED%95%B4%EA%B2%B0

https://multifrontgarden.tistory.com/307

https://colabear754.tistory.com/201

https://guui-dev-lee.tistory.com/7

https://www.inflearn.com/questions/1138421/%ED%98%84%EC%9E%AC-springboot-3-2-1-%EB%B6%80%ED%84%B0-configurationproperties-%EB%A5%BC-%EC%82%AC%EC%9A%A9%ED%95%9C-%EC%84%A4%EC%A0%95%EA%B0%92-%EB%B0%94%EC%9D%B8%EB%94%A9%EC%97%90-%EC%9D%B4%EC%8A%88%EA%B0%80-%EC%9E%88%EB%8A%94%EA%B2%83-%EA%B0%99%EC%8A%B5%EB%8B%88%EB%8B%A4