Spring Boot 첫 프로젝트 만들기 — start.spring.io 세팅부터 첫 GET API 실행까지

들어가며

자바로 백엔드 개발을 시작하려는 사람에게 스프링 부트는 피할 수 없는 관문이다. 막상 시작하려니 어떤 버전을 골라야 하는지, IntelliJ는 어디서 내려받는지, Gradle 빌드 파일은 왜 두 종류인지, 물어볼 곳도 마땅치 않다.

이 글에서는 PC에 JDK도 없는 상태에서 시작한다. 브라우저 주소창에 http://localhost:8080/hello를 쳤을 때 아래 JSON이 나오면 끝이다.

{"message": "Hello, Spring Boot!"}

설치 순서는 JDK → IntelliJ → 프로젝트 생성 → 코드 작성 → 실행, 딱 다섯 단계다.

---

준비물

항목	버전	비고
JDK	21 LTS	Eclipse Temurin 추천. JDK 8·11은 Spring Boot 3.x와 맞지 않음
IntelliJ IDEA	2024.x 이상	Community Edition으로 충분. 무료
Spring Boot	3.3.x	start.spring.io에서 자동 선택
Gradle	8.x	프로젝트 안에 내장되어 있어 별도 설치 불필요
OS	Windows 10+ / macOS 12+ / Ubuntu 22.04+	셋 다 동일한 순서로 진행

참고 인터넷이 연결된 환경이면 된다. 회사 내부망이라면 Maven Central 접근 여부를 먼저 확인하자.

---

따라 하기

Step 1. JDK 21 설치

Eclipse Temurin 다운로드 페이지에 접속한다. 필터를 아래처럼 맞춘다.

• Version: 21
• OS: 자신의 운영체제
• Architecture: x64 (대부분의 PC)

Windows라면 .msi, macOS라면 .pkg 파일을 내려받아 설치한다. 중간에 나오는 체크박스들은 기본값 그대로 두면 된다.

설치가 끝나면 터미널(Windows는 PowerShell 또는 명령 프롬프트, macOS는 Terminal)을 열고 확인한다.

java -version

아래처럼 나오면 정상이다.

openjdk version "21.0.3" 2024-04-16
OpenJDK Runtime Environment Temurin-21.0.3+9 (build 21.0.3+9)
OpenJDK 64-Bit Server VM Temurin-21.0.3+9 (build 21.0.3+9, mixed mode)

주의 11.x나 17.x가 보인다면 시스템에 이전 JDK가 남아있는 것이다. 환경변수 JAVA_HOME을 새로 설치한 JDK 21 경로로 바꿔야 한다.

---

Step 2. IntelliJ IDEA 설치

JetBrains IntelliJ IDEA 다운로드에서 스크롤을 내리면 Community Edition(무료)이 보인다. Ultimate(유료)가 아닌 Community를 받는다.

설치 옵션 중 "Create Desktop Shortcut"와 ".java 파일 연결" 체크박스만 켜두고 진행한다. 설치 완료 후 처음 실행하면 테마를 고르는 화면이 나온다. Light/Dark 취향대로 고르면 된다.

---

Step 3. start.spring.io에서 프로젝트 내려받기

브라우저에서 start.spring.io를 연다. 왼쪽 설정 패널을 아래처럼 맞춘다.

항목	선택값
Project	Gradle - Groovy
Language	Java
Spring Boot	3.3.x 중 (SNAPSHOT) 없는 버전
Group	com.example
Artifact	demo
Packaging	Jar
Java	21

오른쪽 Dependencies 패널에서 "ADD DEPENDENCIES" 버튼을 클릭하고 Spring Web을 검색해 추가한다.

화면 아래쪽 GENERATE 버튼을 누르면 demo.zip이 내려받아진다. 바탕화면이나 원하는 폴더에 압축을 풀어둔다.

---

Step 4. IntelliJ에서 프로젝트 열기

IntelliJ를 실행하고 Open을 클릭한다. 압축 푼 demo 폴더를 선택한다.

팝업이 하나 뜬다. "Trust Project" 또는 "Trust and Open"을 클릭한다. 이 단계를 건너뛰면 코드 실행이 막힌다.

오른쪽 하단에 Gradle 빌드 진행 표시줄이 돌기 시작한다. 처음 실행할 때는 라이브러리를 모두 내려받느라 2~5분 걸린다. 완료될 때까지 기다린다.

프로젝트 구조는 다음과 같다.

demo/
├── build.gradle
├── gradlew          ← Mac/Linux 실행 스크립트
├── gradlew.bat      ← Windows 실행 스크립트
└── src/
    └── main/
        ├── java/
        │   └── com/example/demo/
        │       └── DemoApplication.java  ← 메인 클래스
        └── resources/
            └── application.properties   ← 설정 파일

---

Step 5. Hello API 코드 작성

왼쪽 파일 탐색기에서 src/main/java/com/example/demo 폴더를 찾는다.

이 폴더에서 우클릭 → New → Java Class를 선택한다. 클래스 이름은 HelloController로 입력하고 Enter.

생성된 파일에 아래 코드를 그대로 붙여넣는다. 기존에 자동 생성된 내용은 모두 지우고 아래 내용으로 교체한다.

package com.example.demo;

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

import java.util.Map;

// @RestController: 이 클래스가 HTTP 요청을 처리하는 컨트롤러임을 선언
// 반환값은 자동으로 JSON으로 변환됨
@RestController
public class HelloController {

    // @GetMapping("/hello"): GET /hello 요청이 오면 이 메서드를 실행
    @GetMapping("/hello")
    public Map<String, String> hello() {
        // Map.of("message", "Hello, Spring Boot!")는
        // JSON { "message": "Hello, Spring Boot!" }으로 변환됨
        return Map.of("message", "Hello, Spring Boot!");
    }
}

---

Step 6. 실행 및 확인

왼쪽 파일 탐색기에서 DemoApplication.java를 더블클릭한다. 파일이 열리면 에디터 왼쪽 줄 번호 옆 초록 삼각형(▶)을 클릭하고 Run을 선택한다.

또는 IntelliJ 하단 Terminal 탭을 열고:

# Mac / Linux
./gradlew bootRun

# Windows
gradlew.bat bootRun

하단 콘솔에 아래 줄이 보이면 서버가 뜬 것이다.

Started DemoApplication in 2.341 seconds (process running for 2.563)

브라우저 주소창에 입력한다.

http://localhost:8080/hello

화면에 아래가 뜨면 성공이다.

{"message":"Hello, Spring Boot!"}

---

전체 코드 (복붙용)

build.gradle

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.3.4'
    id 'io.spring.dependency-management' version '1.1.6'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

repositories {
    mavenCentral()
}

dependencies {
    // 웹 MVC + 내장 Tomcat 포함
    implementation 'org.springframework.boot:spring-boot-starter-web'
    // 테스트 도구 (JUnit 5 포함)
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

tasks.named('test') {
    useJUnitPlatform()
}

DemoApplication.java (자동 생성, 수정 없음)

package com.example.demo;

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

// @SpringBootApplication: 자동 설정 + 컴포넌트 스캔을 한 번에 활성화
@SpringBootApplication
public class DemoApplication {

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

HelloController.java

package com.example.demo;

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

import java.util.Map;

@RestController
public class HelloController {

    @GetMapping("/hello")
    public Map<String, String> hello() {
        return Map.of("message", "Hello, Spring Boot!");
    }
}

---

요청 흐름 다이어그램

graph LR
    A[브라우저 GET /hello] --> B[Spring Boot 내장 서버 8080]
    B --> C[HelloController.hello 메서드]
    C --> D[Map.of 반환]
    D --> E[Jackson이 JSON으로 직렬화]
    E --> F["응답: {message: Hello, Spring Boot!}"]

---

자주 만나는 에러와 해결

에러 1: Gradle 빌드 실패 — "Could not resolve"

FAILURE: Build failed with an exception.
Could not resolve org.springframework.boot:spring-boot-starter-web:3.3.4.

원인: 인터넷 연결 문제거나, 회사·학교 망에서 Maven Central 접근을 막아놓은 경우다.

1. IntelliJ 오른쪽 Gradle 패널에서 새로고침 버튼(♻) 클릭
2. 그래도 안 되면 와이파이를 핫스팟 등 다른 네트워크로 바꿔 재시도
3. 회사 내부망이라면 build.gradle의 repositories 블록에 사내 Nexus/Artifactory 주소 추가

에러 2: 포트 충돌 — "Port 8080 was already in use"

APPLICATION FAILED TO START
Web server failed to start. Port 8080 was already in use.

원인: 이미 다른 프로그램이 8080 포트를 쓰고 있다.

해결 A — 포트 번호 바꾸기:

src/main/resources/application.properties 파일에 한 줄 추가.

server.port=8081

이후 http://localhost:8081/hello로 접속.

해결 B — 기존 프로세스 종료:

# Mac / Linux
lsof -i :8080
kill -9 [PID 숫자]

# Windows PowerShell
netstat -ano | findstr :8080
taskkill /PID [PID 숫자] /F

에러 3: Java 버전 불일치 — "Unsupported class file major version"

java.lang.UnsupportedClassVersionError: com/example/demo/DemoApplication
has been compiled by a more recent version of the Java Runtime

원인: 컴파일한 JDK 버전과 실행하는 JVM 버전이 다르다.

해결: IntelliJ 상단 메뉴 File → Project Structure → Project Settings → SDK에서 JDK 21이 선택되어 있는지 확인. 없으면 "Add SDK → JDK"로 설치한 경로를 지정한다.

에러 4: 정상 실행인데 브라우저에서 404

{
  "timestamp": "...",
  "status": 404,
  "error": "Not Found",
  "path": "/hello"
}

원인: 십중팔구 패키지 문제다. HelloController.java가 DemoApplication.java와 같은 패키지이거나 그 하위 패키지에 있어야 스프링이 감지한다.

확인: 두 파일 모두 첫 줄이 package com.example.demo;인지 체크. 다르다면 맞춰준다.

---

핵심 요약

• Spring Boot 3.x는 JDK 17 이상 필수. 처음이라면 JDK 21 LTS
• start.spring.io → Spring Web 의존성 추가 → GENERATE → 압축 해제
• @RestController + @GetMapping으로 첫 API 완성
• ./gradlew bootRun 또는 IntelliJ ▶ 버튼으로 실행
• 404 에러의 90%는 패키지 위치 문제, 8080 충돌은 포트 번호 변경으로 해결

---

마무리

PC에 JDK가 없던 상태에서 {"message":"Hello, Spring Boot!"}까지 왔다. 스프링 부트는 처음 환경 세팅이 가장 높은 벽이다. 그 벽을 넘었으니 이제 코드 쌓는 일만 남았다.

다음 단계로 해볼 것들:

• application.yml로 전환: properties 대신 yml 포맷으로 설정 파일 바꾸기
• POST 요청 받기: @PostMapping과 @RequestBody로 데이터 받는 법
• MariaDB 연결: spring-boot-starter-data-jpa + MariaDB 드라이버로 DB CRUD 만들기
• 에러 처리: @ExceptionHandler로 예외를 JSON으로 응답하는 법