Spring Boot 입문 튜토리얼 | 30분 만에 REST API 만들기 [초보자용]

들어가며: 30분 만에 첫 API 만들기

“Spring Boot가 뭔지는 알겠는데, 어디서부터 시작해야 할지 모르겠습니다.”

이 튜토리얼은 완전 초보자를 위한 가이드입니다. 설치 → 프로젝트 생성 → REST API → 실행 → 배포까지 30분이면 충분합니다. 복잡한 이론 없이 코드를 복사해서 실행하며 배웁니다.

이 튜토리얼에서 만들 것

간단한 TODO 관리 REST API:

• GET /api/todos - 할 일 목록 조회
• POST /api/todos - 할 일 추가
• PUT /api/todos/{id} - 할 일 수정
• DELETE /api/todos/{id} - 할 일 삭제

사전 요구사항

• Java 17 이상 설치 (OpenJDK 추천)
• IDE: IntelliJ IDEA Community (무료) 또는 VS Code

---

1단계: Java 설치 확인 (3분)

# 터미널에서 확인
java -version

# 출력 예시:
# openjdk version "17.0.2" 2022-01-18
# OpenJDK Runtime Environment (build 17.0.2+8-86)

Java가 없다면:

• Windows: https://adoptium.net/ → JDK 17 다운로드
• Mac: brew install openjdk@17
• Linux: sudo apt install openjdk-17-jdk

---

2단계: 프로젝트 생성 (5분)

방법 1: Spring Initializr (웹)

1. https://start.spring.io/ 접속
2. 다음과 같이 설정:
   • Project: Maven
   • Language: Java
   • Spring Boot: 3.2.x (최신 안정 버전)
   • Packaging: Jar
   • Java: 17
3. Dependencies 추가:
   • Spring Web
   • Spring Data JPA
   • H2 Database
4. GENERATE 클릭 → ZIP 다운로드
5. 압축 해제 후 IDE로 열기

방법 2: IntelliJ IDEA

1. New Project → Spring Initializr
2. 위와 동일하게 설정
3. Create

---

3단계: 첫 REST API 만들기 (10분)

프로젝트 구조

src/main/java/com/example/demo/
├── DemoApplication.java      # 메인
├── controller/
│   └── TodoController.java   # REST API
├── model/
│   └── Todo.java             # 데이터 모델
├── repository/
│   └── TodoRepository.java   # DB 접근
└── service/
    └── TodoService.java      # 비즈니스 로직

1) 데이터 모델 (Todo.java)

src/main/java/com/example/demo/model/Todo.java 파일 생성:

package com.example.demo.model;

import jakarta.persistence.*;

@Entity
@Table(name = "todos")
public class Todo {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    private String title;
    private boolean completed;
    
    // 기본 생성자 (JPA 필수)
    public Todo() {}
    
    public Todo(String title) {
        this.title = title;
        this.completed = false;
    }
    
    // Getter & Setter
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    
    public String getTitle() { return title; }
    public void setTitle(String title) { this.title = title; }
    
    public boolean isCompleted() { return completed; }
    public void setCompleted(boolean completed) { this.completed = completed; }
}

2) Repository (TodoRepository.java)

src/main/java/com/example/demo/repository/TodoRepository.java:

package com.example.demo.repository;

import com.example.demo.model.Todo;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

@Repository
public interface TodoRepository extends JpaRepository<Todo, Long> {
    // 기본 CRUD는 JpaRepository가 자동 제공
    // findAll(), save(), deleteById() 등
}

놀라운 점: 인터페이스만 만들었는데 Spring Data JPA가 자동으로 구현체를 생성합니다!

3) Service (TodoService.java)

src/main/java/com/example/demo/service/TodoService.java:

package com.example.demo.service;

import com.example.demo.model.Todo;
import com.example.demo.repository.TodoRepository;
import org.springframework.stereotype.Service;
import java.util.List;
import java.util.Optional;

@Service
public class TodoService {
    private final TodoRepository repository;
    
    // 생성자 주입 (권장 방식)
    public TodoService(TodoRepository repository) {
        this.repository = repository;
    }
    
    public List<Todo> getAllTodos() {
        return repository.findAll();
    }
    
    public Optional<Todo> getTodoById(Long id) {
        return repository.findById(id);
    }
    
    public Todo createTodo(Todo todo) {
        return repository.save(todo);
    }
    
    public Todo updateTodo(Long id, Todo todoDetails) {
        Todo todo = repository.findById(id)
            .orElseThrow(() -> new RuntimeException("Todo not found"));
        todo.setTitle(todoDetails.getTitle());
        todo.setCompleted(todoDetails.isCompleted());
        return repository.save(todo);
    }
    
    public void deleteTodo(Long id) {
        repository.deleteById(id);
    }
}

4) Controller (TodoController.java)

src/main/java/com/example/demo/controller/TodoController.java:

package com.example.demo.controller;

import com.example.demo.model.Todo;
import com.example.demo.service.TodoService;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/api/todos")
public class TodoController {
    private final TodoService service;
    
    public TodoController(TodoService service) {
        this.service = service;
    }
    
    // GET /api/todos - 전체 조회
    @GetMapping
    public List<Todo> getAllTodos() {
        return service.getAllTodos();
    }
    
    // GET /api/todos/{id} - 단건 조회
    @GetMapping("/{id}")
    public ResponseEntity<Todo> getTodoById(@PathVariable Long id) {
        return service.getTodoById(id)
            .map(ResponseEntity::ok)
            .orElse(ResponseEntity.notFound().build());
    }
    
    // POST /api/todos - 생성
    @PostMapping
    public Todo createTodo(@RequestBody Todo todo) {
        return service.createTodo(todo);
    }
    
    // PUT /api/todos/{id} - 수정
    @PutMapping("/{id}")
    public ResponseEntity<Todo> updateTodo(
        @PathVariable Long id,
        @RequestBody Todo todoDetails
    ) {
        try {
            Todo updated = service.updateTodo(id, todoDetails);
            return ResponseEntity.ok(updated);
        } catch (RuntimeException e) {
            return ResponseEntity.notFound().build();
        }
    }
    
    // DELETE /api/todos/{id} - 삭제
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteTodo(@PathVariable Long id) {
        service.deleteTodo(id);
        return ResponseEntity.ok().build();
    }
}

5) application.properties 설정

src/main/resources/application.properties:

# 서버 포트
server.port=8080

# H2 데이터베이스 (개발용)
spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.driverClassName=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=

# JPA 설정
spring.jpa.database-platform=org.hibernate.dialect.H2Dialect
spring.jpa.hibernate.ddl-auto=create-drop
spring.jpa.show-sql=true

# H2 콘솔 활성화
spring.h2.console.enabled=true
spring.h2.console.path=/h2-console

---

4단계: 실행 및 테스트 (7분)

서버 실행

# Maven
./mvnw spring-boot:run

# 또는 IntelliJ에서 DemoApplication.java 실행

출력:

Tomcat started on port 8080
Started DemoApplication in 2.345 seconds

API 테스트 (curl)

# 1. TODO 추가
curl -X POST http://localhost:8080/api/todos \
  -H "Content-Type: application/json" \
  -d '{"title": "Spring Boot 배우기", "completed": false}'

# 응답:
# {"id":1,"title":"Spring Boot 배우기","completed":false}

# 2. 전체 조회
curl http://localhost:8080/api/todos

# 응답:
# [{"id":1,"title":"Spring Boot 배우기","completed":false}]

# 3. 수정
curl -X PUT http://localhost:8080/api/todos/1 \
  -H "Content-Type: application/json" \
  -d '{"title": "Spring Boot 배우기", "completed": true}'

# 4. 삭제
curl -X DELETE http://localhost:8080/api/todos/1

브라우저에서 테스트

1. H2 콘솔 접속: http://localhost:8080/h2-console

   • JDBC URL: jdbc:h2:mem:testdb
   • Username: sa
   • Password: (빈칸)

2. SQL 쿼리:

SELECT * FROM todos;

---

5단계: 핵심 개념 이해 (5분)

Spring Boot의 마법

1) @SpringBootApplication

@SpringBootApplication
// = @Configuration + @EnableAutoConfiguration + @ComponentScan

• 자동 설정: Tomcat, JPA 자동 구성
• 컴포넌트 스캔: @Controller, @Service 자동 인식

2) 의존성 주입 (DI)

public TodoController(TodoService service) {
    this.service = service;
}

• Spring이 TodoService 객체를 자동으로 생성해서 주입
• new TodoService() 직접 호출 불필요

3) JPA (Java Persistence API)

@Entity
public class Todo { ... }

• Java 객체 ↔ 데이터베이스 자동 매핑
• SQL 작성 불필요

4) RESTful 패턴

@GetMapping    // 조회 (SELECT)
@PostMapping   // 생성 (INSERT)
@PutMapping    // 수정 (UPDATE)
@DeleteMapping // 삭제 (DELETE)

---

실무 팁

자주 하는 실수

1) 생성자 주입 안 함

// ❌ 나쁜 예: 필드 주입
@Autowired
private TodoService service;

// ✅ 좋은 예: 생성자 주입
private final TodoService service;
public TodoController(TodoService service) {
    this.service = service;
}

2) @RequestBody 빠뜨림

// ❌ 에러 발생
@PostMapping
public Todo create(Todo todo) { ... }

// ✅ JSON을 객체로 변환
@PostMapping
public Todo create(@RequestBody Todo todo) { ... }

3) CORS 에러

// 프론트엔드 연동 시 필요
@CrossOrigin(origins = "http://localhost:3000")
@RestController
public class TodoController { ... }

디버깅 팁

# 로그 레벨 설정 (application.properties)
logging.level.org.springframework=DEBUG
logging.level.com.example=DEBUG

# SQL 로그 상세히 보기
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true

---

다음 단계: 실무로 가는 길

이 튜토리얼을 마쳤다면 다음을 학습하세요:

필수 학습 (순서대로)

1) Exception 처리

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(RuntimeException.class)
    public ResponseEntity<String> handleNotFound(RuntimeException ex) {
        return ResponseEntity.status(404).body(ex.getMessage());
    }
}

2) Validation

public class Todo {
    @NotBlank(message = "제목은 필수입니다")
    private String title;
}

@PostMapping
public Todo create(@Valid @RequestBody Todo todo) { ... }

3) Spring Security (인증)

// 의존성 추가 후
@EnableWebSecurity
public class SecurityConfig { ... }

4) 테스트

@SpringBootTest
class TodoControllerTest {
    @Test
    void testGetAllTodos() { ... }
}

5) 프로덕션 DB (PostgreSQL)

spring.datasource.url=jdbc:postgresql://localhost:5432/mydb
spring.datasource.username=postgres
spring.datasource.password=password
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

추천 학습 경로

이 튜토리얼 (30분)
   ↓
[Spring Boot 완벽 가이드] (3시간) ← 실무 수준
   ↓
실전 프로젝트 (1-2주)
   ↓
포트폴리오 제작 (1개월)

---

흔한 에러 및 해결

에러 1: Port 8080 already in use

# 포트 변경 (application.properties)
server.port=8081

에러 2: Could not find or load main class

# Maven 클린 빌드
./mvnw clean install

에러 3: Failed to configure a DataSource

# H2 의존성 확인 (pom.xml)
<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <scope>runtime</scope>
</dependency>

---

실전 프로젝트 아이디어

이제 배운 내용으로 실전 프로젝트를 만들어 보세요:

초급

• 간단한 게시판 API
• 날씨 정보 저장 서비스
• 간단한 블로그 백엔드

중급

• 사용자 인증이 있는 TODO 앱
• 파일 업로드 서비스
• 실시간 채팅 서버 (WebSocket)

고급

• 마이크로서비스 아키텍처
• OAuth2 로그인
• Redis 캐싱 + PostgreSQL

---

빠른 레퍼런스

주요 애노테이션

애노테이션	용도	예시
@RestController	REST API 컨트롤러	클래스에 적용
@GetMapping	GET 요청 처리	메서드에 적용
@PostMapping	POST 요청 처리	메서드에 적용
@RequestBody	JSON → 객체 변환	파라미터에 적용
@PathVariable	URL 경로 변수	/{id}
@Service	비즈니스 로직	클래스에 적용
@Repository	DB 접근	인터페이스에 적용
@Entity	JPA 엔티티	클래스에 적용

자주 쓰는 프로퍼티

# 서버 설정
server.port=8080
server.servlet.context-path=/api

# 데이터베이스
spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.username=sa
spring.datasource.password=

# JPA
spring.jpa.show-sql=true
spring.jpa.hibernate.ddl-auto=create-drop

# 로깅
logging.level.root=INFO
logging.level.com.example=DEBUG

---

마무리

핵심 정리

1. Spring Initializr로 30초 안에 프로젝트 생성
2. Controller → Service → Repository 3계층 구조
3. JPA로 SQL 없이 DB 조작
4. @RestController로 JSON API 자동 생성

30분 동안 배운 것

• Spring Boot 프로젝트 생성
• REST API 4가지 (GET, POST, PUT, DELETE)
• JPA로 데이터베이스 연동
• H2 인메모리 DB 사용
• 로컬에서 실행 및 테스트

다음에 배울 것

• Exception 처리 및 Validation
• Spring Security 인증/인가
• PostgreSQL/MySQL 연동
• 테스트 작성 (JUnit, MockMvc)
• Docker로 배포

축하합니다! 첫 Spring Boot API를 만들었습니다. 이제 Spring Boot 완벽 가이드로 넘어가 실무 수준을 익히세요.

---

관련 글 (내부 링크)

Spring Boot와 함께 보면 좋은 백엔드 개발 가이드입니다:

• Spring Boot 완벽 가이드 | REST API·JPA·Security·Actuator - 이 튜토리얼 다음 단계
• Java 시리즈 #10 Spring Boot | REST API 서버 만들기 - 더 상세한 설명
• Java 시리즈 #1 Java 입문 | 기초 문법 - Java 기초
• NestJS 완벽 가이드 | TypeScript 백엔드 - TypeScript 대안
• FastAPI 완벽 가이드 | Python 백엔드 - Python 대안
• Supabase 완벽 가이드 | PostgreSQL·인증·스토리지 - 백엔드 대안

---

한 줄 요약: 30분이면 Spring Boot로 첫 REST API를 만들 수 있습니다. Controller·Service·Repository 구조와 JPA 기본만 알면 실무 프로젝트도 시작할 수 있습니다.

---

자주 묻는 질문 (FAQ)

Q. 이 내용을 실무에서 언제 쓰나요?

A. Java Spring Boot 완전 초보자를 위한 입문 튜토리얼. 설치부터 첫 REST API 배포까지 30분이면 충분합니다. 코드 복사만으로 따라할 수 있는 단계별 가이드. Start now. 실무에서는 위 본문의 예제와 선택 가이드를 참고해 적용하면 됩니다.

Q. 선행으로 읽으면 좋은 글은?

A. 각 글 하단의 이전 글 또는 관련 글 링크를 따라가면 순서대로 배울 수 있습니다. C++ 시리즈 목차에서 전체 흐름을 확인할 수 있습니다.

Q. 더 깊이 공부하려면?

A. cppreference와 해당 라이브러리 공식 문서를 참고하세요. 글 말미의 참고 자료 링크도 활용하면 좋습니다.

---

같이 보면 좋은 글 (내부 링크)

이 주제와 연결되는 다른 글입니다.

• Spring Boot 완벽 가이드 | REST API·JPA·Security·Actuator·배포
• Java Spring Boot | REST API 서버 만들기
• Java 시작하기 | JDK 설치부터 Hello World까지
• NestJS 완벽 가이드: 엔터프라이즈급 Node.js 프레임워크

---

이 글에서 다루는 키워드 (관련 검색어)

Spring Boot, Java, 입문, 튜토리얼, REST API, 초보자 등으로 검색하시면 이 글이 도움이 됩니다.