AI 지식 / / 2025. 10. 10. 06:44

[Spring Boot 번역] Properties and Configuration

출처: https://docs.spring.io/spring-boot/4.0-SNAPSHOT/how-to/properties-and-configuration.html

이 섹션에서는 속성 설정 및 읽기, 구성 설정 및 Spring Boot 애플리케이션과의 상호작용에 대한 주제를 다룹니다.

빌드 시점에 속성 자동 확장하기

프로젝트의 빌드 구성에도 지정된 일부 속성을 하드코딩하는 대신, 기존 빌드 구성을 사용하여 자동으로 확장할 수 있습니다. 이는 Maven과 Gradle 모두에서 가능합니다.

Maven을 사용한 자동 속성 확장

Maven 프로젝트에서 리소스 필터링을 사용하여 속성을 자동으로 확장할 수 있습니다. spring-boot-starter-parent를 사용하는 경우, 다음 예제와 같이 @..@ 플레이스홀더를 사용하여 Maven '프로젝트 속성'을 참조할 수 있습니다:

Properties

app.encoding=@project.build.sourceEncoding@
app.java.version=@java.version@

YAML

app:
  encoding: "@project.build.sourceEncoding@"
  java:
    version: "@java.version@"

프로덕션 구성만 이런 방식으로 필터링됩니다(즉, src/test/resources에는 필터링이 적용되지 않습니다).

addResources 플래그를 활성화하면 spring-boot:run goal이 src/main/resources를 클래스패스에 직접 추가할 수 있습니다(핫 리로딩 목적). 이렇게 하면 리소스 필터링과 이 기능을 우회하게 됩니다. 대신 exec:java goal을 사용하거나 플러그인의 구성을 사용자 정의할 수 있습니다. 자세한 내용은 플러그인 사용 페이지를 참조하세요.

starter parent를 사용하지 않는 경우, pom.xml의 <build/> 요소 내부에 다음 요소를 포함해야 합니다:

<resources>
    <resource>
        <directory>src/main/resources</directory>
        <filtering>true</filtering>
    </resource>
</resources>

또한 <plugins/> 내부에 다음 요소를 포함해야 합니다:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-resources-plugin</artifactId>
    <version>2.7</version>
    <configuration>
        <delimiters>
            <delimiter>@</delimiter>
        </delimiters>
        <useDefaultDelimiters>false</useDefaultDelimiters>
    </configuration>
</plugin>

구성에서 표준 Spring 플레이스홀더(예: ${placeholder})를 사용하는 경우 useDefaultDelimiters 속성이 중요합니다. 해당 속성이 false로 설정되지 않으면 빌드 시 확장될 수 있습니다.

Gradle을 사용한 자동 속성 확장

다음 예제와 같이 Java 플러그인의 processResources 작업을 구성하여 Gradle 프로젝트의 속성을 자동으로 확장할 수 있습니다:

tasks.named('processResources') {
    expand(project.properties)
}

그런 다음 다음 예제와 같이 플레이스홀더를 사용하여 Gradle 프로젝트의 속성을 참조할 수 있습니다:

Properties

app.name=${name}
app.description=${description}

YAML

app:
  name: "${name}"
  description: "${description}"

Gradle의 expand 메서드는 Groovy의 SimpleTemplateEngine을 사용하여 ${..} 토큰을 변환합니다. ${..} 스타일은 Spring 자체의 속성 플레이스홀더 메커니즘과 충돌합니다. 자동 확장과 함께 Spring 속성 플레이스홀더를 사용하려면 다음과 같이 Spring 속성 플레이스홀더를 이스케이프하세요: \${..}.

SpringApplication의 구성 외부화하기

SpringApplication에는 bean 속성 setter가 있으므로 애플리케이션을 생성할 때 Java API를 사용하여 동작을 수정할 수 있습니다. 또는 spring.main.*에 속성을 설정하여 구성을 외부화할 수 있습니다. 예를 들어, application.properties에 다음 설정이 있을 수 있습니다:

Properties

spring.main.web-application-type=none
spring.main.banner-mode=off

YAML

spring:
  main:
    web-application-type: "none"
    banner-mode: "off"

그러면 시작 시 Spring Boot 배너가 출력되지 않고, 애플리케이션은 임베디드 웹 서버를 시작하지 않습니다.

외부 구성에 정의된 속성은 Java API로 지정된 값을 재정의하고 대체하지만, primary sources는 주목할 만한 예외입니다. Primary sources는 SpringApplication 생성자에 제공되는 것입니다:

Java

import org.springframework.boot.Banner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication application = new SpringApplication(MyApplication.class);
        application.setBannerMode(Banner.Mode.OFF);
        application.run(args);
    }

}

Kotlin

import org.springframework.boot.Banner
import org.springframework.boot.SpringApplication
import org.springframework.boot.autoconfigure.SpringBootApplication

@SpringBootApplication
object MyApplication {

    @JvmStatic
    fun main(args: Array<String>) {
        val application = SpringApplication(MyApplication::class.java)
        application.setBannerMode(Banner.Mode.OFF)
        application.run(*args)
    }

}

또는 SpringApplicationBuilder의 sources(…​) 메서드에 제공되는 것입니다:

Java

import org.springframework.boot.Banner;
import org.springframework.boot.builder.SpringApplicationBuilder;

public class MyApplication {

    public static void main(String[] args) {
        new SpringApplicationBuilder()
            .bannerMode(Banner.Mode.OFF)
            .sources(MyApplication.class)
            .run(args);
    }

}

Kotlin

import org.springframework.boot.Banner
import org.springframework.boot.builder.SpringApplicationBuilder

object MyApplication {

    @JvmStatic
    fun main(args: Array<String>) {
        SpringApplicationBuilder()
            .bannerMode(Banner.Mode.OFF)
            .sources(MyApplication::class.java)
            .run(*args)
    }

}

위의 예제에서 다음 구성이 있다고 가정하면:

Properties

spring.main.sources=com.example.MyDatabaseConfig,com.example.MyJmsConfig
spring.main.banner-mode=console

YAML

spring:
  main:
    sources: "com.example.MyDatabaseConfig,com.example.MyJmsConfig"
    banner-mode: "console"

실제 애플리케이션은 배너를 표시하고(구성에 의해 재정의됨) ApplicationContext에 대해 세 개의 소스를 사용합니다. 애플리케이션 소스는 다음과 같습니다:

  • MyApplication (코드에서)
  • MyDatabaseConfig (외부 구성에서)
  • MyJmsConfig (외부 구성에서)

애플리케이션의 외부 속성 위치 변경하기

기본적으로 다양한 소스의 속성은 정의된 순서로 Spring Environment에 추가됩니다(정확한 순서는 "Spring Boot Features" 섹션의 Externalized Configuration 참조).

동작을 변경하기 위해 다음 시스템 속성(또는 환경 변수)을 제공할 수도 있습니다:

  • spring.config.name (SPRING_CONFIG_NAME): 파일 이름의 루트로 기본값은 application입니다.
  • spring.config.location (SPRING_CONFIG_LOCATION): 로드할 파일(예: 클래스패스 리소스 또는 URL). 이 문서에 대해 별도의 Environment 속성 소스가 설정되며 시스템 속성, 환경 변수 또는 명령줄로 재정의할 수 있습니다.

환경에서 무엇을 설정하든 Spring Boot는 항상 위에서 설명한 대로 application.properties를 로드합니다. 기본적으로 YAML을 사용하는 경우 '.yaml' 및 '.yml' 확장자를 가진 파일도 목록에 추가됩니다.

로드되는 파일에 대한 자세한 정보를 원하면 org.springframework.boot.context.config의 로깅 수준을 설정하여 trace로 설정할 수 있습니다.

'짧은' 명령줄 인수 사용하기

일부 사람들은 명령줄에서 구성 속성을 설정할 때 --server.port=9000 대신 --port=9000을 사용하는 것을 선호합니다. 다음 예제와 같이 application.properties에서 플레이스홀더를 사용하여 이 동작을 활성화할 수 있습니다:

Properties

server.port=${port:8080}

YAML

server:
  port: "${port:8080}"

spring-boot-starter-parent POM에서 상속하는 경우, maven-resources-plugins의 기본 필터 토큰이 ${*}에서 @로 변경되었습니다(즉, ${maven.token} 대신 @maven.token@). Spring 스타일 플레이스홀더와의 충돌을 방지하기 위함입니다. application.properties에 대해 Maven 필터링을 직접 활성화한 경우 기본 필터 토큰을 다른 구분 기호를 사용하도록 변경할 수도 있습니다.

이 특정 경우, 포트 바인딩은 Heroku 또는 Cloud Foundry와 같은 PaaS 환경에서 작동합니다. 이 두 플랫폼에서는 PORT 환경 변수가 자동으로 설정되며 Spring은 Environment 속성의 대문자 동의어에 바인딩할 수 있습니다.

외부 속성에 YAML 사용하기

YAML은 JSON의 상위 집합이며, 따라서 다음 예제와 같이 계층적 형식으로 외부 속성을 저장하기에 편리한 구문입니다:

spring:
  application:
    name: "cruncher"
  datasource:
    driver-class-name: "com.mysql.jdbc.Driver"
    url: "jdbc:mysql://localhost/test"
server:
  port: 9000

application.yaml이라는 파일을 생성하고 클래스패스의 루트에 넣으세요. 그런 다음 의존성에 snakeyaml을 추가하세요(Maven 좌표 org.yaml:snakeyaml, spring-boot-starter를 사용하는 경우 이미 포함되어 있음). YAML 파일은 Java Map<String,Object>(JSON 객체와 같음)로 파싱되고, Spring Boot는 맵을 평탄화하여 Java의 Properties 파일에 익숙한 많은 사람들이 사용하는 것처럼 한 수준 깊이이고 마침표로 구분된 키를 갖도록 합니다.

앞의 예제 YAML은 다음 application.properties 파일에 해당합니다:

spring.application.name=cruncher
spring.datasource.driver-class-name=com.mysql.jdbc.Driver
spring.datasource.url=jdbc:mysql://localhost/test
server.port=9000

YAML에 대한 자세한 내용은 "Spring Boot Features" 섹션의 Working With YAML 참조하세요.

Active Spring Profiles 설정하기

Spring Environment에는 이에 대한 API가 있지만, 일반적으로 시스템 속성(spring.profiles.active) 또는 OS 환경 변수(SPRING_PROFILES_ACTIVE)를 설정합니다. 또한 다음과 같이 -D 인수를 사용하여 애플리케이션을 시작할 수 있습니다(main 클래스 또는 jar 아카이브 앞에 넣어야 함):

$ java -jar -Dspring.profiles.active=production demo-0.0.1-SNAPSHOT.jar

Spring Boot에서는 다음 예제와 같이 application.properties에서 active profile을 설정할 수도 있습니다:

Properties

spring.profiles.active=production

YAML

spring:
  profiles:
    active: "production"

이 방식으로 설정된 값은 시스템 속성 또는 환경 변수 설정으로 대체되지만 SpringApplicationBuilder.profiles() 메서드로는 대체되지 않습니다. 따라서 후자의 Java API를 사용하여 기본값을 변경하지 않고 프로파일을 보강할 수 있습니다.

자세한 내용은 "Spring Boot Features" 섹션의 Profiles 참조하세요.

기본 프로파일 이름 설정하기

기본 프로파일은 활성 프로파일이 없을 때 활성화되는 프로파일입니다. 기본적으로 기본 프로파일의 이름은 default이지만, 시스템 속성(spring.profiles.default) 또는 OS 환경 변수(SPRING_PROFILES_DEFAULT)를 사용하여 변경할 수 있습니다.

Spring Boot에서는 다음 예제와 같이 application.properties에서 기본 프로파일 이름을 설정할 수도 있습니다:

Properties

spring.profiles.default=dev

YAML

spring:
  profiles:
    default: "dev"

자세한 내용은 "Spring Boot Features" 섹션의 Profiles 참조하세요.

환경에 따라 구성 변경하기

Spring Boot는 활성 프로파일을 기반으로 조건부로 활성화할 수 있는 다중 문서 YAML 및 Properties 파일을 지원합니다(자세한 내용은 Working With Multi-Document Files 참조).

문서에 spring.config.activate.on-profile 키가 포함되어 있으면 프로파일 값(쉼표로 구분된 프로파일 목록 또는 프로파일 표현식)이 Spring Environment.acceptsProfiles() 메서드에 전달됩니다. 프로파일 표현식이 일치하면 해당 문서가 최종 병합에 포함됩니다(그렇지 않으면 포함되지 않음). 다음 예제를 참조하세요:

Properties

server.port=9000
#---
spring.config.activate.on-profile=development
server.port=9001
#---
spring.config.activate.on-profile=production
server.port=0

YAML

server:
  port: 9000
---
spring:
  config:
    activate:
      on-profile: "development"
server:
  port: 9001
---
spring:
  config:
    activate:
      on-profile: "production"
server:
  port: 0

앞의 예제에서 기본 포트는 9000입니다. 그러나 'development'라는 Spring 프로파일이 활성화되면 포트는 9001입니다. 'production'이 활성화되면 포트는 0입니다.

문서는 발견되는 순서대로 병합됩니다. 나중 값이 이전 값을 재정의합니다.

외부 속성에 대한 내장 옵션 검색하기

Spring Boot는 런타임에 application.properties(또는 YAML 파일 및 기타 위치)의 외부 속성을 애플리케이션에 바인딩합니다. 지원되는 모든 속성의 완전한 목록은 한 곳에 없습니다(기술적으로 불가능함). 클래스패스의 추가 jar 파일에서 기여할 수 있기 때문입니다.

Actuator 기능이 있는 실행 중인 애플리케이션에는 @ConfigurationProperties를 통해 사용 가능한 모든 바인딩되고 바인딩 가능한 속성을 보여주는 configprops 엔드포인트가 있습니다.

부록에는 Spring Boot에서 지원하는 가장 일반적인 속성 목록이 있는 application.properties 예제가 포함되어 있습니다. 최종 목록은 @ConfigurationProperties 및 @Value 어노테이션과 Binder의 가끔 사용에 대한 소스 코드를 검색하여 얻을 수 있습니다. 속성 로드의 정확한 순서에 대한 자세한 내용은 Externalized Configuration을 참조하세요.

반응형
저작자표시 (새창열림)
  • 네이버 블로그 공유
  • 네이버 밴드 공유
  • 페이스북 공유
  • 카카오스토리 공유
AI 지식 관련 글
글 더보기

티스토리툴바