Spring Boot application.yml 실전 가이드 ① – 구조 이해와 설정 예제 모음

Spring Boot로 백엔드 애플리케이션을 개발할 때 application.yml 파일은 거의 반드시 만나게 되는 핵심 설정 파일입니다.
초기에는 복잡하고 생소하게 느껴질 수 있지만, 프로젝트 규모가 커질수록 이 파일을 얼마나 잘 설계했는지가 유지 보수성과 개발 효율성에 큰 영향을 주게 됩니다.

이 글에서는 application.yml이 어떤 파일인지, 기본 문법은 어떤지, 그리고 실무에서 자주 사용하는 설정 항목들을 실제 예제와 함께 "이 값은 무엇을 의미하는가" 중심으로 설명합니다.

---

1. application.yml이란?

Spring Boot의 환경 설정 파일입니다. 다음과 같은 내용을 정의합니다.

• 서버 포트 번호
• DB 접속 정보
• 파일 업로드 관련 설정
• 메일/도메인 등 서비스 운영 정보
• 인증, API 키 등 보안 관련 값
• 실행 환경 구분(dev, prod 등)

---

2. 기본 문법 요약

server: port: 8080

my-list:
  - apple
  - banana

• : 기준으로 key-value를 표현하고,
• 계층 구조는 들여쓰기로 표현하며,
• **공백(Space)**을 사용해야 하며 Tab은 오류 원인이 됩니다.

---

3. 실무에서 자주 사용하는 설정 예시 + 설명

1) 서버 포트 설정

server:
  port: 8081

• 서버가 실행될 포트 번호를 지정합니다.
• 여러 애플리케이션을 동시에 띄우거나 Nginx 등과 포트를 나눌 때 유용합니다.

 

2) 실행 환경 구분 (Profiles)

spring:
  profiles:
    active: dev

• 현재 사용할 프로파일 설정 파일을 지정합니다.
• 예: application-dev.yml, application-prod.yml 등

 

3) DB 연결 정보

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/mydb
    username: myuser
    password: mypass
    driver-class-name: org.postgresql.Driver

• Spring이 데이터베이스와 연결하는 데 필요한 정보입니다.
• 환경별로 다른 DB를 사용하려면 -dev, -test 프로파일에 맞게 분기해줍니다.

 

4) 메일 발송자 설정

app:
  mail:
    sender:
      address: no-reply@example.com
      name:
        ja: 株式会社サンプル
        en: Sample Inc.
    reply:
      address: support@example.com

• 사용자에게 발송할 이메일의 발신자 주소 및 이름입니다.
• 다국어 지원이 필요한 경우 언어 코드(jp/en 등)로 나누어 관리합니다.

 

5) 도메인 및 콜백 URL

app:
  domain:
    root: https://www.example.com
    front: https://front.example.com

• root: 시스템의 기본 URL (예: 마케팅용 루트 도메인)
• front: 프론트엔드 웹 앱의 URL (예: Vue/React 기반 화면)

  login-cb-url:
    sign-in: /login/callback
    logout: /logout/callback

• 로그인/로그아웃 성공 후 사용자가 이동하게 될 콜백 주소입니다.

 

6) S3 파일 업로드 설정

app:
  s3:
    bucket:
      temporary: my-temp-bucket
      customer-upload: my-upload-bucket
    region: ap-northeast-1
    upload:
      expiration-seconds: 600
      max-bytes: 10485760

• bucket.temporary: 임시 파일을 업로드할 S3 버킷 (예: presigned URL 사용)
• bucket.customer-upload: 고객이 업로드하는 파일을 위한 실제 버킷
• expiration-seconds: 업로드 URL 만료시간 (초)
• max-bytes: 허용 가능한 최대 업로드 크기 (바이트)

 

7) 인증 관련 설정

app-cloud:
  auth:
    customer-password-salt: salt-value

• 비밀번호 해싱 시 사용할 salt 값입니다.
• 반드시 외부에서 주입하도록 설계하고, Git에 올리지 않아야 합니다.

  selmid:
    client-id: selmid-client-id
    client-secret: selmid-client-secret
    token-signing:
      private-key: -----BEGIN PRIVATE KEY-----
      key-id: abcdef123456

• selmid는 외부 인증 시스템 (예: Azure AD, OAuth 서버 등)의 클라이언트 정보입니다.
• private-key, key-id는 JWT 서명에 사용될 비공개 키 정보입니다.

 

8) 외부 API 연동

google:
  maps:
    api-key: google-maps-api-key
    url-signing-secret: signing-secret

twilio:
  auth:
    id: twilio-auth-id
    token: twilio-auth-token

• 외부 API(Google Maps, Twilio) 사용을 위한 인증 정보입니다.
• 반드시 .gitignore된 secret 파일로 분리해서 관리하는 것이 좋습니다.

 

9) 다운로드 링크 설정

download:
  cloud-front-base-url: https://cdn.example.com
  expiration-seconds: 3600

• CDN을 통한 다운로드 URL을 만들 때 사용하는 기본 주소입니다.
• presigned URL 사용 시 만료시간도 함께 설정합니다.

 

10) 캐시 만료 설정

cache:
  cache-groups:
    sampleCache:
      expire: 100

• 캐시 그룹 이름별로 TTL(Time To Live)을 초 단위로 설정합니다.
• Redis, Ehcache 등에서 활용됩니다.

 

11) RSS 피드 타임아웃

rss-feed:
  connect-timeout-millis: 3000
  read-timeout-millis: 5000

• 외부 RSS 데이터를 불러올 때의 연결 및 응답 시간 제한 설정입니다.
• 너무 길게 설정할 경우 전체 응답이 지연될 수 있어 주의가 필요합니다.

---

4. 전체 구조 샘플

spring:
  profiles:
    active: dev

app:
  domain:
    root: https://www.example.com

  mail:
    sender:
      address: no-reply@example.com

  s3:
    bucket:
      temporary: example-temp-bucket
    upload:
      expiration-seconds: 600

  env:
    profile: dev

---

5. 초보자를 위한 팁

• Tab 대신 반드시 Space로 들여쓰기 하세요.
• 환경이 많아지면 application-dev.yml, application-prod.yml로 분리해서 관리하세요.
• application-secret.yml에 민감한 정보를 분리하고 Git에 올리지 마세요.
• @Value, @ConfigurationProperties를 통해 설정값을 Java 클래스에 주입할 수 있습니다.
• 공통된 값은 상수처럼 한 곳에 정리하면 유지보수가 쉬워집니다.

---

6. 마무리

지금까지 Spring Boot에서 자주 사용되는 `application.yml` 설정 항목들을 정리해보았습니다.   설정의 의미와 사용 목적을 이해하고 나면, 복잡해 보였던 yml 구조도 점점 익숙해질 수 있습니다.
다음 글에서는 "설정은 했는데 적용되지 않는 경우"를 주제로,  실무에서 겪기 쉬운 실수와 그 해결 방법들을 자세히 소개할 예정입니다.
읽어주셔서 감사합니다.