Spring Profile로 환경별 설정 관리하기 – 개발자라면 꼭 알아야 할 환경 분리 전략

대부분의 Spring Boot 프로젝트는 개발(dev), 운영(prod), 테스트(test) 등 환경에 따라 DB 접속 정보, API 키, 로깅 레벨, 보안 설정 등이 달라집니다. 이러한 설정을 하나의 코드베이스 안에서 깔끔하게 분리하고 유지하려면 Spring Profile 기능을 반드시 이해하고 있어야 합니다.

Spring Profile의 개념과 설정 방법, 실무에서의 활용 팁까지 정리해보겠습니다.

 

---

1. Spring Profile이란?

Spring Profile은 빈(Bean) 등록이나 설정 파일 로딩을 조건부로 수행할 수 있도록 도와주는 기능입니다. 즉, dev, test, prod 같은 프로파일을 정의하고, 실행 시점에 어떤 프로파일을 활성화할지 지정하면 그에 맞는 설정만 적용되도록 구성할 수 있습니다.

이 기능을 사용하면 코드 수정 없이, 설정만으로도 다양한 환경을 유연하게 대응할 수 있습니다.

 

---

2. application.properties vs application-{profile}.yml

Spring Boot는 기본적으로 application.properties 또는 application.yml 파일을 통해 설정을 로딩합니다. 여기에 프로파일을 붙이면 환경별로 구분된 설정을 따로 관리할 수 있습니다.

# 기본 설정
application.yml

# 개발 환경 설정
application-dev.yml

# 운영 환경 설정
application-prod.yml

실행 시 --spring.profiles.active=dev 로 지정하면, application.yml + application-dev.yml이 합쳐져 로딩됩니다.

 

---

3. profile 설정 방법

3-1. VM 옵션으로 설정 (가장 일반적)

-Dspring.profiles.active=dev

3-2. application.yml 내부에서 설정

spring:
  profiles:
    active: dev

단, 이 방법은 jar 배포 이후 바꾸기 어렵기 때문에 운영 환경에서는 외부 설정 파일 또는 시스템 환경변수로 설정하는 걸 권장합니다.

3-3. 환경변수로 설정 (Docker/K8s에서 자주 사용)

SPRING_PROFILES_ACTIVE=prod

3-4. application.yml 내부 분기 (profiles include)

spring:
  profiles:
    group:
      dev: [common, local-db]
      prod: [common, rds-db]

복수의 profile을 그룹화해서 재사용할 수 있습니다. Spring Boot 2.4 이상에서 지원합니다.

 

---

4. @Profile 어노테이션으로 Bean 조건부 등록

Profile은 설정 파일뿐만 아니라, @Component나 @Configuration에도 사용할 수 있습니다.

@Profile("dev")
@Service
public class LocalEmailSender implements EmailSender {
    ...
}

@Profile("prod")
@Service
public class SmtpEmailSender implements EmailSender {
    ...
}

이렇게 하면 실행 중인 프로파일에 따라 다른 구현체가 자동으로 주입됩니다.

 

---

5. 실무 팁 및 주의사항

• application.yml은 공통 설정만 포함하고, 환경별 설정은 별도 분리하세요.
• 배포 자동화 시 profile 설정 누락으로 인한 사고가 많습니다. CI/CD 파이프라인에서 명확히 지정하세요.
• profile 명칭은 dev/test/stage/prod처럼 팀 내 컨벤션을 정해두고 일관성 있게 사용하세요.
• 운영 환경 정보(DB 주소, API 키 등)는 절대 Git에 커밋하지 마세요. 외부 설정파일 or Parameter Store 활용 추천
•  

---

6. 설정을 잘 나눠야 운영이 편하다

Spring Profile은 단순히 설정 파일을 나누는 도구가 아닙니다. 실행 환경에 따라 코드를 바꾸지 않고도 다른 구성과 동작을 할 수 있도록 만들어주는 스프링의 강력한 환경 추상화 수단입니다.

잘 구성된 Profile 전략은 유지보수를 훨씬 더 쉽게 해주며, 배포 사고를 줄이고 팀 전체의 생산성을 높여 줄 것입니다.