Spring Boot 프로파일(Profile) 완벽 가이드: 개발/운영 환경 1초 만에 전환하기

안녕하세요. IT 기술 블로거입니다.

개발자라면 누구나 한 번쯤 이런 경험이 있을 것입니다.
“로컬에서는 잘 돌아갔는데, 서버에 올리니까 DB 연결 에러가 나요!”

대부분의 원인은 환경(Environment) 차이입니다. 로컬 PC, 개발 서버(Dev), 운영 서버(Prod)는 사용하는 DB 주소, 로그 레벨, 외부 API 키 값 등이 모두 다릅니다. 이 모든 설정을 하나의 파일에서 주석 처리 해가며 관리하고 계신가요?

Spring Boot는 프로파일(Profile)이라는 강력한 기능을 통해 이 문제를 우아하게 해결합니다. 오늘은 프로파일의 개념부터 활성화 방법, 그리고 실무적인 그룹핑 전략까지 심도 있게 다뤄보겠습니다.

1. 프로파일(Profile)이란 무엇인가?

프로파일은 “런타임 환경에 따라 선택적으로 활성화되는 빈(Bean)이나 설정(Configuration)의 그룹”입니다.

쉽게 말해, “나는 지금 dev 모드야”라고 선언하면 dev 태그가 붙은 설정들만 읽어오고, “나는 prod 모드야”라고 하면 prod 설정들만 읽어오는 식입니다. 이를 통해 코드 수정이나 재빌드 없이, 실행 시점의 파라미터만으로 애플리케이션의 동작 방식을 바꿀 수 있습니다.

2. 프로파일 정의 및 파일 구성

프로파일별 설정 파일은 application-{profile}.yml 형식을 따릅니다.

• application.yml: 모든 환경에 적용되는 기본(Default) 설정
• application-local.yml: 로컬 개발용
• application-dev.yml: 개발 서버용
• application-prod.yml: 운영 서버용

application.yml (기본)

spring:
  application:
    name: my-commerce-app
  profiles:
    active: local # 기본적으로 local 프로파일 활성화

application-dev.yml (개발)

server:
  port: 8080
logging:
  level:
    root: DEBUG # 개발 중에는 상세 로그 필요
spring:
  datasource:
    url: jdbc:mysql://dev-db:3306/db

application-prod.yml (운영)

server:
  port: 80
logging:
  level:
    root: INFO # 운영 중에는 중요 로그만
spring:
  datasource:
    url: jdbc:mysql://prod-db:3306/db

3. 프로파일 활성화 방법 (Activation)

작성한 프로파일을 적용하는 방법은 다양합니다. 우선순위에 따라 덮어써지기도 하므로 잘 알아두어야 합니다.

3.1. application.yml에서 설정

가장 기본적인 방법입니다.

spring:
  profiles:
    active: dev

3.2. JAR 실행 시 커맨드 라인 인자 (가장 많이 사용)

배포 스크립트나 도커 컨테이너 실행 시 주로 사용합니다.

java -jar my-app.jar --spring.profiles.active=prod

3.3. JVM 시스템 프로퍼티

java -Dspring.profiles.active=prod -jar my-app.jar

3.4. OS 환경 변수

클라우드 환경(AWS, Kubernetes)에서 유용합니다.

export SPRING_PROFILES_ACTIVE=prod
./mvnw spring-boot:run

4. 코드 수준에서의 프로파일 제어 (@Profile)

설정 파일뿐만 아니라, 자바 코드(Bean) 자체를 특정 프로파일에서만 띄울 수도 있습니다.

@Configuration
public class PaymentConfig {

    // 'dev' 프로파일일 때만 빈으로 등록됨
    @Bean
    @Profile("dev")
    public PaymentService mockPaymentService() {
        return new MockPaymentService(); // 가짜 결제 모듈
    }

    // 'prod' 프로파일일 때만 빈으로 등록됨
    @Bean
    @Profile("prod")
    public PaymentService realPaymentService() {
        return new RealPaymentService(); // 실제 PG사 연동 모듈
    }
}

이렇게 하면 개발 중에는 실제 결제가 일어나지 않도록 안전하게 테스트하고, 운영 배포 시에는 자동으로 실제 결제 모듈이 동작하게 됩니다. if-else 문으로 환경을 체크하는 지저분한 코드를 싹 없앨 수 있죠.

5. 고급: 프로파일 그룹 (Profile Groups)

Spring Boot 2.4부터 도입된 기능으로, 하나의 프로파일이 여러 하위 프로파일을 포함하도록 그룹핑할 수 있습니다.

예를 들어 prod 환경이면서 클라우드 aws 설정을 같이 로드해야 한다면?

application.yml

spring:
  profiles:
    group:
      production: # 'production' 프로파일을 활성화하면
        - prod      # prod 프로파일과
        - aws       # aws 프로파일,
        - common    # common 프로파일이 모두 함께 활성화됨

이제 --spring.profiles.active=production 하나만 입력해도 prod, aws, common 설정이 모두 로드됩니다. 설정 관리의 복잡도를 획기적으로 낮춰주는 꿀기능입니다.

결론

프로파일은 Spring Boot가 제공하는 가장 유연하고 강력한 기능 중 하나입니다.
단순히 DB 주소를 바꾸는 것을 넘어, 애플리케이션의 동작 모드 자체를 환경에 맞게 스위칭하는 핵심 메커니즘입니다.

1. 환경별로 application-{profile}.yml 파일을 분리하세요.
2. @Profile 어노테이션을 적극 활용해 테스트와 운영 로직을 분리하세요.
3. 배포 시에는 환경 변수나 커맨드 라인 인자로 프로파일을 주입하세요.

이 세 가지만 기억해도 여러분의 배포 파이프라인은 훨씬 안정적이고 우아해질 것입니다.

다음 글에서는 이러한 프로파일 기능을 활용해 “개발/운영 환경을 분리하는 가장 쉽고 확실한 전략”에 대해 더 구체적인 시나리오와 함께 알아보겠습니다.