전체 메뉴

테마

Chapter 01

프로젝트 시작하기

Spring Boot 4.1.1과 JDK 21로 Initializr 프로젝트를 만들고 build.gradle과 시작 클래스를 읽은 뒤, 첫 REST API와 MockMvc 테스트를 작성하고 bootRun·curl로 실행해 자주 만나는 오류까지 확인합니다.

난이도
입문
예상 학습
90분
Spring Boot 기준
Spring Boot 4.1.1
JDK 기준
JDK 21
최종 검토

전체 24개 Chapter 중 Chapter 01입니다. 예제 코드는 공개 저장소 spring-boot-curriculum의 examples/ch01-hello-spring 폴더에서 확인할 수 있습니다.

저녁 거실 소파에서 노트북의 프로젝트 폴더 구조를 함께 보며 이야기하는 아빠와 아들 개발자
Chapter 01은 프로젝트 폴더 구조를 함께 읽는 데서 시작합니다.

Learning goals

오늘 배울 내용

  • Spring Framework와 Spring Boot의 역할을 구분해서 설명하기
  • Spring Initializr로 만든 프로젝트의 build.gradle과 폴더 구조 읽기
  • @SpringBootApplication과 @RestController가 하는 일을 설명하고 첫 API 만들기
  • MockMvc로 컨트롤러 테스트를 쓰고 bootRun과 curl로 응답과 로그 확인하기
  • 처음 만나는 대표 오류 메시지의 원인과 해결 방법 찾기
  1. 프로젝트 생성
  2. 구조 읽기
  3. 컨트롤러 작성
  4. MockMvc 테스트
  5. 실행과 요청
  6. 오류 대응
이 Chapter의 진행 흐름

가장 작은 서버 하나로 전체 흐름을 익힙니다

이 Chapter는 Spring Boot 과정의 출발점입니다. 스프링을 한 번도 써 보지 않았어도 따라올 수 있도록, 가장 작은 서버 하나를 만들어 실행하고 요청을 보내 보는 데까지를 다룹니다. 기능은 작지만 프로젝트를 만들고, 실행하고, 테스트하는 전체 흐름이 모두 들어 있습니다. 이후 Chapter는 모두 이 흐름 위에서 기능을 하나씩 더합니다.

Chapter를 마치면 아래 세 가지를 직접 만들고 확인한 상태가 됩니다.

만드는 것 설명
GET /hello 이름을 받아 인사 문자열을 돌려주는 API
GET /info 앱 이름, Java 버전, Boot 버전을 JSON으로 돌려주는 API
MockMvc 테스트 4건 서버를 띄우지 않고 위 API가 올바르게 동작하는지 자동으로 확인하는 테스트

준비물과 예제 저장소

항목 내용
사전 지식 Java 기본 문법(클래스, 메서드, 인터페이스, record). 스프링 경험은 필요 없습니다.
JDK 21 (java -version으로 확인)
Gradle 설치 불필요. 저장소의 Wrapper(gradlew)를 씁니다.
도구 터미널, curl, 편집기 또는 IDE
코드 아래 저장소를 내려받습니다.
git clone https://github.com/devguna81/spring-boot-curriculum.git
cd spring-boot-curriculum

이 Chapter의 코드는 공개 저장소의 examples/ch01-hello-spring 폴더에 있습니다. 모든 명령은 저장소 루트에서 실행합니다. Windows에서는 ./gradlew 대신 gradlew.bat을 씁니다.

본문의 실행 결과는 원고 작성 시 컨테이너(JDK 21.0.11)에서 직접 돌려서 얻은 값이고, GitHub Actions에서도 같은 빌드가 통과했습니다. 실행 로그와 의존성 캐시에서 확인한 버전은 다음과 같습니다.

항목 값 어디서 확인했나
Spring Boot 4.1.1 /info 응답
Spring Framework 7.0.9 Gradle 의존성 캐시
내장 서버 Apache Tomcat 11.0.24 기동 로그
Java 21 build.gradle의 toolchain
Gradle 9.8.1 Gradle Wrapper

Java는 21 이상이 필요합니다. 17로는 이 과정의 빌드가 통과하지 않으며, 그때 나오는 오류 메시지는 아래 오류 절에서 확인합니다.

서버를 직접 만든다면 해야 하는 일

브라우저가 GET /hello를 보냈을 때 “Hello”라는 글자를 돌려주는 서버를 Java만으로 만든다고 생각해 봅니다. 최소한 이런 일을 직접 해야 합니다.

  1. 네트워크 연결을 받아 HTTP 요청 문장을 읽는다 (서버 소프트웨어).
  2. 요청의 경로와 메서드를 보고 어떤 Java 메서드를 부를지 정한다 (요청 분배).
  3. 쿼리 문자열의 값을 꺼내 Java 변수로 바꾼다 (파라미터 변환).
  4. Java 객체를 JSON 문자열로 바꿔 응답에 쓴다 (직렬화).
  5. 이 모든 부품 객체를 만들고 서로 연결한다 (객체 생성과 연결).
  6. 설정 값(포트, 이름 등)을 파일에서 읽어 각 부품에 전달한다 (설정 관리).
  7. 서버를 켜고 끄는 일, 오류가 났을 때 응답 문장을 만드는 일을 처리한다 (생명주기와 오류 처리).

하나하나는 어렵지 않지만, 서비스를 만들 때마다 같은 일을 처음부터 다시 쓰게 됩니다. 스프링은 이 반복되는 부분을 미리 만들어 둔 도구입니다.

Spring Framework는 부품과 조립 틀입니다

Spring Framework는 위 목록의 대부분을 해결하는 라이브러리 묶음입니다. 크게 두 가지로 나누어 이해하면 쉽습니다.

첫째, 객체를 만들고 연결해 주는 컨테이너입니다. 우리가 new로 직접 객체를 만들고 서로 넘겨주는 대신, 스프링이 필요한 객체를 만들어 두고 필요한 곳에 넣어 줍니다. 이 방식을 IoC(제어의 역전)와 DI(의존성 주입)라고 부르며, Chapter 03 IoC, DI, Bean에서 코드로 직접 비교합니다. 지금은 “객체를 만들고 이어 붙이는 일을 스프링이 맡는다” 정도만 기억하면 됩니다.

둘째, 그 컨테이너 위에서 쓰는 기능 모음입니다. 웹 요청 처리(Spring MVC), 데이터베이스 접근, 트랜잭션, 테스트 지원이 여기에 들어 있습니다. 이 Chapter에서 쓰는 @GetMapping, @RequestParam, MockMvc가 모두 이 기능 모음에서 나옵니다.

Spring Boot는 조립과 실행을 맡습니다

Framework만으로도 서버를 만들 수 있지만, 쓰려면 결정할 것이 많습니다. 어떤 라이브러리를 어느 버전으로 같이 쓸지, 서버는 어떤 것을 붙일지, 설정은 어떻게 연결할지를 모두 정해야 합니다. Spring Boot는 이 결정을 미리 해 둔 기본값 묶음입니다.

두 계층의 관계를 위에서 아래로 쌓아 보면 다음과 같습니다. 위가 우리가 쓰는 코드이고, 아래로 갈수록 기반이 됩니다.

계층 담당하는 것
우리 코드 HelloController, AppInfo
Spring Boot 스타터, 자동 구성, 내장 서버, 실행 jar
Spring Framework 컨테이너(IoC/DI), Spring MVC, 트랜잭션, 테스트 지원
JDK 21 Java 실행 환경

Boot는 Framework를 대신하는 것이 아니라 그 위에서 조립과 실행을 맡습니다. 그래서 컨트롤러 코드에 보이는 애노테이션 대부분은 Framework 것이고, @SpringBootApplication과 build.gradle의 스타터는 Boot 것입니다. Boot가 하는 일은 크게 네 가지입니다.

Boot가 하는 일 쉬운 설명 이 과정에서 만나는 곳
스타터(starter) 기능 하나에 필요한 라이브러리를 한 줄로 가져온다. 버전도 서로 맞는 조합으로 정해 준다 이 Chapter의 build.gradle
자동 구성 클래스패스에 어떤 라이브러리가 있는지 보고 필요한 설정을 대신 만든다 이 Chapter의 @SpringBootApplication
내장 서버 서버(Tomcat)를 앱 안에 넣어서 java -jar로 바로 실행한다 이 Chapter의 기동 로그와 실행
운영 기능 상태 확인, 지표 같은 기능을 의존성 하나로 켠다 Chapter 22 운영의 Actuator

정리하면 Framework는 부품이고, Boot는 그 부품을 알맞게 조립해서 바로 켤 수 있는 상태로 내주는 도구입니다. 그래서 새 프로젝트는 Framework가 아니라 Boot로 시작하는 것이 보통입니다.

Boot 4에서 달라진 두 가지를 먼저 알아 둡니다

이 과정은 Boot 4.1.1을 씁니다. 인터넷에서 찾은 Boot 3 시절 예제를 그대로 따라 하다가 막히는 이유는 대부분 아래 두 가지이며, 두 곳 모두 이 Chapter의 코드에서 직접 확인합니다.

  • 큰 jar가 작은 모듈로 쪼개지면서 스타터 이름이 기술 이름을 따라 정리되었습니다. 웹 스타터는 spring-boot-starter-web이 아니라 spring-boot-starter-webmvc로 만들어집니다.
  • 같은 이유로 테스트 지원 클래스의 패키지 경로도 바뀌었습니다. @AutoConfigureMockMvc의 import 경로가 달라져, Boot 3 경로로 쓰면 컴파일이 되지 않습니다.

두 가지 모두 공식 마이그레이션 가이드에 같은 내용이 있고, 코드를 쓰기 전에 문서나 jar 안을 확인하면 미리 알 수 있는 종류입니다.

자주 하는 오해 사실
Spring Boot는 Spring을 대체하는 새 프레임워크다 Boot는 Framework 위에서 설정과 실행을 단순하게 만들어 주는 도구입니다. Framework 코드를 그대로 씁니다.
자동 구성은 마법이라 건드릴 수 없다 클래스패스에 라이브러리가 있으면 켜지는 규칙입니다. 필요하면 설정으로 끄거나 바꿀 수 있습니다.
내장 서버라서 운영에는 못 쓴다 java -jar로 실행하는 내장 Tomcat은 운영에서도 흔한 방식입니다. 이 과정의 Docker 실습에서도 같은 jar를 씁니다.
Boot 3 예제는 4에서 그냥 된다 스타터 이름과 테스트 패키지 경로가 달라져 그대로는 막히는 지점이 있습니다.

Initializr에서 고르는 항목

스프링 프로젝트는 빈 폴더에서 손으로 시작하지 않고, 뼈대를 만들어 주는 웹 도구인 Spring Initializr(https://start.spring.io)에서 시작하는 것이 보통입니다. 프로젝트 설정을 고르면 압축 파일로 뼈대를 만들어 줍니다. 이 프로젝트에서 고른 값은 다음과 같습니다.

항목 고른 값 의미
Project Gradle 빌드 도구입니다. 컴파일, 테스트, 실행 파일 만들기를 맡습니다. Maven도 있지만 이 과정은 Gradle을 씁니다.
Language Java 코드를 쓸 언어입니다.
Spring Boot 4.1.1 사용할 Boot 버전입니다.
Java 21 컴파일과 실행에 쓸 JDK 버전입니다.
Dependencies Spring Web 웹 API를 만들 때 필요한 라이브러리 묶음입니다.

의존성(Dependencies)은 “이 프로젝트가 쓰는 외부 라이브러리”입니다. 처음에는 Spring Web 하나만 고릅니다. 데이터베이스나 보안이 필요하면 그때 한 줄씩 추가합니다. 처음부터 많이 담으면 어떤 기능이 어떤 라이브러리에서 오는지 구분하기 어려워지기 때문입니다.

build.gradle은 plugins와 dependencies 순서로 읽습니다

빌드 파일을 읽을 수 있으면 코드를 열지 않고도 이 프로젝트가 어떤 라이브러리로 만들어졌는지 알 수 있고, 오류 메시지의 절반이 이 파일에서 풀립니다. 이 저장소의 ch01 예제 build.gradle은 이렇게 생겼습니다.

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

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-webmvc'

    testImplementation 'org.springframework.boot:spring-boot-starter-webmvc-test'
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}

모듈의 build.gradle은 “어떤 빌드 기능을 붙이고(plugins) 어떤 라이브러리를 가져올지(dependencies)“만 적습니다. JDK 버전과 테스트 설정 같은 공통 사항은 루트 build.gradle이 모든 모듈에 내려 줍니다.

plugins는 빌드 기능을 붙입니다

플러그인 하는 일
java Java 컴파일, 테스트 실행, jar 만들기 같은 기본 작업을 붙입니다.
org.springframework.boot bootRun(바로 실행)과 bootJar(실행 가능한 jar 만들기) 같은 Boot 전용 작업을 붙입니다.
io.spring.dependency-management 의존성 버전을 Boot가 정한 조합에 맞춰 줍니다.

세 번째 플러그인 덕분에 dependencies에 버전 번호를 적지 않아도 됩니다. 위 코드에서 spring-boot-starter-webmvc 뒤에 :4.1.1 같은 버전이 없는 이유입니다. 버전은 한 곳에서 관리하며, 이 저장소에서는 루트의 gradle.properties에 있습니다.

springBootVersion=4.1.1
dependencyManagementVersion=1.1.7

Boot 버전을 올릴 때 이 한 줄만 바꾸면 모든 예제가 같이 올라갑니다.

dependencies는 언제 쓰는 라이브러리인지 구분합니다

줄 앞의 키워드가 “언제 쓰는 라이브러리인가”를 정합니다.

키워드 쓰이는 때
implementation 코드를 컴파일하고 실행할 때 필요합니다.
testImplementation 테스트 코드를 컴파일하고 실행할 때만 필요합니다. 실행 파일에는 들어가지 않습니다.
testRuntimeOnly 테스트를 실행할 때만 필요하고, 코드에서 직접 부르지는 않습니다.

그래서 이 프로젝트는 세 가지를 가져옵니다.

  • spring-boot-starter-webmvc: 웹 API에 필요한 모든 것. 내장 Tomcat, Spring MVC, JSON 변환 라이브러리가 함께 들어옵니다.
  • spring-boot-starter-webmvc-test: 웹 계층 테스트 도구(MockMvc 등)입니다.
  • junit-platform-launcher: JUnit 테스트를 실행하는 데 쓰는 런처입니다.

스타터 이름이 webmvc로 바뀐 이유

스타터(starter)는 “이 기능을 쓰려면 필요한 라이브러리를 한 묶음으로 가져오는 의존성”입니다. 웹 API를 만들려면 서버, 요청 처리, JSON 변환, 로깅이 모두 필요한데, 스타터 한 줄이 이 목록을 대신 적어 줍니다.

Boot 3까지 웹 스타터는 spring-boot-starter-web이었습니다. Boot 4는 하나였던 큰 jar를 기능별 작은 모듈로 쪼개면서 스타터 이름을 기술 이름에 맞춰 정리했고, 서블릿 기반 웹 MVC는 spring-boot-starter-webmvc가 되었습니다. 같은 이유로 테스트 스타터도 spring-boot-starter-webmvc-test처럼 기술 이름이 붙습니다.

원고 작성 시 옛 이름 spring-boot-starter-web으로 바꿔도 이 예제의 테스트 4건은 통과했지만, 그 이유는 확인하지 않았습니다. 이 과정은 Initializr가 만든 이름(webmvc)을 그대로 따릅니다. 새 이름을 쓰면 이후 버전에서도 안전하기 때문입니다.

루트 빌드와 모듈 빌드의 두 겹 구조

이 과정의 예제는 Chapter마다 모듈이 하나씩 생기는 Gradle 멀티 프로젝트입니다. 루트의 settings.gradle이 모듈 목록을 가지고 있습니다.

include 'examples:ch01-hello-spring'
include 'examples:ch02-config-profile'
// ... 챕터가 추가될 때마다 한 줄씩 늘어난다

루트 build.gradle은 모든 모듈이 공유하는 설정만 둡니다.

subprojects {
    group = 'com.jqdom.curriculum'
    version = '0.0.1-SNAPSHOT'

    repositories {
        mavenCentral()
    }

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

        tasks.withType(Test).configureEach {
            useJUnitPlatform()
            testLogging {
                events 'passed', 'skipped', 'failed'
                exceptionFormat 'full'
            }
        }
    }
}
  • repositories { mavenCentral() }: 라이브러리를 내려받을 저장소입니다.
  • toolchain의 languageVersion = 21: “이 프로젝트는 JDK 21로 빌드한다”는 선언입니다. 컴퓨터에 다른 JDK가 있어도 Gradle이 21을 찾아 씁니다. 21이 없으면 빌드가 멈춥니다.
  • useJUnitPlatform(): 테스트를 JUnit으로 실행합니다.
  • testLogging: 테스트 결과를 PASSED, FAILED로 한 줄씩 출력합니다. 아래 테스트 실행 결과에 나오는 HelloControllerTests > ... PASSED 줄이 이 설정에서 나옵니다.

모듈의 build.gradle에는 그 모듈에만 필요한 의존성만 있기 때문에, Chapter가 진행될수록 이 파일이 어떻게 늘어나는지 비교해 볼 수 있습니다.

이 Chapter에서 쓰는 Gradle 명령은 네 가지입니다.

명령 하는 일 쓰는 곳
./gradlew :examples:ch01-hello-spring:compileJava Java 컴파일만 수행 코드 문법 오류 확인
./gradlew :examples:ch01-hello-spring:test 컴파일 후 테스트 실행 MockMvc 테스트
./gradlew :examples:ch01-hello-spring:bootRun 바로 서버 실행 서버 실행과 curl 요청
./gradlew :examples:ch01-hello-spring:bootJar 실행 가능한 jar 생성 실행 가능한 jar 확인

:examples:ch01-hello-spring처럼 앞에 모듈 경로를 붙이면 그 모듈만 작업합니다. 경로를 생략하면 모든 모듈에 대해 실행되어 시간이 오래 걸리므로, Chapter 학습 중에는 항상 모듈 경로를 붙이는 편이 빠릅니다.

프로젝트 구조는 세 갈래로 읽습니다

프로젝트를 만들면 폴더와 파일이 한꺼번에 생깁니다. 어디에 무엇을 두는지 알아야 새 코드를 어디에 쓸지도 정할 수 있습니다. ch01 모듈의 구조는 이렇습니다.

ch01-hello-spring/
├── build.gradle
└── src
    ├── main
    │   ├── java/com/jqdom/curriculum/ch01
    │   │   ├── Ch01Application.java
    │   │   ├── HelloController.java
    │   │   └── AppInfo.java
    │   └── resources/application.yml
    └── test/java/com/jqdom/curriculum/ch01
        ├── Ch01ApplicationTests.java
        └── HelloControllerTests.java
위치 두는 것 이 모듈의 예
src/main/java 실제로 실행되는 Java 코드 Ch01Application, HelloController, AppInfo
src/main/resources 설정 파일, 정적 파일, SQL 같은 코드가 아닌 자원 application.yml
src/test/java 테스트 코드. 실행 파일에는 포함되지 않습니다 HelloControllerTests

이 구분은 Maven과 Gradle이 모두 쓰는 표준 배치입니다. 이 규칙을 따르면 빌드 도구가 따로 설정하지 않아도 어디서 코드를 컴파일하고 어디서 설정 파일을 찾을지 압니다.

시작 클래스의 패키지가 스캔 범위를 정합니다

코드는 모두 com.jqdom.curriculum.ch01 패키지 아래에 있습니다. 시작 클래스가 이 패키지에 있기 때문에, 스프링은 시작 클래스가 속한 패키지와 그 하위 패키지만 훑어서 Bean 후보를 찾습니다. 이 과정을 컴포넌트 스캔이라고 부릅니다. 컨트롤러를 시작 클래스보다 바깥 패키지에 두면 스프링이 찾지 못해서 URL이 404가 됩니다.

규칙은 간단합니다. 시작 클래스를 가장 바깥 패키지에 두고, 나머지 클래스를 그 아래에 둡니다. 컴포넌트 스캔은 Chapter 03 IoC, DI, Bean에서 실험으로 다시 확인합니다.

시작 클래스 하나로 서버가 켜집니다

서버를 켜는 코드는 이것이 전부입니다.

@SpringBootApplication
public class Ch01Application {

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

SpringApplication.run(Ch01Application.class, args)는 다음 일을 순서대로 처리합니다.

  1. 스프링 컨테이너(ApplicationContext)를 만듭니다. 이후 만들어지는 모든 객체(Bean)가 이 안에 담깁니다.
  2. 설정 파일(application.yml)을 읽어 컨테이너에 올립니다.
  3. 컴포넌트 스캔과 자동 구성으로 필요한 Bean을 만들어 연결합니다.
  4. 웹 라이브러리가 있으면 내장 Tomcat을 만들어 켭니다.

args는 실행할 때 명령행에서 넘긴 인자입니다. 이 값으로 설정을 덮어쓰는 방법은 Chapter 02 설정과 Profile에서 다룹니다.

@SpringBootApplication은 사실 세 애노테이션을 합친 것입니다.

포함된 것 하는 일
@SpringBootConfiguration 이 클래스가 설정 클래스임을 알립니다. 여기서 직접 Bean을 등록할 수도 있습니다.
@EnableAutoConfiguration 클래스패스의 라이브러리를 보고 설정을 자동으로 구성합니다. 웹 스타터가 있으므로 Tomcat과 DispatcherServlet이 만들어집니다.
@ComponentScan 이 클래스의 패키지 아래에서 @Component가 붙은 클래스를 찾아 Bean으로 등록합니다. @RestController도 @Component의 일종이라 여기서 발견됩니다.

“자동으로 된다”는 말이 마법처럼 들리지만 실제로는 규칙입니다. 라이브러리가 있으면 켜지고, 없으면 켜지지 않습니다. 이 규칙을 알면 “왜 이 기능이 갑자기 켜졌지” 또는 “왜 안 켜졌지”를 의존성 목록에서 찾을 수 있습니다.

기동 로그에서 확인할 다섯 줄

실행하면 콘솔에 로그가 쏟아집니다. 전부 읽을 필요는 없고, 핵심은 다섯 줄입니다.

Starting Ch01Application v0.0.1-SNAPSHOT using Java 21.0.11
No active profile set, falling back to 1 default profile: "default"
Starting Servlet engine: [Apache Tomcat/11.0.24]
Tomcat started on port 8080 (http) with context path '/'
Started Ch01Application in 3.737 seconds
로그 읽는 법
Starting Ch01Application ... Java 21.0.11 어떤 클래스가 어떤 JDK로 시작되는지 보여 줍니다. JDK 버전 문제는 여기서 먼저 확인합니다.
No active profile set ... 환경별 설정(Profile)을 고르지 않아 기본값을 쓴다는 뜻입니다. Chapter 02에서 다룹니다.
Starting Servlet engine: [Apache Tomcat/11.0.24] 내장 서버가 켜졌습니다. 별도 Tomcat을 설치하지 않았습니다.
Tomcat started on port 8080 접속 주소는 http://localhost:8080입니다. 포트가 겹치면 여기서 막힙니다.
Started Ch01Application in 3.737 seconds 모든 준비가 끝난 시점입니다. 이 줄이 나오면 요청을 받을 수 있습니다.

요청이 컨트롤러에 도착하는 순서

서버가 켜진 뒤 GET /hello 요청이 오면 아래 순서로 처리됩니다.

  1. 내장 Tomcat이 네트워크로 들어온 요청 문장을 읽어 요청 객체로 만듭니다.
  2. DispatcherServlet이 요청의 경로(/hello)와 메서드(GET)를 보고 어느 컨트롤러 메서드를 부를지 정합니다. Spring MVC의 문지기 역할입니다.
  3. 정해진 컨트롤러 메서드(@GetMapping이 붙은 HelloController의 메서드)가 실행됩니다.
  4. 반환값(문자열이나 객체)을 응답 본문으로 바꿉니다. 객체이면 JSON으로 바뀝니다.
  5. Tomcat이 HTTP 응답을 돌려보냅니다.

우리가 쓰는 코드는 3번 하나뿐입니다. 나머지는 스프링이 대신 처리합니다.

첫 API는 문자열과 JSON을 하나씩 돌려줍니다

이제 요청을 받아 응답을 돌려주는 컨트롤러를 만듭니다. GET /hello는 문자열을, GET /info는 JSON을 돌려줍니다.

요청 응답 형태
GET /hello Hello, Spring Boot! 문자열
GET /hello?name=devguna Hello, devguna! 문자열
GET /info 앱 이름, Java 버전, Boot 버전 JSON 객체

REST API는 “주소(URL)와 메서드(GET, POST 등)로 기능을 구분하는 웹 API”입니다. 여기서는 읽기 전용인 GET만 쓰고, 나머지 메서드는 Chapter 05 CRUD API와 DTO에서 다룹니다.

@RestController
public class HelloController {

    private final String applicationName;

    public HelloController(@Value("${spring.application.name}") String applicationName) {
        this.applicationName = applicationName;
    }

    @GetMapping("/hello")
    public String hello(@RequestParam(defaultValue = "Spring Boot") String name) {
        return "Hello, " + name + "!";
    }

    @GetMapping("/info")
    public AppInfo info() {
        return new AppInfo(
                applicationName,
                System.getProperty("java.version"),
                SpringBootVersion.getVersion());
    }
}

짧은 코드지만 애노테이션 네 개와 Java 문법 두 개(생성자, record)가 들어 있습니다. 요청이 어느 메서드로 가서 어떤 응답이 되는지 먼저 표로 보면 다음과 같습니다.

요청 처리 메서드 반환 타입 응답 본문
GET /hello?name=devguna hello(name) String Hello, devguna!
GET /info info() AppInfo record Jackson이 JSON으로 변환한 {name, javaVersion, springBootVersion}

@RestController는 반환값을 응답 본문으로 씁니다

컨트롤러는 “웹 요청을 받아 처리하는 클래스”입니다. @RestController를 붙이면 두 가지가 정해집니다.

  1. 이 클래스를 스프링이 찾아서 Bean으로 등록합니다(컴포넌트 스캔 대상).
  2. 메서드의 반환값을 화면 이름이 아니라 응답 본문으로 씁니다.

두 번째가 중요합니다. @RestController는 @Controller와 @ResponseBody를 합친 것과 같습니다. @Controller로 바꾸면 어떤 일이 생기는지는 아래 오류 절에서 실험 결과로 확인합니다.

@GetMapping과 @RequestParam이 주소와 값을 연결합니다

@GetMapping("/hello")
public String hello(@RequestParam(defaultValue = "Spring Boot") String name) {
    return "Hello, " + name + "!";
}
  • @GetMapping("/hello"): “GET 방식으로 /hello가 오면 이 메서드를 부른다”는 선언입니다. DispatcherServlet이 이 정보를 보고 메서드를 고릅니다.
  • @RequestParam: 쿼리 문자열의 ?name=... 값을 메서드 파라미터 name에 넣습니다.
  • defaultValue = "Spring Boot": name이 없을 때 쓸 값입니다. 이 설정이 없으면 name이 없는 요청은 오류가 납니다.
  • 반환값 String은 그대로 응답 본문이 됩니다.

그래서 /hello는 Hello, Spring Boot!, /hello?name=devguna는 Hello, devguna!가 됩니다.

@Value는 설정 파일의 값을 생성자로 넘깁니다

컨트롤러가 앱 이름을 알아야 하는데, 이름은 코드가 아니라 설정 파일(application.yml)에 있습니다.

spring:
  application:
    name: ch01-hello-spring

@Value("${spring.application.name}")는 “설정 파일의 spring.application.name 값을 가져와라”입니다. 스프링이 컨트롤러를 만들 때 이 값을 찾아 생성자에 넣어 줍니다. 값을 필드에 바로 넣지 않고 생성자로 받는 이유는 Chapter 03에서 다룹니다. 지금은 두 가지만 기억하면 됩니다.

  • 설정 파일의 키가 없으면 서버가 뜨지 않습니다. 실제 메시지는 아래 오류 절에서 봅니다.
  • ${...} 안의 이름은 파일의 들여쓰기 구조를 점(.)으로 이은 것입니다.

record를 반환하면 JSON이 됩니다

/info는 문자열이 아니라 AppInfo 객체를 돌려줍니다. AppInfo는 필드 세 개를 가진 데이터 클래스입니다.

public record AppInfo(String name, String javaVersion, String springBootVersion) {
}

record는 “값을 담는 불변 객체”를 한 줄로 선언하는 Java 문법입니다. 생성자, 값을 꺼내는 메서드, equals, toString이 자동으로 만들어집니다. 이 과정에서는 요청과 응답에 쓰는 데이터(DTO)를 모두 record로 씁니다.

객체를 반환하면 스프링이 JSON으로 바꿔 응답합니다. 이 변환은 Jackson이라는 라이브러리가 하고, record의 필드 이름이 그대로 JSON 키가 됩니다.

{"name":"ch01-hello-spring","javaVersion":"21.0.11","springBootVersion":"4.1.1"}

System.getProperty("java.version")은 실행 중인 JDK 버전이고, SpringBootVersion.getVersion()은 사용 중인 Boot의 버전 문자열입니다. 앞의 버전표에서 Spring Boot 4.1.1을 /info 응답에서 확인했다고 한 것이 이 메서드입니다.

두 메서드는 반환 타입만 다른데 응답 형태가 달라집니다. 스프링이 반환 타입을 보고 알맞은 변환 방식을 고르기 때문입니다.

반환 타입 응답 본문
String 문자열 그대로 (Hello, Spring Boot!)
record 같은 객체 JSON ({"name":...})

이 과정의 이후 API는 대부분 객체(record)를 돌려주고, 목록은 객체의 배열, 오류는 오류 정보를 담은 객체가 됩니다. URL 설계와 상태 코드는 Chapter 04 HTTP와 REST, Controller에서 체계적으로 다룹니다.

메서드 하나로 새 주소를 여는 연습

  1. HelloController에 아래 메서드를 추가합니다.
@GetMapping("/bye")
public String bye(@RequestParam(defaultValue = "Spring Boot") String name) {
    return "Bye, " + name + "!";
}
  1. ./gradlew :examples:ch01-hello-spring:bootRun으로 서버를 켭니다.
  2. curl "http://localhost:8080/bye?name=devguna"를 호출합니다.
  3. Bye, devguna!가 나오면 성공입니다.

메서드를 추가하고 @GetMapping만 붙였는데 새 주소가 열린다는 것이 컴포넌트 스캔과 DispatcherServlet이 하는 일입니다.

MockMvc로 서버 없이 컨트롤러를 확인합니다

서버를 띄우고 브라우저나 curl로 눌러 볼 수도 있지만, 코드를 고칠 때마다 사람이 손으로 확인하는 방식은 곧 한계에 부딪힙니다. 테스트 코드로 만들어 두면 build 명령 한 번에 같은 확인이 자동으로 반복됩니다. 이 예제의 테스트는 4건입니다.

테스트 확인하는 것
contextLoads 스프링 컨텍스트(전체 설정)가 오류 없이 뜨는지
helloReturnsDefaultGreeting /hello의 기본값 인사
helloReturnsGreetingWithName /hello?name=...로 이름을 넘긴 경우
infoReturnsJson /info가 JSON이고 필드 값이 기대와 맞는지

가장 간단한 contextLoads는 본문이 비어 있습니다.

@SpringBootTest
class Ch01ApplicationTests {

	@Test
	void contextLoads() {
	}

}

빈 테스트처럼 보이지만 @SpringBootTest가 전체 스프링 컨텍스트를 띄우기 때문에, 설정 값이 빠졌거나 Bean 연결이 깨졌으면 여기서 실패합니다. 아래 오류 절에서 application.yml의 키를 지우면 이 테스트까지 모두 실패하는 것을 확인합니다. 가장 싼 안전망입니다.

Boot 4에서 @AutoConfigureMockMvc 경로가 바뀌었습니다

Boot 3 시절 경로로 @AutoConfigureMockMvc를 import하면 컴파일되지 않습니다. Boot 4의 테스트 모듈 jar 안에서 클래스 목록을 확인하면 패키지가 바뀌어 있습니다.

Boot 3: org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc
Boot 4: org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc

테스트 스타터 이름(spring-boot-starter-webmvc-test)이 바뀐 것과 같은 이유입니다. 기능이 모듈 단위로 쪼개지면서 클래스 위치도 기술 이름을 따라 정리되었습니다. 인터넷에서 찾은 Boot 3 예제를 복사하면 가장 먼저 만나는 컴파일 오류가 이 import입니다.

테스트 코드 전체

@SpringBootTest
@AutoConfigureMockMvc
class HelloControllerTests {

    @Autowired
    private MockMvc mockMvc;

    @Test
    void helloReturnsDefaultGreeting() throws Exception {
        mockMvc.perform(get("/hello"))
                .andExpect(status().isOk())
                .andExpect(content().string("Hello, Spring Boot!"));
    }

    @Test
    void helloReturnsGreetingWithName() throws Exception {
        mockMvc.perform(get("/hello").param("name", "devguna"))
                .andExpect(status().isOk())
                .andExpect(content().string("Hello, devguna!"));
    }

    @Test
    void infoReturnsJson() throws Exception {
        mockMvc.perform(get("/info"))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.name").value("ch01-hello-spring"))
                .andExpect(jsonPath("$.javaVersion", startsWith("21")))
                .andExpect(jsonPath("$.springBootVersion", startsWith("4.")));
    }
}

테스트 한 건은 다음 순서로 실행됩니다. 실제 Tomcat은 켜지 않지만, 요청 매핑과 JSON 변환 같은 실제 코드는 그대로 지나갑니다.

  1. 테스트 메서드가 mockMvc.perform(get("/hello"))로 요청을 만듭니다.
  2. 서버 없이 DispatcherServlet이 호출됩니다.
  3. DispatcherServlet이 HelloController의 메서드를 부릅니다.
  4. 응답 객체가 만들어집니다.
  5. andExpect가 status, content, jsonPath를 검증합니다.

클래스 애노테이션과 MockMvc의 역할

  • @SpringBootTest: 실제 애플리케이션과 같은 스프링 컨텍스트를 띄웁니다. application.yml도 읽으므로 컨트롤러의 @Value 주입까지 함께 검증됩니다.
  • @AutoConfigureMockMvc: 이 컨텍스트에 MockMvc를 만들어 넣어 줍니다. 이 애노테이션이 있어야 @Autowired MockMvc를 받을 수 있습니다.

MockMvc는 실제 Tomcat 없이 DispatcherServlet에 요청을 흘려 보내는 가짜 클라이언트입니다. 네트워크를 쓰지 않아 빠르고, 포트가 겹쳐도 상관없습니다. 그러면서도 요청 매핑, 파라미터 변환, JSON 변환은 실제 코드가 그대로 동작합니다.

perform으로 요청하고 andExpect로 검증합니다

mockMvc.perform(get("/hello").param("name", "devguna"))

get("/hello")는 GET /hello 요청을 만들고, .param("name", "devguna")는 ?name=devguna를 붙입니다. perform이 실제로 요청을 보냅니다.

andExpect는 “응답이 이래야 한다”는 조건을 하나씩 겁니다. 하나라도 어긋나면 테스트가 실패합니다.

검증 의미
status().isOk() HTTP 상태 코드가 200입니다.
content().string("Hello, Spring Boot!") 응답 본문이 이 문자열과 정확히 같습니다.
jsonPath("$.name").value("ch01-hello-spring") JSON의 name 키 값이 이 문자열입니다.
jsonPath("$.javaVersion", startsWith("21")) javaVersion 값이 “21”로 시작합니다.

jsonPath의 $는 JSON 전체를 뜻하고, $.name은 최상위의 name 키입니다. 값이 JDK마다 다른 javaVersion처럼 정확한 값을 고정하기 어려운 경우에는 startsWith 같은 조건(Hamcrest 매처)을 두 번째 인자로 줍니다. 그래서 JDK 21의 패치 버전이 바뀌어도 테스트가 깨지지 않습니다.

테스트 4건의 실행 결과

이 Chapter만 빌드하면 테스트가 함께 실행됩니다.

OS 명령
Linux / macOS ./gradlew :examples:ch01-hello-spring:build
Windows gradlew.bat :examples:ch01-hello-spring:build

원고 작성 시 4건이 모두 통과했습니다. 루트 build.gradle의 testLogging 설정 덕분에 건별 결과가 출력됩니다.

Ch01ApplicationTests > contextLoads() PASSED
HelloControllerTests > helloReturnsGreetingWithName() PASSED
HelloControllerTests > helloReturnsDefaultGreeting() PASSED
HelloControllerTests > infoReturnsJson() PASSED

테스트가 실패하면 FAILED와 함께 기대한 값과 실제 값이 출력됩니다. 이 방식(@SpringBootTest)은 전체 컨텍스트를 띄우는 가장 무거운 형태이고, 필요한 부분만 띄우는 단위·슬라이스 테스트는 Chapter 19 단위·슬라이스 테스트에서 다룹니다.

bootRun으로 서버를 켜고 curl로 요청합니다

테스트가 통과했다고 해서 서버가 사람이 쓰는 방식으로 동작한다는 뜻은 아닙니다. 이번에는 서버를 실제로 켜서 터미널에서 요청을 보내 보고, 응답과 로그를 눈으로 확인합니다. 준비물은 JDK 21뿐이며, Gradle은 저장소에 포함된 Wrapper가 정해진 버전으로 내려받아 씁니다.

OS 실행
Linux / macOS ./gradlew :examples:ch01-hello-spring:bootRun
Windows gradlew.bat :examples:ch01-hello-spring:bootRun

:examples:ch01-hello-spring는 “루트 아래 examples 폴더의 ch01-hello-spring 모듈”이라는 뜻입니다. 모듈 이름 앞에 :로 경로를 이어 쓰는 것이 Gradle의 규칙입니다. bootRun은 Boot 플러그인이 붙여 준 작업으로, 컴파일 후 바로 실행합니다.

기동이 끝나면 앞의 기동 로그 절에서 본 다섯 줄이 나오고, 그중 Started Ch01Application in 3.737 seconds 같은 Started ... 줄이 보이면 성공입니다. 서버는 터미널을 점유한 채 계속 실행되므로, 요청은 터미널을 하나 더 열어서 보냅니다. 종료하려면 서버 터미널에서 Ctrl + C를 누릅니다.

실습은 다음 순서로 진행합니다.

  1. 터미널 1에서 bootRun을 실행합니다.
  2. Started ... 로그가 보이는지 확인합니다. 보이지 않으면 아래 오류 절의 점검표로 갑니다.
  3. 터미널 2에서 curl 요청을 보냅니다.
  4. 응답을 확인한 뒤 터미널 1에서 Ctrl + C로 서버를 끕니다.

Started ... 줄이 확인되기 전에 요청을 보내면 연결이 거부될 수 있습니다. 서버가 켜지는 데 몇 초가 걸립니다.

세 가지 요청과 응답

curl은 터미널에서 HTTP 요청을 보내는 도구입니다. 먼저 기본 인사입니다.

curl http://localhost:8080/hello
Hello, Spring Boot!

name을 주지 않았으므로 코드의 defaultValue가 쓰였습니다. 다음은 이름을 넘기는 요청입니다.

curl "http://localhost:8080/hello?name=devguna"
Hello, devguna!

주소에 ?가 들어 있으면 셸이 특수문자로 해석할 수 있으므로 주소 전체를 큰따옴표로 감쌉니다. 마지막은 객체 응답입니다.

curl http://localhost:8080/info
{"name":"ch01-hello-spring","javaVersion":"21.0.11","springBootVersion":"4.1.1"}

record의 필드 이름이 그대로 JSON 키가 되었습니다. javaVersion과 springBootVersion은 실행 환경에서 읽은 값이라, 다른 JDK로 실행하면 다른 값이 나옵니다. 한 줄로 붙어 나오는 JSON은 JSON 포매터에 붙여 넣으면 키별로 나누어 읽기 쉽습니다.

매핑이 없는 경로는 Boot가 404 JSON으로 답합니다

매핑하지 않은 경로를 호출해 봅니다.

curl http://localhost:8080/nope
{"timestamp":"2026-10-17T02:17:25.343Z","status":404,"error":"Not Found","path":"/nope"}

코드를 한 줄도 쓰지 않았는데 JSON 오류 본문이 나왔습니다. 처리할 메서드가 없는 요청에 대해 Boot가 기본 오류 응답을 만들어 주기 때문입니다.

키 뜻
timestamp 오류가 난 시각
status HTTP 상태 코드. 404는 “찾을 수 없음”
error 상태 코드의 이름
path 요청한 경로

404가 나오면 가장 먼저 의심할 것은 주소를 잘못 썼는지, 그다음이 컨트롤러가 컴포넌트 스캔 범위 안에 있는지입니다. 오류 응답을 원하는 형태로 바꾸는 방법은 Chapter 06 검증과 예외 처리에서 다룹니다.

브라우저와 실행 가능한 jar로도 확인합니다

GET 요청이라 브라우저 주소창에 http://localhost:8080/hello?name=devguna를 입력해도 같은 결과를 볼 수 있습니다. 다만 POST나 DELETE처럼 주소창으로 보낼 수 없는 요청은 curl이나 테스트 코드로 확인하게 되므로 curl에 익숙해지는 편이 좋습니다.

개발 중에는 bootRun을 쓰지만, 서버에 배포할 때는 bootJar 작업으로 실행 가능한 jar 하나를 만들고 java -jar로 실행합니다.

java -jar ch01-hello-spring-0.0.1-SNAPSHOT.jar

Tomcat이 jar 안에 들어 있으므로 별도 서버 설치가 필요 없습니다. 원고 작성 시 jar로 실행해 같은 요청 4개(기본 인사, 이름 지정, /info, 없는 경로)를 보냈을 때도 모두 위와 같은 응답이었습니다. 컨테이너로 실행하는 방법은 Chapter 22 운영에서 이어집니다.

요청 기대 응답
curl http://localhost:8080/hello Hello, Spring Boot!
curl "http://localhost:8080/hello?name=devguna" Hello, devguna!
curl http://localhost:8080/info name, javaVersion, springBootVersion 세 키를 가진 JSON
curl http://localhost:8080/nope status가 404인 JSON

오류 메시지는 맨 아래 Caused by부터 읽습니다

처음 Spring Boot를 다룰 때 막히는 곳은 대부분 비슷합니다. 포트가 겹치거나, 설정 값이 빠졌거나, JDK 버전이 맞지 않거나, 애노테이션을 하나 잘못 쓰는 경우입니다. 아래 메시지는 원고 작성 시 앞의 예제를 한 군데씩 일부러 틀리게 만들어 얻은 실제 메시지이며, 실험 후 코드는 되돌렸습니다.

스프링 오류는 이런 모양으로 길게 나옵니다.

Error creating bean with name 'helloController' ...
  Caused by: ...
    Caused by: PlaceholderResolutionException: Could not resolve placeholder ...

위쪽의 Error creating bean ...은 “결과”입니다. 원인은 맨 아래 Caused by에 있습니다. 길면 맨 아래부터 거꾸로 읽으세요. 이 습관 하나가 오류 해결 시간을 가장 크게 줄여 줍니다.

8080 포트가 이미 사용 중일 때

다른 프로세스(이전에 켠 서버 포함)가 8080을 쓰고 있으면 기동이 멈춥니다.

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

같은 포트에 두 서버가 동시에 붙을 수 없기 때문이며, 흔히 이전 서버를 끄지 않았을 때 생깁니다. 이전 서버를 Ctrl + C로 종료하거나 다른 프로세스를 정리합니다. 포트를 바꾸는 server.port는 Chapter 02에서 다룹니다.

설정 파일에 키가 없을 때

application.yml이 없거나 spring.application.name 키가 없으면 컨트롤러를 만드는 단계에서 막힙니다.

PlaceholderResolutionException: Could not resolve placeholder 'spring.application.name' in value "${spring.application.name}"

컨트롤러 생성자가 @Value("${spring.application.name}")로 값을 요구하는데 찾을 수 없기 때문입니다. 이 실험에서는 키를 지웠더니 테스트 4건이 모두 실패했습니다. contextLoads까지 실패한 이유는 컨텍스트 자체가 뜨지 못했기 때문입니다. 메시지에 빠진 키 이름이 그대로 나오므로, 설정 파일에 그 키가 있는지와 들여쓰기가 맞는지 확인합니다. YAML은 들여쓰기가 구조를 정합니다.

JDK 21이 없을 때

JDK 17로 빌드하면 Gradle이 JDK 21을 찾지 못합니다.

Cannot find a Java installation on your machine ... matching: {languageVersion=21 ...}

루트 build.gradle의 toolchain이 JDK 21을 요구하기 때문입니다. JDK 21을 설치하고 java -version으로 현재 버전을 확인하세요. 설치했는데도 같은 메시지가 나면 환경 변수 JAVA_HOME이 다른 JDK를 가리키지 않는지 봅니다.

@RestController를 @Controller로 바꿨을 때

@RestController를 @Controller로 바꿨더니 테스트 4건 중 3건이 실패했습니다.

Response content expected:<Hello, Spring Boot!> but was:<>
Circular view path [info]: would dispatch back to the current handler URL [/info] again. Check your ViewResolver setup!

@Controller는 반환값을 화면(뷰) 이름으로 해석합니다. 문자열을 돌려주는 메서드는 본문이 비고, 객체를 돌려주는 메서드는 Circular view path가 납니다. 둘 다 “뷰를 찾으려 했다”는 같은 원인입니다. JSON이나 문자열 응답을 주는 API 컨트롤러는 @RestController를 쓰고, HTML 화면을 만드는 컨트롤러는 Chapter 13 Thymeleaf에서 @Controller로 씁니다.

테스트 import 패키지가 없다고 나올 때

테스트 의존성을 spring-boot-starter-test로만 두면 @AutoConfigureMockMvc를 쓰는 테스트가 컴파일되지 않습니다.

error: package org.springframework.boot.webmvc.test.autoconfigure does not exist

Boot 4에서 MockMvc 연동은 spring-boot-starter-webmvc-test에 들어 있으므로, 이 스타터가 없으면 해당 패키지가 클래스패스에 없습니다. testImplementation 'org.springframework.boot:spring-boot-starter-webmvc-test'를 두고, Boot 3 경로(...test.autoconfigure.web.servlet...)를 import에 쓰고 있다면 Boot 4 경로로 고칩니다.

기동, 컴파일, 응답 순서로 범위를 좁힙니다

문제가 생기면 앞 단계가 해결되기 전에 뒤 단계를 의심하지 않습니다.

순서 질문 아니라면
1 서버가 기동되었나? 콘솔 맨 아래 Caused by 읽기
2 테스트가 컴파일되나? import 경로와 *-test 스타터 확인
3 응답이 기대와 같은가? 컨트롤러 애노테이션과 URL 확인

이 Chapter에서 만난 실수를 증상별로 모으면 다음과 같습니다.

증상 가장 먼저 볼 것
Port 8080 was already in use 이전에 켠 서버가 아직 떠 있는지
Could not resolve placeholder 'x' 설정 파일에 키 x가 있는지, 들여쓰기가 맞는지
Cannot find a Java installation ... languageVersion=21 JDK 21 설치 여부와 JAVA_HOME
응답 본문이 비어 있음 / Circular view path 컨트롤러가 @RestController인지
테스트 import가 컴파일되지 않음 *-test 스타터 의존성과 Boot 4 import 경로
모든 URL이 404 컨트롤러가 시작 클래스의 패키지 아래에 있는지
특정 URL만 404 매핑 경로와 요청 주소를 글자 단위로 비교(/helo 같은 철자)
파라미터 없이 호출했더니 400 @RequestParam의 defaultValue 지정 또는 required=false
expected:<...> but was:<...> 메시지의 두 값을 나란히 놓고 공백·마침표 비교
요청을 보냈더니 연결 거부 Started ... 줄이 나온 뒤 요청했는지
주소의 ? 때문에 셸 오류 주소 전체를 큰따옴표로 감쌌는지

이 Chapter의 애노테이션 한눈에 보기

애노테이션 붙이는 곳 하는 일
@SpringBootApplication 시작 클래스 설정 클래스 지정, 자동 구성, 컴포넌트 스캔을 한 번에 켭니다.
@RestController 컨트롤러 클래스 Bean으로 등록하고 반환값을 응답 본문으로 씁니다.
@GetMapping("/경로") 컨트롤러 메서드 GET 요청을 이 메서드에 연결합니다.
@RequestParam 메서드 파라미터 쿼리 문자열 값을 받습니다.
@Value("${키}") 생성자 파라미터 설정 파일의 값을 가져옵니다.
@SpringBootTest 테스트 클래스 전체 컨텍스트를 띄웁니다.
@AutoConfigureMockMvc 테스트 클래스 MockMvc를 만들어 넣어 줍니다. Boot 4 경로는 org.springframework.boot.webmvc.test.autoconfigure입니다.
@Test 테스트 메서드 이 메서드를 테스트로 실행합니다.

원고 작성 시 참고한 자료는 Spring Initializr, Spring Boot 4.0 Migration Guide, Spring Framework Reference: Spring Web MVC입니다. 더 깊게 보고 싶다면 Spring Boot 공식 문서, Gradle 사용자 가이드, JUnit 5 사용자 가이드를 함께 보세요.

확인 범위와 한계

  • Windows(gradlew.bat) 명령은 적었지만 원고 작성 시 직접 실행해 검증하지 않았습니다.
  • 빌드와 실행은 개발 PC가 아니라 컨테이너(JDK 21.0.11)에서 확인했고, GitHub Actions에서도 같은 빌드가 통과했습니다.
  • 옛 스타터 이름(spring-boot-starter-web)이 동작한 이유는 확인하지 않았습니다.

직접 해보기

  1. https://start.spring.io에서 위 표대로 고르고 GENERATE로 내려받은 뒤, build.gradle의 스타터 이름을 저장소의 examples/ch01-hello-spring/build.gradle과 비교해 보세요. 버전 번호가 파일에 어떻게 적혀 있는지가 다릅니다.
  2. HelloController의 defaultValue를 "World"로 바꾸고 /hello가 어떻게 달라지는지 확인한 뒤, @GetMapping("/ping") 메서드를 추가해 pong을 돌려주게 만들어 보세요.
  3. AppInfo에 String greeting 필드를 하나 추가하고 info()의 반환값을 고쳐 JSON 키가 늘어나는지 확인해 보세요. 바꾼 뒤 테스트가 실패하는 모습도 함께 봅니다.
  4. helloReturnsDefaultGreeting의 기대 문자열을 "Hello, World!"로 바꿔 실행하고, 실패 메시지에서 기대값과 실제값이 어떻게 보이는지 읽어 보세요. 존재하지 않는 경로 /nope를 호출해 status().isNotFound()를 검증하는 테스트도 하나 추가해 보세요.
  5. 서버를 켠 상태에서 터미널을 하나 더 열어 curl -i http://localhost:8080/hello를 실행해 보세요. -i를 붙이면 상태 줄과 헤더가 함께 나옵니다.
  6. application.yml에서 spring.application.name을 지우고 build를 실행해 PlaceholderResolutionException 메시지가 어느 줄에 나오는지 찾아보세요. 마지막 Caused by부터 읽으면 됩니다.
  7. @RestController를 @Controller로 바꿔 테스트를 돌리고, 실패한 테스트와 통과한 테스트가 어떻게 갈리는지 보세요. 왜 contextLoads는 통과하는지도 생각해 봅니다.

스스로 설명하는 연습

  • @SpringBootApplication이 합쳐 놓은 세 애노테이션은 @SpringBootConfiguration, @EnableAutoConfiguration, @ComponentScan입니다. 각각이 무엇을 하는지 한 문장씩 말해 보세요.
  • testImplementation으로 선언한 라이브러리는 실행 jar에 포함되지 않습니다. 테스트 컴파일과 실행에만 쓰이기 때문입니다.
  • 새 Chapter 모듈을 추가하려면 루트 settings.gradle에 include 'examples:모듈이름' 한 줄을 추가합니다.
  • /hello와 /info의 응답 형태가 다른 이유는 반환 타입이 다르기 때문입니다. String은 그대로, record 객체는 Jackson이 JSON으로 바꿉니다.
  • 요청이 컨트롤러 메서드에 도착하기까지 거치는 두 단계는 내장 Tomcat과 DispatcherServlet입니다.

이번 장의 정리

  • Spring Framework는 서버를 만들 때 반복되는 일을 대신하는 부품 모음이고, Spring Boot는 그 부품을 알맞게 조립해 바로 실행되게 하는 도구입니다.
  • Boot 4는 웹 스타터가 spring-boot-starter-webmvc이고, @AutoConfigureMockMvc 경로가 org.springframework.boot.webmvc.test.autoconfigure로 바뀌었습니다.
  • build.gradle은 plugins로 빌드 기능을, dependencies로 라이브러리를 정하며, 버전은 dependency-management 플러그인과 gradle.properties에서 한 곳으로 관리합니다.
  • 시작 클래스는 가장 바깥 패키지에 두고, 요청은 Tomcat, DispatcherServlet, 컨트롤러 순서로 처리됩니다.
  • @RestController와 @GetMapping으로 첫 API를 만들고, 문자열은 그대로, record는 JSON으로 응답합니다.
  • MockMvc 테스트 4건으로 서버 없이 매핑과 응답을 검증하고, bootRun과 curl로 실제 응답과 기동 로그를 확인했습니다.
  • 오류는 기동, 컴파일, 응답 순서로 범위를 좁히고, 긴 메시지는 맨 아래 Caused by부터 읽습니다.

지금은 설정 값이 application.yml의 한 줄이 전부입니다. 다음 Chapter 02 설정과 Profile에서는 개발과 운영 환경을 Profile로 나누고, 명령행 인자와 환경 변수로 값을 덮어쓰는 순서를 확인합니다.

FAQ

자주 묻는 질문

Spring Boot는 Spring Framework를 대체하는 새 프레임워크인가요?

아닙니다. Spring Framework는 객체를 만들고 연결하는 컨테이너와 웹·데이터 접근·테스트 기능 모음이고, Spring Boot는 그 위에서 라이브러리 조합, 자동 구성, 내장 서버, 실행 jar를 미리 맞춰 주는 도구입니다. 컨트롤러에 쓰는 @GetMapping 같은 애노테이션 대부분은 Framework 것이고, @SpringBootApplication과 build.gradle의 스타터가 Boot 것입니다.

Boot 3 자료의 spring-boot-starter-web을 Boot 4에서 그대로 써도 되나요?

Boot 4는 큰 jar를 기능별 모듈로 쪼개면서 서블릿 기반 웹 스타터 이름을 spring-boot-starter-webmvc로 정리했습니다. 이 Chapter의 예제에서 옛 이름으로 바꿔도 테스트 4건은 통과했지만 그 이유는 확인하지 않았으므로, Initializr가 만들어 주는 webmvc 이름을 그대로 따르는 편이 안전합니다.

JDK 17로는 이 Chapter의 예제를 빌드할 수 없나요?

루트 build.gradle의 toolchain이 JDK 21을 요구하므로, 컴퓨터에 JDK 21이 없으면 "Cannot find a Java installation on your machine ... matching: {languageVersion=21 ...}" 메시지와 함께 빌드가 시작되지 않습니다. JDK 21을 설치하고, 그래도 같은 메시지가 나오면 JAVA_HOME이 다른 JDK를 가리키지 않는지 확인합니다.

MockMvc 테스트가 통과했는데 서버를 직접 실행해 확인해야 하나요?

MockMvc는 실제 Tomcat 없이 DispatcherServlet에 요청을 보내 매핑, 파라미터 변환, JSON 변환을 검증합니다. 사람이 쓰는 방식으로 포트에 연결해 응답과 기동 로그를 확인하려면 bootRun으로 서버를 켜고 curl로 요청을 보내는 확인도 한 번은 해 보는 것이 좋습니다.

작성·편집 ToolPado

콘텐츠 유형 Spring Boot 학습 가이드

기술 기준 Spring Boot 4.1.1 · JDK 21

마지막 검토