TIL - 20251106

1106 Spring Boot 웹 개발: Controller와 REST API의 기초

---

✅ 1. Spring MVC의 핵심: Controller와 요청 매핑

• Spring Boot 웹 개발은 Spring MVC 프레임워크를 기반으로 동작합니다. 여기서 컨트롤러(Controller)는 클라이언트의 HTTP 요청을 가장 먼저 받아 처리하는 관문 역할을 합니다.

➕ 주요 어노테이션

1. @Controller:

   • 이 어노테이션이 붙은 클래스를 Spring이 컨트롤러로 인식하고, Bean으로 등록하여 관리합니다.
   • 전통적인 Spring MVC에서는 주로 ModelAndView 객체나 뷰(View)의 이름을 반환하여 HTML 페이지를 렌더링하는 데 사용됩니다.

2. @RestController:

   • @Controller와 @ResponseBody를 합친 어노테이션입니다.
   • 현대적인 웹 개발, 특히 REST API를 만들 때 주로 사용됩니다.
   • 이 어노테이션이 붙은 컨트롤러의 모든 메서드는 뷰를 찾는 대신, 반환하는 값(객체, 문자열 등)을 HTTP 응답 본문(Body)에 직접 써서 보냅니다. 객체를 반환하면, Spring Boot가 자동으로 JSON 형식으로 변환하여 응답합니다.

3. @RequestMapping:

   • 특정 URL 경로와 컨트롤러의 메서드를 매핑(mapping)하는 역할을 합니다.
   • 클래스 레벨에 붙여 공통 경로를 지정하고, 메서드 레벨에 붙여 세부 경로를 지정할 수 있습니다.

4. HTTP 메서드별 매핑 어노테이션 (축약형):

   • @RequestMapping을 더 명확하고 간결하게 사용하기 위한 어노테이션들입니다.
   • @GetMapping: HTTP GET 요청을 처리 (데이터 조회)
   • @PostMapping: HTTP POST 요청을 처리 (데이터 생성)
   • @PutMapping: HTTP PUT 요청을 처리 (데이터 전체 수정)
   • @PatchMapping: HTTP PATCH 요청을 처리 (데이터 일부 수정)
   • @DeleteMapping: HTTP DELETE 요청을 처리 (데이터 삭제)

   @RestController
   @RequestMapping("/api/users") // 공통 경로
   public class UserController {
   
       @GetMapping("/{userId}") // GET /api/users/{userId}
       public User getUser(@PathVariable Long userId) {
           // ... 사용자 조회 로직 ...
       }
   
       @PostMapping
       public ResponseEntity<User> createUser(@RequestBody UserCreateRequest request) {
           // ... 사용자 생성 로직 ...
       }
   }

---

✅ 2. 요청 데이터(Request Data) 처리하기

• 클라이언트가 보낸 데이터를 컨트롤러 메서드에서 받는 방법은 데이터의 위치에 따라 다릅니다.

어노테이션	데이터 위치	설명	예시
@PathVariable	URL 경로	URL 경로의 일부를 변수로 받음. (e.g., /users/123)	@GetMapping("/{id}") public User getUser(@PathVariable Long id)
@RequestParam	쿼리 파라미터	URL의 ? 뒤에 오는 Key-Value 쌍을 받음. (e.g., /search?keyword=java)	@GetMapping("/search") public List<Item> search(@RequestParam String keyword)
@RequestBody	HTTP Body	요청의 본문에 담긴 JSON, XML 등의 데이터를 Java 객체(DTO)로 변환하여 받음. (주로 POST, PUT 요청)	@PostMapping public void createUser(@RequestBody UserDto userDto)
@ModelAttribute	폼 데이터	application/x-www-form-urlencoded 형식의 폼 데이터를 객체로 바인딩. (주로 서버 사이드 렌더링에서 사용)

---

✅ 3. REST API (Representational State Transfer)

• REST는 웹 서비스를 설계하기 위한 아키텍처 스타일(설계 원칙) 중 하나입니다. REST의 원칙을 잘 따르는 API를 RESTful API라고 합니다.

➕ REST의 핵심 구성 요소

1. 자원 (Resource):

   • API가 제공하는 모든 정보는 자원으로 간주됩니다. (e.g., 사용자, 게시글, 상품)
   • 자원은 URI(Uniform Resource Identifier)를 통해 고유하게 식별됩니다. (e.g., /users/123)
   • URI는 자원을 표현하는 데 집중해야 합니다. (동사보다는 명사 사용)
     • 나쁜 예: /getUsers, /createUser
     • 좋은 예: /users

2. 행위 (Verb):

   • 자원에 대한 행위는 HTTP 메서드(Verb)를 통해 표현합니다.
   • GET (조회), POST (생성), PUT (전체 수정), DELETE (삭제)

3. 표현 (Representation):

   • 자원의 상태는 JSON이나 XML과 같은 형식으로 표현되어 클라이언트와 서버 간에 주고받습니다.

➕ RESTful API 설계의 장점

• 직관성: URI와 HTTP 메서드만 봐도 API가 어떤 동작을 하는지 쉽게 이해할 수 있습니다.
• 무상태성 (Stateless): 각 요청은 서버가 클라이언트의 상태를 저장하지 않고 독립적으로 처리됩니다. 이는 서버의 확장성(Scalability)을 높여줍니다.
• 일관성: 정해진 규칙을 따르므로, API의 통일성이 높아지고 협업이 용이해집니다.

---

✅ 4. 응답 데이터(Response Data) 처리하기: ResponseEntity

• 컨트롤러 메서드는 단순히 데이터 객체만 반환할 수도 있지만, ResponseEntity 객체를 사용하면 더 정교한 응답을 만들 수 있습니다.

• ResponseEntity의 장점:

  1. HTTP 상태 코드(Status Code)를 명시적으로 제어할 수 있습니다.
     • 200 OK (성공), 201 CREATED (생성 성공), 400 BAD_REQUEST (클라이언트 오류), 404 NOT_FOUND (자원 없음), 500 INTERNAL_SERVER_ERROR (서버 오류)
  2. HTTP 헤더(Headers)를 직접 설정할 수 있습니다.
  3. 응답 본문(Body)에 실제 데이터를 담을 수 있습니다.

  @PostMapping
  public ResponseEntity<User> createUser(@RequestBody UserCreateRequest request) {
      User newUser = userService.create(request);
      // 201 Created 상태 코드와 함께 생성된 사용자 정보를 응답
      return ResponseEntity.status(HttpStatus.CREATED).body(newUser);
  }
  
  @GetMapping("/{userId}")
  public ResponseEntity<User> getUser(@PathVariable Long userId) {
      try {
          User user = userService.findById(userId);
          // 200 OK 상태 코드와 함께 사용자 정보를 응답
          return ResponseEntity.ok(user);
  
      } catch (UserNotFoundException e) {
          // 사용자를 찾지 못한 경우 404 Not Found 상태 코드를 응답
          return ResponseEntity.notFound().build();
      }
  }

---

📌 요약

• @RestController는 REST API를 만들기 위한 핵심 어노테이션으로, 반환 값을 JSON 형태로 응답 본문에 직접 써줍니다.
• 클라이언트의 요청 데이터는 위치에 따라 @PathVariable, @RequestParam, @RequestBody 등을 사용하여 받습니다.
• REST API는 자원(URI, 명사), 행위(HTTP 메서드), 표현(JSON)이라는 세 가지 요소로 구성된 아키텍처 스타일입니다.
• ResponseEntity를 사용하면, 데이터뿐만 아니라 HTTP 상태 코드와 헤더까지 포함된 풍부하고 명확한 응답을 클라이언트에게 보낼 수 있습니다.