Spring Boot 실무 가이드 · Part 4
같은 빌드 결과물을 환경별로 다르게 실행하는 방법 이해하기
작성 기준2026년 7월버전과 지원 현황은 이후 달라질 수 있으니 공식 문서를 함께 확인하세요.
이 파트에서 다루는 내용
Spring Boot는 application.properties와 application.yml을 모두 지원합니다. 둘 다 같은 값을 표현할 수 있지만, 계층 구조가 있는 설정은 yml이 읽기 쉽습니다.
설정 파일은 src/main/resources에 둡니다. 여기 들어간 값은 빌드 결과물에 포함되므로, 환경마다 달라지는 값과 비밀정보를 여기에 그대로 적으면 안 됩니다.
server:
port: 8080
spring:
application:
name: order-service
datasource:
url: jdbc:mysql://localhost:3306/orderdb
username: ${DB_USERNAME}
password: ${DB_PASSWORD}
jpa:
hibernate:
ddl-auto: validate
open-in-view: false
logging:
level:
com.example.order: DEBUG
app:
order:
max-item-count: 50
cancel-limit-hours: 24username과 password를 환경변수로 받는 형태에 주목하세요. 값을 파일에 적지 않고 실행 환경에서 주입합니다. open-in-view는 트랙 C에서 다룹니다.
Spring Boot는 여러 위치에서 설정을 읽고, 충돌하면 우선순위가 높은 값을 씁니다. 이 규칙을 알아야 '설정을 바꿨는데 반영이 안 된다'는 상황을 풀 수 있습니다.
아래로 갈수록 우선순위가 높습니다. 즉 실행할 때 준 값이 파일에 적은 값을 이깁니다.
기본값은 파일에 두고, 환경마다 달라지는 값과 비밀정보는 환경변수로 주입합니다. 같은 jar를 개발·운영에서 그대로 씁니다.
spring.datasource.url은 SPRING_DATASOURCE_URL이 됩니다. 점은 밑줄로, 대문자로 바꿉니다. 컨테이너 환경에서 자주 씁니다.
java -jar app.jar --server.port=9090처럼 커맨드라인으로 덮어써서 설정 문제인지 빠르게 확인할 수 있습니다.
설정값을 코드에서 읽는 방법은 @Value와 @ConfigurationProperties 두 가지입니다. 값이 하나뿐이면 @Value도 괜찮지만, 관련된 설정이 여러 개면 묶어서 받는 편이 낫습니다.
묶어서 받으면 타입이 보장되고, 오타가 났을 때 기동 시점에 잡히며, 어떤 설정이 있는지 클래스만 봐도 알 수 있습니다.
값 하나를 간단히 읽을 때 씁니다. 여러 곳에 흩어지면 어떤 설정이 쓰이는지 파악하기 어려워집니다.
관련 설정을 하나의 타입으로 받습니다. 검증 애노테이션을 붙여 잘못된 값이면 기동을 실패시킬 수도 있습니다.
// record로 받으면 불변이고 코드가 짧습니다 (Java 17+)
@ConfigurationProperties(prefix = "app.order")
public record OrderProperties(
int maxItemCount,
int cancelLimitHours
) {
}
// 사용하는 쪽
@Service
@RequiredArgsConstructor
public class OrderService {
private final OrderProperties orderProperties;
public void validate(Order order) {
if (order.itemCount() > orderProperties.maxItemCount()) {
throw new IllegalArgumentException("주문 가능 수량을 초과했습니다");
}
}
}
// 메인 클래스 또는 설정 클래스에 스캔 대상 지정
@EnableConfigurationProperties(OrderProperties.class)yml의 app.order.max-item-count가 자바의 maxItemCount로 자동 매핑됩니다. 하이픈 표기와 카멜 표기를 Spring이 맞춰 줍니다.
프로파일은 실행 환경마다 다른 설정을 쓰기 위한 장치입니다. local, dev, prod처럼 이름을 정하고 파일을 나눕니다.
활성화는 실행할 때 지정합니다. 파일 안에 운영 프로파일을 기본값으로 박아 두면 실수로 운영 설정이 로컬에서 도는 사고가 납니다.
특정 프로파일에서만 등록할 빈을 지정합니다. 로컬 전용 목 구현이나 개발용 초기 데이터 로더에 씁니다.
프로파일이 늘수록 조합이 늘고 검증이 어려워집니다. 환경 개수만큼만 두고 기능 분기에는 쓰지 않습니다.
# application.yml (공통)
spring:
application:
name: order-service
---
# application-local.yml
spring:
datasource:
url: jdbc:h2:mem:testdb
jpa:
hibernate:
ddl-auto: create-drop
---
# application-prod.yml
spring:
jpa:
hibernate:
ddl-auto: validate
logging:
level:
root: WARN
# 실행
# java -jar app.jar --spring.profiles.active=prod
# 또는 환경변수 SPRING_PROFILES_ACTIVE=prod운영에서 ddl-auto를 validate 이상으로 두지 않는 점을 보세요. create나 update는 스키마를 건드릴 수 있어 운영에서 매우 위험합니다.
DB 비밀번호, API 키, 토큰이 설정 파일에 그대로 들어간 채 커밋되는 사고가 가장 흔합니다. 한 번 저장소에 올라가면 이후 커밋에서 지워도 이력에 남습니다.
설정 파일에는 자리표시자만 두고 실제 값은 실행 환경에서 넣습니다. 컨테이너와 CI/CD 환경에 잘 맞습니다.
빌드·배포 과정에서 비밀값이 필요하면 Jenkins Credentials로 주입합니다. Jenkins 코스에서 다룬 방식과 동일합니다.
서버의 지정 경로에 설정 파일을 두고 실행 시 읽게 합니다. 파일 권한 관리가 필요합니다.
값을 지우는 커밋만으로는 해결되지 않습니다. 이력에 남아 있으므로 해당 키와 비밀번호를 즉시 폐기하고 새로 발급해야 합니다. 저장소 이력 정리는 그다음 문제입니다.
본문은 현장에서 가장 많이 쓰는 3.x 기준입니다. 4.x에서 달라진 부분만 아래에 정리합니다.