B컷전문 | 개발과 인생의 이야기

Spring Boot에서 REST API를 어떻게 설계하고 컨트롤러를 구성할 수 있는지 실전 예제와 함께 설명합니다. 계층 구조, JSON 응답, REST 컨벤션까지 정리했습니다.

---

Spring Boot 시리즈 2편 – REST API 설계와 Controller 작성 가이드

Spring Boot를 활용한 웹 애플리케이션 개발의 핵심은 RESTful API 설계입니다.
이번 편에서는 실무에서 가장 많이 사용하는 REST API 구조 설계 패턴, 컨트롤러 구현 방식, 그리고 DTO 사용 전략까지 상세히 다루어 보겠습니다.

---

📌 REST API란?

REST(Representational State Transfer)는 HTTP 기반의 자원 중심 아키텍처 스타일입니다.
Spring Boot에서는 @RestController를 통해 RESTful API를 쉽게 구현할 수 있습니다.

키워드: Spring Boot REST API, @RestController, HTTP Method, DTO, Controller 설계

---

🧱 1. 프로젝트 디렉토리 기본 구조

Spring Boot에서 REST API를 구성할 때는 아래와 같은 구조가 가장 일반적입니다:

src/
└── main/
    └── java/
        └── com.example.demo/
            ├── controller/
            │   └── UserController.java
            ├── dto/
            │   └── UserDto.java
            ├── service/
            │   └── UserService.java
            ├── repository/
            │   └── UserRepository.java
            └── entity/
                └── User.java

✅ 계층별 역할

• Controller: HTTP 요청/응답 처리
• Service: 비즈니스 로직 처리
• Repository: DB 접근 (JPA/Hibernate 등)
• DTO(Entity): 데이터 전송 객체

---

🔧 2. @RestController로 API 설계하기

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

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

    @PostMapping
    public ResponseEntity<UserDto> createUser(@RequestBody UserDto userDto) {
        return ResponseEntity.ok(userService.createUser(userDto));
    }
}

주요 애노테이션

애노테이션 설명

@RestController	JSON 기반 응답 처리
@RequestMapping	공통 URL 경로 지정
@GetMapping, @PostMapping	HTTP 메서드 매핑
@RequestBody	요청 본문을 객체로 매핑
@ResponseBody	자동 JSON 변환 응답

---

📦 3. DTO를 활용한 클린한 데이터 설계

**DTO(Data Transfer Object)**는 컨트롤러와 서비스 간 역할 분리와 보안을 위한 핵심 설계 요소입니다.

public class UserDto {
    private String name;
    private String email;
}

엔티티(Entity) 그대로 노출하는 것이 아니라, DTO로 래핑하여 필요한 정보만 전달합니다.
이는 계층 간 결합도를 낮추고, API 응답의 유연성을 확보할 수 있게 해줍니다.

---

⚙️ 4. 예외 처리 – 글로벌 방식 추천

실무에서는 단순히 try-catch가 아닌, **전역 예외 처리(ControllerAdvice)**를 적용합니다.

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity<String> handleUserNotFound(UserNotFoundException e) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(e.getMessage());
    }
}

---

✅ REST API 설계 시 주의할 점

항목 설명

URL 설계	동사 대신 리소스 기반 명명 (예: /users)
응답 포맷	JSON 기반 통일, 상태 코드 명확화
입력 검증	@Valid, @Validated와 함께 BindingResult 사용
Swagger 활용	API 문서 자동화 및 테스트 툴 적용 권장

---

🧠 실무 인사이트

• 컨트롤러는 "thin", 서비스는 "fat"이 원칙입니다. 컨트롤러는 로직을 담지 말고 서비스에 위임하세요.
• DTO를 적극 활용하고, 엔티티를 직접 노출하지 마세요. 보안 문제 및 확장성 문제가 생깁니다.
• 모든 API에는 명확한 응답 구조를 정해두고, 실패 시 예외 메시지도 표준화하세요.

---

✅ 마무리 요약

항목 정리

컨트롤러 구성	@RestController, @RequestMapping, @PostMapping 등
URL 패턴	/api/리소스명 형식 권장
DTO 전략	Entity 분리, 계층 간 전송 전용 객체
예외 처리	@ControllerAdvice를 통한 글로벌 처리
응답 구조	ResponseEntity로 HTTP 상태 명확히 제어

---

📌 다음 편 예고

Spring Boot 시리즈 3편: Spring Data JPA를 활용한 DB 연동 – Repository와 Entity 설계 전략