Spring Boot와 RESTful API 구축하기

Spring Boot와 RESTful API 구축하기

Overview

Spring Boot는 Java 기반의 강력한 프레임워크로, RESTful API를 구축하는 데 매우 적합합니다. REST(Representational State Transfer)는 웹 서비스에서 데이터를 전송하는 데 널리 사용되는 아키텍처 스타일로, HTTP 프로토콜을 기반으로 클라이언트와 서버 간의 상호작용을 단순화합니다. Spring Boot는 설정이 간편하고 강력한 기능을 제공하여 RESTful API 개발을 쉽게 만들어줍니다. 이 글에서는 Spring Boot로 RESTful API를 구축하는 방법을 단계별로 설명하고, 실제 예제와 함께 각 단계에서 발생할 수 있는 오류와 그 해결 방법도 함께 다루겠습니다.

1. Spring Boot 프로젝트 생성

먼저 Spring Boot 프로젝트를 생성합니다. Spring Boot는 초기 프로젝트 설정을 간편하게 해주는 Spring Initializr라는 도구를 제공합니다.

1.1. Spring Initializr 사용하기

• Spring Initializr 웹사이트에 접속합니다.
• Project: Maven Project (또는 Gradle을 사용할 수도 있습니다)
• Language: Java
• Spring Boot: 최신 버전 선택
• Project Metadata:
• Group: com.example
• Artifact: demo
• Name: demo
• Description: Demo project for Spring Boot
• Package name: com.example.demo
• Dependencies: Spring Web 선택

Generate 버튼을 클릭하여 프로젝트를 다운로드합니다. 다운로드한 ZIP 파일을 추출하고, IDE(예: IntelliJ IDEA, Eclipse)에서 열어 프로젝트를 시작합니다.

1.2. 프로젝트 구조

기본적으로 생성된 Spring Boot 프로젝트는 다음과 같은 구조를 갖습니다:

src/
└── main/
├── java/
│    └── com/
│        └── example/
│            └── demo/
│                ├── DemoApplication.java
│                └── controller/
└── resources/
├── application.properties
└── static/

• DemoApplication.java: Spring Boot 애플리케이션의 진입점입니다.
• application.properties: 애플리케이션 설정 파일입니다.

2. RESTful API 구현

이제 실제로 RESTful API를 구현해보겠습니다. 예를 들어, 간단한 "Hello World" API를 만들어보겠습니다.

2.1. Controller 클래스 생성

com.example.demo.controller 패키지에 HelloController.java 클래스를 생성합니다.

package com.example.demo.controller;

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

@RestController
@RequestMapping("/api")
public class HelloController {

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

• @RestController: 이 클래스가 RESTful 웹 서비스의 컨트롤러임을 나타냅니다.
• @RequestMapping("/api"): 이 컨트롤러의 모든 메서드는 /api 경로로 시작합니다.
• @GetMapping("/hello"): 이 메서드는 HTTP GET 요청을 처리하고 /api/hello 경로에 매핑됩니다.

2.2. API 테스트

이제 애플리케이션을 실행하고 API를 테스트해보겠습니다. IDE에서 DemoApplication.java를 실행하면, 기본적으로 서버가 http://localhost:8080에서 시작됩니다.

웹 브라우저 또는 Postman과 같은 API 클라이언트를 사용하여 http://localhost:8080/api/hello에 GET 요청을 보내면, "Hello, World!"라는 응답을 받을 수 있습니다.

3. 요청과 응답 데이터 처리

이제 요청 파라미터를 처리하고 JSON 응답을 반환하는 방법을 살펴보겠습니다. 예를 들어, 사용자의 이름을 받아서 인사하는 API를 구현해보겠습니다.

3.1. RequestParam 사용하기

package com.example.demo.controller;

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

@RestController
@RequestMapping("/api")
public class GreetingController {

@GetMapping("/greet")
public String greet(@RequestParam(value = "name", defaultValue = "Guest") String name) {
return "Hello, " + name + "!";
}
}

• @RequestParam: HTTP 요청 파라미터를 메서드 매개변수로 바인딩합니다. name이라는 파라미터가 요청에 없으면 "Guest"가 기본값으로 사용됩니다.

3.2. JSON 응답 처리하기

JSON 응답을 반환하는 방법은 @ResponseBody를 사용하여 객체를 반환하면 됩니다.

package com.example.demo.controller;

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

@RestController
@RequestMapping("/api")
public class UserController {

@GetMapping("/user")
public User getUser() {
return new User("John", "Doe", 30);
}

public static class User {
private String firstName;
private String lastName;
private int age;

public User(String firstName, String lastName, int age) {
this.firstName = firstName;
this.lastName = lastName;
this.age = age;
}

// Getters and setters
public String getFirstName() { return firstName; }
public void setFirstName(String firstName) { this.firstName = firstName; }
public String getLastName() { return lastName; }
public void setLastName(String lastName) { this.lastName = lastName; }
public int getAge() { return age; }
public void setAge(int age) { this.age = age; }
}
}

• 이 메서드는 User 객체를 반환하며, Spring Boot는 자동으로 JSON으로 변환하여 응답합니다.

4. 에러 처리

RESTful API를 구현하다 보면 다양한 에러가 발생할 수 있습니다. Spring Boot에서는 @ControllerAdvice와 @ExceptionHandler를 사용하여 에러를 처리할 수 있습니다.

4.1. 전역 에러 처리기

package com.example.demo.exception;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestController;

@ControllerAdvice
@RestController
public class GlobalExceptionHandler {

@ExceptionHandler(Exception.class)
public final ResponseEntity<ErrorResponse> handleAllExceptions(Exception ex) {
ErrorResponse error = new ErrorResponse("Server Error", ex.getMessage());
return new ResponseEntity<>(error, HttpStatus.INTERNAL_SERVER_ERROR);
}

public static class ErrorResponse {
private String error;
private String message;

public ErrorResponse(String error, String message) {
this.error = error;
this.message = message;
}

// Getters and setters
public String getError() { return error; }
public void setError(String error) { this.error = error; }
public String getMessage() { return message; }
public void setMessage(String message) { this.message = message; }
}
}

• @ControllerAdvice: 전역적으로 에러를 처리할 수 있는 클래스입니다.
• @ExceptionHandler: 특정 예외를 처리하는 메서드입니다. 위의 예제에서는 모든 예외를 처리하고 있습니다.

5. 테스트와 문서화

RESTful API는 테스트와 문서화가 중요합니다. Spring Boot에서는 Spring Boot Test를 통해 API 테스트를 작성할 수 있으며, Spring REST Docs를 통해 API 문서화를 할 수 있습니다.

5.1. Spring Boot Test

package com.example.demo;

import org.junit.jupiter.api.Test;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.test.web.servlet.MockMvc;

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;

@WebMvcTest
public class HelloControllerTest {

@Autowired
private MockMvc mockMvc;

@Test
public void testSayHello() throws Exception {
mockMvc.perform(get("/api/hello"))
.andExpect(status().isOk())
.andExpect(content().string("Hello, World!"));
}
}

• MockMvc: Spring MVC 테스트를 위한 유틸리티로, 실제 서블릿 컨테이너를 시작하지 않고도 API를 테스트할 수 있습니다.

5.2. Spring REST Docs

Spring REST Docs 공식 문서를 참고하여 API 문서를 생성할 수 있습니다.

참고문서

• Spring Boot 공식 문서
• Spring Initializr 사용법
• [Spring MVC 공식 문서](https://docs.spring.io/spring-framework/docs/current/reference/html/web.html