RESTful API와 Spring Boot의 REST 컨트롤러 설계하기

오늘은 RESTful API의 기본 개념과 이를 기반으로 Spring Boot에서 REST 컨트롤러를 설계하는 방법을 학습합니다. RESTful API는 HTTP 프로토콜을 활용하여 자원을 CRUD(생성, 조회, 수정, 삭제)할 수 있는 표준적인 아키텍처 스타일입니다.

---

1. RESTful API란 무엇인가?

**REST(Representational State Transfer)**는 웹 서비스 설계 원칙을 기반으로 자원의 상태를 클라이언트와 서버 간에 주고받을 수 있는 구조를 제공합니다.

• 특징:
  • Stateless(무상태성): 서버는 클라이언트 상태를 저장하지 않습니다.
  • Resource 기반: 자원을 URL로 식별합니다.
  • HTTP 메서드 활용: 자원 조작을 HTTP 메서드로 구분합니다.
    • GET: 조회
    • POST: 생성
    • PUT: 수정
    • DELETE: 삭제

---

2. Spring Boot에서 REST 컨트롤러 구현하기

(1) 데이터베이스 엔터티

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

@Entity
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;
    private String email;

    // Getter, Setter
}

---

(2) 레포지토리 인터페이스

Spring Data JPA의 기본 CRUD 메서드를 사용합니다.

import org.springframework.data.jpa.repository.JpaRepository;

public interface UserRepository extends JpaRepository<User, Long> {
}

---

(3) 서비스 클래스

서비스 클래스에서 비즈니스 로직을 처리합니다.

import org.springframework.stereotype.Service;

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

@Service
public class UserService {

    private final UserRepository userRepository;

    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 User updateUser(Long id, User userDetails) {
        return userRepository.findById(id)
                .map(user -> {
                    user.setName(userDetails.getName());
                    user.setEmail(userDetails.getEmail());
                    return userRepository.save(user);
                })
                .orElseThrow(() -> new RuntimeException("User not found"));
    }

    public void deleteUser(Long id) {
        userRepository.deleteById(id);
    }
}

---

(4) REST 컨트롤러

RESTful API의 각 HTTP 메서드를 매핑합니다.

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;

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

    @GetMapping
    public List<User> getAllUsers() {
        return userService.getAllUsers();
    }

    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@PathVariable Long id) {
        return userService.getUserById(id)
                .map(ResponseEntity::ok)
                .orElse(ResponseEntity.notFound().build());
    }

    @PostMapping
    public User createUser(@RequestBody User user) {
        return userService.createUser(user);
    }

    @PutMapping("/{id}")
    public User updateUser(@PathVariable Long id, @RequestBody User userDetails) {
        return userService.updateUser(id, userDetails);
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
        userService.deleteUser(id);
        return ResponseEntity.noContent().build();
    }
}

---

3. API 테스트 방법

1. GET /api/users
   모든 사용자 목록을 반환합니다.
2. GET /api/users/{id}
   특정 ID의 사용자 정보를 반환합니다.
   • 존재하지 않으면 404 응답을 반환합니다.
3. POST /api/users
   새로운 사용자를 생성합니다.
   • 요청 본문에 JSON 데이터를 포함해야 합니다.

     {
       "name": "John Doe",
       "email": "john@example.com"
     }
     

4. PUT /api/users/{id}
   기존 사용자의 정보를 수정합니다.
   • 요청 본문에 수정할 데이터를 포함합니다.
5. DELETE /api/users/{id}
   특정 사용자를 삭제합니다.

---

4. 주요 사항 및 주의점

• Validation: 데이터 유효성 검사를 추가하여 요청 데이터를 검증해야 합니다.
• 예외 처리: 커스텀 예외를 만들어 클라이언트에 더 명확한 에러 메시지를 전달합니다.
• RESTful 설계 규칙 준수: HTTP 메서드와 상태 코드를 일관되게 사용합니다.