Gradle을 사용한 Spring Boot 프로젝트의 구조와 설정

 

Gradle을 사용한 Spring Boot 프로젝트의 구조와 설정을 정리한 문서입니다.
복습 용으로, 개인 학습과 문서화 연습의 성격이 강합니다.

개발환경
IDE : IntelliJ IDEA Ultimate 2024.3.1.1
JDK : JetBrains Runtime (JBR) 17.0.12
빌드 도구 : Gradle 8.12.1

프로젝트 환경
Java : 17
Spring Boot : 3.4.2
JDK : JetBrains Runtime (JBR) 17.0.12
빌드 도구 : Gradle 8.12.1

 

---

Spring Boot 프로젝트 생성

Type : Gradle

프로젝트 타입이자, 빌드 용 툴을 설정합니다.

해당 문서는 Gradle을 사용한 Spring Boot 프로젝트 구조를 복습하는 과정이기에 Gradle을 선택했습니다.

Gradle : 최신 프로젝트에서 많이 사용되고 빌드 속도가 빠릅니다.

Maven : XML 기반으로 전통적으로 많이 사용됩니다.

 

Group : com.example

기업명이나 회사 도메인을 주로 기입합니다.

해당 문서는 Gradle을 사용한 Spring Boot 프로젝트 구조를 복습하는 과정이기에 example로 기입했습니다.

 

Artifact : GradleProjectArchitecture

프로젝트의 고유 이름을 기입합니다. Name과 연동됩니다.

 

Package Name  : com.example.gradleprojectarchitecture

코드에서 사용할 최상위 패키지 이름이 됩니다.

 

Java : 17

자바 버전을 설정합니다.

해당 문서는 Gradle을 사용한 Spring Boot 프로젝트 구조를 복습하는 과정이기에 설치된 버전 중 가장 많이 이용해왔던 17을 선택했습니다.

 

Packaging : JAR

패키징 방식을 설정합니다. Spring Boot에서 기본 옵션으로 되어있기에 JAR을 선택했습니다.

• JAR(Java Archive): 독립 실행 가능, Spring Boot에서 기본 옵션
• WAR(Web Application Archive): 서블릿 컨테이너(Tomcat 등) 배포용

보통 JAR 사용 (특별한 이유 없으면 WAR 안 씀)

 

---

 

의존성(Dependencies) : Spring Web

Spring Web 웹 개발 기본 라이브러리를 추가했습니다. 

해당 문서는 Gradle을 사용한 Spring Boot 프로젝트 구조를 복습하는 과정이기에 가장 기초적인 라이브러리만 추가했습니다.

* 프로젝트의 build.gradle파일의 dependencies에 명시되며, 프로젝트 생성 단계에서 추가하지 않아도 추후에 명시할 수 있습니다.

Spring boot 의 버전과 의존성(Dependencies)를 설정하는 단계

 

여기서 Spring Web의 설명으로 (1) Spring MVC를 사용하여 RESTful 웹 애플리케이션을 빌드합니다. (2) 기본 내장 컨테이너로 Apache Tomcat을 사용합니다. 라고 말하고 있습니다.

 

아래에 첨부된 링크입니다.

https://spring.io/guides/gs/rest-service

https://spring.io/guides/gs/serving-web-content

https://spring.io/guides/tutorials/rest

 

왼쪽 : build.gradle 파일 / 오른쪽 : IntelliJ IDE에서 Gradle 을 빌드 툴로 선택하면 뜨는 Gradle tool window

* IntelliJ IDE에서 Gradle 을 빌드 툴로 선택하면 뜨는 Gradle tool window 탭 공식문서 첨부 :         https://www.jetbrains.com/help/idea/jetgradle-tool-window.html

* Gradle에 연결된 프로젝트, 해당 Tasks(*하단 접은 글에 내용 포함), dependencies, 그리고 build.gradle 파일에 대한 모든 변경 사항이 표시합니다.

 

 

 

Spring Web을 선택하면 Spring Boot에서 제공하는 spring-boot-starter-web을 추가합니다.

build.gradle파일의 dependencies에 명시되어 있고, Gradle tool window의 Dependencies를 확인하면 Classpath로 spring-boot-starter-web 의존성을 확인하실 수 있습니다.

 

이때, Spring Boot가 Spring과의 차이로 강조하는 스타터 의존성(Starter Dependencies), 자동 설정(Auto Configuration), 기본으로 포함된 내장 서버(Embedded Server)가 부분적으로 이루어지는 부분이기도 합니다.

 

스타터 의존성(Starter Dependencies)은 필요한 라이브러리를 한 번에 추가할 수 있도록 지원하는 것이고,

자동 설정(Auto Configuration)은 프로젝트에 필요한 설정을 자동으로 구성해주는 것이고, 

내장 서버(Embedded Server)는 서버를 기본으로 포함하는 것입니다.

 

spring-boot-starter-web 의존성(Starter Dependencies) 을 추가하면

(1) Spring Boot가 Spring MVC 관련 자동 설정(Auto Configuration)을 활성화하고, HTTP 요청과 응답을 처리하는 기능을 통해 RESTful 웹 애플리케이션을 빌드할 수 있게 합니다.

(2) spring-boot-starter-web에는 spring-boot-starter-tomcat을 추가하면 Tomcat을 내장 서버(Embedded Server)로 실행하는 데 필요한 라이브러리들이 자동으로 포함합니다.

Gradle 태스크(Tasks) : Gradle의 주요 개념 중 하나로, 특정 작업 단위를 태스크로 정의합니다.

 

 

Gradle tool window, 오른쪽 사이드바에 코끼리 아이콘으로 배치

 

내장 Tasks 몇 가지 예시

 

bootRun : 애플리케이션을 실행합니다. (Spring Boot 플러그인 제공
bootJar : 실행 가능한 JAR 파일을 생성합니다. (Spring Boot 플러그인 제공)

build : 프로젝트를 빌드하고 테스트까지 실행합니다.

test : 테스트를 실행합니다.

---

 

 

프로젝트 구조및 간략 정리

프로젝트의 구조

 

 

1. Gradle Wrapper 관련 구성 요소

gradlew, gradlew.bat	Gradle Wrapper 실행 스크립트
gradle/wrapper/	Gradle Wrapper 설정 폴더 (하위에 있는 gradle-wrapper.properties 파일)

 

2. Gradle 관련 구성 요소

build.gradle, settings.gradle	Gradle 빌드 및 프로젝트 설정 파일 * 이런 설정 파일들을 확인하고 공부하는 데 두는 의의는, Gradle은 결국 빌드 프로그램이고 우리가 커스텀해서 쓸 수 있다는 것을 알기 위해서 입니다. 당장은 대충 '이런 게 있다' 지나가도 되는 부분.
.gradle/	의존성 다운로드 및 빌드 결과를 저장해놓는 Gradle 폴더

 

3. Spring Boot 관련 구성 요소

src/main/java/	애플리케이션의 Java 소스 코드 디렉토리
src/main/resources/	리소스 파일들 (예: application.properties, 템플릿 등)
application.properties	Spring Boot 애플리케이션 설정 파일 (DB, 포트 등)

 

4. 그 외 구성 요소

.idea/	IntelliJ IDEA 설정 파일
.gitignore, .gitattributes	Git 관련 설정 파일 (추적하지 않을 파일 지정 등)
HELP.md	프로젝트 설명 파일 (Spring Initializr로 생성된 경우)

 

---

 

 

1. Gradle Wrapper 관련 구성 요소

Gradle Wrapper를 사용하면 로컬에 Gradle이 설치되어 있지 않아도 프로젝트를 실행할 수 있습니다.

gradle-wrapper.properties 설정 파일에 지정된 Gradle 버전으로 다운로드, 실행하기 때문에 "일관된 버전의 Gradle을 사용할 수 있도록 도와주는 스크립트", "협업 시에 모든 개발자가 동일한 Gradle 버전을 사용하게 해준다." 라고 표현합니다.

gradle 폴더

Gradle Wrapper 관련 파일 저장소.

gradlew, gradlew.bat 파일

 

Gradle Wrapper 실행 파일들.

 

gradlew 는 Linux/macOS용 실행 파일

// Unix, macOS 빌드및 테스트 실행 명령어
./gradlew build

gradlew.bat 은 Window 용 실행 파일

// Window 빌드및 테스트 실행 명령어
gradlew.bat build

 

 

gradle-wrapper.properties 파일

gradle-wrapper.properties는 Gradle 버전이 정의된 설정 파일.

Gradle 8.12.1 를 다운받고 있다.

distributionBase=GRADLE_USER_HOME

distribution(분포)Base(배경) : Gradle을 어디에 설치할지를 결정하는 값

GRADLE_USER_HOME : 기본적으로 ~/.gradle/

 

Gradle Wrapper가 다운로드한 Gradle 바이너리를 ~/.gradle/ 폴더에 저장합니다.

distributionPath=wrapper/dists

distributionPath : Gradle이 실제로 저장될 하위 폴더 경로

/wrapper/dists/ : GRADLE_USER_HOME 폴더 하위에 생성할 폴더 경로

 

GRADLE_USER_HOME/wrapper/dists/ 폴더 안에 Gradle 버전별로 저장됩니다.

 

*Base Directory와 Sub Directory 를 나눠서 관리하면 경로 유연성이 커집니다.

---

distributionUrl=https\://services.gradle.org/distributions/gradle-8.12.1-bin.zip

distributionUrl : Gradle을 다운로드할 URL   

https\://services.gradle.org/distributions/gradle-8.12.1-bin.zip : gradle 버전 8.12.1을 다운로드

 

-bin.zip은 Gradle 실행에 필요한 최소한의 파일만 포함된 버전입니다.
-all.zip 문서, 샘플 코드도 포함됩니다.

---

networkTimeout=10000

networkTimeout : Gradle을 다운로드할 때 네트워크 타임아웃 시간(단위: ms)

10초(10,000ms) 동안 반응이 없다면 타임아웃으로 간주합니다.

---

validateDistributionUrl=true

validateDistributionUrl : 다운로드하려는 distributionUrl이 올바른지 검증할지에 대한 여부

 

true면 Gradle이 URL이 유효한지 확인하고, 잘못된 경우 다운로드를 차단합니다.

---

zipStoreBase=GRADLE_USER_HOME

zipStoreBase : 다운로드한 zip 파일이 저장될 하위 폴더

GRADLE_USER_HOME :  ~/.gradle/에 저장

 

zipStorePath=wrapper/dists

zipStorePath : 다운로드한 zip 파일이 저장될 하위 폴더

wrapper/dists : GRADLE_USER_HOME 폴더 하위에 생성할 폴더 경로

 

*distribution{Base/Path} 경로들은 zip 파일을 압축 해제한 것을 보관하는 경로이고, 해당 경로는 초기에 다운로드받은 zip 파일을 보관하는 경로입니다.

 

---

2. Gradle 관련 구성 요소

Gradle 빌드 및 프로젝트 설정 파일로 구성돼있습니다.

 

.gradle 폴더

Gradle의 빌드 캐시 및 임시 파일 저장소

Gradle 캐시를 통해 의존성 다운로드 및 빌드 결과를 재사용하면 빌드 속도를 최적화시킬 수 있다.

* 로컬 서버로 빌드한다면 신경쓰지 않아도 되지만, 만약 원격 서버를 쓰게 된다면 신경써야 합니다.
원격 서버는 다른 사람들도 빌드를 하기 때문에 빌드 속도가 느려집니다. 때문에 빌드 과정도 최적화해두면 해둘 수록 좋습니다.

 

build.gradle 파일

 

plugins : Gradle 프로젝트에서 사용하는 플러그인을 정의하는 곳이다. 여기서는 Java와 Spring Boot 관련 플러그인을 설정한다.

id 'java' :
Java 프로젝트로서 필요한 태스크(compile.java, test, *jar 등)를 자동으로 등록해 Java 애플리케이션을 빌드할 수 있도록 하는 기본 플러그인입니다.
* .jar은 확장자로, .class 파일 여러 개를 하나로 묶어 실행하거나 배포할 수 있는 "ZIP 파일 같은 Java 전용 패키지" 입니다.
* Java 프로젝트를 빌드하면 jar 태스크가 실행되어 .jar 파일이 생성됩니다.


id 'org.springframework.boot' version '3.4.2' :
Spring Boot와 관련된 태스크(bootRun, bootJar, bootBuildImage 등)를 제공하여 Spring 애플리케이션을 실행하고 관리할 수 있도록 하는 플러그인입니다.

id 'io.spring.dependency-management' version '1.1.7' :
Spring에서 권장하는 의존성 버전 관리* 방식인 dependencyManagement를 사용하게 하는 플러그인입니다

* 버전 관리: 여러 라이브러리를 사용할 때 각 라이브러리의 버전이 일관되게 유지되도록 관리합니다.
예를 들어, Spring Boot 프로젝트에서 사용하는 라이브러리들의 버전을 명시적으로 지정하거나, 특정 버전 이상의 라이브러리만 사용하도록 할 수 있습니다.
* 의존성 관계 관리: 라이브러리 A가 라이브러리 B를 의존하고, 라이브러리 B가 라이브러리 C를 의존하는 등의 복잡한 관계에서 각 의존성들의 버전을 일관되게 관리하는 것입니다.

group : 기업명이나 회사 도메인을 주로 사용한다. 예: com.company
version: 버전 관리. 개발 단계에서는 SNAPSHOT을 사용하여 특정 구간을 저장한다.

java : Java 프로젝트를 설정하는 부분으로, JDK 17(JetBrains Runtime (JBR) 17.0.12 를 쓰겠다고 프로젝트 생성 때 지정)을 사용한다고 설정하고 있다. toolchain을 통해 사용하려는 Java 버전을 지정할 수 있다.

repositories: 의존하는 라이브러리들이 위치한 저장소를 정의한다. Gradle은 의존성을 이 저장소에서 다운로드한다.

Maven Central은 공용 저장소로, 대부분의 오픈소스 라이브러리를 다운로드할 수 있는 기본 저장소
필요시 프라이빗 저장소를 설정할 수 있다.

 

dependencies: 프로젝트가 의존하는 프레임워크나 라이브러리 설정한다.

 

implementation(런타임 및 컴파일 시 필요한 의존성)

testImplementation(테스트에만 필요한 의존성)

testRuntimeOnly(테스트 런타임에만 필요한 의존성)

이 구분을 "스코프"라고 부르며, 그외에도 다양한 스코프가 있습니다.

상황에 따라 적절한 스코프를 사용하하면 빌드 속도(성능)가 빨라지고, 메모리 사용량(리소스)도 줄일 수 있습니다.

 

tasks.named('test'): 특정 테스트 작업을 설정한다.

useJUnitPlatform() 은 JUnit 5 플랫폼을 사용하도록 설정하고 있다.

 

settings.gradle 파일

프로젝트 전체의 설정을 다루는 파일.

멀티 프로젝트 설정 시, 하위 프로젝트들을 등록할 때 사용된다.

멀티 프로젝트는 하나의 Gradle 설정(settings.gradle) 아래 여러 개의 서브 프로젝트(모듈)를 포함하는 구조입니다.

자바에서 모듈(Module)은 독립적으로 배포될 수 있는 코드의 단위입니다.

rootProject.name = 'my-multi-project'
include 'core', 'service', 'web'

이렇게 하면 core, service, web 세 개의 모듈이 하나의 프로젝트로 빌드됩니다.

 

 

---

3. Spring Boot 관련 구성 요소

애플리케이션 코드 및 설정들로 구성돼 있습니다.

src/main/resources 폴더

애플리케이션의 리소스 파일들이 위치하는 폴더.

외부 설정 파일이나 템플릿 파일이 여기에 포함된다.

• static: 정적 리소스 배치 예: 이미지, CSS 파일 등
• templates: HTML 템플릿 파일 배치
• application.properties: 애플리케이션 설정 파일 예: 서버 자체 설정, DB 설정, 포트 번호, 외부 API 설정

초기에는 Spring Boot 애플리케이션에 대한 설정을 application.propertie나 application.yml 에 한번에 해버려도 괜찮습니다.

* 직관성에 의해 .yml을 사용하는 회사가 더 많다고 합니다. 때문에 하단의 예시 또한 yml로 된 것을 가져왔습니다.

그러나 프로젝트 규모가 커지고 연동 대상이 많아지면, 지정해야하는 설정이 많아집니다.

이때, 특정 설정을 변경하려면 일일이 찾아가는 번거로움이나 오타 등의 실수를 유발할 수 있습니다.

 

때문에 주제에 따라 설정을 따로 모아둬서(파일 분리) 가독성을 높이고, 바로 찾아갈 수 있도록 하고, 실수를 방지하려 합니다.

 

서버 자체 설정

DB 연결 정보

메시지 큐 / 스트리밍 플랫폼(Kafka, RabbitMQ 등) 연결 정보

외부 API 연동 정보

캐시 설정

로그 레벨

배포 환경별 차이가 있는 기타 설정

 

등의 주제로 나뉠 수 있습니다.

 

아래는 DB와 Kafka 설정 파일의 예시로 파일을 분리해둔 것입니다.

// 폴더 구조, 코드잇 자료에서 발췌
src
 └─ main
     └─ resources
         ├─ application.yaml                 (공통/기본 설정)
         ├─ application-dev.yaml             (개발 환경 설정)
         ├─ application-prod.yaml            (운영 환경 설정)
         ├─ kafka-config.yaml                (Kafka 관련 공통 설정)
         ├─ kafka-config-dev.yaml            (Kafka 개발 환경 설정)
         ├─ kafka-config-prod.yaml           (Kafka 운영 환경 설정)
         ├─ db-config.yaml                   (DB 관련 공통 설정)
         ├─ db-config-dev.yaml               (DB 개발 환경 설정)
         └─ db-config-prod.yaml              (DB 운영 환경 설정)

 

 

또한 환경(공통, 개발, 운영 등)에 따라서 설정을 달리할 수 있습니다.

 

환경에 따라서 설정을 다르게 하고 싶을 때는,

 

application.yaml, application-dev.yaml, application-prod.yaml

*네이밍은 언제나 달라질 수 있습니다.

 

파일에 spring.config.import, @PropertySource 을 통해 설정 파일을 로드합니다. Spring Boot 2.4+ 버전부터는 spring.config.import 를 쓰는 편이 간단하고 자동화되어 있어 선호됩니다.

// 코드잇 자료에서 발췌
// application.yaml 으로, 공통 설정 파일

spring:
  application:
    name: sample-app

# 로깅 레벨 (전역)
logging:
  level:
    root: INFO

# classpath는 src/main/resources/ 입니다.
spring:
  config:
    import:
      - "classpath:kafka-config.yaml"
      - "classpath:db-config.yaml"

// 코드잇 자료에서 발췌
// application-dev.yaml 으로, 개발 환경

spring:
  profiles: dev
server:
  port: 8080

logging:
  level:
    com.mycompany: DEBUG

spring:
  config:
    import:
      - "classpath:kafka-config-dev.yaml"
      - "classpath:db-config-dev.yaml"

// 명령어를 통해 dev 활성화
$ java -jar myapp.jar --spring.profiles.active=dev

 

설정 파일 로드 순서 : application.yaml -> application-dev.yaml -> kafka-config.yaml + kafka-config-dev.yaml -> db-config.yaml + db-config-dev.yaml

// 코드잇 자료에서 발췌
// application-prod.yaml 으로, 운영 환경
spring:
  profiles: prod
server:
  port: 8081

logging:
  level:
    com.mycompany: ERROR

spring:
  config:
    import:
      - "classpath:kafka-config-prod.yaml"
      - "classpath:db-config-prod.yaml"

// 명령어를 통해 prod 활성화
$ java -jar myapp.jar --spring.profiles.active=prod

 

설정 파일 로드 순서 : application.yaml -> application-prod.yaml -> kafka-config.yaml + kafka-config-prod.yaml -> db-config.yaml + db-config- prod.yaml

 

src/main/java 폴더

프로젝트의 Java 소스 코드가 위치하는 폴더.

 

패키지와 import 간의 관계

각 Java 클래스는 패키지 내에서 정의되어야 합니다.

예를 들어, com.example.service 패키지 내에 UserService라는 클래스를 두면, 해당 클래스는 com.example.service.UserService로 임포트해야 합니다.

 

Java에서 import는 클래스가 다른 패키지에 있을 때 그 클래스를 사용할 수 있도록 하는 기능입니다.

예를 들어, import com.example.service.UserService;는 UserService 클래스를 현재 클래스에서 사용할 수 있도록 해줍니다.

 

src/test/java

테스트 코드가 위치하는 폴더.

 

특정 클래스를 테스트할 때

특정 클래스를 테스트할 때는 해당 클래스와 동일한 패키지 구조를 가져가는 것이 일반적입니다.

예를 들어, com.example.service.UserService 클래스를 테스트하려면 com.example.service.UserServiceTest와 같은 테스트 클래스를 만들고 테스트를 작성합니다.

---

4. 그외 구성 요소

IntelliJ IDEA, Git 등의 개발 환경을 위한 파일들로, 프로젝트의 코드와 직접적인 관련이 없으며 현재 복습하고자 하는 주제와 다르나, 프로젝트 구성 요소로서 존재해 추가합니다.

 

.idea 폴더

IntelliJ IDEA 프로젝트 설정.

로컬 저장소(repository)에서 Git이 추적하지 않도록(commit되지 않도록) 제외한다.

 

.gitignore 파일

Git에서 추적하지 않을 파일 목록

.gitattributes 파일

Git에서 파일 속성(줄바꿈 방식 등) 관리

 

help.md 파일

프로젝트 초기 생성 시 포함되는 기본 문서

 

External Libraries

프로젝트에서 사용하는 외부 라이브러리를 보여주는 목록.

IDE에서 관리하는 것으로, 로컬에 존재하는 실제 폴더가 아니다.

 

Scratches and Consoles

IntelliJ에서 임시 코드 실행 공간