Spring Boot application.properties 완전 정복 — 실무 핵심 설정 모음
Spring Boot로 프로젝트를 시작할 때, 가장 먼저 마주치는 파일이 바로 application.properties입니다. 설정 하나 잘못 건드렸다가 서버가 안 뜨거나, DB 연결이 끊기거나, 로그가 쏟아지는 경험 한 번쯤 해보셨죠? 이 글에서는 실무에서 자주 쓰는 핵심 설정들을 한 곳에 정리했습니다. 초보자도 바로 복사해서 쓸 수 있도록 예시 코드와 함께 설명해드릴게요.
1. application.properties란 무엇인가요?
application.properties는 Spring Boot 애플리케이션의 동작 방식을 제어하는 설정 파일입니다. 쉽게 말해, “이 앱은 몇 번 포트에서 실행할 건지”, “어떤 DB에 붙을 건지”, “로그는 얼마나 자세히 남길 건지” 같은 것들을 이 파일 하나로 조정할 수 있어요.
Spring Boot는 이 파일을 프로젝트 시작 시점에 자동으로 읽어들이기 때문에, 코드를 수정하지 않고도 동작을 바꿀 수 있다는 게 가장 큰 장점입니다. 파일 위치는 보통 src/main/resources/application.properties입니다.
비슷한 역할을 하는 application.yml도 있는데, 둘의 차이는 표기 형식입니다. .properties는 key=value 형식으로 단순하고 직관적이며, .yml은 들여쓰기 기반의 계층 구조로 복잡한 설정을 표현하기에 유리합니다. 이 글에서는 .properties 형식을 기준으로 설명합니다.
2. 서버 기본 설정 — 포트와 컨텍스트 경로
가장 자주 바꾸는 설정 중 하나가 바로 서버 포트입니다. Spring Boot는 기본적으로 8080 포트를 사용하지만, 다른 서비스와 충돌이 날 때는 포트를 바꿔야 하죠.
properties
# 서버 포트 설정
server.port=8080
# 컨텍스트 패스 설정 (예: http://localhost:8080/api)
server.servlet.context-path=/api
# 서버 연결 타임아웃 (밀리초 단위)
server.connection-timeout=20000
# Tomcat 최대 스레드 수
server.tomcat.max-threads=200
# HTTP 요청 최대 헤더 크기
server.max-http-header-size=8KB포트를 0으로 설정하면 Spring Boot가 사용 가능한 포트를 자동으로 골라줍니다. 테스트 환경에서 포트 충돌을 피하고 싶을 때 유용한 팁이에요.
컨텍스트 패스를 /api로 설정하면 모든 엔드포인트 앞에 /api가 붙게 됩니다. 예를 들어 기존에 http://localhost:8080/users이던 주소가 http://localhost:8080/api/users로 바뀝니다. API 서버를 구성할 때 자주 쓰는 패턴입니다.
3. 데이터베이스 연결 설정 — MySQL, PostgreSQL, H2
실무 프로젝트에서 DB 설정은 빠질 수 없습니다. application.properties에서 데이터소스를 설정하는 방법을 DB별로 정리해드릴게요.
MySQL 연결 설정
properties
spring.datasource.url=jdbc:mysql://localhost:3306/mydb?useSSL=false&serverTimezone=Asia/Seoul&characterEncoding=UTF-8
spring.datasource.username=root
spring.datasource.password=yourpassword
spring.datasource.driver-class-name=com.mysql.cj.jdbc.DriverPostgreSQL 연결 설정
properties
spring.datasource.url=jdbc:postgresql://localhost:5432/mydb
spring.datasource.username=postgres
spring.datasource.password=yourpassword
spring.datasource.driver-class-name=org.postgresql.DriverH2 인메모리 DB (개발/테스트용)
properties
spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.driver-class-name=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=
# H2 콘솔 활성화 (브라우저에서 DB 조회 가능)
spring.h2.console.enabled=true
spring.h2.console.path=/h2-consoleH2 콘솔을 활성화하면 브라우저에서 http://localhost:8080/h2-console에 접속해 SQL을 직접 실행해볼 수 있어서 개발 초기에 매우 편리합니다. 단, 운영 환경에서는 반드시 비활성화해야 합니다.
4. JPA / Hibernate 설정 — DDL과 SQL 출력 옵션
Spring Boot에서 JPA(Java Persistence API)를 쓴다면 아래 설정들이 핵심입니다.
properties
# DDL 자동 처리 전략
# none | validate | update | create | create-drop
spring.jpa.hibernate.ddl-auto=update
# SQL 콘솔 출력 여부
spring.jpa.show-sql=true
# SQL 포맷팅 (들여쓰기 적용)
spring.jpa.properties.hibernate.format_sql=true
# Hibernate 방언 설정 (DB 종류에 맞게)
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQL8Dialect
# 지연 로딩 관련 (Open Session In View)
spring.jpa.open-in-view=falseddl-auto 옵션은 매우 중요합니다. 각 값의 의미를 정확히 알고 써야 해요.
| 옵션 | 설명 | 추천 환경 |
|---|---|---|
none | 아무것도 하지 않음 | 운영 |
validate | 엔티티와 테이블 구조 검증만 | 운영 |
update | 변경된 부분만 반영 | 개발 |
create | 시작 시 테이블 새로 생성 | 개발/테스트 |
create-drop | 시작 시 생성, 종료 시 삭제 | 테스트 |
운영 환경에서 create나 create-drop을 쓰면 데이터가 전부 날아갑니다. 꼭 none 또는 validate를 사용하세요.
spring.jpa.open-in-view=false로 설정하는 것도 권장됩니다. 기본값이 true인데, 트랜잭션 범위 밖에서 쿼리가 실행되는 문제를 막기 위해 false로 바꾸는 게 좋은 습관입니다.
5. 로깅 설정 — 레벨과 파일 출력
로그 설정은 디버깅의 핵심입니다. 너무 적으면 문제 파악이 안 되고, 너무 많으면 로그 파일이 터집니다. 적절히 조절하는 방법을 알아볼게요.
properties
# 전체 로그 레벨 설정
logging.level.root=INFO
# 특정 패키지만 DEBUG로 설정
logging.level.com.example.myapp=DEBUG
# Spring Security 로그 (인증 문제 디버깅 시)
logging.level.org.springframework.security=DEBUG
# SQL 파라미터 값 출력 (Hibernate)
logging.level.org.hibernate.type.descriptor.sql=TRACE
# 로그 파일 경로
logging.file.name=logs/application.log
# 로그 파일 최대 크기
logging.logback.rollingpolicy.max-file-size=10MB
# 로그 파일 보관 기간 (일)
logging.logback.rollingpolicy.max-history=30로그 레벨은 TRACE → DEBUG → INFO → WARN → ERROR 순서로 점점 덜 자세해집니다. 개발 중에는 DEBUG, 운영 중에는 INFO 또는 WARN을 많이 씁니다.
특정 패키지만 로그 레벨을 따로 지정할 수 있어서, 내가 만든 코드(com.example.myapp)는 DEBUG로, 스프링 내부 코드는 INFO로 설정하는 식으로 깔끔하게 관리할 수 있습니다.
6. 프로파일 설정 — 개발/운영 환경 분리
실무에서는 개발 환경(dev)과 운영 환경(prod)의 설정이 다를 때가 많습니다. Spring Boot는 프로파일(Profile) 기능으로 이를 깔끔하게 분리할 수 있어요.
기본 설정 파일 구조
src/main/resources/
├── application.properties ← 공통 설정
├── application-dev.properties ← 개발 환경 설정
└── application-prod.properties ← 운영 환경 설정application.properties (공통)
properties
spring.application.name=my-spring-app
# 활성화할 프로파일 지정
spring.profiles.active=devapplication-dev.properties
properties
server.port=8080
spring.datasource.url=jdbc:h2:mem:devdb
spring.jpa.hibernate.ddl-auto=create-drop
spring.jpa.show-sql=true
logging.level.root=DEBUGapplication-prod.properties
properties
server.port=80
spring.datasource.url=jdbc:mysql://prod-server:3306/proddb
spring.jpa.hibernate.ddl-auto=validate
spring.jpa.show-sql=false
logging.level.root=WARN운영 서버에 배포할 때는 spring.profiles.active=prod로 바꾸거나, 실행 명령어에 -Dspring.profiles.active=prod 옵션을 추가하면 됩니다. 민감한 운영 DB 비밀번호는 환경변수로 주입하는 방식도 함께 고려해보세요.
7. 그 외 자주 쓰는 설정 모음
마지막으로 실무에서 종종 필요한 기타 설정들을 정리했습니다.
Spring MVC / 인코딩 설정
properties
# 응답 인코딩
server.servlet.encoding.charset=UTF-8
server.servlet.encoding.enabled=true
server.servlet.encoding.force=true
# 날짜 포맷 (JSON 응답)
spring.jackson.date-format=yyyy-MM-dd HH:mm:ss
spring.jackson.time-zone=Asia/Seoul파일 업로드 설정
properties
# 파일 업로드 활성화
spring.servlet.multipart.enabled=true
# 단일 파일 최대 크기
spring.servlet.multipart.max-file-size=10MB
# 요청 전체 최대 크기
spring.servlet.multipart.max-request-size=50MBSpring Actuator (모니터링)
properties
# 모든 엔드포인트 노출
management.endpoints.web.exposure.include=*
# 특정 엔드포인트만 노출 (권장)
management.endpoints.web.exposure.include=health,info,metrics
# Actuator 경로 변경
management.endpoints.web.base-path=/actuatorThymeleaf 설정 (템플릿 엔진)
properties
# 캐시 비활성화 (개발 시 자동 반영)
spring.thymeleaf.cache=false
spring.thymeleaf.prefix=classpath:/templates/
spring.thymeleaf.suffix=.html결론 — application.properties, 이제 두렵지 않죠?
application.properties는 Spring Boot 프로젝트의 심장부와 같습니다. 서버 포트, DB 연결, JPA 전략, 로깅 레벨, 프로파일 분리까지 — 이 파일 하나로 애플리케이션의 거의 모든 동작을 제어할 수 있어요.
오늘 다룬 내용을 간단히 요약하면 이렇습니다.
- 서버 설정: 포트, 컨텍스트 패스, Tomcat 튜닝
- DB 설정: MySQL, PostgreSQL, H2 각각의 연결 방법
- JPA 설정:
ddl-auto옵션을 환경에 맞게 신중하게 선택 - 로깅 설정: 패키지별 레벨 조절과 파일 출력
- 프로파일 분리: 개발과 운영 환경을 파일로 깔끔하게 나누기
지금 당장 여러분의 application.properties 파일을 열어서, 불필요한 설정은 정리하고 빠진 설정은 채워보세요. 작은 설정 하나가 성능과 안정성에 큰 차이를 만들어냅니다.