Spring - RESTful API Http 응답 제어하기 (ResponseEntity 사용법)

https://hanke-r.tistory.com/entry/Spring-Spring-Boot%EB%A1%9C-RESTful-API-%EC%84%A4%EA%B3%84

Spring - Spring Boot로 RESTful API 설계

 

이전 글에서 Spring boot로 RESTful API를 만들어 봤는데,

이번 글에서는 ResponseEntity를 사용하여 Http 상태 코드를 추가해서 성공과 오류를 명확히 하는 API로 만들어보자.

 

ResponseEntity를 사용하면 HTTP 상태 코드, 응답 헤더, 응답 본문을 명시적으로 설정할 수 있다.

 

---

ResponseEntity의 주요 특징

 

특징을 알아보자.

- HTTP 상태 코드 제어: 상태 코드를 직접 지정 가능 (200 OK, 404 NOT FOUND, 등)

- 응답 헤더 설정: 커스텀 헤더를 추가할 수 있음

- 응답 본문 설정: JSON, 문자열, 객체 등 다양한 타입의 본문을 설정 가능

- RESTful API에서 활용: 상태 코드와 응답 데이터를 함께 반환하여 클라이언트와 서버 간의 명확한 통신을 지원

 

 

---

 

 

응답코드 반환

 

이전 글에서 특정 사용자 조회를 GET방식으로 불러왔었는데, 이 코드를 변경해서 응답 코드별로 return 해보자.

    // GET: 특정 사용자 조회
    @GetMapping("/{id}")
    public User getUserById(@PathVariable int id) {
        return users.stream()
                .filter(user -> user.getId() == id)
                .findFirst()
                .orElseThrow(() -> new RuntimeException("User not found"));
    }

 

 

ResponseEntity 응답 코드 (200, 404)

    /**
     * GET: 특정 사용자 조회
     * ReponseEntity<User> -> ResponseEntity.ok() 200 OK
     */
    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@PathVariable int id) {
        return users.stream()
                .filter(user -> user.getId() == id)
                .findFirst()
                .map(ResponseEntity::ok)
                .orElseGet(() -> ResponseEntity.status(HttpStatus.NOT_FOUND).body(null));
    }

 

 

---

ResponseEntity 응답 헤더 추가

 

이번에는 응답 코드에 이어서 응답 헤더를 추가해 보자.

/**
 * GET: 특정 사용자 조회
 * ReponseEntity<User> -> ResponseEntity.ok() 200 OK
 * ResponseEntity<User> -> ResponseEntity.status(HttpStatus.NOT_FOUND).body(null)
 *
 * 응답헤더 추가
 * HttpHeaders headers = new HttpHeaders();
 * headers.add("X-Server-ID", "Server-1");
 * headers.add("X-Response-Time", String.valueOf(System.currentTimeMillis()));
 */
@GetMapping("/{id}")
public ResponseEntity<User> getUserById(@PathVariable int id) {
    return users.stream()
            .filter(user -> user.getId() == id)
            .findFirst()
            .map(user -> {
                HttpHeaders headers = new HttpHeaders();
                headers.add("X-Server-ID", "Server-1"); // 커스텀 헤더 추가
                headers.add("X-Response-Time", String.valueOf(System.currentTimeMillis())); // 응답 시간 정보 추가
                return ResponseEntity.ok()
                        .headers(headers) // 헤더 설정
                        .body(user);
            })
            .orElseGet(() -> {
                HttpHeaders headers = new HttpHeaders();
                headers.add("X-Server-ID", "Server-1"); // 동일한 커스텀 헤더
                return ResponseEntity.status(HttpStatus.NOT_FOUND)
                        .headers(headers)
                        .body(null); // 본문 없음
            });
}

우리가 원하는 대로 header에 잘 추가된 것 같다.

 

---

단순한 예제로 구성해 봤는데, Http 상태 코드들이 매우 많아서 각 상황별로 잘 사용하길 바란다.

 

정리

 

HttpStatus 클래스의 주요 상태 코드

1xx : 지원 안 함

2xx : 성공 응답

200	HttpStatus.OK	요청이 성공적으로 처리되었으며, 응답 본문에 결과가 포함.
201	HttpStatus.CREATED	리소스가 성공적으로 생성. 새로 생성된 리소스의 위치를 헤더에 포함 가능.
202	HttpStatus.ACCEPTED	요청이 접수되었으나, 아직 처리되지 않음. (비동기 작업용)
204	HttpStatus.NO_CONTENT	요청이 성공했으나, 응답 본문 없음.

 

3xx : 리다이렉션

301	HttpStatus.MOVED_PERMANENTLY	요청한 리소스가 영구적으로 이동
302	HttpStatus.FOUND	요청한 리소스가 임시적으로 이동
304	HttpStatus.NOT_MODIFIED	요청한 리소스가 수정되지 않음, 클라이언트는 캐시된 버전을 사용

 

4xx : 클라이언트 오류

400	HttpStatus.BAD_REQUEST	클라이언트 요청 오류 (유효성 검증 실패 등)
401	HttpStatus.UNAUTHORIZED	인증이 필요하지만 제공되지 않았거나 실패
403	HttpStatus.FORBIDDEN	요청은 이해했지만, 권한이 없어 거부
404	HttpStatus.NOT_FOUND	요청한 리소스를 찾을 수 없음
405	HttpStatus.METHOD_NOT_ALLOWED	지원되지 않는 HTTP 메서드를 요청
409	HttpStatus.CONFLICT	요청이 서버의 현재 상태와 충돌
422	HttpStatus.UNPROCESSABLE_ENTITY	요청이 올바르지만, 처리할 수 없음

 

5xx: 서버 오류

500	HttpStatus.INTERNAL_SERVER_ERROR	서버에서 요청을 처리하는 동안 오류가 발생
502	HttpStatus.BAD_GATEWAY	게이트웨이 또는 프록시 서버에서 잘못된 응답을 받음
503	HttpStatus.SERVICE_UNAVAILABLE	서버가 일시적으로 사용 불가능 상태
504	HttpStatus.GATEWAY_TIMEOUT	게이트웨이 또는 프록시 서버가 응답을 기다리는 동안 시간이 초과

 

이번글에 이어서 다음글에서는 RESTful API의 핵심인 URI 명명 규칙에 대해서 알아보자.

 

 

끝