같은 JAR를 설정만 바꿔 여러 환경에서 실행합니다
Chapter 01 프로젝트 시작하기에서는 설정 값이 application.yml의 한 줄뿐이었습니다. 이 Chapter는 포트, 앱 이름, 문구처럼 “코드를 고치지 않고 바꾸고 싶은 값”을 설정 파일로 빼고, 같은 JAR를 개발과 운영 환경에서 다르게 동작시키는 방법을 다룹니다. 서버가 켜질 때 가장 먼저 읽는 파일이 application.yml이므로, 이 파일의 위치와 문법을 먼저 익혀 두면 이후의 Profile, 우선순위, 오류 메시지가 훨씬 쉽게 읽힙니다.
Chapter를 마치면 아래 내용을 직접 실행해 확인한 상태가 됩니다.
| 확인하는 것 | 설명 |
|---|---|
| 기본 파일과 Profile 파일 | 공통 값은 application.yml에, 환경마다 다른 값만 application-dev.yml, application-prod.yml에 둡니다. |
GET /config, GET /greeting |
활성 Profile과 최종 설정 값, 설정이 반영된 인사말을 돌려주는 확인용 API입니다. |
| 설정 우선순위 | 기본 파일, Profile 파일, 환경 변수, 명령행 인자 순서로 값이 덮어써지는 것을 실행 결과로 확인합니다. |
| 테스트 6건 | Profile별 응답과 테스트 속성 덮어쓰기를 자동으로 검증합니다. |
준비물과 예제 저장소
| 항목 | 내용 |
|---|---|
| 사전 지식 | Chapter 01 프로젝트 시작하기의 프로젝트 구조, bootRun, curl 사용법 |
| JDK | 21 |
| Spring Boot | 4.1.1 |
| Gradle | 설치 불필요. 저장소 루트의 Wrapper(gradlew)를 씁니다. |
이 Chapter의 코드는 공개 저장소의 examples/ch02-config-profile 폴더에 있습니다. 모든 명령은 저장소 루트에서 실행하며, Windows에서는 ./gradlew 대신 gradlew.bat을 씁니다. 본문에서 다루는 파일은 다음과 같습니다.
| 대상 | 링크 |
|---|---|
| 기본 설정 | application.yml |
| dev 설정 | application-dev.yml |
| prod 설정 | application-prod.yml |
| 시작 클래스 | Ch02Application.java |
| 컨트롤러 | ConfigController.java |
| 설정 프로퍼티 | GreetingProperties.java |
| Profile 테스트 | ProfileTests.java |
| 속성 덮어쓰기 테스트 | PropertyOverrideTests.java |
| 기본 Profile 테스트 | DefaultProfileTests.java |
application.yml과 YAML 문법
바뀌는 값은 코드 밖에 둡니다
값을 코드에 직접 적으면 이런 일이 생깁니다.
String greetingPrefix = "Hello"; // 운영에서는 "Welcome"으로 바꿔야 한다면?
int port = 8080; // 개발 서버는 8081을 써야 한다면?
값 하나를 바꾸려고 코드를 열어 고치고, 빌드하고, 다시 배포해야 합니다. 같은 프로그램이 환경에 따라 다른 값을 가져야 한다면 그 값은 코드 밖에 둡니다. 코드는 “설정에서 값을 읽는다”까지만 알고, 실제 값은 설정 파일이나 실행 환경이 정합니다. 이 Chapter 전체에서 이 원칙을 따릅니다.
application.yml의 위치
Spring Boot는 클래스패스 루트의 application.yml(또는 application.properties)을 자동으로 읽습니다. Gradle 프로젝트에서는 src/main/resources 폴더가 클래스패스 루트입니다.
ch02-config-profile/
└── src/main/resources/
├── application.yml # 모든 환경에 공통
├── application-dev.yml # dev Profile일 때만 (다음 글)
└── application-prod.yml # prod Profile일 때만 (다음 글)
.properties와 .yml은 같은 정보를 다른 모양으로 적는 두 형식입니다. 이 과정은 계층 구조가 눈에 잘 보이는 .yml을 씁니다.
## application.properties 형식
app.greeting.prefix=Hello
## application.yml 형식
app:
greeting:
prefix: Hello
두 파일은 같은 키 app.greeting.prefix를 뜻합니다. YAML에서는 들여쓴 구조가 점으로 이어진 이름이 됩니다.
이 Chapter의 기본 설정
예제의 application.yml은 이렇습니다.
spring:
application:
name: ch02-config-profile
app:
owner: devguna
greeting:
prefix: Hello
suffix: "!"
max-length: 20
이 파일에서 만들어지는 키는 다음과 같습니다.
| 키 | 값 | 쓰임 |
|---|---|---|
spring.application.name |
ch02-config-profile |
앱 이름. Spring이 정한 키 |
app.owner |
devguna |
소유자 이름. 우리가 정한 키 |
app.greeting.prefix |
Hello |
인사말 앞부분 |
app.greeting.suffix |
! |
인사말 끝부분 |
app.greeting.max-length |
20 |
이름을 이 길이까지만 사용 |
spring.으로 시작하는 키는 Spring이 이미 의미를 정해 둔 것이고, app.으로 시작하는 키는 이 예제가 직접 정한 이름입니다. 직접 정하는 키에는 겹치지 않도록 app 같은 고유한 접두사를 붙이는 것이 관례입니다.
YAML 문법 기본 규칙
들여쓰기가 구조를 정한다
app:
greeting: # app 아래
prefix: Hello # app.greeting 아래
- 들여쓰기는 공백으로 합니다. 탭 문자는 쓸 수 없습니다.
- 같은 단계의 키는 들여쓰기 칸 수가 같아야 합니다. 이 과정은 2칸을 씁니다.
- 들여쓰기가 틀리면 키가 엉뚱한 곳에 붙거나 아예 인식되지 않습니다. 이 오류의 실제 모습은 아래 “YAML을 틀리면 어떻게 되나” 절에서 봅니다.
키와 값
키: 값형태이고 콜론(:) 뒤에 공백이 있어야 합니다.prefix:Hello는 값이 아니라 키 하나로 읽힙니다.- 숫자(
20), 참/거짓(true)은 따옴표 없이 씁니다. - 주석은
#으로 시작합니다.
따옴표가 필요한 값
대부분의 문자열은 따옴표 없이 쓰지만, YAML에서 특별한 뜻을 가진 문자가 값이면 감싸야 합니다.
suffix: "!" # ! 는 YAML에서 특수 문자라 따옴표가 필요하다
!처럼 YAML이 자기 문법으로 해석하는 문자가 값일 때가 대표적입니다. 헷갈리면 문자열 값은 따옴표로 감싸는 것이 안전합니다. 따옴표를 쓰지 않아도 Hi (dev)처럼 공백과 괄호가 있는 값이 그대로 읽히는 것은 아래 “이 예제의 환경별 파일” 절에서 확인합니다.
키 이름의 표기
max-length처럼 소문자와 하이픈(kebab-case)으로 쓰는 것이 Spring Boot의 권장 표기입니다. 코드에서는 maxLength로 읽어도 같은 키로 연결됩니다. 이 규칙(relaxed binding)은 아래 “relaxed binding” 절에서 다룹니다.
이후 Chapter에서 설정 값을 다시 만나는 곳
application.yml의 키는 뒤 Chapter에서도 계속 늘어납니다. 같은 파일을 읽는 눈으로 아래 사례를 보세요.
| 설정 | 하는 일 | 다루는 곳 |
|---|---|---|
bulk.in-chunk-size: 500, bulk.batch-chunk-size: 100 |
IN 목록과 배치 묶음의 크기를 코드 밖으로 뺌 | Chapter 17의 청크와 foreach, Chapter 18의 keyset 페이징 |
logging.pattern.console, management.endpoints.web.exposure.include |
로그 모양과 열 엔드포인트 | Chapter 22의 요청 번호 로그와 Actuator |
spring.sql.init.mode |
스키마 스크립트 자동 실행 여부(H2에서만 기본) | Chapter 20의 PostgreSQL 컨테이너 테스트 |
키가 점으로 이어지는 과정
YAML의 들여쓰기 구조는 Spring 안에서 점(.)으로 이어진 하나의 키로 바뀝니다. 이 Chapter의 application.yml을 기준으로 따라가 보겠습니다.
위 application.yml에서 값이 있는 끝 키까지 경로를 점으로 이으면 app.owner, app.greeting.prefix, app.greeting.suffix, app.greeting.max-length 네 개의 키가 됩니다. 중간 노드(app, greeting)는 값이 없는 묶음일 뿐이어서 키로는 읽히지 않습니다. 코드에서 @Value("${app.greeting.prefix}")로 쓰는 이름이 바로 이 경로입니다. 이 Chapter의 코드는 이 이름을 그대로 쓰므로, 들여쓰기를 보면서 점으로 이은 이름을 머릿속으로 써 보는 연습을 해 두세요.
YAML을 틀리면 어떻게 되나
문법 실수는 두 갈래로 나뉩니다. 서버가 아예 뜨지 않는 실수와, 아무 오류 없이 값만 이상해지는 실수입니다. 이 Chapter의 예제(examples/ch02-config-profile)에서 application.yml을 한 군데씩 일부러 틀리고 :examples:ch02-config-profile:test를 실행해 얻은 결과입니다.
| 틀린 부분 | 결과 | 읽는 법 |
|---|---|---|
| 들여쓰기에 탭 문자 사용 | 컨텍스트 로딩 실패. found character '\t(TAB)' that cannot start any token. (Do not use \t(TAB) for indentation) |
메시지가 탭을 직접 지목합니다. 편집기에서 탭이 공백으로 바뀌는지 확인합니다. |
prefix: Hello를 prefix:Hello로 변경(콜론 뒤 공백 없음) |
컨텍스트 로딩 실패. mapping values are not allowed here |
키:값이 하나의 글자로 읽혀 매핑으로 인정되지 않습니다. |
suffix 한 줄만 들여쓰기 3칸 |
컨텍스트 로딩 실패. expected <block end>, but found '<block mapping start>' |
같은 단계 키의 칸 수가 맞지 않습니다. 메시지의 줄 번호 근처를 봅니다. |
suffix: "!"에서 따옴표를 뺌(suffix: !) |
서버는 정상 기동, 테스트만 실패. 인사말 끝의 !가 사라짐(Hello, devguna! 기대, Hello, devguna 실제) |
!는 YAML에서 특수 문자라 값이 빈 문자열이 됩니다. 오류가 없어서 가장 위험합니다. |
앞의 세 가지는 서버가 뜨지 않아 바로 알아챕니다. 네 번째처럼 조용히 틀리는 경우는 결과를 눈으로 확인하는 습관이 없으면 놓칩니다. 이 Chapter가 /config와 /greeting 같은 확인용 엔드포인트와 테스트를 같이 두는 이유입니다. 설정을 바꿨다면 응답을 한 번 불러 보세요.
확인 문제
app.greeting.max-length를 YAML 구조로 직접 써 보세요. (힌트: 들여쓰기 세 단계입니다.)application.yml과application.properties가 같은 폴더에 둘 다 있으면 어떻게 될지 먼저 예상해 보고, 공식 문서(Externalized Configuration)에서 확인해 보세요. 이 절의 예제는 한 형식만 씁니다.- 값에
:(콜론과 공백)이나#이 들어가는 문자열은 따옴표가 필요한지 YAML 규칙으로 설명해 보세요.
답: 1) app: 아래 greeting: 아래 max-length: 20 순서로 들여씁니다. 2) 두 파일 모두 읽히고, 같은 키가 둘 다에 있으면 공식 문서(Externalized Configuration) 기준으로 .properties 값이 우선합니다. 이 예제에서는 실행해 확인하지 않았습니다. 3) 값 안의 : 와 #은 YAML 문법으로 해석되므로 따옴표로 감싸는 편이 안전합니다.
직접 해 보기
examples/ch02-config-profile/src/main/resources/application.yml을 열어 위 표의 키 다섯 개를 찾아보세요.suffix: "!"에서 따옴표를 지우고 서버를 켜 보세요. 어떤 일이 생기는지 확인하고, 되돌려 놓으세요. 결과는 위 “YAML을 틀리면 어떻게 되나” 표의 네 번째 줄과 비교해 보세요.max-length의 값을5로 바꾸면/greeting?name=devguna의 응답이 어떻게 달라지는지 예상해 보세요.
Profile로 환경별 설정 나누기
개발할 때는 8081 포트에 “Hi (dev)“라는 문구를 쓰고, 운영에서는 8082 포트에 “Welcome”을 쓰고 싶다고 해 봅시다. 설정 파일을 환경마다 따로 복사해 관리하면 공통 값을 바꿀 때마다 모든 파일을 고쳐야 합니다. Spring Boot의 Profile은 이 문제를 “공통은 한 곳, 다른 것만 환경별 파일”로 푸는 방법입니다.
이 절에서는 Profile이 무엇이고, 환경별 파일이 기본 설정 위에 어떻게 덮어쓰는지를 파일 구조로 확인합니다. 실제로 켜서 비교하는 것은 아래 “세 실행을 한눈에 비교” 절에서 합니다.
Profile은 환경 이름표다
Profile은 “지금 어떤 환경으로 실행 중인가”를 나타내는 이름표입니다. dev(개발), prod(운영), test(테스트)처럼 팀이 이름을 직접 정합니다. 이름표를 하나 켜면 Boot는 기본 설정 파일에 더해 그 이름이 붙은 설정 파일도 읽습니다.
| 파일 | 읽히는 때 |
|---|---|
application.yml |
항상 |
application-dev.yml |
dev Profile이 켜져 있을 때 |
application-prod.yml |
prod Profile이 켜져 있을 때 |
파일 이름은 application- 뒤에 Profile 이름을 붙인 형식을 지켜야 합니다. application_dev.yml처럼 이름 규칙이 틀리면 Profile을 켜도 읽히지 않습니다.
이 예제의 환경별 파일
앞의 “이 Chapter의 기본 설정” 절에서 본 기본 파일에 이어 dev와 prod 파일이 있습니다.
## application-dev.yml
server:
port: 8081
app:
greeting:
prefix: Hi (dev)
## application-prod.yml
server:
port: 8082
app:
greeting:
prefix: Welcome
suffix: "."
max-length: 10
dev 파일은 포트와 prefix 두 개만 가지고 있고, prod 파일은 포트와 인사말 설정 세 개를 모두 가지고 있습니다. Hi (dev)처럼 공백과 괄호가 있는 값도 따옴표 없이 문자열로 읽힙니다.
덮어쓰기는 키 단위로 일어난다
여기서 가장 중요한 규칙은 환경별 파일이 기본 파일을 통째로 바꾸지 않는다는 점입니다. 같은 키가 있으면 환경별 값이 이기고, 환경별 파일에 없는 키는 기본 파일의 값이 그대로 남습니다.
dev Profile로 실행하면 기본 파일이 먼저 올라가고, 켜진 Profile의 파일이 같은 이름의 키만 덮어씁니다. dev 파일에 없는 키는 기본 파일 값이 그대로 남습니다. 두 파일이 합쳐진 최종 설정은 다음과 같습니다.
| 키 | 기본 파일 | dev 파일 | 최종 값 |
|---|---|---|---|
server.port |
(없음, Boot 기본 8080) | 8081 |
8081 |
app.owner |
devguna |
(없음) | devguna |
app.greeting.prefix |
Hello |
Hi (dev) |
Hi (dev) |
app.greeting.suffix |
! |
(없음) | ! |
app.greeting.max-length |
20 |
(없음) | 20 |
dev에서 바뀐 것은 prefix와 포트뿐이고, suffix, max-length, owner는 기본 값을 그대로 씁니다. prod는 세 값을 모두 바꿔 두었기 때문에 Welcome, ., 10이 최종 값이 됩니다. 이렇게 하면 공통 값을 한 번만 적고, 환경마다 정말 다른 것만 환경별 파일에 적게 됩니다.
Profile을 지정하지 않으면
Profile을 켜지 않고 실행하면 default라는 이름의 Profile로 실행되고, 기동 로그에 이런 줄이 찍힙니다.
No active profile set, falling back to 1 default profile: "default"
이때는 application.yml만 적용됩니다. 앞 Chapter의 기동 로그 읽기에서 본 줄이 바로 이것입니다.
환경별 파일에 무엇을 넣을까
실무에서 환경마다 달라지는 것은 대체로 포트, 데이터베이스 주소, 외부 연동 주소, 로그 수준입니다. 한 가지 주의할 점이 있습니다. 비밀번호나 API 키 같은 민감한 값은 환경별 파일에 적어 저장소에 올리지 않고, 환경 변수나 별도 비밀 관리 수단으로 넘깁니다. 이 Chapter는 그 방법의 기초인 환경 변수 덮어쓰기까지만 다루고, 비밀 관리 자체는 다루지 않습니다.
Profile과 환경 변수를 다시 만나는 곳
- 컨테이너에서는 환경 변수(
SPRING_DATASOURCE_URL등)가 기본 설정을 덮어씁니다. Chapter 22 운영의 compose 실습에서 확인합니다. - 테스트에서
@ActiveProfiles("oracle")로 DB별 설정을 고릅니다. Chapter 11 Oracle 연결과 JSON 매핑과 Chapter 23 종합 프로젝트 1에서 같은 시나리오를 H2와 Oracle에서 돌립니다. - 데모 계정 생성 같은 기능은 기본으로 꺼 두고 환경 변수로만 켭니다. Chapter 24 종합 프로젝트 2의 데모 계정이 이 방식입니다.
왜 파일을 나누고, 차이만 적을까
환경마다 파일 전체를 복사해 두는 방법도 있습니다. 그러나 복사본은 시간이 지나면 어긋납니다. 기본 파일에 새 키를 추가했는데 prod 복사본에는 빠뜨리면, prod에서만 값이 없어 장애가 납니다. 반대로 “공통은 기본 파일, 다른 것만 Profile 파일”로 나누면 파일에 적힌 키가 곧 그 환경의 차이입니다. dev 파일을 열면 dev가 기본과 무엇이 다른지가 한눈에 보이는 것이 장점입니다.
이 예제의 파일별 키 수도 이 원칙을 보여 줍니다. dev는 2개(server.port, app.greeting.prefix), prod는 4개(server.port와 인사말 3개)만 가지고 있고 app.owner와 spring.application.name은 기본 파일에만 있습니다.
Profile 이름을 다룰 때 알아 둘 점
- 이름은 자유롭게 정할 수 있습니다.
dev,prod,test는 관례일 뿐 Boot가 특별 취급하지 않습니다. 이 Chapter의 파일명application-dev.yml의dev가 그대로 Profile 이름입니다. - 여러 Profile을 동시에 켤 수 있습니다(
--spring.profiles.active=dev,local처럼 쉼표로 구분). 같은 키가 둘 이상의 Profile 파일에 있으면 공식 문서 기준으로 나중에 적은 Profile이 우선합니다. 이 예제는 한 번에 하나만 켭니다. - Profile은 설정 파일뿐 아니라
@Profile("dev")를 붙인 Bean을 켜고 끄는 데도 쓸 수 있습니다. 이 과정은 설정 파일 분리만 다루고@Profile코드는 쓰지 않습니다.
자주 하는 실수
| 실수 | 증상 | 확인 방법 |
|---|---|---|
| 새 키를 dev에만 추가하고 기본 파일에는 넣지 않음 | default나 prod로 실행하면 값이 없어 기본값(@DefaultValue)이나 오류로 이어짐 |
기본 파일에 모든 키의 기본 값이 있는지 점검 |
파일 이름의 Profile 이름 오타(application-develop.yml인데 dev로 실행) |
Profile은 켜졌는데 값이 안 바뀜 | /config 응답의 activeProfiles와 파일명을 대조 |
| 환경별 파일에 비밀번호를 적어 저장소에 올림 | 비밀 값이 이력에 남음 | 비밀 값은 환경 변수로 전달, 아래 “비밀 값은 어디에” 절 참고 |
확인 문제
application-prod.yml에서max-length: 10한 줄을 지우고 prod로 실행하면max-length는 얼마가 될까요?- 같은 키를
application.yml과application-dev.yml에 모두 적었는데default로 실행하면 어느 값이 쓰일까요?
답: 1) 기본 파일의 20입니다. 2) 기본 파일의 값입니다. dev 파일은 dev Profile이 켜졌을 때만 읽힙니다.
직접 해 보기
application-dev.yml과application-prod.yml을 열어, 기본 파일과 겹치는 키를 표시해 보세요.- prod에서
/greeting?name=abcdefghijklmnop을 부르면 어떤 응답이 나올지 위 규칙으로 예상해 보세요. (실제 결과는 아래 “prod로 실행하기” 절에 있습니다.) application-qa.yml을 새로 만들어 포트를8083으로 정하고, 그 파일이 읽히려면 어떤 Profile 이름을 켜야 할지 생각해 보세요.
설정 값 읽기 1: @Value와 Environment
설정 파일에 값을 적었으면 코드에서 읽어야 합니다. Spring Boot가 제공하는 방법은 여러 가지인데, 이 절에서는 가장 간단한 두 가지를 봅니다. 값 하나를 바로 꽂아 넣는 @Value와, 실행 환경 전체에 질문하는 Environment입니다.
Chapter 01에서 @Value("${spring.application.name}")를 한 번 써 봤습니다. 이 절에서는 그때 넘어갔던 부분, 곧 기본값과 키가 없을 때의 동작, 그리고 Environment가 무엇을 알려 주는지를 정리합니다.
컨트롤러의 생성자
예제의 컨트롤러는 설정을 읽는 세 가지 방법을 한 생성자에서 받습니다.
설정이 컨트롤러까지 오는 길은 이렇습니다. 설정 파일의 값이 Environment에 모이고, @Value는 그중 키 하나를 꺼내 생성자 파라미터에 넣어 줍니다. 컨트롤러는 파일을 직접 열지 않습니다.
public ConfigController(
Environment environment,
GreetingProperties greeting,
@Value("${app.owner:unknown}") String owner) {
this.environment = environment;
this.greeting = greeting;
this.owner = owner;
}
이 절은 Environment와 @Value 두 가지를 다루고, 가운데 GreetingProperties는 아래 “설정 객체 만들기” 절에서 설명합니다.
주요 코드 설명: @Value
@Value("${app.owner:unknown}") String owner
${...}안의 이름이 찾을 설정 키입니다. 여기서는app.owner입니다.- 콜론(
:) 뒤의unknown은 키가 없을 때 쓸 기본값입니다. 기본값을 적지 않으면 키가 없을 때 서버가 뜨지 않습니다. Chapter 01에서${spring.application.name}에 기본값이 없어서 키를 지우면 기동이 실패했던 것이 바로 이 규칙입니다. - 이 예제에서는
app.owner가 기본 파일에devguna로 있으므로owner에는devguna가 들어갑니다.unknown은 키가 없을 때만 쓰입니다.
@Value는 필드, 생성자 파라미터 어디든 붙일 수 있지만, 이 과정은 생성자 파라미터에 붙입니다. 이유는 Chapter 03 IoC, DI, Bean에서 다룹니다.
주요 코드 설명: Environment
List<String> profiles = Arrays.asList(environment.getActiveProfiles());
String name = environment.getProperty("spring.application.name");
String port = environment.getProperty("server.port", "8080");
Environment는 “지금 실행 환경에 대해 아는 모든 것”을 담은 객체입니다. 그중 이 예제가 쓰는 기능은 두 가지입니다.
getActiveProfiles(): 켜진 Profile 이름 배열. Profile 없이 실행하면 빈 배열입니다.getProperty(키)또는getProperty(키, 기본값): 설정 값 하나를 문자열로 가져옵니다. 키가 없으면null또는 기본값을 돌려줍니다.
server.port를 getProperty("server.port", "8080")로 읽는 데서, 이 예제에는 default Profile에 포트 설정이 없고 Boot의 기본 포트 8080을 그대로 쓴다는 것을 알 수 있습니다.
/config가 보여 주는 것
GET /config는 Environment와 주입받은 값들을 모아 JSON으로 보여 줍니다. 응답을 만드는 record는 이렇습니다.
public record ConfigView(
String applicationName,
List<String> activeProfiles,
String serverPort,
String owner,
GreetingProperties greeting) {
}
응답으로 설정을 눈으로 확인할 수 있게 해 두면, 이 Chapter처럼 “환경이 바뀌었을 때 값이 어떻게 달라지는가”를 테스트로 고정하기 쉽습니다.
@Value와 Environment 중 무엇을 쓸까
| 상황 | 알맞은 방법 |
|---|---|
| 키 하나를 한 곳에서 쓴다 | @Value("${키:기본값}") |
| 키 이름을 코드에서 동적으로 만든다 | Environment.getProperty(...) |
| 활성 Profile을 알아야 한다 | Environment.getActiveProfiles() |
| 관련 설정이 여러 개 있다 | @ConfigurationProperties (아래 “설정 객체 만들기” 절) |
@Value는 키 이름을 문자열로 적기 때문에 오타를 컴파일러가 잡지 못합니다. 설정이 늘어날수록 문자열이 코드 곳곳에 흩어지므로, 관련된 값이 셋 이상이면 @ConfigurationProperties로 묶는 방식이 더 안전합니다.
@Value의 기본값을 다시 만나는 곳
@Value("${bulk.batch-async:true}")처럼 콜론 뒤에 기본값을 두면 설정이 없을 때의 동작이 정해집니다. 배치 실행기를 테스트에서만 같은 스레드로 돌리게 하는 데 쓰입니다(Chapter 18 AOP와 온디맨드 배치의 온디맨드 배치 설계). 설정으로 뺀 값은 테스트에서 줄여 경계를 만드는 데도 유용합니다(Chapter 17 모듈 호출 오케스트레이션의 청크 경계 테스트).
기본값이 없으면 서버가 뜨지 않는다
@Value("${app.owner:unknown}")의 :unknown을 지우고 application.yml에서 owner 키도 지워서 실행해 보았습니다(examples/ch02-config-profile 복사본에서 :examples:ch02-config-profile:test 실행). 컨텍스트 로딩 테스트부터 전부 실패했고 원인은 이 줄이었습니다.
org.springframework.util.PlaceholderResolutionException:
Could not resolve placeholder 'app.owner' in value "${app.owner}"
기본값이 있으면 키가 없어도 조용히 기본값이 쓰이고, 기본값이 없으면 시작 단계에서 실패합니다. 어느 쪽이 좋은지는 값의 성격에 따라 다릅니다.
| 값의 성격 | 알맞은 선택 |
|---|---|
| 없어도 동작해야 하는 값(표시용 문구 등) | 기본값 지정 |
| 없으면 운영이 위험한 값(접속 주소, 비밀번호) | 기본값을 두지 않고 시작 단계에서 실패시킴 |
없을 때 조용히 넘어가는 편이 편해 보여도, 필수 값에 기본값을 두면 설정을 빠뜨린 사실을 늦게 발견합니다.
따라 하기: /config로 값 확인하기
- 저장소를 받고 저장소 루트(
ls gradlew로 확인)에서./gradlew :examples:ch02-config-profile:bootRun을 실행합니다. Wrapper는 루트에만 있어서examples/ch02-config-profile안에서 실행하면./gradlew: not found가 납니다. 모듈 폴더에서 실행하려면../../gradlew :examples:ch02-config-profile:bootRun처럼 경로를 지정합니다. - 다른 터미널에서
curl http://localhost:8080/config를 호출합니다. - 응답의
owner가devguna이고activeProfiles가 빈 배열이면 성공입니다. 이 값들이 컨트롤러 생성자에서Environment와@Value로 읽은 것입니다. application.yml의owner를me로 바꿔 다시 실행하고 응답이 따라 바뀌는지 확인합니다.
자주 하는 실수
| 실수 | 증상 | 해결 |
|---|---|---|
@Value("app.owner")처럼 ${ }를 빠뜨림 |
설정 값이 아니라 문자열 app.owner 자체가 들어감 |
${app.owner} 형식으로 적기 |
| 키 철자 오타에 기본값이 있음 | 오류 없이 항상 기본값이 쓰임 | /config 응답으로 실제 값 확인 |
필드 주입(@Value를 필드에 붙임) |
동작은 하지만 테스트에서 값을 넣기 어려움 | 생성자 파라미터에 붙이기 |
확인 문제
@Value("${키}")에 기본값을 주지 않으면, 설정 파일에 그 키가 없을 때 어떻게 되나요?Environment로는@Value로 하기 어려운 어떤 조회를 할 수 있나요?
답: 1) 서버가 기동에 실패합니다. 기본값은 ${키:기본값} 형태로 지정합니다. 2) 활성 Profile을 조회하고, 키를 이름으로 지정해 임의의 설정 값을 조회할 수 있습니다.
직접 해 보기
ConfigController에서${app.owner:unknown}을${app.owner}로 바꾸고,application.yml에서owner줄을 지우면 어떻게 되는지 예상해 보세요. (Chapter 01의 “설정 파일에 키가 없을 때” 절에서 본 메시지와 같은 종류입니다.)- 기본값을
unknown으로 둔 채owner줄을 지우면/config응답의owner가 무엇이 되는지 예상해 보세요. environment.getProperty("app.greeting.prefix")를 호출해 직접 값을 출력해 보세요.
설정 값 읽기 2: @ConfigurationProperties
@Value로 키 하나를 읽는 것은 쉽지만, 인사말 설정처럼 서로 관련된 값이 prefix, suffix, max-length 셋이면 문자열 키가 세 곳에 흩어집니다. 이럴 때 같은 접두사의 설정을 객체 하나로 묶어 주입하는 것이 @ConfigurationProperties입니다.
이 절에서는 record로 설정 객체를 만들고, 기본값과 표기 규칙(relaxed binding)을 확인하고, 등록하지 않으면 어떻게 되는지를 실제 오류로 봅니다.
설정 객체 만들기
@ConfigurationProperties(prefix = "app.greeting")
public record GreetingProperties(
@DefaultValue("Hello") String prefix,
@DefaultValue("!") String suffix,
@DefaultValue("20") int maxLength) {
}
설정 파일의 키는 이렇게 record의 필드로 연결됩니다. prefix = "app.greeting"이 접두사를 정하고, 그 아래 키가 이름이 같은 필드에 묶입니다. max-length는 relaxed binding으로 maxLength에 이어집니다.
코드 읽기
prefix = “app.greeting”
이 객체가 읽는 설정 키의 공통 접두사입니다. app.greeting.prefix, app.greeting.suffix, app.greeting.max-length가 각각 prefix, suffix, maxLength에 들어갑니다. 접두사를 틀리면 어떻게 되는지는 아래 “2. @ConfigurationProperties의 prefix를 틀리면” 절에서 봅니다.
record를 쓰는 이유
record는 생성자로 값을 받는 불변 객체입니다. 설정은 서버가 켜질 때 한 번 정해지면 바뀌면 안 되므로 불변인 record가 잘 맞습니다. 일반 클래스로 만들면 setter를 열어야 해서 실수로 값이 바뀔 수 있습니다.
@DefaultValue
설정에 키가 없을 때 쓸 값입니다. @DefaultValue("20") int maxLength처럼 문자열로 적어도 int로 변환됩니다. 기본값이 없으면 키가 없을 때 null(숫자는 0)이 들어갑니다.
relaxed binding
YAML의 max-length와 코드의 maxLength는 표기가 다른데도 같은 설정으로 이어집니다. Boot는 max-length, maxLength, max_length, MAXLENGTH를 모두 같은 키로 보는 느슨한 규칙(relaxed binding)을 씁니다. 환경 변수로 값을 줄 때는 이 규칙에 따라 app.greeting.max-length를 APP_GREETING_MAXLENGTH처럼 대문자와 밑줄로 씁니다. 이 규칙이 실제로 동작하는 것은 아래 “실험: dev의 prefix를 덮어쓰기” 절에서 환경 변수로 확인합니다.
등록하지 않으면 기동이 실패한다
처음에는 이 클래스에 @ConfigurationProperties만 붙이면 끝인 줄 알았습니다. 그래서 시작 클래스의 @ConfigurationPropertiesScan을 빼 보았더니, 기본값으로 동작하는 것이 아니라 서버가 뜨지 않았습니다.
APPLICATION FAILED TO START
Parameter 1 of constructor in com.jqdom.curriculum.ch02.ConfigController required a bean of type 'com.jqdom.curriculum.ch02.GreetingProperties' that could not be found.
@ConfigurationProperties는 “이 클래스는 설정 묶음이다”라는 표시일 뿐이고, 스프링이 Bean으로 만들어 주지는 않습니다. 컨트롤러가 이 객체를 주입받으려는데 Bean이 없으니 막힌 것입니다. 등록 방법은 두 가지입니다.
@SpringBootApplication
@ConfigurationPropertiesScan // 패키지 아래의 설정 클래스를 모두 찾아 등록
public class Ch02Application {
public static void main(String[] args) {
SpringApplication.run(Ch02Application.class, args);
}
}
또는 개별 클래스를 @EnableConfigurationProperties(GreetingProperties.class)로 지정할 수도 있습니다. 이 예제는 앞의 방식을 씁니다. 등록되지 않은 클래스는 존재하지 않는 것과 같다는 점, 곧 Bean 등록의 기본 원리는 Chapter 03 IoC, DI, Bean에서 본격적으로 다룹니다.
컨트롤러에서 사용하기
주입받은 객체는 평범한 record라 필드 접근처럼 메서드로 읽습니다.
@GetMapping("/greeting")
public String greeting(@RequestParam(defaultValue = "Spring Boot") String name) {
String shortName = name.length() > greeting.maxLength()
? name.substring(0, greeting.maxLength())
: name;
return greeting.prefix() + ", " + shortName + greeting.suffix();
}
이름이 max-length보다 길면 그 길이까지만 잘라서 prefix, 이름suffix 형태의 인사말을 만듭니다. 설정이 실제 동작에 영향을 주는 것을 눈으로 보이려고 만든 로직입니다. 기본 설정에서는 Hello, 이름!이 됩니다.
@Value와 @ConfigurationProperties 비교
@Value |
@ConfigurationProperties |
|
|---|---|---|
| 단위 | 키 하나 | 같은 접두사의 설정 묶음 |
| 기본값 | ${키:기본값} |
@DefaultValue |
| 타입 변환 | 가능 | 가능 (중첩 객체, 목록도 가능) |
| 키 이름 | 문자열을 코드에 적음 | 필드 이름에서 만들어짐 |
| 등록 | 필요 없음 | @ConfigurationPropertiesScan 등 필요 |
| 테스트 | 값이 흩어져 있음 | 객체 하나를 만들어 넘기기 쉬움 |
값이 한두 개이면 @Value로 충분하고, 관련 설정이 여럿이면 객체로 묶습니다. 이 예제는 두 방식을 일부러 같은 컨트롤러에서 비교했습니다.
바인딩 과정과 실패하는 지점
@ConfigurationProperties가 값을 채우는 일은 세 단계입니다. 단계마다 실패하는 모습이 다릅니다.
| 단계 | 하는 일 | 여기서 틀리면 |
|---|---|---|
| 1. 등록 | @ConfigurationPropertiesScan이 설정 클래스를 Bean으로 만듦 |
기동 실패(required a bean of type ...) |
| 2. 키 찾기 | prefix와 필드 이름으로 키를 찾음 |
오류 없이 @DefaultValue로 채워짐 |
| 3. 타입 변환 | 문자열을 int 등으로 바꿈 |
기동 실패(Failed to bind properties under ...) |
2단계의 조용한 실패가 가장 위험합니다. @DefaultValue가 있어서 설정을 못 찾아도 앱이 멀쩡히 뜨기 때문입니다. 아래 “2. @ConfigurationProperties의 prefix를 틀리면” 절에서 prefix를 틀려 실제로 3건이 실패한 결과를 볼 수 있습니다.
record를 쓰면 좋은 점과 주의점
- 필드가
final이라 설정이 중간에 바뀔 수 없습니다. 기동 시점에 한 번 정해진 값만 쓴다는 뜻입니다. - 생성자 하나로 값이 채워지므로, 테스트에서는
new GreetingProperties("Hi", "?", 5)처럼 직접 만들어 쓸 수 있습니다. 파일을 읽는 설정 로딩 없이도 컨트롤러 로직을 시험할 수 있다는 점이@Value를 흩어 놓은 경우와 다릅니다. - 설정이 비밀번호처럼 외부에서 주입되는 값이어도 같은 방식으로 받을 수 있습니다. 어디서 오든 이 record 하나만 바라보면 됩니다.
자주 하는 실수
| 실수 | 증상 | 해결 |
|---|---|---|
@ConfigurationPropertiesScan을 빠뜨림 |
required a bean of type ...GreetingProperties |
시작 클래스에 추가하거나 @EnableConfigurationProperties 사용 |
prefix 값에 철자 오류 |
모든 값이 기본값으로 동작 | /config 응답의 greeting 객체 확인 |
maxLength 칸에 숫자가 아닌 값 |
Failed to bind properties under 'app.greeting.max-length' |
값의 타입 확인 |
확인 문제
app.greeting.max-length,app.greeting.maxLength,APP_GREETING_MAXLENGTH세 표기가 모두 같은 설정으로 이어지는 이유는 무엇인가요?- 설정이 하나뿐인 경우에도
@ConfigurationProperties를 써야 할까요?
답: 1) Boot의 relaxed binding이 표기를 같은 이름으로 정규화하기 때문입니다. 2) 꼭 그렇지는 않습니다. 한두 개면 @Value로 충분하고, 관련 설정이 늘면 객체로 묶는 쪽이 읽기 쉽습니다.
직접 해 보기
GreetingProperties에@DefaultValue("false") boolean upperCase필드를 추가하고,greeting()이upperCase일 때 인사말을 대문자로 바꾸도록 고쳐 보세요. 설정 파일에는 아무것도 적지 않아도 기본값으로 동작해야 합니다.@ConfigurationPropertiesScan을 지우고 위의 오류 메시지가 그대로 나오는지 확인해 보세요. 확인한 뒤에는 꼭 되돌려 놓으세요.application.yml에서max-length를max_length로 바꿔 보세요. 값이 적용되는지 예상하고,/config로 확인해 보세요.
default, dev, prod 실행해 비교하기
지금까지 Profile과 설정 읽기를 따로 봤습니다. 이 절에서는 둘을 합쳐서, 같은 JAR를 Profile만 바꿔 실행했을 때 같은 요청이 어떤 응답을 돌려주는지 직접 비교합니다. 결과를 눈으로 확인하면 “키 단위 덮어쓰기”가 말이 아니라 사실이 됩니다.
Profile 켜는 방법
같은 JAR가 Profile에 따라 다르게 동작할 때 코드와 빌드 결과는 하나이고, 실행 인자만 다릅니다. 개발 중에는 Gradle로 실행하면서 인자를 넘깁니다.
| OS | 실행 |
|---|---|
| Linux / macOS | ./gradlew :examples:ch02-config-profile:bootRun --args='--spring.profiles.active=dev' |
| Windows | gradlew.bat :examples:ch02-config-profile:bootRun --args="--spring.profiles.active=dev" |
--spring.profiles.active=dev가 “dev Profile을 켜라”는 설정입니다. 인자를 --args 안에 넣는 것은 Gradle이 이 값을 앱에 그대로 전달하게 하기 위해서입니다.
배포용으로 JAR를 만들어 실행할 때는 JAR 파일명 뒤에 인자를 둡니다.
java -jar ch02-config-profile-0.0.1-SNAPSHOT.jar --spring.profiles.active=dev
JAR 앞에 두면 Boot에 닿기 전에 JVM이 먼저 막습니다. 이 오류는 아래 “5. JAR 앞에 인자를 두었다” 절에서 정리합니다.
default로 실행하기
Profile 없이 실행하고 두 가지를 요청했습니다.
GET /greeting?name=devguna
Hello, devguna!
GET /config
{"applicationName":"ch02-config-profile","activeProfiles":[],"serverPort":"8080","owner":"devguna","greeting":{"prefix":"Hello","suffix":"!","maxLength":20}}
기동 로그에는 No active profile set, falling back to 1 default profile: "default"가 찍힙니다. activeProfiles가 빈 배열이고, 모든 값이 기본 파일에서 왔습니다.
dev로 실행하기
--spring.profiles.active=dev를 붙이면 포트와 prefix만 달라집니다.
GET /greeting?name=devguna
Hi (dev), devguna!
GET /config
{"applicationName":"ch02-config-profile","activeProfiles":["dev"],"serverPort":"8081","owner":"devguna","greeting":{"prefix":"Hi (dev)","suffix":"!","maxLength":20}}
포트가 8081로 바뀌었으므로 요청 주소도 localhost:8081입니다. suffix(!), maxLength(20), owner는 기본 파일의 값 그대로입니다. 앞의 “덮어쓰기는 키 단위로 일어난다” 절에서 표로 예상한 것과 같습니다.
prod로 실행하기
prod는 인사말 설정 세 개를 모두 바꿔 두었습니다. 이름이 maxLength보다 긴 경우를 보려고 열여섯 글자를 보냈습니다.
GET /greeting?name=abcdefghijklmnop
Welcome, abcdefghij.
GET /config
{"applicationName":"ch02-config-profile","activeProfiles":["prod"],"serverPort":"8082","owner":"devguna","greeting":{"prefix":"Welcome","suffix":".","maxLength":10}}
abcdefghijklmnop(16자)가 maxLength 10자에서 abcdefghij로 잘렸고, suffix는 .입니다. owner만 어느 Profile에도 없어서 기본 값 devguna입니다.
세 실행을 한눈에 비교
| 항목 | default | dev | prod |
|---|---|---|---|
| activeProfiles | [] |
["dev"] |
["prod"] |
| 포트 | 8080 | 8081 | 8082 |
| prefix | Hello | Hi (dev) | Welcome |
| suffix | ! |
! |
. |
| maxLength | 20 | 20 | 10 |
| owner | devguna | devguna | devguna |
표에서 dev의 값 중 기본 파일에서 온 것(suffix, maxLength, owner)과 dev 파일에서 온 것(포트, prefix)을 구분해 보세요. 같은 JAR를 한 줄도 고치지 않고 이만큼 다르게 동작시킨 것입니다.
응답으로 값의 출처 추적하기
설정이 예상과 다르게 동작할 때는 /config 같은 확인용 엔드포인트가 가장 빠른 단서입니다. 이 예제처럼 설정 값을 응답으로 내보내면 “어느 Profile이 켜져 있고 최종 값이 무엇인가”를 로그를 뒤지지 않고 알 수 있습니다. 다만 실제 서비스에서는 비밀번호나 키가 포함된 설정을 이렇게 노출하면 안 되므로, 운영용 점검 엔드포인트는 보호하거나 민감한 값을 가려야 합니다(Chapter 22 운영의 Actuator에서 다룹니다).
확인 순서를 정해 두면 빠르다
Profile을 바꿔 실행한 뒤에는 같은 순서로 확인하면 어디서 어긋났는지 빨리 찾습니다.
- 기동 로그:
The following 1 profile is active: "dev"같은 줄이 있는지 봅니다. default일 때는No active profile set, falling back to 1 default profile: "default"가 나옵니다. - 포트:
Tomcat started on port 8081처럼 기대한 포트인지 봅니다. /config응답:activeProfiles와serverPort,greeting값을 봅니다./greeting응답: 문구가 기대한 prefix와 suffix인지 봅니다.
앞에서 뒤로 갈수록 세부 값을 확인하는 순서입니다. 1번에서 Profile이 켜지지 않았다면 뒤 단계를 볼 필요가 없습니다.
성공 판정 기준
| 실행 | 성공 기준 |
|---|---|
| default | activeProfiles가 [], 포트 8080, Hello, devguna! |
| dev | activeProfiles가 ["dev"], 포트 8081, Hi (dev), devguna! |
| prod | activeProfiles가 ["prod"], 포트 8082, 16자 이름이 10자로 잘림 |
자주 하는 실수
| 실수 | 증상 | 해결 |
|---|---|---|
| dev로 켜고 8080으로 호출 | 연결 거부(해당 포트에서 수신 중이 아님) | 포트가 8081로 바뀐 것을 확인 |
--args 없이 bootRun에 --spring.profiles.active=dev만 붙임 |
Gradle이 인자를 앱에 전달하지 않음 | --args='--spring.profiles.active=dev' 형식 사용 |
| JAR 앞에 인자를 둠 | Unrecognized option |
JAR 파일명 뒤에 두기, 아래 “5. JAR 앞에 인자를 두었다” 절 참고 |
확인 문제
- JAR 파일로 실행할 때
--spring.profiles.active=dev는 명령의 어디에 두어야 하나요? - dev Profile로 실행했을 때
application-dev.yml에 적지 않은 키의 값은 어디서 오나요?
답: 1) JAR 뒤에 둡니다. 2) 기본 설정 파일(application.yml)의 값이 그대로 남습니다.
직접 해 보기
- default, dev, prod를 차례로 실행해 위 응답과 같은지 확인해 보세요. 포트가 다르므로 요청 주소의 포트를 맞춰야 합니다.
- dev로 실행한 서버를 끄지 않은 채 같은 명령을 한 번 더 실행하면 어떤 오류가 나는지 확인해 보세요. (메시지는 아래 “6. 포트가 이미 사용 중이다” 절에 있습니다.)
--spring.profiles.active=dev,prod처럼 둘을 함께 켜면 어느 쪽 값이 이길지 예상해 보세요. 이 Chapter에서는 확인하지 않았으니 직접 실행해 결과를 기록해 보세요.
설정 우선순위: 명령행, 환경 변수, 파일
같은 키가 여러 곳에 있으면 어느 값이 이길까요? 운영 서버에서 설정 파일을 고치지 않고 포트나 문구만 급히 바꿔야 하는 상황, 또는 컨테이너에서 환경 변수로 값을 넘기는 상황이 모두 이 질문에 달려 있습니다.
이 절에서는 Profile 파일의 값을 환경 변수와 명령행 인자로 덮어써 보고, 결과를 공식 문서의 순서와 대조합니다. 마지막으로 테스트에서 같은 일을 하는 방법도 봅니다.
실험: dev의 prefix를 덮어쓰기
dev Profile의 prefix는 Hi (dev)입니다. 같은 키를 환경 변수와 명령행 인자로 다시 지정해 응답이 어떻게 변하는지 보았습니다.
| 실행 조건 | 응답 |
|---|---|
| dev (아무것도 덮어쓰지 않음) | Hi (dev), devguna! |
dev + 명령행 --app.greeting.prefix=CLI |
CLI, devguna! |
dev + 환경 변수 APP_GREETING_PREFIX=ENV |
ENV, devguna! |
환경 변수 ENV와 명령행 CLI를 함께 지정 |
CLI, devguna! |
환경 변수 APP_GREETING_MAXLENGTH=5, 이름 abcdefghij |
Hello, abcde! |
각 줄에서 알 수 있는 것은 이렇습니다.
- 2번째 줄: 명령행 인자가 Profile 파일의 값을 이깁니다.
- 3번째 줄: 환경 변수도 Profile 파일의 값을 이깁니다.
- 4번째 줄: 둘이 겹치면 명령행이 환경 변수를 이깁니다.
- 5번째 줄:
max-length를 환경 변수로 줄 때 이름은APP_GREETING_MAXLENGTH입니다. 점(.)과 하이픈(-)을 없애거나 밑줄로 바꾸고 대문자로 쓰는 규칙입니다.
정리하면 이런 순서다
네 수단이 한 키를 두고 겨룰 때 최종값은 아래 순서로 정해집니다. 아래로(화살표 방향으로) 갈수록 우선순위가 높고, 뒤의 값이 앞의 값을 덮어씁니다. 위 실험 표의 네 번째 줄(환경 변수와 명령행 동시 지정 → CLI)이 이 순서를 그대로 보여 줍니다.
기본 설정 파일 (application.yml)
→ Profile 설정 파일 (application-dev.yml)
→ OS 환경 변수 (APP_GREETING_PREFIX)
→ 명령행 인자 (--app.greeting.prefix)
공식 문서(Externalized Configuration)에 이보다 많은 항목이 순서대로 나와 있지만, 이 예제에서 직접 확인한 범위는 위 네 단계입니다. 문서의 순서와 실험 결과가 일치했습니다.
이 순서가 실무에서 쓰이는 방식은 이렇습니다.
| 수단 | 주로 쓰는 때 |
|---|---|
| 기본 파일 | 모든 환경에 공통인 값 |
| Profile 파일 | 환경마다 다른 값(포트, 문구, 주소) |
| 환경 변수 | 컨테이너, 서버에서 배포 시점에 정하는 값, 비밀번호 |
| 명령행 인자 | 일회성 변경, 급한 조치, 디버깅 |
테스트에서 덮어쓰기
테스트에서는 같은 일을 애노테이션으로 합니다.
@SpringBootTest(properties = "app.greeting.prefix=Override")
class PropertyOverrideTests {
@Autowired
private GreetingProperties greeting;
@Test
void testPropertyWinsOverApplicationYml() {
assertEquals("Override", greeting.prefix());
assertEquals("!", greeting.suffix());
}
}
@SpringBootTest(properties = ...)는 테스트 안에서만 쓰는 우선순위 높은 설정입니다. prefix만 덮어썼고 suffix는 파일의 값 !가 그대로라는 점이 키 단위 덮어쓰기를 다시 확인해 줍니다.
Profile은 @ActiveProfiles로 지정합니다.
@Nested
@SpringBootTest
@AutoConfigureMockMvc
@ActiveProfiles("dev")
class Dev {
@Autowired
MockMvc mockMvc;
@Test
void overridesPrefixOnly() throws Exception {
mockMvc.perform(get("/greeting").param("name", "devguna"))
.andExpect(status().isOk())
.andExpect(content().string("Hi (dev), devguna!"));
mockMvc.perform(get("/config"))
.andExpect(jsonPath("$.activeProfiles[0]").value("dev"))
.andExpect(jsonPath("$.owner").value("devguna"))
.andExpect(jsonPath("$.greeting.suffix").value("!"))
.andExpect(jsonPath("$.greeting.maxLength").value(20));
}
}
dev에서 덮어쓰지 않은 owner, suffix, maxLength가 기본 값 그대로인지까지 함께 확인합니다. @Nested는 테스트 클래스 안에 클래스를 중첩해 Profile별 테스트를 묶는 JUnit 기능입니다. 이 Chapter의 테스트는 모두 6건이고 통과했습니다.
| 테스트 클래스 | 건수 | 확인하는 것 |
|---|---|---|
Ch02ApplicationTests |
1 | 컨텍스트 로딩 |
DefaultProfileTests |
2 | 기본 설정, 긴 이름 자르기 |
ProfileTests.Dev |
1 | dev가 prefix만 덮어쓰고 나머지는 유지 |
ProfileTests.Prod |
1 | prod가 세 값을 덮어씀 |
PropertyOverrideTests |
1 | 테스트 속성이 파일을 이김 |
비밀 값은 어디에
환경 변수가 파일보다 우선하고 저장소에 남지 않는다는 점이 중요합니다. 데이터베이스 비밀번호나 API 키를 application-prod.yml에 적어 저장소에 올리면 안 되고, 환경 변수로 넘기는 것이 기본 방법입니다. 이후 Chapter에서 데이터베이스 접속 정보를 다룰 때 이 방식을 그대로 씁니다.
환경 변수 이름 만드는 규칙
실험에서 app.greeting.max-length의 환경 변수 이름을 APP_GREETING_MAXLENGTH로 지었습니다. 변환 규칙을 정리하면 이렇습니다.
| 설정 키 | 환경 변수 이름 | 규칙 |
|---|---|---|
app.greeting.prefix |
APP_GREETING_PREFIX |
점(.)을 밑줄(_)로, 대문자로 |
app.greeting.max-length |
APP_GREETING_MAXLENGTH |
하이픈(-)은 없애거나 밑줄로 바꿈 |
환경 변수 이름은 셸에 따라 점이나 하이픈을 허용하지 않는 경우가 많아서, 이런 규칙으로 바꿔 쓰는 것이 Boot의 관례입니다.
우선순위가 필요한 상황
| 상황 | 쓰는 수단 | 이유 |
|---|---|---|
| 컨테이너에서 DB 주소를 환경마다 다르게 | 환경 변수 | 이미지를 다시 만들지 않고 실행 시점에 주입 |
| 장애 중 로그 수준이나 문구를 잠깐 바꿈 | 명령행 인자 | 파일을 고치지 않고 재시작만으로 변경 |
| 테스트에서 특정 값을 고정 | @SpringBootTest(properties = ...) |
테스트 안에서만 유효하고 다른 테스트에 번지지 않음 |
이 흐름은 뒤에서 컨테이너와 CI를 다룰 때 실제로 쓰입니다. 환경 변수로 접속 정보를 넘기는 모습은 Chapter 22 운영의 compose 설정에서 볼 수 있습니다.
자주 하는 실수
| 실수 | 증상 | 해결 |
|---|---|---|
| 환경 변수 이름에 점이나 하이픈을 그대로 사용 | 셸에서 지정 자체가 안 되거나 값이 적용되지 않음 | 대문자와 밑줄로 변환 |
| 환경 변수를 지정했는데 적용되지 않는다고 착각 | 실행한 셸과 앱을 띄운 셸이 다름 | 같은 셸에서 export 후 실행하거나 명령 앞에 변수를 붙임 |
| 값이 안 바뀌어 파일만 계속 수정 | 더 높은 우선순위의 수단이 값을 덮고 있음 | 환경 변수·명령행에 같은 키가 있는지 확인 |
확인 문제
- 같은 키를 기본 설정 파일, Profile 파일, 환경 변수, 명령행 인자가 모두 지정하면 어느 값이 최종값이 되나요?
- 우선순위는 어느 방향으로 높아지나요?
답: 1) 명령행 인자의 값입니다. 이 절의 실험에서는 환경 변수와 명령행을 동시에 지정하면 CLI가 나왔습니다. 2) 기본 파일, Profile 파일, 환경 변수, 명령행 순으로 아래로 갈수록 높고, 뒤의 값이 앞의 값을 덮어씁니다.
직접 해 보기
- dev로 실행하면서
--app.greeting.prefix=CLI를 붙여CLI, devguna!가 나오는지 확인해 보세요. - 환경 변수를 같이 지정해 보세요. Linux/macOS는
APP_GREETING_PREFIX=ENV ./gradlew ...bootRun --args='--spring.profiles.active=dev'처럼 실행합니다. Windows에서는 환경 변수 지정 방법이 다르므로 직접 확인해 보세요. PropertyOverrideTests의properties값을app.greeting.suffix=?로 바꾸고suffix검증으로 고쳐 테스트를 돌려 보세요.
자주 만나는 오류와 해결 방법
설정 오류는 두 종류로 나뉩니다. 서버가 아예 뜨지 않는 오류는 메시지가 나오니 고치기 쉽습니다. 더 위험한 것은 서버가 멀쩡히 떠서 기대와 다른 값으로 조용히 동작하는 경우입니다. 아무 오류도 나지 않기 때문입니다.
이 절에서는 이 Chapter의 예제를 일부러 한 군데씩 틀리게 만들어 얻은 실제 결과를 정리합니다. 모두 같은 코드를 바꿔 테스트를 돌린 뒤 되돌린 것이고, 저장소에는 올리지 않았습니다.
조용히 틀리는 오류
1. 오타를 내도 조용히 기본값으로 돈다
application-dev.yml의 prefix:를 prefx:로 틀렸습니다. 서버는 정상으로 뜨고 한 테스트만 실패했습니다.
overridesPrefixOnly()
Response content expected:<Hi (dev), devguna!> but was:<Hello, devguna!>
prefx는 어떤 설정과도 연결되지 않아 그냥 무시되고, 기본 파일의 Hello가 쓰였습니다. 오류가 없으므로 값이 기대와 다르면 키의 철자와 들여쓰기를 먼저 봅니다. 이 예제처럼 설정 값을 응답으로 확인하는 테스트가 있어야 드러납니다.
2. @ConfigurationProperties의 prefix를 틀리면
prefix = "app.greeting"을 "app.greetings"로 바꾸면 모든 설정이 기본값(@DefaultValue)으로 돌아갑니다. 6건 중 3건이 실패했습니다.
overridesPrefixSuffixAndMaxLength()
expected:<Welcome, abcdefghij.> but was:<Hello, abcdefghijklmnop!>
testPropertyWinsOverApplicationYml()
expected: <Override> but was: <Hello>
이 경우에도 오류는 나지 않습니다. @DefaultValue가 있으면 바인딩이 실패해도 기본값으로 채워지기 때문에, 설정이 전혀 적용되지 않은 것을 눈치채기 어렵습니다. 편리한 기본값이 오류를 가리는 경우입니다.
서버가 뜨지 않는 오류
3. Failed to bind properties under ‘app.greeting.max-length’
숫자 칸에 문자(abc)를 적으면 이번에는 서버가 뜨지 않습니다. 6건 중 5건이 실패했습니다.
Failed to bind properties under 'app.greeting.max-length' to int
Failed to convert from type [java.lang.String] to type [@org.springframework.boot.context.properties.bind.DefaultValue int] for value [abc]
메시지가 키 이름(app.greeting.max-length)과 잘못된 값(abc)을 정확히 알려 줍니다. 이쪽은 오히려 고치기 쉬운 오류입니다.
4. 설정 클래스를 등록하지 않았다
시작 클래스의 @ConfigurationPropertiesScan을 빼면 기본값으로 동작하는 것이 아니라 기동이 실패합니다.
APPLICATION FAILED TO START
Parameter 1 of constructor in com.jqdom.curriculum.ch02.ConfigController required a bean of type 'com.jqdom.curriculum.ch02.GreetingProperties' that could not be found.
등록되지 않은 클래스는 존재하지 않는 것과 같습니다. @ConfigurationPropertiesScan이나 @EnableConfigurationProperties를 확인하세요.
실행 환경 오류
5. JAR 앞에 인자를 두었다
Unrecognized option: --spring.profiles.active=dev
Error: Could not create the Java Virtual Machine.
--spring.profiles.active=dev를 JAR 파일명 앞에 두면 Boot가 읽기 전에 JVM이 먼저 옵션으로 해석하려다 막힙니다. java -jar app.jar --spring.profiles.active=dev처럼 JAR 뒤에 지정합니다.
6. 포트가 이미 사용 중이다
Port 8081 was already in use.
같은 Profile을 이미 실행 중이면 포트가 겹칩니다. 기존 프로세스를 끄거나 --server.port=...로 바꿉니다.
7. 파일 이름 규칙이 틀렸다
application_dev.yml처럼 밑줄을 쓰면 Profile을 켜도 읽히지 않습니다. 이름은 application-{profile}.yml 형식이어야 합니다. 이 오류는 별도 메시지가 없이 조용히 무시됩니다. 이 실험은 하지 않았고, 공식 문서의 파일 이름 규칙에 따른 설명입니다.
오류를 찾아가는 순서
증상이 서버가 뜨는지 여부에 따라 접근이 갈립니다. 서버가 안 떴다면 콘솔 로그의 원인 줄을 읽고, 떴다면 /config 응답으로 실제로 적용된 값을 확인합니다. 응답이 맞다면 설정 문제가 아닙니다.
이 Chapter에서 직접 재현해 본 문법 오류
YAML 문법에 관한 오류는 앞의 “YAML을 틀리면 어떻게 되나” 절에서 실제 메시지를 정리했습니다. 탭 문자, 콜론 뒤 공백 누락, 들여쓰기 불일치는 서버가 뜨지 않고, 따옴표 없는 !는 값이 빈 문자열이 되어 조용히 틀립니다. 필수 키에 기본값이 없을 때의 Could not resolve placeholder 오류는 앞의 “기본값이 없으면 서버가 뜨지 않는다” 절에서 확인했습니다.
증상별 정리
| 증상 | 가장 먼저 볼 것 |
|---|---|
| 서버는 뜨는데 값이 기본값 | 키 철자, 들여쓰기, @ConfigurationProperties의 prefix |
Failed to bind properties under '키' |
메시지의 키와 값의 타입 |
required a bean of type '...Properties' |
@ConfigurationPropertiesScan 또는 @EnableConfigurationProperties |
Unrecognized option: --spring... |
인자가 JAR 파일명 뒤에 있는지 |
Port ... was already in use |
이미 실행 중인 서버, --server.port |
| Profile을 켰는데 값이 안 바뀜 | 파일 이름 application-{profile}.yml, 활성 Profile(/config) |
지금의 한계
- Windows 실행은 검증하지 못했습니다.
- 외부 설정 서버, 암호화된 설정, 한 파일 안에서
---로 Profile을 나누는 방식(multi-document)은 다루지 않았습니다. - 로그 수준(
logging.level)은 이 예제에 DEBUG 로그를 남기는 코드가 없어 Profile별 차이를 보여 줄 수 없으므로 다루지 않았습니다.
직접 해 보기
application-dev.yml의prefix:를prefx:로 틀리게 바꿔build를 돌려, 어떤 테스트가 실패하는지 확인하고 되돌려 보세요.max-length: abc로 바꿔 메시지에서 키 이름이 어떻게 나오는지 읽어 보세요.- 오류 메시지를 만났을 때는 맨 아래
Caused by부터 읽는 습관을 유지하세요. 읽는 법은 Chapter 01의 “오류 메시지는 맨 아래 Caused by부터 읽습니다” 절에 있습니다.
이 Chapter를 마치며
설정을 읽는 코드는 어렵지 않지만, 짐작과 실제 결과가 반대인 곳이 두 군데 있었습니다. 설정 클래스를 등록하지 않으면 기본값으로 동작할 것 같지만 기동이 실패하고, JAR 앞에 둔 인자는 Boot에 닿기 전에 JVM에서 막힙니다. 둘 다 직접 실행해 확인해 두면 같은 실수를 피할 수 있습니다.
이제 같은 JAR를 Profile, 환경 변수, 명령행 인자로 다르게 동작시킬 수 있고 우선순위도 결과로 확인했습니다. 비밀번호 같은 민감한 값을 안전하게 관리하는 방법은 아직 다루지 않았습니다.
용어와 참고 자료
아래 표는 이 Chapter에 나온 용어와 참고한 사이트를 모은 것입니다. 앞 Chapter의 용어는 Chapter 01 프로젝트 시작하기를 참고하세요.
참고한 자료
- Spring Boot Reference: Externalized Configuration: 덮어쓰기 우선순위 목록을 확인했습니다. 환경 변수보다 명령행 인자가 뒤에 있다는 순서를 보고, 직접 실행한 결과(명령행이 이긴다)가 문서와 맞는지 대조했습니다.
- Spring Boot Reference: Profiles:
spring.profiles.active로 Profile을 켜는 방법과application-{profile}파일 규칙을 확인했습니다. - YAML 공식 사이트
- Spring Boot Reference: Configuration Metadata
설정 파일
| 용어 | 설명 |
|---|---|
application.yml |
Boot가 자동으로 읽는 기본 설정 파일입니다. 클래스패스 루트(src/main/resources)에 둡니다. |
| YAML | 들여쓰기로 구조를 표현하는 설정 형식입니다. 탭을 쓸 수 없고 공백으로 들여씁니다. |
.properties |
키=값 한 줄씩 적는 설정 형식입니다. YAML과 같은 키를 뜻합니다. |
| kebab-case | max-length처럼 소문자와 하이픈으로 쓰는 키 표기입니다. Boot가 권장합니다. |
Profile
| 용어 | 설명 |
|---|---|
| Profile | 실행 환경을 구분하는 이름표입니다. 켜진 Profile의 설정 파일이 기본 설정 위에 덮어씁니다. |
| default Profile | Profile을 지정하지 않았을 때 자동으로 쓰이는 이름입니다. application.yml만 적용됩니다. |
| 활성 Profile | 지금 켜져 있는 Profile입니다. spring.profiles.active로 정하고 Environment로 조회합니다. |
| 키 단위 덮어쓰기 | 환경별 파일이 같은 키만 바꾸고 나머지는 기본 값을 유지하는 규칙입니다. |
설정 읽기
| 용어 | 설명 |
|---|---|
@Value |
설정 키 하나를 필드나 생성자 인자로 주입하는 애노테이션입니다. ${키:기본값} 형식으로 기본값을 줍니다. |
Environment |
활성 Profile과 모든 설정 값을 담은 Spring의 실행 환경 객체입니다. |
@ConfigurationProperties |
같은 접두사의 설정을 객체 하나로 묶어 주입합니다. record와 함께 쓰면 값이 바뀌지 않는 설정 객체가 됩니다. |
@DefaultValue |
@ConfigurationProperties 객체에서 키가 없을 때 쓸 값을 정합니다. |
@ConfigurationPropertiesScan |
패키지 아래의 설정 클래스를 찾아 Bean으로 등록합니다. 없으면 설정 객체를 주입받을 수 없습니다. |
| relaxed binding | max-length, maxLength, MAXLENGTH처럼 표기가 달라도 같은 키로 보는 규칙입니다. |
덮어쓰기와 우선순위
| 용어 | 설명 |
|---|---|
| 명령행 인자 | 실행할 때 --키=값으로 넘기는 설정입니다. 이 예제에서 가장 우선순위가 높았습니다. |
| 환경 변수 | OS에 설정한 변수입니다. 키를 대문자와 밑줄로 바꿔 쓰며 파일보다 우선합니다. |
| 설정 우선순위 | 같은 키가 여러 곳에 있을 때 이기는 순서입니다. 파일 < Profile 파일 < 환경 변수 < 명령행 인자. |
@ActiveProfiles |
테스트에서 Profile을 지정하는 애노테이션입니다. |
@SpringBootTest(properties = ...) |
테스트 안에서만 쓰는 설정 덮어쓰기입니다. |
@Nested |
테스트 클래스 안에 클래스를 중첩해 묶는 JUnit 기능입니다. |
오류
| 용어 | 설명 |
|---|---|
Failed to bind properties under '키' |
설정 값을 객체 필드 타입으로 바꾸지 못했다는 오류입니다. 키와 값이 메시지에 나옵니다. |
| 조용한 기본값 | 키 오타나 prefix 불일치로 설정이 적용되지 않아 오류 없이 기본 값으로 동작하는 상태입니다. |
직접 해보기
./gradlew :examples:ch02-config-profile:bootRun으로 default를 켜고,--args='--spring.profiles.active=dev'와 prod로 차례로 다시 실행해/greeting?name=devguna응답과 포트가 “default, dev, prod 실행해 비교하기” 절의 결과와 같은지 확인해 보세요.- prod로 실행한 상태에서
/greeting?name=abcdefghijklmnop을 호출하기 전에max-length: 10규칙으로 응답을 먼저 예상하고, 실제 응답과 비교해 보세요. - dev로 실행하면서
--app.greeting.prefix=CLI를 붙이고, 이어서 환경 변수APP_GREETING_PREFIX=ENV까지 함께 지정해 어느 값이 이기는지 “설정 우선순위: 명령행, 환경 변수, 파일” 절의 순서로 설명해 보세요. - 시작 클래스에서
@ConfigurationPropertiesScan을 지우거나application-dev.yml의prefix:를prefx:로 바꿔 빌드한 뒤, 오류 메시지의 맨 아래Caused by에서 원인 키를 찾고 원래대로 되돌려 보세요. max-length를max_length로 바꿔 relaxed binding이 어디까지 이름 차이를 받아 주는지/config응답으로 확인해 보세요.
이번 장의 정리
- 환경에 따라 달라지는 값은 코드가 아니라
application.yml에 두고, YAML의 공백 들여쓰기 계층은 점으로 이어진 키(app.greeting.prefix)가 됩니다. - Profile을 켜면
application-{profile}.yml이 기본 파일 위에 키 단위로 덮어쓰고, 지정하지 않으면default로 기본 파일만 적용됩니다. - 값 하나는
@Value("${키:기본값}"), 활성 Profile과 임의의 키는Environment, 같은 접두사의 설정 묶음은@ConfigurationPropertiesrecord로 읽습니다. 설정 클래스는@ConfigurationPropertiesScan으로 등록해야 합니다. - 같은 JAR를
--spring.profiles.active로 default, dev, prod에서 실행해 포트와 문구가 달라지는 것을/config와/greeting응답으로 확인했습니다. - 우선순위는 기본 파일, Profile 파일, 환경 변수, 명령행 인자 순서이고 뒤쪽이 이깁니다. 비밀 값은 파일이 아니라 환경 변수로 넘깁니다.
- 키 오타와 prefix 불일치는 오류 없이 기본값으로 동작하므로 응답과 테스트로 확인하고, 기동 실패는 메시지의 키와 값의 타입부터 읽습니다.
이 Chapter 내내 컨트롤러는 Environment와 설정 객체를 생성자로 받았습니다. 다음 Chapter 03 IoC, DI, Bean에서는 그 객체들이 누구에 의해 어떻게 만들어지고 연결되는지를 다룹니다.