1. Spring MVC와 RESTful API 개념 이해하기 🧠

일단 기본 개념부터 확실히 잡고 가자구요! 너무 어렵게 생각하지 마세요~ 쉽게 설명해드릴게요 ㅎㅎ

Spring MVC란 뭘까요? 🤔

Spring MVC는 Model-View-Controller 패턴을 기반으로 한 웹 애플리케이션 개발 프레임워크예요. 간단히 말하면:

1. Model: 데이터와 비즈니스 로직을 담당해요
2. View: 사용자에게 보여지는 화면을 담당해요
3. Controller: 사용자 요청을 처리하고 Model과 View를 연결해주는 역할을 해요

RESTful API는 뭔가요? 🌐

REST(Representational State Transfer)는 웹 서비스를 설계하는 아키텍처 스타일이에요. RESTful API는 이 원칙을 따르는 API를 말하죠.

쉽게 말하면, 인터넷 주소(URL)로 자원을 표현하고, HTTP 메서드(GET, POST, PUT, DELETE 등)로 자원에 대한 행동을 정의하는 방식이에요. 마치 "이 주소로 와서 이런 행동을 해줘~"라고 말하는 것과 같아요! ㅋㅋㅋ

왜 RESTful API가 중요할까요? 🔍

요즘 개발 트렌드는 프론트엔드와 백엔드를 분리하는 방식으로 가고 있어요. 프론트엔드(React, Vue, Angular 등)와 백엔드(Spring, Node.js 등) 사이에 데이터를 주고받는 방법으로 RESTful API가 널리 사용되고 있죠.

또한 모바일 앱, 웹, IoT 기기 등 다양한 클라이언트를 지원해야 하는 현대 애플리케이션에서는 RESTful API가 필수적이에요. 재능넷에서도 이런 API 개발 관련 재능이 인기가 많다고 하네요! 😊

2. 개발 환경 설정하기 ⚙️

자, 이제 실제로 코딩을 시작해볼까요? 먼저 개발 환경부터 세팅해봐요!

필요한 도구들 🛠️

1. JDK 8 이상 (11 또는 17 추천)
2. IDE (IntelliJ IDEA, Eclipse, VS Code 등)
3. Maven 또는 Gradle (의존성 관리 도구)
4. Postman (API 테스트 도구)

Spring Boot 프로젝트 생성하기 🚀

Spring Boot를 사용하면 Spring MVC 프로젝트를 쉽게 설정할 수 있어요. Spring Initializr(https://start.spring.io/)를 사용해서 프로젝트를 생성해볼게요!

'Generate' 버튼을 클릭하면 프로젝트 zip 파일이 다운로드돼요. 이걸 압축 해제하고 IDE로 열어주세요!

기본 의존성 살펴보기 📦

생성된 pom.xml 파일을 살펴볼까요? 주요 의존성들이 이미 추가되어 있어요:

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <dependency>
        <groupId>com.h2database</groupId>
        <artifactId>h2</artifactId>
        <scope>runtime</scope>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>
    

각 의존성의 역할을 간단히 설명하자면:

1. spring-boot-starter-web: Spring MVC, RESTful API 개발에 필요한 라이브러리
2. spring-boot-starter-data-jpa: 데이터베이스 접근을 위한 JPA 라이브러리
3. h2: 인메모리 데이터베이스, 개발 및 테스트용
4. lombok: 반복적인 코드(getter, setter 등)를 줄여주는 라이브러리

애플리케이션 설정하기 ⚙️

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=

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

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

이제 기본 환경 설정이 완료됐어요! 프로젝트를 실행해보면 Spring Boot 애플리케이션이 8080 포트에서 실행되는 것을 확인할 수 있어요. 짝짝짝! 👏

3. 첫 번째 RESTful API 만들기 🎯

자, 이제 본격적으로 API를 만들어볼까요? 간단한 사용자(User) API를 만들어볼게요!

프로젝트 구조 만들기 📂

먼저 패키지 구조를 다음과 같이 만들어주세요:

src/main/java/com/example/restapidemmo/
  ├── controller/
  ├── model/
  ├── repository/
  ├── service/
  └── RestApiDemoApplication.java
    

모델(Entity) 만들기 📝

User 엔티티를 만들어볼게요. model 패키지에 User.java 파일을 생성해주세요:

package com.example.restapidemo.model;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;

@Entity
@Data
@NoArgsConstructor
@AllArgsConstructor
public class User {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    private String name;
    private String email;
    private int age;
}
    

여기서 Lombok의 @Data 어노테이션을 사용하면 getter, setter, toString, equals, hashCode 메서드를 자동으로 생성해줘요. 진짜 편해요 ㅋㅋㅋ

리포지토리 만들기 🗄️

이제 데이터베이스 접근을 위한 리포지토리를 만들어볼게요. repository 패키지에 UserRepository.java 파일을 생성해주세요:

package com.example.restapidemo.repository;

import com.example.restapidemo.model.User;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

@Repository
public interface UserRepository extends JpaRepository<User, Long> {
    // JpaRepository가 기본적인 CRUD 메서드를 제공해줍니다!
}
    

Spring Data JPA의 JpaRepository를 상속받으면 기본적인 CRUD(Create, Read, Update, Delete) 메서드를 자동으로 사용할 수 있어요. 진짜 개발자 인생 꿀이죠? 😄

서비스 만들기 ⚙️

비즈니스 로직을 담당할 서비스 클래스를 만들어볼게요. service 패키지에 UserService.java 파일을 생성해주세요:

package com.example.restapidemo.service;

import com.example.restapidemo.model.User;
import com.example.restapidemo.repository.UserRepository;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.List;
import java.util.Optional;

@Service
public class UserService {

    private final UserRepository userRepository;

    @Autowired
    public UserService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    public List<User> getAllUsers() {
        return userRepository.findAll();
    }

    public Optional<User> getUserById(Long id) {
        return userRepository.findById(id);
    }

    public User createUser(User user) {
        return userRepository.save(user);
    }

    public Optional<User> updateUser(Long id, User userDetails) {
        return userRepository.findById(id)
                .map(user -> {
                    user.setName(userDetails.getName());
                    user.setEmail(userDetails.getEmail());
                    user.setAge(userDetails.getAge());
                    return userRepository.save(user);
                });
    }

    public boolean deleteUser(Long id) {
        return userRepository.findById(id)
                .map(user -> {
                    userRepository.delete(user);
                    return true;
                })
                .orElse(false);
    }
}
    

서비스 클래스에서는 리포지토리를 통해 데이터베이스에 접근하고, 비즈니스 로직을 처리해요. @Autowired를 사용해서 의존성 주입(DI)을 받고 있네요!

컨트롤러 만들기 🎮

이제 RESTful API의 핵심인 컨트롤러를 만들어볼게요. controller 패키지에 UserController.java 파일을 생성해주세요:

package com.example.restapidemo.controller;

import com.example.restapidemo.model.User;
import com.example.restapidemo.service.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.List;

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

    private final UserService userService;

    @Autowired
    public UserController(UserService userService) {
        this.userService = userService;
    }

    // 모든 사용자 조회
    @GetMapping
    public ResponseEntity<List<User>> getAllUsers() {
        List<User> users = userService.getAllUsers();
        return new ResponseEntity<>(users, HttpStatus.OK);
    }

    // 특정 사용자 조회
    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@PathVariable Long id) {
        return userService.getUserById(id)
                .map(user -> new ResponseEntity<>(user, HttpStatus.OK))
                .orElse(new ResponseEntity<>(HttpStatus.NOT_FOUND));
    }

    // 사용자 생성
    @PostMapping
    public ResponseEntity<User> createUser(@RequestBody User user) {
        User createdUser = userService.createUser(user);
        return new ResponseEntity<>(createdUser, HttpStatus.CREATED);
    }

    // 사용자 수정
    @PutMapping("/{id}")
    public ResponseEntity<User> updateUser(@PathVariable Long id, @RequestBody User user) {
        return userService.updateUser(id, user)
                .map(updatedUser -> new ResponseEntity<>(updatedUser, HttpStatus.OK))
                .orElse(new ResponseEntity<>(HttpStatus.NOT_FOUND));
    }

    // 사용자 삭제
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
        boolean deleted = userService.deleteUser(id);
        return deleted ? 
                new ResponseEntity<>(HttpStatus.NO_CONTENT) : 
                new ResponseEntity<>(HttpStatus.NOT_FOUND);
    }
}
    

컨트롤러에서는 다음과 같은 RESTful API 엔드포인트를 정의했어요:

1. GET /api/users: 모든 사용자 조회
2. GET /api/users/{id}: 특정 사용자 조회
3. POST /api/users: 새 사용자 생성
4. PUT /api/users/{id}: 사용자 정보 수정
5. DELETE /api/users/{id}: 사용자 삭제

여기서 @RestController는 @Controller + @ResponseBody를 합친 것으로, 메서드의 반환값이 HTTP 응답 본문에 직접 매핑된다는 의미예요. REST API를 만들 때 딱이죠! 👍

애플리케이션 실행하기 🚀

이제 애플리케이션을 실행해볼까요? IDE에서 RestApiDemoApplication.java 파일을 실행하거나, 터미널에서 다음 명령어를 실행해주세요:

./mvnw spring-boot:run
    

애플리케이션이 성공적으로 실행되면 http://localhost:8080/api/users 주소로 API를 테스트해볼 수 있어요!

4. HTTP 메서드 활용하기 🔄

RESTful API에서는 HTTP 메서드를 활용해 자원에 대한 행동을 정의해요. 각 메서드의 의미와 사용법을 자세히 알아볼게요!

주요 HTTP 메서드 📋

GET 메서드 활용하기 🔍

GET 메서드는 자원을 조회할 때 사용해요. 우리 API에서는 다음과 같이 사용했죠:

// 모든 사용자 조회
@GetMapping
public ResponseEntity<List<User>> getAllUsers() {
    List<User> users = userService.getAllUsers();
    return new ResponseEntity<>(users, HttpStatus.OK);
}

// 특정 사용자 조회
@GetMapping("/{id}")
public ResponseEntity<User> getUserById(@PathVariable Long id) {
    return userService.getUserById(id)
            .map(user -> new ResponseEntity<>(user, HttpStatus.OK))
            .orElse(new ResponseEntity<>(HttpStatus.NOT_FOUND));
}
    

GET 요청은 URL 파라미터나 쿼리 스트링을 통해 데이터를 전달해요. 예를 들면:

1. URL 파라미터: /api/users/1 (ID가 1인 사용자 조회)
2. 쿼리 스트링: /api/users?name=John (이름이 John인 사용자 조회)

POST 메서드 활용하기 ➕

POST 메서드는 새로운 자원을 생성할 때 사용해요:

// 사용자 생성
@PostMapping
public ResponseEntity<User> createUser(@RequestBody User user) {
    User createdUser = userService.createUser(user);
    return new ResponseEntity<>(createdUser, HttpStatus.CREATED);
}
    

POST 요청은 요청 본문(Request Body)에 데이터를 담아 전송해요. Spring MVC에서는 @RequestBody 어노테이션을 사용해 요청 본문을 자바 객체로 변환해줘요.

POST 요청 예시 (JSON 형식):

{
    "name": "홍길동",
    "email": "hong@example.com",
    "age": 25
}
    

PUT 메서드 활용하기 🔄

PUT 메서드는 자원을 완전히 대체(수정)할 때 사용해요:

// 사용자 수정
@PutMapping("/{id}")
public ResponseEntity<User> updateUser(@PathVariable Long id, @RequestBody User user) {
    return userService.updateUser(id, user)
            .map(updatedUser -> new ResponseEntity<>(updatedUser, HttpStatus.OK))
            .orElse(new ResponseEntity<>(HttpStatus.NOT_FOUND));
}
    

PUT 요청도 POST와 마찬가지로 요청 본문에 데이터를 담아 전송해요. 다만, PUT은 자원을 완전히 대체하는 의미이므로, 요청 본문에 모든 필드를 포함해야 해요.

PATCH 메서드 활용하기 🩹

PATCH 메서드는 자원을 부분적으로 수정할 때 사용해요. 우리 예제에는 없지만, 다음과 같이 구현할 수 있어요:

// 사용자 부분 수정
@PatchMapping("/{id}")
public ResponseEntity<User> partialUpdateUser(@PathVariable Long id, @RequestBody Map<String, Object> updates) {
    return userService.partialUpdateUser(id, updates)
            .map(updatedUser -> new ResponseEntity<>(updatedUser, HttpStatus.OK))
            .orElse(new ResponseEntity<>(HttpStatus.NOT_FOUND));
}
    

PATCH 요청은 변경할 필드만 포함하는 요청 본문을 전송해요. 예를 들어, 이메일만 변경하고 싶다면:

{
    "email": "new.email@example.com"
}
    

DELETE 메서드 활용하기 ❌

DELETE 메서드는 자원을 삭제할 때 사용해요:

// 사용자 삭제
@DeleteMapping("/{id}")
public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
    boolean deleted = userService.deleteUser(id);
    return deleted ? 
            new ResponseEntity<>(HttpStatus.NO_CONTENT) : 
            new ResponseEntity<>(HttpStatus.NOT_FOUND);
}
    

DELETE 요청은 보통 URL 파라미터를 통해 삭제할 자원의 ID를 전달해요. 요청 본문은 일반적으로 비어있어요.

이렇게 HTTP 메서드를 적절히 활용하면 RESTful API의 의도를 명확하게 표현할 수 있어요. 개발자들이 API를 보고 직관적으로 이해할 수 있게 되죠! 😊

5. 요청/응답 처리하기 📤📥

RESTful API에서는 요청과 응답을 어떻게 처리하는지 자세히 알아볼게요!

요청 처리하기 📥

Spring MVC에서는 다양한 방법으로 클라이언트의 요청 데이터를 받을 수 있어요:

1. 경로 변수 (@PathVariable) 📍

URL 경로에 포함된 변수를 받을 때 사용해요:

@GetMapping("/users/{id}")
public ResponseEntity<User> getUserById(@PathVariable Long id) {
    // id 값을 사용하여 처리
}
    

2. 쿼리 파라미터 (@RequestParam) 🔍

URL의 쿼리 스트링 파라미터를 받을 때 사용해요:

@GetMapping("/users")
public ResponseEntity<List<User>> searchUsers(
        @RequestParam(required = false) String name,
        @RequestParam(required = false) Integer minAge) {
    // name, minAge 값을 사용하여 처리
}
    

3. 요청 본문 (@RequestBody) 📦

JSON이나 XML 같은 형식의 요청 본문을 자바 객체로 변환할 때 사용해요:

@PostMapping("/users")
public ResponseEntity<User> createUser(@RequestBody User user) {
    // user 객체를 사용하여 처리
}
    

4. 요청 헤더 (@RequestHeader) 📋

HTTP 요청 헤더 값을 받을 때 사용해요:

@GetMapping("/users")
public ResponseEntity<List<User>> getUsers(
        @RequestHeader("Authorization") String authToken) {
    // authToken 값을 사용하여 인증 처리
}
    

응답 처리하기 📤

Spring MVC에서는 ResponseEntity 클래스를 사용해 HTTP 응답을 구성할 수 있어요:

@GetMapping("/users/{id}")
public ResponseEntity<User> getUserById(@PathVariable Long id) {
    return userService.getUserById(id)
            .map(user -> new ResponseEntity<>(user, HttpStatus.OK))
            .orElse(new ResponseEntity<>(HttpStatus.NOT_FOUND));
}
    

ResponseEntity를 사용하면 다음과 같은 요소를 설정할 수 있어요:

1. 응답 본문(Body): 클라이언트에게 반환할 데이터
2. 상태 코드(Status Code): HTTP 상태 코드 (200 OK, 404 Not Found 등)
3. 헤더(Headers): HTTP 응답 헤더

주요 HTTP 상태 코드 🚦

RESTful API에서 자주 사용되는 HTTP 상태 코드를 알아볼게요:

응답 형식 📄

RESTful API에서는 주로 JSON 형식으로 응답을 반환해요. Spring MVC에서는 Jackson 라이브러리를 통해 자바 객체를 자동으로 JSON으로 변환해줘요.

일관된 응답 형식을 위해 공통 응답 객체를 만들어 사용하는 것도 좋은 방법이에요:

public class ApiResponse<T> {
    private boolean success;
    private String message;
    private T data;
    
    // 생성자, getter, setter 생략
}
    

이 응답 객체를 사용하면 다음과 같이 일관된 형식의 응답을 반환할 수 있어요:

@GetMapping("/users/{id}")
public ResponseEntity<ApiResponse<User>> getUserById(@PathVariable Long id) {
    return userService.getUserById(id)
            .map(user -> {
                ApiResponse<User> response = new ApiResponse<>(true, "사용자를 찾았습니다.", user);
                return new ResponseEntity<>(response, HttpStatus.OK);
            })
            .orElse(new ResponseEntity<>(
                new ApiResponse<>(false, "사용자를 찾을 수 없습니다.", null),
                HttpStatus.NOT_FOUND
            ));
}
    

이렇게 하면 클라이언트는 항상 동일한 형식의 응답을 받을 수 있어서 처리하기가 편해져요! 👍

6. 예외 처리와 유효성 검사 🛡️

RESTful API에서 예외 처리와 유효성 검사는 매우 중요해요. 어떻게 구현하는지 알아볼게요!

전역 예외 처리 🌐

Spring MVC에서는 @ControllerAdvice와 @ExceptionHandler를 사용해 전역 예외 처리를 구현할 수 있어요:

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ApiResponse<Void>> handleResourceNotFoundException(ResourceNotFoundException ex) {
        ApiResponse<Void> response = new ApiResponse<>(false, ex.getMessage(), null);
        return new ResponseEntity<>(response, HttpStatus.NOT_FOUND);
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ApiResponse<Void>> handleGenericException(Exception ex) {
        ApiResponse<Void> response = new ApiResponse<>(false, "서버 오류가 발생했습니다.", null);
        return new ResponseEntity<>(response, HttpStatus.INTERNAL_SERVER_ERROR);
    }
}
    

그리고 사용자 정의 예외 클래스를 만들어 사용할 수 있어요:

public class ResourceNotFoundException extends RuntimeException {
    public ResourceNotFoundException(String message) {
        super(message);
    }
}
    

이제 서비스 클래스에서 이 예외를 던지면 됩니다:

public User getUserById(Long id) {
    return userRepository.findById(id)
            .orElseThrow(() -> new ResourceNotFoundException("ID가 " + id + "인 사용자를 찾을 수 없습니다."));
}
    

유효성 검사 ✅

Spring Boot에서는 Bean Validation을 사용해 간편하게 유효성 검사를 구현할 수 있어요. 먼저 의존성을 추가해주세요:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>
    

그리고 모델 클래스에 유효성 검사 어노테이션을 추가해요:

@Entity
@Data
@NoArgsConstructor
@AllArgsConstructor
public class User {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @NotBlank(message = "이름은 필수 항목입니다.")
    private String name;
    
    @NotBlank(message = "이메일은 필수 항목입니다.")
    @Email(message = "유효한 이메일 형식이 아닙니다.")
    private String email;
    
    @Min(value = 0, message = "나이는 0 이상이어야 합니다.")
    @Max(value = 150, message = "나이는 150 이하여야 합니다.")
    private int age;
}
    

컨트롤러에서는 @Valid 어노테이션을 사용해 유효성 검사를 활성화해요:

@PostMapping
public ResponseEntity<ApiResponse<User>> createUser(@Valid @RequestBody User user) {
    User createdUser = userService.createUser(user);
    ApiResponse<User> response = new ApiResponse<>(true, "사용자가 생성되었습니다.", createdUser);
    return new ResponseEntity<>(response, HttpStatus.CREATED);
}
    

유효성 검사 실패 시 발생하는 예외를 처리하기 위해 예외 핸들러를 추가해요:

@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<ApiResponse<Map<String, String>>> handleValidationExceptions(MethodArgumentNotValidException ex) {
    Map<String, String> errors = new HashMap<>();
    
    ex.getBindingResult().getFieldErrors().forEach(error -> {
        errors.put(error.getField(), error.getDefaultMessage());
    });
    
    ApiResponse<Map<String, String>> response = new ApiResponse<>(false, "유효성 검사 실패", errors);
    return new ResponseEntity<>(response, HttpStatus.BAD_REQUEST);
}
    

이렇게 하면 유효성 검사 실패 시 어떤 필드에서 어떤 문제가 있는지 상세한 정보를 클라이언트에게 제공할 수 있어요! 👍

7. API 문서화하기 📚

API를 개발했다면 다른 개발자들이 쉽게 이해하고 사용할 수 있도록 문서화하는 것이 중요해요. Spring Boot에서는 Swagger나 SpringDoc을 사용해 API 문서를 자동으로 생성할 수 있어요!

SpringDoc OpenAPI 사용하기 📝

SpringDoc은 OpenAPI 3.0 스펙을 지원하는 라이브러리예요. 먼저 의존성을 추가해주세요:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.9</version>
</dependency>
    

이제 OpenAPI 설정 클래스를 만들어볼게요:

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("사용자 관리 API")
                        .description("Spring Boot로 개발한 RESTful API 예제")
                        .version("1.0.0")
                        .contact(new Contact()
                                .name("개발자 이름")
                                .email("developer@example.com"))
                        .license(new License().name("MIT License")));
    }
}
    

컨트롤러와 모델 클래스에 API 문서화를 위한 어노테이션을 추가해요:

@RestController
@RequestMapping("/api/users")
@Tag(name = "사용자 관리", description = "사용자 CRUD API")
public class UserController {

    // ...

    @Operation(summary = "사용자 조회", description = "ID로 사용자를 조회합니다.")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "사용자 조회 성공"),
        @ApiResponse(responseCode = "404", description = "사용자를 찾을 수 없음")
    })
    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@PathVariable Long id) {
        // ...
    }

    // 다른 메서드에도 유사하게 어노테이션 추가
}
    

애플리케이션을 실행하고 http://localhost:8080/swagger-ui.html에 접속하면 자동으로 생성된 API 문서를 볼 수 있어요!

이렇게 API 문서를 자동으로 생성하면 다음과 같은 장점이 있어요:

1. API 엔드포인트, 파라미터, 응답 형식 등을 한눈에 확인할 수 있어요
2. API를 직접 테스트해볼 수 있는 UI를 제공해요
3. 코드가 변경되면 문서도 자동으로 업데이트돼요
4. 다른 개발자들이 API를 쉽게 이해하고 사용할 수 있어요

재능넷 같은 플랫폼에서 API 개발 관련 재능을 판매한다면, 이렇게 문서화가 잘 된 API를 제공하는 것이 큰 경쟁력이 될 수 있어요! 😉

8. 보안 적용하기 🔒

RESTful API에 보안을 적용하는 방법을 알아볼게요. Spring Security를 사용하면 쉽게 보안 기능을 구현할 수 있어요!

Spring Security 설정하기 🛡️

먼저 Spring Security 의존성을 추가해주세요:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>
    

기본적인 보안 설정 클래스를 만들어볼게요:

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .csrf().disable()  // RESTful API에서는 CSRF 보호가 필요 없을 수 있어요
            .authorizeRequests()
                .antMatchers("/api/public/**").permitAll()  // 공개 API
                .antMatchers("/api/users/**").authenticated()  // 인증 필요
                .anyRequest().authenticated()
            .and()
            .httpBasic();  // 기본 인증 사용
    }

    @Override
    protected void configure(AuthenticationManagerBuilder auth) throws Exception {
        auth.inMemoryAuthentication()
            .withUser("user").password(passwordEncoder().encode("password")).roles("USER")
            .and()
            .withUser("admin").password(passwordEncoder().encode("admin")).roles("ADMIN");
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }
}
    

이 설정은 매우 기본적인 것이고, 실제 프로젝트에서는 더 복잡한 보안 요구사항이 있을 수 있어요. 하지만 이 예제로 Spring Security의 기본 개념을 이해할 수 있어요!

JWT 인증 구현하기 🔑

RESTful API에서는 JWT(JSON Web Token)를 사용한 인증 방식이 많이 사용돼요. JWT를 사용하려면 추가 의존성이 필요해요:

<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt</artifactId>
    <version>0.9.1</version>
</dependency>
    

JWT 토큰을 생성하고 검증하는 유틸리티 클래스를 만들어볼게요:

@Component
public class JwtTokenUtil {

    @Value("${jwt.secret}")
    private String secret;

    @Value("${jwt.expiration}")
    private Long expiration;

    public String generateToken(UserDetails userDetails) {
        Map<String, Object> claims = new HashMap<>();
        return createToken(claims, userDetails.getUsername());
    }

    private String createToken(Map<String, Object> claims, String subject) {
        Date now = new Date();
        Date expiryDate = new Date(now.getTime() + expiration * 1000);

        return Jwts.builder()
                .setClaims(claims)
                .setSubject(subject)
                .setIssuedAt(now)
                .setExpiration(expiryDate)
                .signWith(SignatureAlgorithm.HS512, secret)
                .compact();
    }

    public String getUsernameFromToken(String token) {
        return getClaimFromToken(token, Claims::getSubject);
    }

    public Date getExpirationDateFromToken(String token) {
        return getClaimFromToken(token, Claims::getExpiration);
    }

    public <T> T getClaimFromToken(String token, Function<Claims, T> claimsResolver) {
        Claims claims = getAllClaimsFromToken(token);
        return claimsResolver.apply(claims);
    }

    private Claims getAllClaimsFromToken(String token) {
        return Jwts.parser().setSigningKey(secret).parseClaimsJws(token).getBody();
    }

    public Boolean validateToken(String token, UserDetails userDetails) {
        final String username = getUsernameFromToken(token);
        return (username.equals(userDetails.getUsername()) && !isTokenExpired(token));
    }

    private Boolean isTokenExpired(String token) {
        final Date expiration = getExpirationDateFromToken(token);
        return expiration.before(new Date());
    }
}
    

그리고 JWT 필터를 만들어 인증 과정을 처리해요:

@Component
public class JwtRequestFilter extends OncePerRequestFilter {

    @Autowired
    private UserDetailsService userDetailsService;

    @Autowired
    private JwtTokenUtil jwtTokenUtil;

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
            throws ServletException, IOException {

        final String requestTokenHeader = request.getHeader("Authorization");

        String username = null;
        String jwtToken = null;

        // JWT 토큰은 "Bearer token" 형식으로 전달됩니다
        if (requestTokenHeader != null && requestTokenHeader.startsWith("Bearer ")) {
            jwtToken = requestTokenHeader.substring(7);
            try {
                username = jwtTokenUtil.getUsernameFromToken(jwtToken);
            } catch (IllegalArgumentException e) {
                System.out.println("JWT 토큰을 가져올 수 없습니다");
            } catch (ExpiredJwtException e) {
                System.out.println("JWT 토큰이 만료되었습니다");
            }
        } else {
            logger.warn("JWT 토큰이 Bearer로 시작하지 않습니다");
        }

        // 토큰이 유효하면 Spring Security 컨텍스트에 인증 정보를 설정합니다
        if (username != null && SecurityContextHolder.getContext().getAuthentication() == null) {
            UserDetails userDetails = this.userDetailsService.loadUserByUsername(username);

            if (jwtTokenUtil.validateToken(jwtToken, userDetails)) {
                UsernamePasswordAuthenticationToken authentication = new UsernamePasswordAuthenticationToken(
                        userDetails, null, userDetails.getAuthorities());
                authentication.setDetails(new WebAuthenticationDetailsSource().buildDetails(request));
                SecurityContextHolder.getContext().setAuthentication(authentication);
            }
        }
        chain.doFilter(request, response);
    }
}
    

마지막으로 Security 설정을 JWT 인증에 맞게 수정해요:

@Configuration
@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Autowired
    private JwtAuthenticationEntryPoint jwtAuthenticationEntryPoint;

    @Autowired
    private UserDetailsService jwtUserDetailsService;

    @Autowired
    private JwtRequestFilter jwtRequestFilter;

    @Autowired
    public void configureGlobal(AuthenticationManagerBuilder auth) throws Exception {
        auth.userDetailsService(jwtUserDetailsService).passwordEncoder(passwordEncoder());
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }

    @Bean
    @Override
    public AuthenticationManager authenticationManagerBean() throws Exception {
        return super.authenticationManagerBean();
    }

    @Override
    protected void configure(HttpSecurity httpSecurity) throws Exception {
        httpSecurity.csrf().disable()
                .authorizeRequests().antMatchers("/api/auth/**").permitAll()
                .anyRequest().authenticated().and()
                .exceptionHandling().authenticationEntryPoint(jwtAuthenticationEntryPoint).and()
                .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS);

        // JWT 필터 추가
        httpSecurity.addFilterBefore(jwtRequestFilter, UsernamePasswordAuthenticationFilter.class);
    }
}
    

이제 로그인 API를 만들어 JWT 토큰을 발급해볼게요:

@RestController
@RequestMapping("/api/auth")
public class AuthController {

    @Autowired
    private AuthenticationManager authenticationManager;

    @Autowired
    private JwtTokenUtil jwtTokenUtil;

    @Autowired
    private UserDetailsService userDetailsService;

    @PostMapping("/login")
    public ResponseEntity<?> createAuthenticationToken(@RequestBody JwtRequest authenticationRequest) throws Exception {
        authenticate(authenticationRequest.getUsername(), authenticationRequest.getPassword());

        final UserDetails userDetails = userDetailsService
                .loadUserByUsername(authenticationRequest.getUsername());

        final String token = jwtTokenUtil.generateToken(userDetails);

        return ResponseEntity.ok(new JwtResponse(token));
    }

    private void authenticate(String username, String password) throws Exception {
        try {
            authenticationManager.authenticate(new UsernamePasswordAuthenticationToken(username, password));
        } catch (DisabledException e) {
            throw new Exception("USER_DISABLED", e);
        } catch (BadCredentialsException e) {
            throw new Exception("INVALID_CREDENTIALS", e);
        }
    }
}
    

이렇게 JWT 인증을 구현하면 RESTful API에 안전하게 접근할 수 있어요. 클라이언트는 로그인 API를 통해 토큰을 받고, 이후 요청에서 이 토큰을 Authorization 헤더에 포함시켜 보내면 돼요!

9. 실전 프로젝트: 간단한 API 서비스 구현 🚀

지금까지 배운 내용을 바탕으로 간단한 API 서비스를 구현해볼게요! 이번에는 할 일 관리(Todo) API를 만들어볼게요.

프로젝트 구조 📂

src/main/java/com/example/restapidemo/
  ├── controller/
  │   ├── TodoController.java
  │   └── AuthController.java
  ├── model/
  │   ├── Todo.java
  │   └── User.java
  ├── repository/
  │   ├── TodoRepository.java
  │   └── UserRepository.java
  ├── service/
  │   ├── TodoService.java
  │   └── UserService.java
  ├── security/
  │   ├── JwtTokenUtil.java
  │   └── JwtRequestFilter.java
  ├── exception/
  │   ├── ResourceNotFoundException.java
  │   └── GlobalExceptionHandler.java
  ├── dto/
  │   ├── TodoDto.java
  │   └── ApiResponse.java
  └── RestApiDemoApplication.java
    

Todo 모델 만들기 📝

@Entity
@Data
@NoArgsConstructor
@AllArgsConstructor
public class Todo {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @NotBlank(message = "제목은 필수 항목입니다.")
    private String title;
    
    private String description;
    
    private boolean completed;
    
    @ManyToOne
    @JoinColumn(name = "user_id")
    private User user;
    
    @CreationTimestamp
    private LocalDateTime createdAt;
    
    @UpdateTimestamp
    private LocalDateTime updatedAt;
}
    

Todo 리포지토리 만들기 🗄️

@Repository
public interface TodoRepository extends JpaRepository<Todo, Long> {
    List<Todo> findByUserIdOrderByCreatedAtDesc(Long userId);
    List<Todo> findByUserIdAndCompletedOrderByCreatedAtDesc(Long userId, boolean completed);
}
    

Todo 서비스 만들기 ⚙️

@Service
public class TodoService {

    private final TodoRepository todoRepository;
    private final UserRepository userRepository;

    @Autowired
    public TodoService(TodoRepository todoRepository, UserRepository userRepository) {
        this.todoRepository = todoRepository;
        this.userRepository = userRepository;
    }

    public List<Todo> getAllTodosByUser(Long userId) {
        return todoRepository.findByUserIdOrderByCreatedAtDesc(userId);
    }

    public List<Todo> getTodosByUserAndStatus(Long userId, boolean completed) {
        return todoRepository.findByUserIdAndCompletedOrderByCreatedAtDesc(userId, completed);
    }

    public Todo getTodoById(Long id, Long userId) {
        Todo todo = todoRepository.findById(id)
                .orElseThrow(() -> new ResourceNotFoundException("ID가 " + id + "인 할 일을 찾을 수 없습니다."));
        
        if (!todo.getUser().getId().equals(userId)) {
            throw new AccessDeniedException("이 할 일에 접근할 권한이 없습니다.");
        }
        
        return todo;
    }

    public Todo createTodo(TodoDto todoDto, Long userId) {
        User user = userRepository.findById(userId)
                .orElseThrow(() -> new ResourceNotFoundException("ID가 " + userId + "인 사용자를 찾을 수 없습니다."));
        
        Todo todo = new Todo();
        todo.setTitle(todoDto.getTitle());
        todo.setDescription(todoDto.getDescription());
        todo.setCompleted(false);
        todo.setUser(user);
        
        return todoRepository.save(todo);
    }

    public Todo updateTodo(Long id, TodoDto todoDto, Long userId) {
        Todo todo = getTodoById(id, userId);
        
        todo.setTitle(todoDto.getTitle());
        todo.setDescription(todoDto.getDescription());
        todo.setCompleted(todoDto.isCompleted());
        
        return todoRepository.save(todo);
    }

    public void deleteTodo(Long id, Long userId) {
        Todo todo = getTodoById(id, userId);
        todoRepository.delete(todo);
    }
}
    

Todo 컨트롤러 만들기 🎮

@RestController
@RequestMapping("/api/todos")
public class TodoController {

    private final TodoService todoService;

    @Autowired
    public TodoController(TodoService todoService) {
        this.todoService = todoService;
    }

    @GetMapping
    public ResponseEntity<ApiResponse<List<Todo>>> getAllTodos(
            @RequestParam(required = false) Boolean completed,
            Authentication authentication) {
        
        UserDetails userDetails = (UserDetails) authentication.getPrincipal();
        User user = ((CustomUserDetails) userDetails).getUser();
        
        List<Todo> todos;
        if (completed != null) {
            todos = todoService.getTodosByUserAndStatus(user.getId(), completed);
        } else {
            todos = todoService.getAllTodosByUser(user.getId());
        }
        
        ApiResponse<List<Todo>> response = new ApiResponse<>(true, "할 일 목록을 조회했습니다.", todos);
        return new ResponseEntity<>(response, HttpStatus.OK);
    }

    @GetMapping("/{id}")
    public ResponseEntity<ApiResponse<Todo>> getTodoById(
            @PathVariable Long id,
            Authentication authentication) {
        
        UserDetails userDetails = (UserDetails) authentication.getPrincipal();
        User user = ((CustomUserDetails) userDetails).getUser();
        
        Todo todo = todoService.getTodoById(id, user.getId());
        
        ApiResponse<Todo> response = new ApiResponse<>(true, "할 일을 조회했습니다.", todo);
        return new ResponseEntity<>(response, HttpStatus.OK);
    }

    @PostMapping
    public ResponseEntity<ApiResponse<Todo>> createTodo(
            @Valid @RequestBody TodoDto todoDto,
            Authentication authentication) {
        
        UserDetails userDetails = (UserDetails) authentication.getPrincipal();
        User user = ((CustomUserDetails) userDetails).getUser();
        
        Todo createdTodo = todoService.createTodo(todoDto, user.getId());
        
        ApiResponse<Todo> response = new ApiResponse<>(true, "할 일을 생성했습니다.", createdTodo);
        return new ResponseEntity<>(response, HttpStatus.CREATED);
    }

    @PutMapping("/{id}")
    public ResponseEntity<ApiResponse<Todo>> updateTodo(
            @PathVariable Long id,
            @Valid @RequestBody TodoDto todoDto,
            Authentication authentication) {
        
        UserDetails userDetails = (UserDetails) authentication.getPrincipal();
        User user = ((CustomUserDetails) userDetails).getUser();
        
        Todo updatedTodo = todoService.updateTodo(id, todoDto, user.getId());
        
        ApiResponse<Todo> response = new ApiResponse<>(true, "할 일을 수정했습니다.", updatedTodo);
        return new ResponseEntity<>(response, HttpStatus.OK);
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<ApiResponse<Void>> deleteTodo(
            @PathVariable Long id,
            Authentication authentication) {
        
        UserDetails userDetails = (UserDetails) authentication.getPrincipal();
        User user = ((CustomUserDetails) userDetails).getUser();
        
        todoService.deleteTodo(id, user.getId());
        
        ApiResponse<Void> response = new ApiResponse<>(true, "할 일을 삭제했습니다.", null);
        return new ResponseEntity<>(response, HttpStatus.OK);
    }
}
    

이렇게 하면 간단한 할 일 관리 API가 완성돼요! 이 API는 다음과 같은 기능을 제공해요:

1. 사용자별 할 일 목록 조회
2. 완료/미완료 상태별 할 일 필터링
3. 할 일 상세 조회
4. 새로운 할 일 생성
5. 할 일 수정
6. 할 일 삭제

또한 JWT 인증을 통해 사용자별로 자신의 할 일만 접근할 수 있도록 보안이 적용되어 있어요. 이런 API는 할 일 관리 앱의 백엔드로 활용할 수 있어요!

재능넷에서도 이런 종류의 API 개발 재능이 인기가 많을 것 같네요. 프론트엔드 개발자들이 이런 백엔드 API를 활용해 다양한 애플리케이션을 만들 수 있으니까요! 😊

10. 마무리 및 다음 단계 🎬

지금까지 Spring MVC를 사용해 RESTful API를 개발하는 방법에 대해 알아봤어요. 정말 많은 내용을 다뤘네요! 👏

배운 내용 정리 📝

1. Spring MVC와 RESTful API 개념 이해하기
2. 개발 환경 설정하기
3. 첫 번째 RESTful API 만들기
4. HTTP 메서드 활용하기
5. 요청/응답 처리하기
6. 예외 처리와 유효성 검사
7. API 문서화하기
8. 보안 적용하기
9. 실전 프로젝트: 간단한 API 서비스 구현

다음 단계로 배울 수 있는 내용 🚀

RESTful API 개발에 더 깊이 들어가고 싶다면 다음과 같은 주제를 공부해보세요:

1. HATEOAS: Hypermedia As The Engine Of Application State - API 응답에 관련 리소스 링크를 포함시켜 클라이언트가 API를 더 쉽게 탐색할 수 있게 하는 기술
2. API 버전 관리: API가 발전함에 따라 이전 버전과의 호환성을 유지하는 방법
3. 캐싱: API 응답을 캐싱하여 성능을 향상시키는 방법
4. 비동기 API: WebFlux를 사용한 비동기 RESTful API 개발
5. 마이크로서비스: 대규모 애플리케이션을 위한 마이크로서비스 아키텍처 설계

마무리 인사 👋

이 글이 여러분의 Spring MVC RESTful API 개발에 도움이 되었으면 좋겠어요! 개발은 계속 배우고 성장하는 과정이니, 꾸준히 공부하고 실습해보세요.

혹시 API 개발에 관한 더 깊은 지식이나 실무 경험이 필요하시다면, 재능넷에서 관련 재능을 찾아보는 것도 좋은 방법이에요. 전문가의 도움을 받아 더 빠르게 성장할 수 있으니까요! 🚀

다음에 또 다른 주제로 찾아올게요. 그때까지 즐거운 코딩하세요! 👨‍💻👩‍💻