압축 파일을 풀었을 뿐인데처음 Spring Boot 프로젝트를 만들면 코드를 작성하기도 전에 이미 꽤 많은 것이 준비돼 있어요. 아직 컨트롤러도 없고, 데이터베이스도 연결하지 않았는데요. 프로젝트 폴더 안에는 빌드 도구 파일, 실행 진입점, 설정 파일, 테스트 폴더, 래퍼(wrapper) 스크립트가 들어 있어요. 그래서 첫 화면에서 이런 생각이 들 수 있어요.src,build.gradle,gradlew,Application.java같은 파일이 한꺼번에 생겨요.
“나는 웹 프로젝트 하나 만들겠다고 했을 뿐인데, 이 파일들은 다 무슨 역할이지?"오늘은 Spring Boot 프로젝트를 직접 만들 때 마주치는 선택지와, 생성된 파일들이 어떤 일을 맡는지 보려고 해요. 목표는 모든 옵션을 외우는 게 아니라 처음 만들어진 프로젝트를 읽을 수 있는 눈을 갖는 거예요.
"Maven이랑 Gradle 중에 뭘 골라야 하지?"
"패키지 이름을 대충 적어도 되는 걸까?"
"DevTools는 개발할 때만 쓰는 건가?”
예시는 Spring Boot 4.x 흐름을 기준으로 설명해요. 구체적인 지원 Java 버전, Maven/Gradle 버전, DevTools 동작처럼 버전에 따라 바뀔 수 있는 내용은 Spring Boot 4.1.0 공식 문서를 확인해 작성했어요. 실제 프로젝트를 만들 때는
start.spring.io 화면의 현재 선택지를 한 번 더 확인하세요.프로젝트 생성기는 빈 폴더에 첫 배치를 깔아줘요
Spring Boot 프로젝트를 만드는 가장 흔한 입구는 Spring Initializr예요. 브라우저에서 옵션을 고르고 압축 파일을 내려받는 방식이죠.
여기서 중요한 건 Initializr가 업무 코드를 만들어주는 게 아니라는 점이에요.
주문 조회, 결제, 회원 가입 같은 코드는 여전히 우리가 작성해야 해요. 대신 그 코드를 올릴 수 있는 Spring Boot 프로젝트의 첫 구조를 맞춰줘요.
명령줄에서는 spring init으로 같은 일을 할 수 있어요
브라우저 대신 터미널에서 만들 수도 있어요. Spring Boot CLI를 설치했다면 spring init 명령이 Spring Initializr를 호출해 프로젝트를 만들어줘요.
먼저 CLI가 없다면 설치부터 해야 해요. Spring Boot 4.1.0 공식 문서 기준으로는 이런 방법들이 안내돼요.
bin/spring 또는 Windows의 bin/spring.bat이 실행되도록 PATH를 잡으면 돼요.
설치가 끝났다면 먼저 두 명령을 기억해두면 좋아요.
spring만 입력하면 사용할 수 있는 명령 목록이 나오고, spring help init은 프로젝트 생성에 쓸 수 있는 옵션을 보여줘요.
그다음 Gradle 프로젝트를 만들려면 이렇게 실행할 수 있어요.
공식 CLI 문서 기준으로
spring init은 기본 대상 서비스를 https://start.spring.io로 잡아요. 그래서 브라우저에서 누르는 “Generate” 버튼과 같은 생성 서비스를 명령줄에서 쓰는 셈이에요.
사용할 수 있는 의존성 이름이나 프로젝트 타입이 헷갈리면 --list로 현재 서비스가 제공하는 선택지를 볼 수 있어요.
--build=gradle만 넣었을 때 CLI가 gradle-project와 gradle-project-kotlin 중 더 구체적인 타입을 고르라고 말할 수 있어요. 이럴 때는 위 예시처럼 --type=gradle-project를 함께 적으면 돼요.
처음 배우는 단계라면 브라우저가 더 편할 수 있어요. 옵션을 눈으로 볼 수 있으니까요. 팀에서 반복 생성하거나 문서에 재현 가능한 명령을 남길 때는 CLI가 편해요.
Maven과 Gradle은 “프로젝트를 어떻게 지을지” 정하는 도구예요
Spring Boot를 시작할 때 가장 먼저 헷갈리는 선택지가 Maven과 Gradle이에요. 둘 다 핵심 역할은 같아요.- 필요한 라이브러리를 내려받아요.
- 소스 코드를 컴파일해요.
- 테스트를 실행해요.
- 실행 가능한 애플리케이션으로 패키징해요.
- Spring Boot가 관리하는 의존성 버전 조합을 적용해요.
예를 들어 Gradle 프로젝트를 만들면 이런 파일을 보게 돼요.
plugins는 Spring Boot 프로젝트를 빌드하는 방법을 붙이고, dependencies는 이 애플리케이션이 어떤 기능 묶음에 기대는지 보여줘요.
여기서 spring-boot-starter-webmvc가 바로 스타터(starter)예요. Spring Boot 4.x 기준으로 Spring MVC 웹 애플리케이션을 만들 때 자주 필요한 Spring MVC, 내장 서버, JSON 처리 같은 조합을 한 번에 끌어오는 출발점이에요.
처음 생성된 폴더를 펼쳐볼게요
웹과 DevTools를 넣은 Java 프로젝트라면 대략 이런 모양을 보게 돼요.
즉, 생성기는 “앞으로 코드를 어디에 놓을지”를 먼저 정해줘요.
이 그림에서 Spring Boot가 대신한 일은 업무 기능 작성이 아니에요. 빌드, 실행, 설정, 테스트를 놓을 기본 자리를 정리한 일이에요.
OrderApplication.java는 실행의 입구예요
생성된 프로젝트에서 가장 먼저 볼 Java 파일은 보통 이런 모양이에요.
오늘은
@SpringBootApplication의 내부 구성을 모두 열지는 않을게요. 뒤 글에서 main 메서드가 어떤 단계를 거쳐 실행 중 애플리케이션으로 바뀌는지 따로 볼 거예요.
지금은 한 가지만 기억하면 돼요.
생성된 Application 클래스는 “여기서부터 우리 애플리케이션을 시작해줘”라고 Spring Boot에 넘기는 입구예요.
패키지 이름은 나중의 탐색 범위를 정해요
패키지 이름은 단순한 폴더명이 아니에요. Spring Boot 공식 문서는 기본 패키지(default package)를 피하고,com.example.project처럼 역방향 도메인 이름을 따르는 패키지명을 권장해요. 또 @SpringBootApplication이 붙은 메인 클래스를 다른 클래스들보다 상위의 루트 패키지에 두는 편을 권장해요.
예를 들어 이런 구조가 자연스러워요.
OrderApplication이 com.example.order에 있으면, 그 아래의 com.example.order.order, com.example.order.payment 같은 패키지들이 애플리케이션의 자연스러운 탐색 범위가 돼요.
반대로 메인 클래스를 너무 깊은 곳에 두면 나중에 컴포넌트 스캔(component scan)에서 “왜 이 클래스는 등록이 안 되지?” 같은 질문을 만나기 쉬워요.
이건 다음 글들에서 빈(bean)과 컴포넌트 스캔을 배울 때 다시 중요해져요.
생성된 파일은 나중의 실행 경계를 미리 정해요
처음에는 생성된 파일들이 단순한 시작 템플릿처럼 보여요. 하지만 조금 더 깊게 보면, 이 파일들은 나중에 Spring Boot가 어떤 방식으로 실행되고, 무엇을 자동으로 준비하고, 어디까지 스캔할지를 미리 정하는 경계가 돼요.
여기서 가장 중요한 연결은 의존성 목록과 자동 설정이에요.
예를 들어 웹 스타터를 넣으면 단순히 “웹 기능을 쓰겠다”는 표시만 생기는 게 아니에요. 빌드 도구는 웹 관련 라이브러리들을 클래스패스에 올리고, Spring Boot는 그 클래스패스를 보고 “웹 애플리케이션 기본 구성이 필요하겠네”라고 판단할 수 있어요.
이 흐름을 알면
build.gradle을 단순한 설치 목록으로만 보지 않게 돼요. 어떤 스타터를 추가하거나 빼는 일은 “라이브러리 하나를 넣고 빼는 일”이면서 동시에 “Boot가 볼 수 있는 자동 설정 후보를 바꾸는 일”이에요.
실무에서는 이 관점이 코드 리뷰에도 바로 이어져요.
- 패키지 루트가 너무 좁으면 나중에 빈이 안 잡히는 문제가 생길 수 있어요.
- 스타터를 무심코 추가하면 예상하지 못한 자동 설정, 필터, 컨버터, 테스트 도구가 따라올 수 있어요.
- 설정 파일에 비밀값을 직접 넣으면 로컬에서는 편해도 운영과 보안 경계가 무너져요.
- 래퍼 스크립트를 지우면 내 컴퓨터에서는 되는데 CI나 동료 환경에서는 빌드가 달라질 수 있어요.
application.properties는 비어 있어도 의미가 있어요
처음 생성된 application.properties 파일에는 애플리케이션 이름 정도만 들어 있거나, 선택에 따라 거의 비어 있을 수 있어요.
설정이 적다고 해서 설정 기능이 없는 건 아니에요. 오히려 “여기에 애플리케이션 설정을 둘 수 있다”는 자리가 먼저 생긴 거예요.
예를 들어 나중에는 이런 설정을 넣게 돼요.
- 서버 포트
- 애플리케이션 이름
- 데이터베이스 연결 정보
- 로그 레벨
- 외부 API 주소
- 프로필(profile)별 설정
DevTools는 초반 학습 마찰을 줄여줘요
처음 Spring Boot를 배울 때 가장 답답한 순간 중 하나는 작은 코드를 바꿀 때마다 애플리케이션을 다시 켜는 일이에요. Spring Boot DevTools는 개발 중 피드백을 빠르게 만들기 위한 도구예요. Gradle에서는 보통 이런 의존성으로 들어가요.java -jar로 실행하는 경우에는 개발 도구가 자동으로 비활성화된다고 설명해요. 운영 환경에서 억지로 켜는 것은 보안상 위험할 수 있어요.
내가 만든 것과 Boot가 만든 것을 나눠볼게요
첫 프로젝트를 만들고 나면 “내가 한 일”과 “Spring Boot가 준비한 일”을 분리해서 보는 습관이 중요해요.
이렇게 나누어 보면 Spring Boot 프로젝트가 덜 신비롭게 보여요.
아직 컨트롤러를 만들지 않았더라도 프로젝트는 이미 “Spring Boot 애플리케이션으로 실행될 준비”를 갖춘 상태예요.
다음 단계부터 우리가 작성할 코드는 이 구조 위에 올라가요.
자, 정리해볼까요?
- Spring Initializr는 업무 코드를 대신 쓰는 도구가 아니라, Spring Boot 프로젝트의 첫 구조를 만들어주는 도구예요.
- Maven과 Gradle은 의존성, 컴파일, 테스트, 패키징을 맡는 빌드 도구예요.
Application.java의main메서드는 Spring Boot 애플리케이션 실행의 입구예요.- 패키지 이름과 메인 클래스 위치는 나중에 컴포넌트 스캔 범위와 연결돼요.
- 스타터와 빌드 파일은 클래스패스를 만들고, 그 클래스패스는 자동 설정 후보를 바꿔요.
- DevTools는 개발 피드백을 빠르게 돕지만, 운영 환경에서 켜두는 도구가 아니에요.