프로젝트 구조와 설정

Spring Boot는 Gradle·Maven의 표준 폴더 구조를 그대로 따르고, 설정은 application.properties 또는 application.yml 한곳에 모읍니다. 이 장에서는 생성된 프로젝트의 파일 배치, 빌드 파일, 설정 파일과 프로필을 차례로 살펴봅니다.

폴더 구조

Initializr로 만든 Gradle 프로젝트는 다음과 같이 생겼습니다. Maven 프로젝트라면 build.gradle.kts 대신 pom.xml, gradlew 대신 mvnw가 있고 빌드 결과가 build/ 대신 target/에 쌓인다는 점만 다릅니다.

demo/
├── build.gradle.kts          # 빌드 설정과 의존성
├── settings.gradle.kts       # 프로젝트 이름
├── gradlew, gradlew.bat      # Gradle 래퍼
└── src/
    ├── main/
    │   ├── java/com/example/demo/
    │   │   ├── DemoApplication.java   # 진입점
    │   │   └── todo/                  # 기능별 패키지
    │   │       ├── TodoController.java
    │   │       ├── TodoService.java
    │   │       └── TodoRepository.java
    │   └── resources/
    │       ├── application.properties # 설정
    │       ├── static/                # 정적 파일(CSS, JS, 이미지)
    │       ├── templates/             # 서버 렌더링 템플릿
    │       └── db/migration/          # Flyway 마이그레이션
    └── test/java/com/example/demo/    # 테스트

빌드 파일

빌드 파일에는 Spring Boot 플러그인과 의존성이 적혀 있습니다. Spring Boot 플러그인과 의존성 관리 플러그인(Maven은 spring-boot-starter-parent)이 Spring Boot와 호환되는 라이브러리 버전을 정해 주므로, 의존성마다 버전을 적지 않습니다.

// build.gradle.kts (플러그인 버전은 Initializr가 채워 줍니다)
java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-webmvc")
    implementation("org.springframework.boot:spring-boot-starter-validation")
    developmentOnly("org.springframework.boot:spring-boot-devtools")
    testImplementation("org.springframework.boot:spring-boot-starter-webmvc-test")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

이전 세대에서는 웹 스타터 이름이 spring-boot-starter-web이었고, 테스트용으로 spring-boot-starter-test 하나만 썼습니다. 현재 세대는 기술마다 ...-test 스타터를 짝지어 둡니다.

진입점과 패키지 규칙

@SpringBootApplication이 붙은 클래스는 가장 위쪽 패키지에 둡니다. 이 어노테이션은 자기 패키지와 그 하위 패키지를 훑어 컴포넌트를 찾기 때문에, com.example.demo 밖에 둔 클래스는 빈으로 등록되지 않습니다. 패키지는 계층(controller, service…)보다 기능(todo, user…)별로 나누는 편이 규모가 커져도 관리하기 쉽습니다.

application.properties와 application.yml

설정은 src/main/resources/application.properties에 키=값 형식으로 적습니다. 같은 내용을 YAML로 쓰고 싶다면 application.yml을 씁니다.

spring:
  application:
    name: demo
  datasource:
    url: jdbc:postgresql://localhost:5432/demo
    username: demo
    password: ${DB_PASSWORD}

server:
  port: 8080

logging:
  level:
    com.example.demo: debug

${DB_PASSWORD}처럼 다른 속성이나 환경 변수를 끌어 쓸 수 있습니다. 비밀번호 같은 값은 파일에 적지 말고 환경 변수로 넘기는 것이 안전합니다.

외부 설정의 우선순위

같은 키가 여러 곳에 있으면 더 바깥쪽 설정이 이깁니다. 자주 쓰는 순서는 다음과 같습니다(아래로 갈수록 우선).

1. jar 안의 application.properties
2. jar 안의 프로필별 파일(application-prod.properties)
3. jar 밖(실행 위치)의 설정 파일
4. 환경 변수(SERVER_PORT=9090)
5. 명령줄 인자(--server.port=9090)

환경 변수는 느슨한 바인딩 규칙에 따라 대문자와 밑줄로 씁니다. spring.datasource.url은 SPRING_DATASOURCE_URL이 됩니다.

프로필

프로필은 환경마다 다른 설정을 고르는 방법입니다. application-dev.yml, application-prod.yml처럼 파일 이름에 프로필을 붙이거나, 한 파일 안에서 ---로 문서를 나눌 수 있습니다.

spring:
  jpa:
    show-sql: false
---
spring:
  config:
    activate:
      on-profile: dev
  jpa:
    show-sql: true

활성 프로필은 실행할 때 고릅니다.

./gradlew bootRun --args='--spring.profiles.active=dev'
SPRING_PROFILES_ACTIVE=prod java -jar build/libs/demo-0.0.1-SNAPSHOT.jar

빈에 @Profile("dev")를 붙이면 그 프로필이 켜졌을 때만 등록됩니다.

정리

• 소스는 src/main/java, 설정과 정적 파일은 src/main/resources, 테스트는 src/test에 둡니다.
• 진입점 클래스는 최상위 패키지에 두고, 나머지는 그 아래에 기능별로 나눕니다.
• 설정은 application.properties/application.yml에 모으고, 환경 변수와 명령줄 인자로 덮어씁니다.
• 환경별 차이는 프로필로 관리합니다.