스프링부트 설치

스프링부트 설치는 사실 별도의 무거운 설치 과정이 아니라 개발 환경을 갖추고 프로젝트를 생성하는 일에 가깝다. 스프링부트는 톰캣(Tomcat)이 내장돼 있어 별도의 웹 서버를 깔 필요가 없고, 프로젝트를 만들 때 필요한 의존성만 골라 넣으면 바로 개발을 시작할 수 있다. 이 글에서는 JDK 설치와 버전 호환부터 IDE 선택, Spring Initializr로 프로젝트 생성, 프로젝트 구조, 첫 실행과 Hello World 컨트롤러까지 스프링부트 설치 전 과정을 단계별로 정리한다.

준비물: JDK와 IDE

JDK 설치와 버전 호환

스프링부트 설치의 첫 단추는 JDK다. Spring Boot 3.x는 Java 17 이상을 요구하므로, 가장 무난한 선택은 LTS 버전인 JDK 17 또는 JDK 21이다. Eclipse Temurin(Adoptium), Oracle JDK, Amazon Corretto 등 어떤 배포판이든 상관없다. 버전이 17 미만이면 프로젝트 생성·빌드 단계에서 바로 에러가 나니 먼저 확인하고 가자.

설치 후 터미널에서 자바 버전을 확인한다. 17 이상이 출력되면 된다.

java -version

# 출력 예시
openjdk version "17.0.10" 2024-01-16
OpenJDK Runtime Environment Temurin-17.0.10+7

버전이 잡히지 않으면 JAVA_HOME 환경 변수와 PATH에 JDK 경로가 등록돼 있는지 확인한다. JDK를 여러 개 설치한 경우 IDE에서 사용할 SDK도 17 이상으로 지정해야 한다.

IDE 선택: IntelliJ · STS · VS Code

스프링부트 개발에 쓰는 IDE는 보통 셋 중 하나다. 어떤 것을 써도 무방하지만, 자바 개발 편의성 면에서는 IntelliJ가 가장 무난하다.

IDE	특징	Spring Initializr 내장
IntelliJ IDEA	자바 개발 편의성이 높음. 프로젝트 생성 마법사(New Project > Spring Boot)는 Ultimate(유료)에서 제공	Ultimate만
Spring Tool Suite(STS)	스프링 전용 도구를 모은 Eclipse 기반 무료 IDE	O(무료)
VS Code	가볍고 무료. 확장(Extension Pack for Java, Spring Boot Extension Pack) 설치 필요	확장 설치 시

VS Code를 쓴다면 마켓플레이스에서 다음 확장을 먼저 설치한다.

• Extension Pack for Java — 자바 언어 지원·디버거·빌드 도구 통합 묶음
• Spring Boot Extension Pack — Spring Initializr·Spring Boot Dashboard 등 스프링 지원 묶음
• Gradle for Java — Gradle 빌드를 IDE에서 실행

IntelliJ Community(무료)나 VS Code처럼 프로젝트 생성 마법사가 없거나 제한적인 환경에서는, 웹 기반 Spring Initializr를 쓰면 IDE 종류와 무관하게 동일한 방식으로 프로젝트를 만들 수 있다. 이 글도 그 방법으로 진행한다.

Spring Initializr로 프로젝트 생성

웹 브라우저에서 https://start.spring.io 에 접속한다. 각 항목을 아래 기준으로 설정한다.

• Project: Gradle – Groovy 권장. 스프링은 Maven으로 배우는 경우가 많지만 최근에는 Gradle을 더 많이 쓴다. Maven을 골라도 무방하다.
• Language: Java
• Spring Boot: 정식(GA) 버전 중 가장 최신을 선택한다(SNAPSHOT·M 표시가 붙은 사전 릴리스는 피한다).
• Project Metadata: Group(예: com.example), Artifact·Name(프로젝트명), Packaging은 Jar, Java는 17(또는 21).

오른쪽 Dependencies에서 ADD DEPENDENCIES를 눌러 필요한 의존성만 추가한다. 웹 애플리케이션을 만들 것이므로 Spring Web을 추가한다. 이 의존성에 내장 톰캣과 Spring MVC가 포함돼 있어, 별도 웹 서버 설치 없이 바로 HTTP 서버를 띄울 수 있다.

의존성은 실제로 쓸 것만 추가하는 게 좋다. 예를 들어 데이터베이스를 아직 쓰지 않는다면 JPA·MyBatis 같은 DB 의존성은 빼는 편이 낫다. DB 연결 정보 없이 DB 의존성만 들어 있으면 실행 시 연결 오류가 나기 때문이다.

설정을 마치고 하단의 GENERATE(단축키 Ctrl+Enter)를 누르면 프로젝트가 zip 파일로 다운로드된다. 압축을 풀어 IDE에서 열면 된다(IntelliJ는 build.gradle 또는 pom.xml이 있는 폴더를 Open). 처음 열면 IDE가 의존성을 내려받느라 잠시 시간이 걸린다.

프로젝트 구조 살펴보기

생성된 Gradle 프로젝트의 주요 구조는 다음과 같다.

demo
├── build.gradle                # 빌드 설정·의존성 정의
├── settings.gradle
├── gradlew / gradlew.bat       # Gradle Wrapper(별도 Gradle 설치 불필요)
└── src
    ├── main
    │   ├── java
    │   │   └── com/example/demo/DemoApplication.java   # 메인 클래스
    │   └── resources
    │       ├── static          # 정적 파일(html·css·js)
    │       ├── templates       # 템플릿(Thymeleaf 등)
    │       └── application.properties   # 설정 파일
    └── test
        └── java                # 테스트 코드

핵심은 DemoApplication.java의 메인 클래스다. 클래스 위에 붙은 @SpringBootApplication 애너테이션 하나가 자동 설정(auto-configuration)·컴포넌트 스캔·설정 클래스 역할을 모두 담당한다. main 메서드의 SpringApplication.run(...)이 호출되면 내장 톰캣이 함께 구동된다.

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

Gradle Wrapper(gradlew)가 포함돼 있어 시스템에 Gradle을 따로 설치하지 않아도 빌드·실행이 가능하다. 빌드 도구로 Maven을 선택했다면 같은 자리에 pom.xml과 mvnw(Maven Wrapper)가 생성된다.

프로젝트 실행 확인

실행 방법은 두 가지다. IDE에서 DemoApplication의 main 메서드 옆 실행 버튼(▶)을 누르거나, 프로젝트 루트에서 터미널 명령으로 띄운다.

# Gradle 프로젝트
./gradlew bootRun

# Maven 프로젝트
./mvnw spring-boot:run

정상적으로 구동되면 콘솔에 스프링 배너와 함께 톰캣이 8080 포트에서 시작됐다는 로그가 찍힌다.

Tomcat started on port 8080 (http) with context path '/'
Started DemoApplication in 1.234 seconds

이 상태에서 브라우저로 http://localhost:8080에 접속하면 기본적으로 404(Whitelabel Error Page)가 보인다. 아직 보여 줄 페이지나 매핑된 경로가 없어서 나타나는 정상적인 동작이다. 화면을 띄우는 방법은 두 가지다.

• 정적 파일: src/main/resources/static/index.html을 만들면 루트 경로에서 자동으로 인식한다.
• 컨트롤러: 자바 코드로 요청 경로를 직접 매핑한다(다음 단계).

첫 컨트롤러 만들기(Hello World)

스프링부트가 제대로 동작하는지 확인하는 가장 확실한 방법은 컨트롤러를 하나 만들어 보는 것이다. DemoApplication.java와 같은 패키지(com.example.demo) 아래에 HelloController.java를 만든다. @SpringBootApplication이 이 패키지 하위를 자동으로 스캔하므로 별도 등록은 필요 없다.

package com.example.demo;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @GetMapping("/hello")
    public String hello() {
        return "Hello, Spring Boot!";
    }
}

@RestController는 반환값을 그대로 HTTP 응답 본문으로 보내는 컨트롤러이고, @GetMapping("/hello")는 GET /hello 요청을 이 메서드에 연결한다. 애플리케이션을 다시 실행한 뒤 브라우저에서 http://localhost:8080/hello로 접속하면 Hello, Spring Boot! 문자열이 출력된다. 여기까지 확인했다면 스프링부트 설치와 첫 실행에 성공한 것이다.

버전 호환과 자주 묻는 질문

Spring Boot 버전 호환 정리

스프링부트는 Spring Framework·Java·빌드 도구 버전이 서로 맞물려 있다. Spring Boot 3.x 계열의 호환 요건은 다음과 같다(Spring Boot 3.3 기준).

구성 요소	요구 버전
Java(JDK)	17 이상 ~ 23 (최소 17)
Spring Framework	6.1.x 이상
Maven	3.6.3 이상
Gradle	7.5 이상(7.x) 또는 8.x
내장 톰캣	Tomcat 10.1.x (기본 포트 8080)

참고로 가장 최신 메이저인 Spring Boot 4.x는 Java 17 이상(최대 26), Spring Framework 7.x, Gradle 8.14 이상을 요구한다. 다만 입문 단계에서는 안정적인 Spring Boot 3.x + JDK 17 조합으로 시작하는 것을 권장한다. 정확한 요건은 공식 문서 System Requirements에서 버전별로 확인할 수 있다.

자주 묻는 질문

Q. Java 버전이 맞지 않으면 어떻게 되나?
A. Spring Boot 3.x에서 JDK 17 미만을 쓰면 빌드 또는 실행 단계에서 버전 오류가 난다. java -version으로 확인하고, IDE의 프로젝트 SDK도 17 이상으로 맞춘다.

Q. Gradle과 Maven 중 무엇을 골라야 하나?
A. 둘 다 스프링부트를 완전히 지원한다. 최근 신규 프로젝트는 Gradle을 더 많이 쓰지만, 팀·강의에서 Maven을 쓴다면 Maven으로 시작해도 된다. Wrapper(gradlew·mvnw)가 동봉돼 별도 설치는 필요 없다.

Q. localhost:8080에서 404가 뜨는데 잘못된 건가?
A. 매핑된 경로가 없을 때 나타나는 정상 동작(Whitelabel Error Page)이다. 정적 index.html을 두거나 컨트롤러를 만들면 해결된다.

정리

• JDK: Spring Boot 3.x는 Java 17 이상 필수. LTS인 JDK 17 또는 21 권장, java -version으로 확인.
• IDE: IntelliJ·STS·VS Code 중 선택. 프로젝트 생성은 웹 Spring Initializr(start.spring.io)가 가장 범용적.
• 프로젝트 생성: Gradle·Java·Jar·Java 17, 의존성은 Spring Web처럼 쓸 것만 추가 후 GENERATE.
• 실행: ./gradlew bootRun(또는 ./mvnw spring-boot:run) → 내장 톰캣 8080 포트 구동.
• 확인: @RestController + @GetMapping으로 첫 컨트롤러를 만들어 /hello 응답 확인.

여기까지 따라왔다면 스프링부트 개발 환경 준비가 끝났다. 다음 단계로는 실제 기능을 붙여 가며 익히는 것이 좋다. 이어지는 실습이 필요하다면 스프링부트 클론코딩 블로그 프로젝트 Part 1에서 게시판 형태의 애플리케이션을 단계별로 만들어 보며 스프링부트의 기능을 차근차근 익혀 보자.