ResponseEntity를 사용하는 이유: 더 나은 REST API 응답 설계를 위한 가이드

안녕하세요. IT 기술 블로거입니다.

Spring Boot로 컨트롤러를 작성하다 보면 두 가지 스타일의 반환 타입을 보게 됩니다.
1. 단순 객체 반환: public Member getMember() { ... }
2. ResponseEntity 반환: public ResponseEntity<Member> getMember() { ... }

단순 객체를 반환해도 JSON으로 잘 나가는데, 왜 굳이 더 복잡해 보이는 ResponseEntity를 사용해야 할까요? 오늘은 REST API의 품질을 결정짓는 응답 설계의 핵심, ResponseEntity에 대해 깊이 있게 다뤄보겠습니다.

1. ResponseEntity란 무엇인가?

ResponseEntity는 HTTP 응답(Response)의 상태 코드(Status Code), 헤더(Headers), 본문(Body)을 직접 제어할 수 있게 해주는 Spring의 특수 클래스입니다.

단순 객체를 반환할 때는 Spring이 기본적으로 200 OK 상태 코드를 보내지만, 실무에서는 성공하더라도 201 Created를 보내야 하거나, 실패 시 구체적인 에러 코드와 메시지를 보내야 하는 상황이 훨씬 많습니다.

2. ResponseEntity를 사용하는 핵심 이유

2.1. 세밀한 상태 코드 제어

REST API 설계 원칙 중 하나는 “적절한 HTTP 상태 코드를 반환하는 것”입니다.
– 데이터 생성 성공: 201 Created
– 조회 결과 없음: 404 Not Found (단순 객체 반환 시 결과가 null이면 200 OK가 나가는 문제가 있음)
– 입력값 오류: 400 Bad Request

2.2. 응답 헤더(Header) 설정

특정 API 응답 시 캐싱을 막거나, 다운로드 파일의 이름을 지정하는 등 헤더 정보를 조작해야 할 때 필수적입니다.

2.3. 유연한 에러 처리

성공 시에는 데이터 객체를 반환하고, 실패 시에는 에러 메시지 객체를 반환하는 등 하나의 메서드에서 다양한 타입의 응답을 처리할 수 있습니다.

3. 실무 코드 예제: ResponseEntity 활용법

예제 1: 조건에 따른 다양한 응답 반환

@GetMapping("/api/members/{id}")
public ResponseEntity<Object> getMember(@PathVariable Long id) {
    Member member = memberService.findById(id);

    if (member == null) {
        // 데이터가 없으면 404 상태 코드와 에러 메시지 반환
        return ResponseEntity.status(HttpStatus.NOT_FOUND)
                .body(new ErrorResponse("회원을 찾을 수 없습니다."));
    }

    // 성공 시 200 OK와 회원 데이터 반환
    return ResponseEntity.ok(member);
}

예제 2: 데이터 생성 시 201 Created 반환

@PostMapping("/api/members")
public ResponseEntity<Member> create(@RequestBody MemberSaveDto saveDto) {
    Member savedMember = memberService.save(saveDto);

    // 빌더 패턴을 사용해 깔끔하게 응답 생성
    return ResponseEntity
            .status(HttpStatus.CREATED) // 201 상태 코드
            .header("Custom-Header", "CodeCamp") // 커스텀 헤더 추가
            .body(savedMember);
}

4. 빌더 패턴 vs 생성자

ResponseEntity는 new ResponseEntity<>(body, status) 처럼 생성자를 쓸 수도 있지만, Spring은 빌더 패턴(Builder Pattern) 사용을 더 권장합니다.

• ResponseEntity.ok().body(data)
• ResponseEntity.status(HttpStatus.CREATED).build()

빌더 패턴이 가독성이 훨씬 좋고, 헤더나 상태 코드를 체이닝(Chaining) 방식으로 설정하기 편리하기 때문입니다.

결론

REST API 개발에서 ResponseEntity를 사용하는 것은 단순한 선택이 아니라 전문성을 가르는 기준입니다. 클라이언트(프론트엔드)는 여러분이 보낸 상태 코드를 보고 다음 동작을 결정합니다.

단순히 200 OK만 남발하는 API가 아니라, ResponseEntity를 통해 HTTP 표준을 준수하는 명확한 소통 창구를 만드시기 바랍니다. 이는 API의 신뢰도를 높이고 협업의 효율성을 극대화해 줄 것입니다.

다음 시간에는 브라우저에서 API를 호출할 때 우리를 가장 당혹스럽게 만드는 빨간 맛 에러, “CORS 오류 해결 방법”에 대해 알아보겠습니다.