Spring · 설정, 자동 구성, 프로파일

Spring Boot^? 의 가장 큰 매력은 "설정을 거의 안 해도 알아서 돌아간다" 입니다. 라이브러리를 하나 추가하기만 하면, Spring이 "아, 이걸 쓰려는구나" 하고 필요한 부품을 스스로 조립해 줍니다(자동 구성). 그리고 바꾸고 싶은 값만 설정 파일 에 적으면 그 부분만 덮어쓰입니다. 이 페이지에서는 스타터로 기능을 들여오는 법, 자동 구성의 원리, 설정값을 외부에서 주입하는 법, 환경별로 다르게 동작시키는 프로파일 까지 차근차근 풀어봅니다.

1. 스타터 — 기능을 묶음으로 들여오기

어떤 기능을 쓰려면 보통 라이브러리 여러 개를 일일이 골라 버전까지 맞춰 넣어야 합니다. 스타터(starter) 는 이 번거로움을 없애 줍니다. "웹을 만들고 싶다"면 spring-boot-starter-web 하나만 넣으면, 그 안에 필요한 라이브러리(웹 서버 톰캣, JSON 변환기 잭슨, MVC 등)가 검증된 버전 조합으로 한 묶음 으로 딸려 옵니다. 마치 라면을 끓일 때 면·스프·건더기가 한 봉지에 들어 있는 것과 같습니다.

아래는 이 프로젝트의 build.gradle 에 실제로 들어 있는 주요 스타터입니다.

2. 자동 구성 — 클래스패스를 보고 알아서 조립

스타터로 라이브러리를 들여오면, Spring Boot가 자동 구성(auto-configuration) 으로 필요한 빈(객체)을 스스로 만들어 등록합니다. 핵심 아이디어는 단순합니다 — "있는 부품을 보고 판단한다." 예를 들어 클래스패스(앱이 실행될 때 들고 있는 라이브러리 목록)에 PostgreSQL 드라이버가 보이면 "DB를 쓰려는구나" 하고 데이터소스 빈을 자동으로 준비합니다.

자동 구성이 "있는 부품을 보고 판단한다"는 것은, 내부적으로 조건부 구성 애너테이션으로 이루어집니다. 빈을 등록하기 전에 "이 조건이 맞을 때만 등록해"라고 단서를 다는 것이죠.

이 "주인이 해 놓은 게 우선"이라는 성질 덕분에 자동 구성은 비침습적(non-invasive) 입니다. 내가 @Bean 으로 직접 만든 객체가 있으면 자동 구성은 양보하고 물러납니다. 그래서 기본은 알아서 돌아가되, 원하는 부분만 직접 손볼 수 있습니다. 어떤 자동 구성이 적용됐는지 궁금하면 실행 시 --debug 옵션을 주면 적용/미적용 내역이 로그로 나옵니다.

3. 외부 설정 — properties와 yml

코드 안에 값을 박아두면 바꿀 때마다 다시 빌드해야 합니다. Spring Boot는 값을 코드 바깥(외부) 에 두도록 권합니다. 가장 흔한 곳이 src/main/resources 의 application.properties 또는 application.yml 입니다. 둘은 적는 문법만 다르고 역할은 같습니다.

// application.properties — 키=값, 평면적
server.port=8084
spring.datasource.url=jdbc:postgresql://localhost:5432/studydb
spring.jpa.show-sql=true

# application.yml — 계층(들여쓰기) 구조, 중복 접두사를 줄임
server:
  port: 8084
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/studydb
  jpa:
    show-sql: true

이 프로젝트는 application.properties 를 사용합니다. 같은 설정을 두 형식으로 적은 것뿐, 내용은 동일합니다.

3-1. 설정 우선순위 — 누가 누구를 덮어쓰나

설정값은 한 곳에만 있는 게 아닙니다. 파일·환경변수·실행 옵션 등 여러 곳에서 올 수 있고, 같은 키가 겹치면 우선순위가 높은 쪽이 이깁니다. 아래는 위로 갈수록(아래를 덮어씀) 강한 순서입니다.

4. 설정값을 코드로 주입받기

파일에 적은 값을 코드에서 꺼내 쓰는 방법은 두 가지입니다. 값 하나를 콕 집어 넣는 @Value 와, 관련 값을 묶어 객체로 받는 @ConfigurationProperties 입니다.

4-1. @Value — 값 하나씩 주입

@Value("${키}") 로 설정값 하나를 필드에 바로 꽂습니다. : 뒤에 기본값도 줄 수 있어, 그 키가 없으면 기본값이 쓰입니다. 간단하지만 값이 많아지면 흩어져서 관리가 번거롭습니다.

@Service
public class JwtService {

  @Value("${app.jwt.secret}")            // 설정에서 비밀키 주입
  private String secret;

  @Value("${app.jwt.expirationMs}")      // 토큰 만료 시간(ms)
  private long expirationMs;

  @Value("${app.stage:dev}")             // 없으면 기본값 "dev"
  private String stage;
}

4-2. @ConfigurationProperties — 묶음으로 타입 안전하게

같은 접두사(prefix)로 시작하는 값들을 한 객체에 통째로 받습니다. 키 이름이 필드 이름과 자동으로 연결(바인딩)되고, 타입(숫자·불리언 등)도 알아서 변환됩니다. 관련 설정이 한 곳에 모여 읽기 좋고, 오타가 줄어듭니다.

@ConfigurationProperties(prefix = "app.jwt")   // app.jwt.* 를 묶어서 바인딩
public class JwtProperties {
  private String secret;             // app.jwt.secret
  private long expirationMs;         // app.jwt.expirationMs
  private long refreshExpirationMs;  // app.jwt.refreshExpirationMs
  // getter / setter
}

이렇게 만든 설정 객체를 빈으로 등록하는 방법은 두 가지입니다.

5. 프로파일 — 환경별로 다르게

개발 PC, 테스트 서버, 운영 서버는 DB 주소나 로그 수준이 서로 다릅니다. 프로파일(profile) 은 이런 "환경 꼬리표"입니다. 환경마다 다른 설정 파일과 빈을 준비해 두고, "지금은 어느 환경"인지만 골라 켜면 그에 맞는 것이 적용됩니다.

# application-dev.properties — 개발 환경
spring.datasource.url=jdbc:postgresql://localhost:5432/studydb
spring.jpa.show-sql=true        # 개발 땐 SQL을 콘솔에 보기

# application-prod.properties — 운영 환경
spring.datasource.url=jdbc:postgresql://db.prod:5432/studydb
spring.jpa.show-sql=false       # 운영 땐 SQL 로그를 끔

// 운영에서만 동작하는 빈
@Configuration
@Profile("prod")
public class ProdMailConfig {
  @Bean
  public MailSender realMailSender() { /* 실제 메일 발송 */ return null; }
}

6. 직접 구성 — 내가 손으로 빈을 정의

자동 구성으로 부족하거나, 외부 라이브러리 객체를 내 방식대로 만들어야 할 때는 직접 빈을 정의합니다. (이 주제는 IoC · DI · 빈 페이지에서 더 깊이 다룹니다.)

@Configuration
public class AppConfig {

  @Bean                                  // 외부 라이브러리 객체를 직접 조립
  public ObjectMapper objectMapper() {
    ObjectMapper m = new ObjectMapper();
    m.registerModule(new JavaTimeModule());
    return m;
  }
}

7. Actuator — 앱의 건강검진 창구

spring-boot-starter-actuator 는 운영 중인 앱의 상태를 들여다보는 엔드포인트(점검 창구) 들을 열어 줍니다. 가장 많이 쓰는 것이 /actuator/health 로, "앱과 DB가 정상인가?"를 알려줍니다. 로드밸런서나 쿠버네티스가 이 창구를 주기적으로 두드려 살아 있는지 확인합니다.

보안상 기본으로는 일부 창구만 열려 있습니다. 어떤 창구를 웹으로 공개할지는 설정으로 고릅니다.

# health, info 창구만 웹으로 공개
management.endpoints.web.exposure.include=health,info

8. 실제 프로젝트 application.properties

아래는 이 프로젝트의 src/main/resources/application.properties 에 실제로 들어 있는 주요 설정값입니다. (비밀키 값 자체는 보안을 위해 생략)

한눈에 — 핵심 정리

다음 단계

• 빈을 등록·주입하는 모든 방법 → Spring IoC · DI · 빈
• 이 설정으로 연결된 DB와 트랜잭션 다루기 → Spring 데이터 · 트랜잭션
• 백엔드 실행 환경 → 백엔드 환경 · 실행 방법