개발 환경 준비와 첫 Spring Boot 프로젝트

이번 장에서 만들 것

이번 장의 목표는 간단합니다. 내 컴퓨터에서 Spring Boot 프로젝트를 만들고, 실행하고, 브라우저에서 응답을 확인하는 것입니다.

아직 데이터베이스도, 로그인도, 게시판 기능도 만들지 않습니다. 먼저 "스프링 서버가 내 컴퓨터에서 켜지고 요청에 답한다"는 경험을 만드는 것이 중요합니다.

이번 장의 끝에서 우리는 다음 주소로 요청을 보낼 수 있어야 합니다.

http://localhost:8080

그리고 브라우저에는 이런 문장이 보일 것입니다.

게시판 API 서버가 실행 중입니다.

이것이 첫 번째 Spring Boot 애플리케이션입니다.

AI 생성 이미지

준비해야 할 도구

Spring Boot 개발을 시작하려면 몇 가지 도구가 필요합니다. 이름은 낯설 수 있지만 역할은 단순합니다.

• Java JDK: 자바 코드를 컴퓨터가 실행할 수 있는 프로그램으로 바꾸고 실행하는 도구입니다. 요리로 비유하면 재료를 손질하고 조리하는 주방 도구입니다.

• IntelliJ IDEA: 코드를 작성하는 편집기입니다. 단순한 메모장이 아니라 자동 완성, 오류 표시, 실행 버튼을 제공하는 개발용 작업대입니다.

• Gradle: 프로젝트를 빌드하고 필요한 라이브러리를 가져오는 도구입니다. 우리가 직접 파일을 하나씩 내려받지 않아도 되게 도와줍니다.

• Git: 코드 변경 기록을 남기는 도구입니다. 나중에 실수했을 때 이전 상태로 돌아가거나 협업할 때 사용합니다.

Spring Boot는 Java 17 이상을 기준으로 시작하는 것이 좋습니다. 공식 첫 애플리케이션 안내에서도 Java 버전을 확인한 뒤 프로젝트를 실행하는 흐름을 사용합니다.¹

설치가 끝났다면 터미널에서 버전을 확인합니다. 터미널은 명령어로 컴퓨터에 일을 시키는 창입니다.

java -version
javac -version
git --version
gradle -v

Windows라면 명령 프롬프트나 PowerShell에서 실행하면 됩니다. macOS라면 터미널 앱을 열면 됩니다.

예상 결과는 대략 다음과 비슷합니다.

java version "17..."
javac 17...
git version 2...
Gradle 8...

정확히 같은 숫자일 필요는 없습니다. 중요한 것은 java와 javac가 모두 17 이상으로 나오는 것입니다.

막히는 지점
java는 되는데 javac가 안 된다면 JRE만 설치했을 가능성이 있습니다. Spring Boot 개발에는 실행만 하는 JRE가 아니라 개발 도구가 포함된 JDK가 필요합니다.

그리고 gradle -v가 안 된다고 해서 너무 당황할 필요는 없습니다. 뒤에서 만들 프로젝트에는 Gradle Wrapper라는 실행 파일이 함께 들어 있습니다. 그래서 내 컴퓨터에 Gradle을 따로 설치하지 않았더라도 ./gradlew bootRun 또는 gradlew.bat bootRun으로 프로젝트를 실행할 수 있습니다. 다만 Gradle이 어떤 역할을 하는지 확인해 두면 이후 빌드 과정을 이해하기가 훨씬 쉽습니다.

IntelliJ IDEA에서 확인할 것

IntelliJ IDEA는 Community 버전으로도 Spring Boot 프로젝트를 열고 실행할 수 있습니다. 처음에는 유료 기능보다 기본 실행 흐름에 익숙해지는 것이 더 중요합니다.

설치 후에는 다음 항목만 확인하면 됩니다.

1. IntelliJ IDEA 실행

2. Settings 또는 Preferences 열기

3. Build, Execution, Deployment → Build Tools → Gradle 확인

4. Gradle JVM이 Java 17 이상인지 확인

여기서 JVM은 Java Virtual Machine의 줄임말입니다. 자바 프로그램을 실행하는 가상의 실행 환경입니다. "이 프로젝트를 어떤 자바로 실행할 것인가?"를 고르는 설정이라고 이해하면 됩니다.

만약 Gradle JVM이 낮은 버전으로 잡혀 있으면 프로젝트가 제대로 빌드되지 않을 수 있습니다. 이때는 앞에서 설치한 JDK 17 이상을 선택하면 됩니다.

Spring Initializr로 프로젝트 만들기

Spring Boot 프로젝트는 직접 폴더와 설정 파일을 하나씩 만들 수도 있습니다. 하지만 처음에는 Spring Initializr를 사용하는 것이 좋습니다. Spring Initializr는 스프링 프로젝트 생성기입니다. 필요한 기본 파일을 자동으로 만들어 주는 시작 템플릿이라고 생각하면 됩니다.

브라우저에서 다음 주소로 이동합니다.

https://start.spring.io

공식 빠른 시작 안내에서도 Spring Initializr에서 프로젝트를 만들고, 웹 의존성을 추가한 뒤, 내려받아 IDE에서 여는 흐름을 사용합니다.²

다음과 같이 선택합니다.

의존성에는 Spring Web을 추가합니다.

의존성은 프로젝트가 빌려 쓰는 외부 기능입니다. 우리가 웹 요청을 직접 바닥부터 처리하지 않고 Spring Web을 사용하는 이유는, HTTP 요청 처리에 필요한 기본 기능을 이미 잘 만들어 두었기 때문입니다.

설정이 끝나면 Generate 버튼을 눌러 zip 파일을 내려받습니다. 압축을 푼 뒤 IntelliJ IDEA에서 해당 폴더를 엽니다.

프로젝트 구조를 처음 볼 때

프로젝트를 열면 여러 파일이 보입니다. 지금은 전부 이해하지 않아도 됩니다. 먼저 중요한 것만 봅니다.

board
 ├─ build.gradle
 ├─ settings.gradle
 ├─ src
 │   ├─ main
 │   │   ├─ java
 │   │   │   └─ com.example.board
 │   │   │       └─ BoardApplication.java
 │   │   └─ resources
 │   │       └─ application.properties
 │   └─ test
 ├─ gradlew
 └─ gradlew.bat

build.gradle은 프로젝트의 준비물 목록입니다. 어떤 자바 버전을 쓰는지, 어떤 라이브러리를 가져올지 적혀 있습니다.

src/main/java는 실제 자바 코드가 들어가는 곳입니다.

BoardApplication.java는 애플리케이션의 시작점입니다. 프로그램으로 치면 전원 버튼과 같습니다.

package com.example.board;

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

@SpringBootApplication
public class BoardApplication {

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

여기서 main 메서드는 자바 프로그램이 시작되는 입구입니다. SpringApplication.run(...)은 Spring Boot 애플리케이션을 실행하라는 명령입니다.

@SpringBootApplication은 "이 클래스가 Spring Boot 애플리케이션의 시작 클래스입니다"라고 알려주는 표시입니다. 자세한 내부 원리는 뒤에서 다룹니다. 지금은 시작점 표시라고 이해하면 충분합니다.

첫 실행하기

IntelliJ IDEA에서 BoardApplication.java를 열면 왼쪽에 초록색 실행 버튼이 보입니다. 이 버튼을 눌러 실행합니다.

터미널에서 실행하고 싶다면 프로젝트 폴더에서 다음 명령어를 사용합니다.

macOS 또는 Linux:

./gradlew bootRun

Windows:

.gradlew.bat bootRun

여기서 gradlew는 Gradle Wrapper입니다. 프로젝트에 포함된 Gradle 실행 파일입니다. 내 컴퓨터에 설치된 Gradle 버전이 조금 달라도 프로젝트가 정한 방식으로 실행할 수 있게 도와줍니다.

실행에 성공하면 콘솔에 여러 줄의 로그가 출력됩니다.

:: Spring Boot ::
Tomcat initialized with port 8080 (http)
Started BoardApplication in 2.345 seconds

로그는 애플리케이션이 켜지는 과정을 보여주는 기록입니다.

Started BoardApplication이 보이면 애플리케이션 실행에 성공한 것입니다.

Tomcat initialized with port 8080은 웹 요청을 받을 서버가 8080번 포트에서 준비되었다는 뜻입니다. Spring Boot는 내장 서버를 사용해 애플리케이션을 바로 실행할 수 있습니다. 그래서 예전처럼 외부 서버를 따로 설치하고 배포하는 과정 없이 main 메서드 실행만으로 웹 서버를 켤 수 있습니다.³

포트는 컴퓨터 안의 문 번호입니다. localhost:8080은 "내 컴퓨터의 8080번 문으로 요청을 보낸다"는 뜻입니다.

첫 컨트롤러 만들기

이제 요청에 응답하는 코드를 작성해 보겠습니다.

src/main/java/com/example/board 폴더에서 HelloController.java 파일을 새로 만듭니다.

package com.example.board;

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

@RestController
public class HelloController {

    @GetMapping("/")
    public String hello() {
        return "게시판 API 서버가 실행 중입니다.";
    }
}

코드는 짧지만 중요한 개념이 들어 있습니다.

@RestController는 이 클래스가 웹 요청에 응답하는 클래스라고 알려줍니다. 컨트롤러는 식당의 주문 접수 직원과 비슷합니다. 손님이 주문을 하면 주방에 전달하고 결과를 돌려주는 역할을 합니다. 웹 애플리케이션에서는 요청을 받고 응답을 돌려줍니다.

@GetMapping("/")은 GET 방식으로 / 주소에 요청이 오면 아래 메서드를 실행하라는 뜻입니다.

hello() 메서드는 문자열을 반환합니다. Spring Boot는 이 문자열을 HTTP 응답 본문에 담아 브라우저로 보냅니다.

이제 애플리케이션을 다시 실행합니다. 이미 실행 중이었다면 정지한 뒤 다시 실행합니다. IntelliJ IDEA에서 실행 중인 애플리케이션을 멈추려면 보통 콘솔 창의 빨간색 정지 버튼을 누르면 됩니다.

브라우저에서 다음 주소를 엽니다.

http://localhost:8080

화면에 다음 문장이 보이면 성공입니다.

게시판 API 서버가 실행 중입니다.

터미널에서 확인하고 싶다면 다음 명령어를 사용할 수도 있습니다.

curl http://localhost:8080

브라우저도 클라이언트이고, curl도 클라이언트입니다. 둘 다 서버에 요청을 보내고 응답을 받습니다. 앞에서 살펴본 요청과 응답의 흐름이 이제 내 컴퓨터에서 실제로 일어난 것입니다.

흔한 오류와 해결법

처음 실행할 때 가장 자주 만나는 문제를 정리해 보겠습니다.

8080 포트를 이미 사용 중일 때

다음과 비슷한 메시지가 나올 수 있습니다.

Port 8080 was already in use

이미 다른 프로그램이 8080번 문을 사용하고 있다는 뜻입니다. 실행 중인 기존 Spring Boot 앱을 종료하거나 포트를 바꿉니다.

src/main/resources/application.properties에 다음을 추가합니다.

server.port=8081

그다음 브라우저에서 다음 주소로 접속합니다.

http://localhost:8081

Whitelabel Error Page가 보일 때

브라우저에 오류 페이지가 보인다면 주소와 컨트롤러 매핑을 확인합니다.

@GetMapping("/")

이 코드는 / 주소에만 응답합니다. 만약 http://localhost:8080/hello로 접속했다면 현재 코드에서는 응답할 메서드가 없습니다.

오류가 항상 나쁜 것은 아닙니다. "요청이 서버까지 도착했지만, 처리할 주소를 찾지 못했다"는 정보이기도 합니다.

컨트롤러가 동작하지 않을 때

HelloController 파일의 위치를 확인합니다.

com.example.board
 ├─ BoardApplication.java
 └─ HelloController.java

처음에는 시작 클래스와 같은 패키지에 두는 것이 가장 안전합니다. 다른 위치에 두면 Spring Boot가 컨트롤러를 찾지 못할 수 있습니다.

이번 장에서 기억할 것

이번 장에서는 개발 환경을 준비하고 첫 Spring Boot 애플리케이션을 실행했습니다.

핵심은 네 가지입니다.

1. Java 17 이상, IntelliJ IDEA, Gradle, Git을 준비하고 버전을 확인합니다.

2. Spring Initializr에서 Gradle, Java, Spring Web을 선택해 프로젝트를 만듭니다.

3. 실행 로그에서 Started ...와 Tomcat ... port 8080을 확인합니다.

4. @RestController와 @GetMapping으로 첫 요청에 응답합니다.

이제 우리에게는 아주 작은 서버가 생겼습니다. 아직 게시판 기능은 없지만, 요청을 받고 응답하는 출발점은 완성되었습니다. 다음 장에서는 스프링 코드를 읽고 쓰기 위해 꼭 필요한 자바 문법을 정리합니다.

참고

¹Developing Your First Spring Boot Application

²Spring Quickstart

³Spring Boot Reference Documentation