스프링 부트에서 데이터 베이스 설정이나 여러 설정을 하는 applicaion.yaml 에는 수천 개의 속성이 존재하는 것 같다.
https://docs.spring.io/spring-boot/appendix/application-properties/index.html
Common Application Properties :: Spring Boot
docs.spring.io
많아도 너무 많다 그런데 그 걸 다 알고 있는 것은 말도 안 되는 일이다. 실제 현업 프로젝트에서도 자주 사용되는 속성은 몇 개 안 될 것 같다. 그렇다면 일단 자주 사용되는 속성을 몇 개 정리해 두고 필요할 때 다시 꺼내 보는 용도로 정리를 하려고 한다.
1. 기본 서버 설정
가장 기본이 되는 애플리케이션 식별 정보와, 최신 Java 버전을 사용할 때 성능을 극대화하기 위한 설정
server:
port: 8080 # 기본 포트 설정 (충돌 시 변경)
shutdown: graceful # 배포 중단 시 처리 중인 요청을 완료하고 종료 (우아한 종료)
spring:
application:
name: my-api-service # 로깅이나 모니터링 시 식별을 위한 앱 이름
threads:
virtual:
enabled: true # Java 21+ 사용 시 필수. 가상 스레드를 활성화하여 동시성 처리 성능 극대화 [4-6]- graceful shutdown은 프로세스 종료 시 처리하고 있는 요청을 끝까지 처리할 수 있는 기능이라고 한다.
2. 데이터베이스 및 JPA (가장 많이 쓰이는 조합)
DB 연결은 로컬(개발)과 운영(Prod) 환경에서 설정이 달라지는 대표적인 부분이다.
A. 로컬 개발용 (H2 인메모리 DB)
빠른 개발과 테스트를 위해 콘솔을 활성화하고 SQL을 눈으로 확인하는 설정이다.
spring:
datasource:
url: jdbc:h2:mem:testdb # 인메모리 DB 주소
username: sa
password: # 보통 공란
driver-class-name: org.h2.Driver
h2:
console:
enabled: true # 브라우저에서 H2 콘솔 접근 허용 (/h2-console)
jpa:
hibernate:
ddl-auto: create-drop # 시작 시 테이블 생성, 종료 시 삭제
show-sql: true # 실행되는 SQL을 콘솔에 출력
properties:
hibernate:
format_sql: true # SQL을 보기 좋게 줄바꿈하여 출력B. 운영 환경용 (MySQL/PostgreSQL)
spring:
datasource:
url: jdbc:postgresql://prod-db-url:5432/mydb
driver-class-name: org.postgresql.Driver
username: myuser
password: mypassword
jpa:
hibernate:
ddl-auto: validate # 운영에서는 절대 create/update를 쓰지 않고 스키마 검증만 수행
open-in-view: false # 트랜잭션 범위 밖에서 DB 커넥션을 점유하지 않도록 설정 (성능 최적화)3. 로깅 (Logging) 및 모니터링
최신 Spring Boot 3.4부터는 구조화된 로깅(Structured Logging)을 지원하여 로그 분석 시스템(ELK 등)과 연동하기 쉬워졌다.
logging:
level:
root: INFO # 기본 로깅 레벨
com.myapp: DEBUG # 내 패키지는 디버그 레벨로 상세하게
org.springframework.web: INFO
org.hibernate.SQL: DEBUG # 쿼리 확인용 (운영에서는 INFO 권장)
# Spring Boot 3.4+ 기능: JSON 로그 출력 (운영 환경 추천)
structured:
format:
console: ecs # Elastic Common Schema 포맷의 JSON 로그 출력4. API 에러 처리 및 문서화 (Swagger)
REST API 개발 시 클라이언트에게 명확한 에러를 전달하고 문서를 자동화하는 설정이다.
spring:
mvc:
problemdetails:
enabled: true # RFC 7807 표준 에러 응답(ProblemDetail) 자동 활성화
springdoc: # Swagger/OpenAPI 설정
api-docs:
path: /api-docs # OpenAPI JSON 문서 경로
swagger-ui:
path: /swagger-ui.html # Swagger UI 접속 경로
enabled: true # 운영 환경에서는 false로 꺼두기도 함5. Actuator (운영 모니터링)
애플리케이션의 상태를 체크하기 위해 Actuator를 사용할 때 주로 쓰는 설정이다. 보안상 필요한 것만 노출해야 한다.
management:
endpoints:
web:
exposure:
include: "health, info, metrics, prometheus" # 노출할 엔드포인트 목록
endpoint:
health:
show-details: always # ⚠️ 주의: 운영 환경에서는 보안을 위해 'never' 또는 'when_authorized' 권장6. 환경별 설정 분리 (Profiles)
Spring Boot 2.4 버전부터는 spring.config.activate.on-profile 속성을 사용하여 하나의 파일(application.yml) 안에서 논리적으로 설정을 분리하거나, 파일 자체를 나누어 관리하는 것을 권장한다.
설정 방법: Multi-Document (--- 구분자 사용) 하나의 YAML 파일 안에서 --- (하이픈 3개)를 사용하여 문서를 나누고, 각 블록이 어떤 환경(Profile)에서 동작할지 지정하는 방식이다. 한눈에 모든 설정을 볼 수 있어 관리가 편리하다.
# --------------------------------------------------------
# 1. 공통 설정 (Common)
# 모든 환경에 기본적으로 적용되는 설정
# --------------------------------------------------------
spring:
application:
name: my-api-service
profiles:
active: local # 기본적으로 활성화할 프로필 (default: local)
---
# --------------------------------------------------------
# 2. 로컬 개발 환경 (Local)
# 'local' 프로필이 활성화되었을 때만 적용
# --------------------------------------------------------
spring:
config:
activate:
on-profile: local # [핵심 속성] 이 설정이 적용될 프로필 지정
datasource:
url: jdbc:h2:mem:testdb
jpa:
hibernate:
ddl-auto: create-drop
---
# --------------------------------------------------------
# 3. 운영 환경 (Prod)
# 'prod' 프로필이 활성화되었을 때만 적용
# --------------------------------------------------------
spring:
config:
activate:
on-profile: prod # [핵심 속성] prod 프로필일 때만 동작
datasource:
url: jdbc:postgresql://prod-db:5432/mydb
jpa:
hibernate:
ddl-auto: validate
open-in-view: false실행 방법 (운영 배포 시) JAR 파일을 실행할 때, 환경 변수나 인자값으로 활성 프로필을 바꿔주면 된다.
# 운영 환경 프로필(prod)로 실행
java -jar my-app.jar --spring.profiles.active=prod