Spring Boot 프로파일과 환경별 설정 관리

소개

애플리케이션은 개발 환경, 테스트 환경, 운영 환경에서 서로 다른 설정을 필요로 한다. Spring Boot의 프로파일(Profile)은 환경별 설정을 깔끔하게 관리하는 표준 방법이다. 이 글은 초보자도 이해하기 쉬운 예제와 함께 프로파일의 기본 개념, 파일 배치, 활성화 방법, @Profile을 이용한 빈 분리, 우선순위 규칙, 운영 시 유의점을 설명한다.

프로파일 기본 개념

프로파일은 환경을 구분하는 이름표다. 특정 프로파일이 활성화되면 해당 프로파일 전용 설정 파일이나 빈이 적용된다. 예를 들어 dev, test, prod 같은 이름을 사용한다. 프로파일을 사용하면 코드 변경 없이 설정만으로 환경을切替할 수 있다.

대표 사용 사례

• 데이터베이스 연결 정보 분리
• 외부 API 엔드포인트 분리
• 로깅 레벨 환경별 조정
• 특정 환경에서만 동작하는 빈 등록

설정 파일 구조와 예제

Spring Boot는 application.properties 또는 application.yml을 기본으로 사용한다. 환경별 파일은 application-{profile}.properties 또는 application-{profile}.yml 형태로 둔다. 활성화된 프로파일 파일이 기본 파일을 덮어쓴다.

기본 설정 예시 (application.properties)

spring.application.name=sample-app
server.port=8080
# 기본 데이터소스 설정(공통)
spring.datasource.username=common_user
spring.datasource.password=common_pass

개발 환경 예시 (application-dev.properties)

spring.profiles=dev
server.port=8081
spring.datasource.url=jdbc:h2:mem:devdb
spring.datasource.username=dev_user
spring.datasource.password=dev_pass
logging.level.root=DEBUG

application.yml에서 프로파일 분리 예

spring:
  profiles:
    active: dev
---
spring:
  profiles: dev
  datasource:
    url: jdbc:h2:mem:devdb
    username: dev_user
    password: dev_pass

프로파일 활성화 방법

프로파일은 여러 방법으로 활성화할 수 있다. 우선순위에 따라 외부 설정이 내부 설정을 덮어쓴다. 대표적인 활성화 방법은 다음과 같다.

• JVM 옵션: -Dspring.profiles.active=dev
• 환경 변수: SPRING_PROFILES_ACTIVE=dev
• application.properties 또는 application.yml에 spring.profiles.active 설정
• SpringApplication.setAdditionalProfiles(...) 또는 SpringApplicationBuilder를 통한 프로그래밍적 설정

# JVM 옵션 예
java -jar -Dspring.profiles.active=dev app.jar

# 환경 변수 예 (Linux)
export SPRING_PROFILES_ACTIVE=dev
java -jar app.jar

@Profile을 이용한 빈 분리

설정 파일뿐 아니라 자바 빈 등록도 프로파일에 따라 분리할 수 있다. @Profile 애노테이션을 사용하면 특정 프로파일에서만 빈이 등록된다. 테스트용 목(Mock) 빈이나 개발 전용 구성에 유용하다.

@org.springframework.context.annotation.Configuration
@org.springframework.context.annotation.Profile("dev")
public class DevConfig {
    @org.springframework.context.annotation.Bean
    public String devBean() {
        return "dev-bean";
    }
}

@org.springframework.context.annotation.Configuration
@org.springframework.context.annotation.Profile("prod")
public class ProdConfig {
    @org.springframework.context.annotation.Bean
    public String prodBean() {
        return "prod-bean";
    }
}

설정 우선순위와 병합 규칙

Spring Boot는 여러 소스의 설정을 병합한다. 우선순위가 높은 쪽이 낮은 쪽을 덮어쓴다. 일반적인 우선순위 예시는 다음과 같다.

• 명령행 인수
• SPRING_APPLICATION_JSON 환경 변수
• 운영체제 환경 변수
• application.properties/application.yml (외부 위치)
• application-{profile}.properties
• application.properties (클래스패스)

따라서 운영 환경에서 민감한 값은 외부 환경 변수나 암호화된 비밀 관리 시스템으로 분리하는 것이 안전하다.

실무 권장 사항

• 민감 정보는 절대 소스 저장소에 두지 않는다. 환경 변수나 시크릿 매니저 사용을 권장한다.
• 프로파일 이름은 명확하게(dev, staging, prod 등) 통일한다.
• 공통 설정은 application.properties에 두고, 환경별 차이는 application-{profile}.properties에 둔다.
• 프로파일별로 다른 빈을 만들 때는 테스트로 빈이 의도치 않게 등록되는지 확인한다.
• CI/CD 파이프라인에서 프로파일 활성화 전략을 문서화한다.

문제 해결 포인트

프로파일이 기대대로 적용되지 않을 때 확인할 항목.

• 실행 시 활성 프로파일이 정확히 설정되었는지 확인(-D 또는 환경 변수)
• application-{profile}.properties 파일명이 정확한지 확인
• 빈이 등록되지 않는 경우 @Profile 값과 활성화된 프로파일 일치 여부 확인
• 설정 우선순위로 인해 덮어쓰기가 발생했는지 로그와 설정 값을 비교

요약

Spring Boot 프로파일은 환경별 설정 관리를 단순화한다. application-{profile}.properties 또는 YAML 분리, @Profile로 빈 제어, 다양한 활성화 방법을 조합하면 환경 전환을 유연하게 처리할 수 있다. 민감 정보는 외부로 분리하고 우선순위를 이해한 상태에서 설정을 구성하면 운영 안정성이 높아진다.