[Spring Boot] application.yml 문법 총정리: 실무 예제로 배우는 설정의 기술

안녕하세요. IT 기술 블로거입니다.

Spring Boot 프로젝트를 시작할 때 개발자가 가장 먼저 마주하는 파일, 바로 application.yml입니다. “그냥 설정 파일 아니야?”라고 가볍게 넘길 수도 있지만, 이 파일 하나를 어떻게 작성하느냐에 따라 프로젝트의 유지보수성과 가독성이 천차만별로 달라집니다.

오늘은 Spring Boot의 사실상 표준 설정 파일인 application.yml의 기본 문법부터, 실수하기 쉬운 포인트, 그리고 실무에서 사용하는 고급 작성 예제까지 아주 상세하게 파헤쳐 보겠습니다. YAML(YAML Ain’t Markup Language)이라는 이름처럼, 마크업 언어가 아닌 데이터 직렬화 양식이 주는 편리함을 제대로 느껴보시기 바랍니다.

1. 왜 XML도, Properties도 아닌 YAML인가?

과거 Spring Framework 시절에는 web.xml이나 applicationContext.xml 같은 XML 설정 지옥(XML Hell)을 경험해야 했습니다. 이후 application.properties가 등장하며 훨씬 간결해졌지만, 계층 구조가 깊어질수록 가독성이 떨어지는 단점이 있었죠.

YAML은 이러한 단점을 완벽하게 보완합니다.
1. 계층 구조 시각화: 들여쓰기(Indent)만으로 부모-자식 관계를 명확히 보여줍니다.
2. 중복 제거: 동일한 상위 키를 반복해서 쓸 필요가 없습니다.
3. 다양한 데이터 타입: 리스트(List), 맵(Map) 등을 직관적으로 표현할 수 있습니다.

2. application.yml 기본 문법 (Syntax)

YAML 문법은 파이썬과 유사하게 들여쓰기(Indentation)가 생명입니다. 탭(Tab) 문자는 허용되지 않으며, 반드시 공백(Space)을 사용해야 합니다. 통상적으로 공백 2칸을 권장합니다.

2.1. Key-Value 구조와 들여쓰기

가장 기본적인 형태입니다. 콜론(:) 뒤에는 반드시 공백이 하나 이상 있어야 합니다.

server:
  port: 8080
  servlet:
    context-path: /api
    session:
      timeout: 30m

위 설정은 server.port=8080, server.servlet.context-path=/api와 동일합니다. 눈으로 보기에도 계층 구조가 훨씬 잘 들어오죠?

2.2. 리스트(List) 표현법

배열이나 리스트 형태의 데이터를 표현할 때는 하이픈(-)을 사용합니다.

my-app:
  admin-users:
    - admin@codecamp.com
    - manager@codecamp.com
    - monitor@codecamp.com

  # 인라인(Inline) 형태로도 작성 가능합니다.
  allowed-ips: [127.0.0.1, 192.168.0.1, 10.0.0.1]

2.3. 텍스트 블록 (Multi-line String)

설정 값에 긴 텍스트나 여러 줄의 문자열을 넣어야 할 때가 있습니다. (예: RSA 공개키, 배너 텍스트 등)

• | (Literal Style): 줄바꿈을 포함하여 그대로 유지합니다.
• > (Folded Style): 줄바꿈을 공백으로 치환하여 한 줄로 만듭니다.

spring:
  banner:
    location: classpath:banner.txt

  messages:
    welcome-msg: |
      안녕하세요!
      Spring Boot의 세계에 오신 것을
      환영합니다.
      (줄바꿈이 유지됩니다)

    error-msg: >
      시스템에 치명적인 오류가
      발생했습니다. 관리자에게
      문의해주세요.
      (한 줄로 이어집니다)

3. 실무 작성 예제 및 꿀팁

단순한 문법을 넘어, 실무에서는 어떻게 활용하는지 살펴보겠습니다.

3.1. 앵커(Anchor)와 별칭(Alias)을 활용한 중복 제거

YAML의 강력한 기능 중 하나인 & (Anchor)와 * (Alias)를 사용하면 반복되는 설정을 획기적으로 줄일 수 있습니다.

common-db-config: &db-config
  driver-class-name: com.mysql.cj.jdbc.Driver
  pool-size: 10
  timeout: 5000

spring:
  datasource:
    # 메인 DB 설정
    primary:
      url: jdbc:mysql://primary-db:3306/main
      username: root
      password: password
      <<: *db-config  # 공통 설정을 여기에 병합(Merge)합니다.

    # 보조 DB 설정
    secondary:
      url: jdbc:mysql://secondary-db:3306/backup
      username: reader
      password: password
      <<: *db-config  # 동일한 설정을 재사용합니다.

이렇게 작성하면 DB 드라이버나 풀 사이즈 설정이 변경될 때 common-db-config 한 곳만 수정하면 되므로 유지보수성이 극대화됩니다.

3.2. 자바 코드와 매핑하기 (@ConfigurationProperties)

application.yml에 작성한 내용을 자바 객체로 바인딩하여 사용하는 것이 Spring Boot의 정석입니다.

application.yml

codecamp:
  blog:
    name: "IT Tech Blog"
    author: "Kama"
    tags:
      - Java
      - Spring
      - DevOps
    settings:
      auto-publish: true
      max-posts: 10

Java Config Class

package com.codecamp.config;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;
import java.util.List;

@Data
@Configuration
@ConfigurationProperties(prefix = "codecamp.blog")
public class BlogProperties {
    private String name;
    private String author;
    private List<String> tags;
    private Settings settings;

    @Data
    public static class Settings {
        private boolean autoPublish;
        private int maxPosts;
    }
}

이렇게 @ConfigurationProperties를 사용하면 YAML의 구조화된 데이터를 자바 객체로 안전하게(Type-safe) 가져와 사용할 수 있습니다. IDE(IntelliJ 등)에서도 자동 완성을 지원받을 수 있어 생산성이 높아집니다.

4. 주의사항 (Common Pitfalls)

1. 탭 문자 사용 금지: 앞서 강조했지만, YAML 파서는 탭 문자를 만나면 에러를 뱉거나 의도치 않게 동작합니다. IDE 설정에서 ‘Tab을 Space로 변환’ 기능을 켜두세요.
2. 콜론 뒤 공백: key:value (X) -> key: value (O). 공백이 없으면 문자열로 인식해버립니다.
3. 특수문자 처리: 값에 :, {, }, [, ] 등의 특수문자가 포함된다면 반드시 따옴표(' 또는 ")로 감싸주어야 합니다.
   • 예: time: "12:00" (따옴표가 없으면 60진수 숫자로 오인될 수 있음)

결론

application.yml은 단순한 텍스트 파일이 아니라, 애플리케이션의 뼈대를 구성하는 중요한 설계도입니다. 계층 구조를 통해 가독성을 높이고, 앵커와 같은 고급 기능을 통해 중복을 제거하며, @ConfigurationProperties를 통해 코드와 유기적으로 결합할 때 Spring Boot의 진정한 생산성을 경험할 수 있습니다.

오늘 소개해 드린 문법과 예제들을 프로젝트에 바로 적용해 보세요. 설정 파일을 열어보는 것이 더 이상 두렵거나 귀찮은 일이 아닐 것입니다.

다음 시간에는 application.yml과 application.properties의 구체적인 차이점과 마이그레이션 포인트에 대해 다뤄보겠습니다. 감사합니다.