[첫번째 프로젝트] 10. spring boot configuration processor

DAEILLIM·2024년 1월 22일

목록 보기

10/17

spring boot configuration processor

spring boot configuartion processor 에 대한 정리는 밸덩의 내용과 동일하다는 점을 참고하기 바랍니다.

https://www.baeldung.com/spring-boot-configuration-metadata

1. Spring Boot Configuration Processor

Spring Boot Configuration Processor는 Spring Boot 애플리케이션에서 @ConfigurationProperties 어노테이션을 사용할 때 도움을 주는 라이브러리입니다. @ConfigurationProperties를 사용하면 YAML 또는 Properties 파일과 같은 외부 구성 소스에서 속성을 읽어와서 Java 객체에 매핑할 수 있습니다. 이를 통해 손쉽게 구성 정보를 다룰 수 있습니다.

Spring Boot Configuration Processor는 이러한 구성 속성을 다루는 데 도움을 주는 메타데이터를 생성합니다. 이 메타데이터는 개발자가 구성 속성을 올바르게 사용하고, IDE에서 지원을 받을 수 있도록 도와줍니다. 또한 런타임 시에 유효성 검사를 수행하여 잘못된 구성 값이 있을 경우 경고를 표시할 수도 있습니다.

주로 spring-boot-configuration-processor 의존성을 프로젝트에 추가하여 사용합니다. 이 의존성을 추가하면 소스 코드 컴파일 시에 메타데이터가 생성되어 IDE에서 구성 속성을 쉽게 사용할 수 있게 됩니다.

예를 들어, 다음은 application.properties 파일에서 설정된 구성 속성을 사용하는 Java 클래스의 간단한 예제입니다:

@ConfigurationProperties(prefix = "example")
public class MyConfig {
    private String name;
    private int age;

    // getters and setters
}

이 클래스를 사용하는 다른 곳에서는 IDE에서 구성 속성의 자동 완성 및 문서화가 지원되어 더 편리하게 사용할 수 있습니다. Spring Boot Configuration Processor는 이러한 자동 완성 및 문서화를 가능하게 해주는 도구 중 하나입니다.

Spring Boot Configuration Processor의 소개에 대해 정리하면 다음과 같습니다.

Configuration 메타데이터를 처리하는데 도움을 주기 위한 도구이다.
프로퍼티의 속성을 수동으로 추적하기 까다롭고 오류가 발생하기 쉬운 대규모 프로젝트에 용이하다.
메타데이터 생성을 자동화함으로써 더 나은 코딩 관행을 장려하고 개발자 생산성을 향상시킨다.

1.1 Spring Boot Configuration Processor 사용 이유

우리는 보통 프로퍼티의 값을 설정할 때, 어떤 기능을 하는지, 기본 값이 있는지, 더이상 사용되지 않는지, 속성이 존재하는지조차 모르는 경우가 많다. Spring Boot Configuration Processor 를 통해 이러한 불편함을 해결할 수 있다.

1.2 IDE 의 자동 완성 (Auto-Completion in IDEs)

IDE 는 메타데이터를 제공받음으로써, 개발자에게 자동 완성 및 유효성 검사 기능을 제공할 수 있다.
구성정보 옵션이 설명, 유형 및 기본 값과 함께 IDE 에 표기되므로 개발자가 애플리케이션의 구성 옵션을 훨씬 쉽게 이해하고 사용 가능하다.

1.3 문서 생성 (Documentation Generation)

구성정보 프로퍼티에 대한 문서를 생성할 수 있다.
속성, 설명, 기본 값 등이 자동으로 문서화되어 코드의 유지보수 및 투명성을 높일 수 있다.

1.4 유효성 검사 및 타입 변환 (Validation and Type Conversion)

유효성 검사 규칙을 적용하고 사용자 지정 구성 유형에 대한 유형 변환을 처리할 수 있다.

2. Spring Boot Configuration Processor 사용

2.1 의존성 추가

Gradle을 사용하면 다음 예제와 같이 주석 프로세서 구성에서 종속성을 선언해야 합니다:

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

2.2 Configuration Properties 정의

@ConfigurationProperties 애노테이션을 꼭 사용해주어야 한다.
configuration processor 는 이 애노테이션이 붙은 클래스 및 메서드를 검색하여 configuration 메타데이터를 생성한다.

@Configuration
@ConfigurationProperties(prefix = "database")
public class DatabaseProperties {
    
    public static class Server {
    
        private String ip;
        private int port;

        // standard getters and setters
    }

    private String username;
    private String password;
    private Server server;

    // standard getters and setters
}

#Simple Properties
database.username=baeldung
database.password=password

2.3 Configuration Properties 테스트 작성

@RunWith(SpringRunner.class)
@SpringBootTest(classes = AnnotationProcessorApplication.class)
@TestPropertySource("classpath:databaseproperties-test.properties")
public class DatabasePropertiesIntegrationTest {

    @Autowired
    private DatabaseProperties databaseProperties;

    @Test
    public void whenSimplePropertyQueriedThenReturnsPropertyValue()
      throws Exception {
        Assert.assertEquals("Incorrectly bound Username property",
          "username", databaseProperties.getUsername());
        Assert.assertEquals("Incorrectly bound Password property",
          "password", databaseProperties.getPassword());
    }
}

2.3 프로젝트 컴파일 후 메타데이터 결과 보기

프로젝트를 빌드하면, 프로세서가 json 파일을 생성한다.
target/classes/META-INF/spring-configuration-metadata.json 경로에 해당 파일이 생긴다.

{
  "groups": [
    {
      "name": "database",
      "type": "com.example.autoconfiguration.annotationprocessor.DatabaseProperties",
      "sourceType": "com.example.autoconfiguration.annotationprocessor.DatabaseProperties"
    },
    {
      "name": "database.server",
      "type": "com.example.autoconfiguration.annotationprocessor.DatabaseProperties$Server",
      "sourceType": "com.example.autoconfiguration.annotationprocessor.DatabaseProperties",
      "sourceMethod": "getServer()"
    }
  ],
  "properties": [
    {
      "name": "database.password",
      "type": "java.lang.String",
      "sourceType": "com.example.autoconfiguration.annotationprocessor.DatabaseProperties"
    },
    {
      "name": "database.server.ip",
      "type": "java.lang.String",
      "sourceType": "com.example.autoconfiguration.annotationprocessor.DatabaseProperties$Server"
    },
    {
      "name": "database.server.port",
      "type": "java.lang.Integer",
      "sourceType": "com.example.autoconfiguration.annotationprocessor.DatabaseProperties$Server",
      "defaultValue": 0
    },
    {
      "name": "database.username",
      "type": "java.lang.String",
      "sourceType": "com.example.autoconfiguration.annotationprocessor.DatabaseProperties"
    }
  ],
  "hints": []
}

3. [심화] Configuration 메타데이터 정보 추가하기

첫번째, 서버에 JavaDoc 코멘트를 추가하겠습니다.
두번째,database.server.port 필드에 기본값을 부여하고 마지막으로 @Min 및 @Max 주석을 추가합니다.

public static class Server {

    /**
     * The IP of the database server
     */
    private String ip;

    /**
     * The Port of the database server.
     * The Default value is 443.
     * The allowed values are in the range 400-4000.
     */
    @Min(400)
    @Max(800)
    private int port = 443;

    // standard getters and setters
}

Spring-configuration-metadata.json 파일을 확인하면 다음과 같은 추가 정보가 반영됩니다:

{
  "groups": [
    {
      "name": "database",
      "type": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties"
    },
    {
      "name": "database.server",
      "type": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties$Server",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties",
      "sourceMethod": "getServer()"
    }
  ],
  "properties": [
    {
      "name": "database.password",
      "type": "java.lang.String",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties"
    },
    {
      "name": "database.server.ip",
      "type": "java.lang.String",
      "description": "The IP of the database server",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties$Server"
    },
    {
      "name": "database.server.port",
      "type": "java.lang.Integer",
      "description": "The Port of the database server. The Default value is 443.
        The allowed values are in the range 400-4000",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties$Server",
      "defaultValue": 443
    },
    {
      "name": "database.username",
      "type": "java.lang.String",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties"
    }
  ],
  "hints": []
}

database.server.ip 및 database.server.port 필드로 차이점을 확인할 수 있습니다. 실제로 추가 정보가 상당히 도움이 됩니다. 결과적으로 개발자와 IDE는 각 속성이 수행하는 작업을 훨씬 쉽게 이해할 수 있습니다.

3.1 메타데이터 형식 이해

JSON 메타데이터 파일을 자세히 살펴보고 그 구성 요소에 대해 살펴봅니다.

groups은 값 자체를 지정하지 않고 다른 속성을 그룹화하는 데 사용되는 상위 항목입니다. 예제에서는 데이터베이스 그룹을 사용했는데, 이것은 구성 속성의 접두사이기도 합니다. 또한 서버 그룹을 사용하여 내부 클래스를 통해 생성하고 IP 및 포트 속성을 그룹화했습니다.

속성은 값을 지정할 수 있는 구성 항목입니다. 이러한 속성은 .properties 또는 .yml 파일로 설정되며 위 예제에서 본 기본값 및 유효성 검사와 같은 추가 정보를 가질 수 있습니다.

힌트는 사용자가 속성 값을 설정하는 데 도움이 되는 추가 정보입니다. 예를 들어, 속성에 허용되는 값 집합이 있으면 각 속성이 수행하는 작업에 대한 설명을 제공할 수 있습니다. IDE는 이러한 힌트에 대해 자동 경쟁 도움말을 제공할 것입니다.

구성 메타데이터의 각 구성 요소에는 구성 속성을 더 자세히 설명하기 위한 고유한 속성이 있습니다.

4. IDE 사용하기

일단 셋업이 된 이후에는 개발자는 자동완성, 검증, 문서화 기능 등의 혜택을 볼 수 있다.

DAEILLIM

필기하고, 타이핑하고, 말하면서 읽고, 코딩하고, 눈으로 읽고 오감으로 공부하기

[첫번째 프로젝트] 10. spring boot configuration processor