전체 메뉴

테마

Chapter 04

HTTP와 REST Controller

HTTP 요청과 응답, REST URL 원칙을 익히고 목록·단건 조회 API를 만들어 200·400·404·405 응답을 테스트합니다.

난이도
입문
예상 학습
85분
Spring Boot 기준
Spring Boot 4.1.1
JDK 기준
JDK 21
최종 검토

전체 24개 Chapter 중 Chapter 04입니다. 예제 코드는 공개 저장소 spring-boot-curriculum의 examples/ch04-rest-controller 폴더에서 확인할 수 있습니다.

Learning goals

오늘 배울 내용

  • HTTP 요청·응답 구성과 메서드별 안전성·멱등성 설명하기
  • REST 원칙에 따라 자원 중심 URL과 상태 코드 설계하기
  • @RequestParam과 @PathVariable을 구분해 조회 API 만들기
  • ResponseEntity로 200·400·404·405 응답을 구분하고 테스트하기
  1. HTTP 구조 읽기
  2. REST URL 설계
  3. 목록 조회
  4. 단건 조회
  5. 상태 코드 비교
  6. 테스트로 고정
이 Chapter의 진행 흐름

이 Chapter에서 완성할 것

Chapter 03 IoC, DI, Bean에서 객체를 만들고 연결하는 규칙을 익혔습니다. 이제 그 위에 웹 API를 제대로 만들 차례입니다. 이 Chapter의 주제는 조회 API입니다. 정상 요청에 JSON이 나오는 것은 당연하고, 정작 알아야 하는 것은 이상한 요청이 들어왔을 때 서버가 무엇을 돌려주는가입니다. 없는 id를 조회하면 200과 빈 본문일까요, 404일까요? /users/abc처럼 숫자가 아닌 값이 들어오면 어떨까요? 이 Chapter는 조회 API를 만들고 404, 400, 405를 직접 일으켜 응답을 비교합니다.

Chapter를 마치면 아래 내용을 직접 만들고 확인한 상태가 됩니다.

만드는 것 설명
GET /users 사용자 목록입니다. keyword로 이름을 검색하고 limit으로 개수를 제한합니다.
GET /users/{id} 사용자 한 명을 조회합니다. 없으면 404입니다.
UserStore DB 없이 메모리에 사용자 4명을 들고 있는 저장소입니다.
MockMvc 테스트 정상 응답과 404, 400, 405를 고정하는 테스트입니다.

사전 지식은 Chapter 01 프로젝트 시작하기의 컨트롤러와 MockMvc, Chapter 03 IoC, DI, Bean의 생성자 주입(컨트롤러가 저장소를 받는 부분)입니다. 코드는 공개 저장소의 examples/ch04-rest-controller 폴더에 있습니다. JDK 21과 Spring Boot 4.1.1을 기준으로 하며, 모든 명령은 저장소 루트에서 Gradle Wrapper로 실행합니다. 실행 결과는 컨테이너에서 JAR로 직접 실행해 얻은 값이고, Windows 실행은 검증하지 못했습니다.

HTTP 요청과 응답 읽기

웹 API를 만들기 전에 서버와 클라이언트가 주고받는 것이 무엇인지부터 알아야 합니다. 컨트롤러 코드가 아무리 짧아도, 요청과 응답의 구성을 모르면 “왜 이 응답이 왔는지” 읽을 수 없습니다.

이 절에서는 HTTP 요청과 응답의 구성, 메서드별 의미, 그리고 상태 코드의 큰 분류를 정리합니다. 코드는 아직 나오지 않습니다.

요청과 응답의 구성

구분 요청 응답
첫 줄 메서드와 경로 (GET /users/1) 상태 코드 (200)
헤더 부가 정보 (Accept, Content-Type) 부가 정보 (Content-Type, Allow)
본문 보낼 데이터 (생성, 수정 때) 돌려줄 데이터 (JSON 등)

조회처럼 보낼 데이터가 없는 요청은 본문이 없습니다. Chapter 01에서 쓴 curl이 이 요청을 대신 보내 주는 도구입니다.

메서드는 “무엇을 하려는가”

메서드 의미 안전한가 반복해도 결과가 같은가(멱등)
GET 조회 예 (서버 상태를 바꾸지 않음) 예
POST 생성 아니오 아니오
PUT 전체 교체 아니오 예
PATCH 부분 수정 아니오 구현에 따라 다름
DELETE 삭제 아니오 예

두 용어를 구체적으로 살펴봅니다.

  • 안전: 요청해도 서버의 데이터가 바뀌지 않는다는 뜻입니다. GET은 몇 번을 눌러도 데이터가 그대로여야 합니다.
  • 멱등: 같은 요청을 여러 번 보내도 결과가 한 번 보낸 것과 같다는 뜻입니다. DELETE /users/1을 두 번 보내도 사용자 1이 없는 상태는 같습니다. 반면 POST /users는 보낼 때마다 새 사용자가 생길 수 있어 멱등이 아닙니다.

네트워크 오류로 응답을 못 받았을 때 같은 요청을 다시 보내도 되는지는 멱등성이 알려 줍니다. 이 Chapter에서는 GET만 만들고, 나머지는 Chapter 05 CRUD API와 DTO에서 직접 만듭니다.

상태 코드는 결과의 요약

상태 코드는 세 자리 숫자이고 첫 자리가 큰 분류입니다.

범위 의미 이 Chapter에서 만나는 것
2xx 성공 200 OK
4xx 클라이언트가 잘못 요청함 400 Bad Request, 404 Not Found, 405 Method Not Allowed
5xx 서버가 처리하지 못함 500 Internal Server Error

4xx와 5xx의 구분이 중요합니다. 4xx는 “요청을 고쳐서 다시 보내라”, 5xx는 “서버 쪽 문제”라는 신호입니다. 아래 “오류 2: 경로 변수 이름이 다르면 500” 절에서 코드 실수가 500으로 나타나는 것을 직접 봅니다.

curl로 요청과 응답 눈으로 보기

curl -i를 붙이면 응답의 첫 줄과 헤더까지 보여 줍니다. 이 Chapter의 서버(examples/ch04-rest-controller)를 켜고 실제로 호출한 결과입니다.

$ curl -i "http://localhost:8080/users?keyword=kim&limit=1"
HTTP/1.1 200
Content-Type: application/json
Content-Length: 58

[{"id":1,"name":"kim","email":"kim@example.com","age":28}]
줄 읽는 법
HTTP/1.1 200 응답의 첫 줄. 상태 코드 200
Content-Type: application/json 본문이 JSON이라는 헤더
Content-Length: 58 본문의 바이트 수
빈 줄 아래 응답 본문

위 표에서 요청과 응답의 구성(첫 줄, 헤더, 본문)을 실제 응답에서 하나씩 찾아볼 수 있습니다. 응답에는 Date 헤더도 함께 오지만 실행할 때마다 값이 달라서 생략했습니다.

이 상태 코드를 다시 만나는 곳

여기서 본 분류는 이후 Chapter에서 계속 이어집니다. 나중에 코드를 읽다가 낯선 상태 코드를 만나면 이 표로 돌아와 보세요.

상태 코드 나오는 상황 다루는 곳
202 Accepted 오래 걸리는 배치를 시작만 시키고 번호를 돌려줌 Chapter 18의 배치 설계
400 비어 있거나 1000개를 넘는 id 목록을 거절 Chapter 17의 입구 검증
401 / 403 인증 실패와 권한 부족의 구분 Chapter 21의 필터 체인
409 같은 이메일로 다시 가입 Chapter 20의 진짜 서버 시나리오
415 JSON을 보내며 contentType을 빠뜨림 Chapter 19의 슬라이스 오류
500 한글 비밀번호가 bcrypt의 72바이트를 넘음 Chapter 24의 글자 수와 바이트 수
503 필수 모듈 호출이 실패(STOP 정책) Chapter 17의 실패 정책

확인 문제

  1. DELETE /users/1을 두 번 보냈을 때 두 번째 응답이 404여도 DELETE가 멱등이라고 말할 수 있는 이유는 무엇인가요?
  2. 4xx와 5xx 중 클라이언트가 요청을 고쳐서 다시 보내야 하는 쪽은 어느 쪽인가요?
  3. 조회 요청에 본문(body)이 없는 이유는 무엇인가요?

답: 1) 멱등은 “서버의 최종 상태가 같다”는 뜻이고, 두 번 모두 id 1이 없는 상태로 끝나기 때문입니다(응답 코드가 같을 필요는 없습니다). 2) 4xx입니다. 3) 조회는 서버에 보낼 데이터가 없고 경로와 쿼리로 충분하기 때문입니다.

직접 해 보기

  1. 서버가 없어도 됩니다. curl -i https://example.com처럼 -i 옵션으로 응답의 첫 줄과 헤더를 출력해 보고, 위 표의 어느 부분인지 짚어 보세요.
  2. 위 표에서 “멱등”이 아닌 메서드가 왜 재시도에 위험한지 한 문장으로 적어 보세요.

REST 원칙과 URL 설계

메서드의 의미를 알았으니 URL을 어떻게 지을지 정해야 합니다. 같은 기능도 /getUser?id=1과 /users/1처럼 전혀 다르게 표현할 수 있습니다. REST는 이 선택에 일관된 기준을 줍니다.

이 절에서는 REST의 기본 원칙 두 가지와, 요청 값을 URL의 어느 위치에 실을지 정하는 기준을 정리합니다.

자원은 URL, 행위는 메서드

REST는 자원을 URL로, 그 자원에 대한 행위를 HTTP 메서드로 표현하는 설계 방식입니다. 아래 표의 첫 열은 “무엇을 하는지”를 URL에 적은 설계이고, 둘째 열은 URL에는 대상(users)만 두고 행위를 메서드에 맡긴 설계입니다.

잘 안 맞는 설계 REST에 맞는 설계 이유
GET /getUser?id=1 GET /users/1 메서드(GET)와 동사(get)가 겹칩니다.
POST /createUser POST /users 생성이라는 행위는 POST가 이미 말합니다.
POST /deleteUser?id=1 DELETE /users/1 삭제는 DELETE 메서드로 표현합니다.

두 가지만 지켜도 읽기 쉬워진다

1. URL에는 명사를 쓴다. 컬렉션은 복수형(/users), 그 안의 한 건은 id를 붙입니다(/users/1). URL을 보면 “무엇”인지 알고, 메서드를 보면 “무엇을 하는지” 압니다.

2. 결과는 상태 코드로 알린다. 자원이 없으면 200에 “없음”이라는 본문을 보내지 않고 404를 보냅니다. 클라이언트는 본문을 해석하기 전에 상태 코드만으로 성공과 실패를 구분할 수 있습니다.

요청 값은 어디에 싣나

조회 API에는 두 종류의 값이 들어옵니다.

위치 예 애노테이션 용도
경로 /users/2 @PathVariable 특정 자원을 가리키는 값
쿼리 문자열 /users?keyword=kim @RequestParam 필터, 정렬, 개수 같은 선택 조건

판단 기준은 이렇습니다. 값이 없으면 가리키는 자원이 달라지거나 존재하지 않게 된다면 경로에 둡니다(/users/2에서 2를 빼면 다른 자원입니다). 값이 없어도 같은 자원 목록을 조건만 달리 보는 것이라면 쿼리 문자열에 둡니다(keyword가 없으면 전체 목록).

이 Chapter의 API 설계

요청 의미 값의 위치
GET /users 사용자 목록 없음
GET /users?keyword=kim&limit=1 이름에 kim이 들어간 사용자 중 1명 쿼리 문자열
GET /users/2 id가 2인 사용자 경로

이후 Chapter의 URL 설계

이 원칙은 뒤 Chapter의 API에서도 그대로 쓰입니다. 다만 모든 경우가 “명사 + 메서드”로 딱 떨어지지는 않아서, 원칙을 어떻게 적용하거나 비껴가는지 비교해 보면 좋습니다.

API 설계 다루는 곳
POST /api/members/summaries 조회인데 POST를 쓴 이유: id 목록이 길어 쿼리 문자열에 담기 어렵기 때문 Chapter 17의 입구 검증
POST /api/batch/member-summaries, GET .../{jobId} 시작은 POST(202), 상태 조회는 번호를 경로에 둔 GET Chapter 18의 온디맨드 배치
/pages/posts, /api/v1/posts 같은 자원을 HTML 화면과 JSON API로 나눠 주소 공간을 분리 Chapter 24의 화면 나누기
/api/admin/** URL 접두사로 권한 규칙을 걸기 쉽게 모음 Chapter 21의 필터 체인

설계를 판단하는 연습

요구 알맞은 설계 값의 위치와 이유
사용자 한 명 조회 GET /users/2 어느 자원인지 가리키는 값이므로 경로
이름으로 검색 GET /users?keyword=kim 목록을 걸러내는 선택 조건이므로 쿼리
한 번에 가져올 개수 제한 GET /users?limit=1 없어도 목록은 의미가 있으므로 쿼리
없는 사용자 조회 404 결과를 본문 문장이 아니라 상태 코드로 알림

자주 하는 실수

실수 왜 문제인가
URL에 get, create, delete 동사를 씀 메서드와 의미가 겹쳐 같은 기능의 URL이 여러 모양이 됨
없는 자원에 200과 "not found" 문자열을 돌려줌 클라이언트가 본문 문자열을 파싱해야 성공 여부를 알 수 있음
필터 조건을 경로에 넣음(/users/kim) 경로는 특정 자원을 가리키는 값이어서 kim이 id인지 이름인지 모호해짐

확인 문제

  1. /users/2와 /users?id=2는 어느 쪽이 REST 원칙에 더 맞나요? 이유는?
  2. 주문 취소를 URL로 설계해 보세요. (힌트: 취소는 삭제일까요, 상태 변경일까요?)

답: 1) /users/2입니다. id는 특정 자원을 가리키는 값이기 때문입니다. 2) 정답이 하나는 아닙니다. 기록을 남기는 취소라면 PATCH /orders/{id}로 상태를 바꾸는 설계가 자연스럽고, 기록을 지우는 것이라면 DELETE /orders/{id}입니다. 요구에 따라 정한 뒤 일관되게 씁니다.

직접 해 보기

  1. 게시글 서비스를 가정하고 “게시글 목록”, “게시글 1건 조회”, “게시글의 댓글 목록”의 URL을 REST 원칙으로 지어 보세요(예: /posts, /posts/{id}, /posts/{id}/comments).
  2. POST /users/delete?id=3을 REST에 맞게 바꿔 보세요.

목록 조회 API 만들기

이제 설계한 API를 코드로 옮깁니다. 먼저 사용자 목록을 돌려주는 GET /users를 만들고, keyword와 limit을 쿼리 문자열로 받아 봅니다.

데이터베이스는 아직 다루지 않으므로 메모리에 고정된 사용자 목록을 들고 있는 저장소를 씁니다.

응답 객체와 저장소

응답으로 내려갈 사용자는 record 하나입니다.

/** 응답으로 내려가는 사용자. record의 컴포넌트 이름이 그대로 JSON 키가 된다. */
public record User(long id, String name, String email, int age) {
}

저장소는 시작할 때 사용자 4명을 메모리에 들고 있습니다.

@Component
public class UserStore {

    private final List<User> users = List.of(
            new User(1, "kim", "kim@example.com", 28),
            new User(2, "lee", "lee@example.com", 35),
            new User(3, "park", "park@example.com", 42),
            new User(4, "kimberly", "kimberly@example.com", 31));

    public List<User> findAll() {
        return users;
    }

    public Optional<User> findById(long id) {
        return users.stream().filter(user -> user.id() == id).findFirst();
    }
}

UserStore는 @Component이므로 Chapter 03에서 배운 대로 컨테이너가 Bean으로 등록합니다. 데이터베이스는 Chapter 07 DataSource와 H2부터 붙입니다. findById가 Optional을 돌려주는 것은 “없을 수 있다”를 타입으로 드러내기 위해서입니다. 아래 “단건 조회 메서드” 절에서 이것이 404로 이어집니다.

목록 조회 메서드

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

    private final UserStore store;

    public UserController(UserStore store) {
        this.store = store;
    }

    @GetMapping
    public List<User> list(
            @RequestParam(required = false) String keyword,
            @RequestParam(defaultValue = "10") int limit) {
        return store.findAll().stream()
                .filter(user -> keyword == null || user.name().contains(keyword))
                .limit(limit)
                .toList();
    }
}

주요 코드 설명

  • @RequestMapping("/users"): 클래스 안 모든 메서드 경로 앞에 붙는 공통 접두사입니다. @GetMapping에 경로를 적지 않으면 GET /users가 됩니다.
  • 생성자 UserController(UserStore store): 컨트롤러도 Bean이고 저장소를 생성자로 받습니다. 생성자가 하나라 @Autowired가 없습니다.
  • @RequestParam(required = false) String keyword: 값이 없어도 되고, 없으면 null입니다. 그래서 필터 조건이 keyword == null ||로 시작합니다.
  • @RequestParam(defaultValue = "10") int limit: 값이 없으면 문자열 "10"이 int 10으로 변환되어 들어옵니다. int는 null이 될 수 없어서 기본값이 필요합니다.
  • 문자열 "1"이 int로 바뀌는 것은 스프링이 자동으로 해 주는 타입 변환입니다. 변환에 실패하면 메서드는 호출되지 않고 400이 나갑니다(아래 “경로 변수가 타입 변환에 실패하면” 절).
  • 반환값 List<User>는 Jackson이 JSON 배열로 바꿉니다. record의 컴포넌트 이름(id, name, email, age)이 JSON 키가 됩니다.

required와 defaultValue

설정 값이 없을 때 쓰는 때
(기본) 400 반드시 필요한 값
required = false null 없어도 되는 값 (객체 타입)
defaultValue = "10" 기본값으로 변환 없으면 정해진 값을 쓸 값

@RequestParam은 기본이 필수입니다. 선택 값에는 둘 중 하나를 꼭 지정해야 합니다. 이를 잊으면 파라미터 없이 부른 요청이 400이 됩니다(아래 “오류 1: 필수 파라미터가 없으면 400” 절).

요청이 닿는 과정

Chapter 01에서 본 DispatcherServlet이 경로와 메서드로 처리할 메서드를 찾습니다. 찾지 못하거나 값을 변환하지 못하는 실패 경로는 아래 “세 가지 이상한 요청” 절에서 직접 일으킵니다.

따라 하기: 목록 API 확인

  1. ./gradlew :examples:ch04-rest-controller:bootRun으로 서버를 켭니다.
  2. 아래를 호출하고 결과를 비교합니다.
curl "http://localhost:8080/users"
curl "http://localhost:8080/users?keyword=kim"
curl "http://localhost:8080/users?keyword=kim&limit=1"
  1. 첫 요청은 4명, 두 번째는 이름에 kim이 들어간 kim과 kimberly, 세 번째는 kim 한 명이 나오면 성공입니다. 필터를 먼저 적용한 뒤 개수를 자른다는 순서를 확인하세요.

자주 하는 실수

실수 증상 해결
선택 파라미터에 required=false도 defaultValue도 없음 파라미터를 생략하면 400 둘 중 하나 지정
limit을 int로 받으면서 required=false만 지정 생략 시 null을 기본형에 넣을 수 없어 오류 기본형이면 defaultValue 사용, 선택 값이면 Integer

확인 문제

  1. keyword가 null일 때 필터가 모든 사용자를 통과시키는 이유를 코드에서 찾아보세요.
  2. limit=0이면 어떤 응답이 나올까요? 직접 호출해 확인해 보세요.

답: 1) 조건이 keyword == null || ... 형태라 null이면 앞 조건이 참이 되어 이름 검사를 건너뜁니다. 2) 빈 배열 []이 나옵니다. 실제로 호출한 결과이고, 이 예제는 limit 값의 범위를 검증하지 않아 0도 그대로 받아 0명을 자릅니다. limit=abc는 숫자로 바꿀 수 없어 400입니다. 값의 범위 검증은 Chapter 06에서 다룹니다.

직접 해 보기

  1. limit의 기본값을 "2"로 바꾸면 GET /users의 결과가 몇 명이 되는지 예측하고 확인하세요.
  2. keyword 필터를 대소문자 무시로 바꿔 보세요(name().toLowerCase().contains(keyword.toLowerCase())). keyword=KIM으로 확인합니다.
  3. age가 30 이상인 사용자만 거르는 minAge 파라미터(선택, 기본 0)를 추가해 보세요.

단건 조회와 ResponseEntity

목록 조회는 “결과가 비어도 정상”입니다. 하지만 id로 한 명을 조회할 때는 그 id가 없을 수 있고, 이때 서버는 “없다”는 것을 상태 코드로 알려야 합니다. 이 절에서는 경로 변수를 받는 방법과, 상태 코드를 직접 정하는 ResponseEntity를 봅니다.

단건 조회 메서드

UserController에 메서드를 하나 더합니다. 경로의 값을 숫자로 바꾸는 데 실패하면 메서드가 호출되기 전에 400이 되고, 성공하면 저장소에서 찾아 있으면 200, 없으면 404를 돌려줍니다.

@GetMapping("/{id}")
public ResponseEntity<User> get(@PathVariable long id) {
    return store.findById(id)
            .map(ResponseEntity::ok)
            .orElseGet(() -> ResponseEntity.notFound().build());
}

주요 코드 설명

  • @GetMapping("/{id}"): 클래스의 /users 접두사와 합쳐져 GET /users/{id}가 됩니다. 중괄호 {id}는 이 자리에 오는 값을 id라는 이름으로 받겠다는 표시입니다.
  • @PathVariable long id: 경로의 {id} 값을 long으로 변환해 받습니다. 이름이 같아야 연결됩니다. 이름이 다르면 아래 “오류 2: 경로 변수 이름이 다르면 500” 절의 500이 됩니다.
  • store.findById(id): 앞의 “응답 객체와 저장소” 절에서 본 대로 Optional<User>를 돌려줍니다.
  • .map(ResponseEntity::ok): 값이 있으면 200 응답으로 감쌉니다.
  • .orElseGet(() -> ResponseEntity.notFound().build()): 값이 없으면 404 응답을 만듭니다. 본문은 채우지 않습니다.

왜 User가 아니라 ResponseEntity를 반환하나

단순히 User를 반환하면 항상 200입니다. 자원이 없을 때 404를 돌려주려면 상태 코드를 코드에서 정할 수 있어야 하고, 그 도구가 ResponseEntity입니다. 상태 코드, 헤더, 본문을 직접 조립하는 객체입니다. 항상 200으로 충분한 메서드(앞의 list)는 ResponseEntity 없이 값을 바로 반환해도 됩니다.

반환 형태 응답 쓰는 때
User 항상 200 실패 경로가 없을 때
ResponseEntity<User> 상태 코드를 코드가 정함 200과 404처럼 갈릴 때

경로 변수가 타입 변환에 실패하면

GET /users/abc처럼 숫자가 아닌 값이 오면 "abc"를 long으로 바꿀 수 없습니다. 컨트롤러 메서드는 호출되지 않고, 스프링이 400을 돌려줍니다. 우리가 400을 위해 쓴 코드는 한 줄도 없습니다. 이 동작은 아래 “세 가지 이상한 요청” 절에서 확인합니다.

ResponseEntity를 다시 만나는 곳

배치를 시작하는 API가 ResponseEntity.accepted().body(...)로 202를 돌려줍니다(Chapter 18 AOP와 온디맨드 배치의 온디맨드 배치 설계). 없는 자원을 404로 바꾸는 처리를 화면과 API에서 갈라 쓰는 방법은 Chapter 24 종합 프로젝트 2의 화면 나누기에 있습니다.

따라 하기: 세 가지 결과 만들기

curl -i http://localhost:8080/users/2     # 200 + 객체
curl -i http://localhost:8080/users/999   # 404, 본문 없음
curl -i http://localhost:8080/users/abc   # 400

실제로 호출한 404 응답은 이렇습니다.

HTTP/1.1 404
Content-Length: 0

본문이 없고 Content-Length: 0입니다. 우리가 ResponseEntity.notFound().build()로 본문 없이 만든 응답이기 때문입니다.

자주 하는 실수

실수 증상 해결
Optional을 .get()으로 바로 꺼냄 값이 없으면 예외로 500 map(...).orElseGet(...) 패턴 사용
없는 자원인데 ResponseEntity.ok(null) 200인데 본문이 비어 클라이언트 혼란 404를 돌려주기
경로 변수 이름과 @PathVariable 이름 불일치 500 (아래 “오류 2: 경로 변수 이름이 다르면 500” 절에서 재현) 이름을 맞추거나 @PathVariable("id") 명시

확인 문제

  1. ResponseEntity<User> 대신 User를 반환하면 어떤 점이 달라지나요?
  2. 존재하지 않는 id에 404를 돌려주는 것과 빈 객체를 200으로 돌려주는 것 중 클라이언트에게 더 명확한 쪽은?

답: 1) 상태 코드를 코드에서 정할 수 없어 항상 200이 됩니다. 2) 404입니다. 상태 코드만 보고 성공 여부를 판단할 수 있기 때문입니다.

직접 해 보기

  1. /users/{id}를 /users/{userId}로, @PathVariable long id를 @PathVariable("userId") long id로 바꿔도 동작하는지 확인하세요. 이름을 명시하면 파라미터 이름과 달라도 연결됩니다.
  2. 존재하지 않는 id에 404 대신 ResponseEntity.status(HttpStatus.NOT_FOUND).body(...)로 메시지를 담은 본문을 돌려주도록 바꿔 보세요. 본문이 있는 404가 어떤 모양인지 확인합니다.
  3. /users/{id}/email을 추가해 이메일 문자열만 돌려주는 메서드를 만들어 보세요. 없으면 404입니다.

실행해서 응답 확인하기

코드를 읽는 것만으로는 부족합니다. JAR를 실행하고 같은 요청을 보내 응답이 설계한 대로 나오는지 눈으로 확인합니다. 이 절은 정상 요청 네 가지를 다룹니다.

실행 방법

OS 실행 이 Chapter만 빌드
Linux / macOS ./gradlew :examples:ch04-rest-controller:bootRun ./gradlew :examples:ch04-rest-controller:build
Windows gradlew.bat :examples:ch04-rest-controller:bootRun gradlew.bat :examples:ch04-rest-controller:build

서버가 켜지면 다른 터미널에서 요청합니다.

정상 요청 네 가지

curl http://localhost:8080/users
curl "http://localhost:8080/users?keyword=kim"
curl "http://localhost:8080/users?keyword=kim&limit=1"
curl http://localhost:8080/users/2

요청이 배열을 돌려주는지 객체를 돌려주는지가 URL 설계(컬렉션과 단건)와 일치하는지 확인하는 것이 이 절의 핵심입니다.

실행 결과

GET /users
200 [{"id":1,"name":"kim","email":"kim@example.com","age":28},{"id":2,"name":"lee","email":"lee@example.com","age":35},{"id":3,"name":"park","email":"park@example.com","age":42},{"id":4,"name":"kimberly","email":"kimberly@example.com","age":31}]

GET /users?keyword=kim
200 [{"id":1,"name":"kim",...},{"id":4,"name":"kimberly",...}]

GET /users?keyword=kim&limit=1
200 [{"id":1,"name":"kim","email":"kim@example.com","age":28}]

GET /users/2
200 {"id":2,"name":"lee","email":"lee@example.com","age":35}

두 번째 줄의 ...은 지면을 위해 줄인 표기이고, 실제 응답에는 모든 필드가 있습니다.

결과 읽기

요청 결과 이유
/users 4명 필터가 없고 limit 기본값 10이 4보다 큽니다.
keyword=kim kim, kimberly 이름에 kim이 포함된 모두입니다.
keyword=kim&limit=1 kim 한 명 필터 후 앞에서 1명만 자릅니다.
/users/2 객체 하나 목록(배열)이 아니라 단건이어서 대괄호가 없습니다.

목록은 JSON 배열([...]), 단건은 JSON 객체({...})로 형태가 다른 점을 눈여겨보세요. 클라이언트가 응답을 처리하는 코드도 이에 맞춰야 합니다.

실행 확인을 자동화하면

여기서 손으로 한 “서버를 켜고 curl로 확인”은 CI의 스모크 테스트가 자동으로 합니다(Chapter 22 운영의 GitHub Actions). CI가 실패하는 대표 사례도 같은 Chapter에서 다룹니다.

응답 헤더까지 확인하는 방법

curl에 -i를 붙이면 상태 코드와 헤더가 보이고, 상태 코드만 필요하면 -w를 씁니다.

curl -i http://localhost:8080/users/2
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/users/999

둘째 명령은 본문을 버리고(-o /dev/null) 상태 코드만 출력합니다. 직접 호출해 보면 404가 나옵니다. 상태 코드만 비교하는 스크립트나 CI 스모크 테스트가 이 방식을 씁니다.

성공 판정 기준

요청 기대 결과
GET /users 200, JSON 배열 4개
GET /users?keyword=kim 200, 2명(kim, kimberly)
GET /users?keyword=kim&limit=1 200, 1명
GET /users/2 200, JSON 객체([로 시작하지 않음)

결과가 기대와 다를 때 점검하는 순서

  1. 서버 콘솔에 Started ... 줄이 있었는지 확인합니다.
  2. 요청한 포트가 8080인지(기동 로그의 Tomcat started on port) 확인합니다.
  3. 주소의 ?와 &가 셸에서 잘리지 않도록 주소 전체를 큰따옴표로 감쌌는지 확인합니다. &를 따옴표 없이 쓰면 셸이 명령을 나눕니다.
  4. 응답이 400이나 404라면 아래 “세 가지 이상한 요청” 절의 표로 원인을 좁힙니다.

자주 하는 실수

실수 증상 해결
&가 있는 주소를 따옴표 없이 입력 limit이 적용되지 않거나 셸이 명령을 둘로 나눔 주소 전체를 큰따옴표로 감싸기
이전 Chapter 서버가 8080을 사용 중 Port 8080 was already in use 이전 서버 종료
목록 결과를 단건 결과로 착각 [ 대괄호 유무를 놓침 응답의 첫 글자로 형태 구분

확인 문제

  1. keyword=kim이 kimberly도 돌려주는 이유는 무엇인가요?
  2. 목록 응답과 단건 응답의 JSON 모양은 어떻게 다른가요?

답: 1) 이름이 kim과 같은 것이 아니라 kim을 포함하는 사용자를 찾는 조건이기 때문입니다. 2) 목록은 배열([...]), 단건은 객체({...})입니다.

직접 해 보기

  1. keyword=Kim(대문자)으로 요청하면 결과가 어떻게 되는지 확인하세요. contains는 대소문자를 구분합니다.
  2. limit=0과 limit=-1을 보내 어떤 응답이 오는지 확인해 보세요. 이 Chapter에서는 이 값들을 검증하지 않았으므로, 결과를 직접 관찰하고 어떻게 처리하고 싶은지 적어 보세요(검증은 Chapter 06 검증과 예외 처리의 주제입니다).
  3. curl -i http://localhost:8080/users/2로 응답 헤더까지 출력해 Content-Type을 확인하세요.

이상한 요청의 응답 비교와 테스트

정상 요청이 되는 것은 당연합니다. API의 품질은 이상한 요청에서 드러납니다. 이 절에서는 세 가지 이상한 요청을 일으켜 응답을 비교하고, 그 약속을 테스트로 고정합니다.

세 가지 이상한 요청

GET /users/999
404 (본문 없음)

GET /users/abc
400 {"timestamp":"2026-10-17T03:46:21.974Z","status":400,"error":"Bad Request","path":"/users/abc"}

POST /users
405  Allow: GET
{"timestamp":"2026-10-17T03:46:22.275Z","status":405,"error":"Method Not Allowed","path":"/users"}

요청은 경로에 맞는 핸들러가 있는지(없으면 404), HTTP 메서드가 맞는지(아니면 405와 Allow 헤더), 값을 타입 변환할 수 있는지(아니면 400)를 차례로 통과해야 컨트롤러에 닿습니다. /users/999는 모든 단계를 통과한 뒤 컨트롤러가 404를 정하고, /users/abc는 타입 변환에서 400이 되며, POST /users는 메서드 단계에서 405가 됩니다.

timestamp는 요청한 시각이므로 실행할 때마다 다릅니다.

요청 상태 나온 이유
GET /users/999 404 경로는 맞지만 id가 999인 사용자가 없어 ResponseEntity.notFound()를 돌려줍니다.
GET /users/abc 400 "abc"를 long으로 바꿀 수 없어 컨트롤러가 호출되기 전에 막힙니다.
POST /users 405 경로(/users)는 있지만 POST를 처리하는 메서드가 없습니다.

실패 경로를 정리하면 이렇습니다. 매핑 자체가 없으면 404, 경로는 맞는데 메서드가 다르면 405, 값 변환에 실패하면 400입니다.

본문이 있는 응답과 없는 응답

세 응답을 나란히 보면 404만 본문이 없습니다.

  • 404는 우리가 ResponseEntity.notFound().build()로 직접 만든 응답입니다. 본문을 채우지 않았기 때문에 비어 있습니다.
  • 400과 405는 코드를 쓰지 않았는데도 Spring Boot가 JSON 오류 본문을 만들어 줍니다.

같은 4xx인데 클라이언트가 받는 모양이 다릅니다. 이 불일치는 Chapter 06에서 오류 응답 형식을 통일하며 다룹니다.

알아 두면 좋은 점

  • 400 응답에는 어느 값이 왜 잘못됐는지가 없습니다. status, error, path뿐입니다.
  • 405 응답의 Allow: GET 헤더는 이 경로에서 쓸 수 있는 메서드를 알려 줍니다. 클라이언트가 어떤 메서드를 써야 하는지 알 수 있는 단서입니다.
  • POST /users가 막힌 것은 이 Chapter에서는 정상입니다. 생성 API는 Chapter 05에서 추가합니다.

약속을 테스트로 고정하기

어떤 요청에 어떤 상태 코드가 나가는지는 API의 약속입니다. 테스트로 남겨 두면 코드를 고치다가 약속이 깨질 때 바로 알 수 있습니다.

@Test
void unknownIdReturns404() throws Exception {
    mockMvc.perform(get("/users/999"))
            .andExpect(status().isNotFound());
}

@Test
void nonNumericIdReturns400() throws Exception {
    mockMvc.perform(get("/users/abc"))
            .andExpect(status().isBadRequest());
}

@Test
void methodsWithoutMappingReturn405() throws Exception {
    mockMvc.perform(post("/users"))
            .andExpect(status().isMethodNotAllowed())
            .andExpect(header().string("Allow", "GET"));
    mockMvc.perform(delete("/users/1"))
            .andExpect(status().isMethodNotAllowed());
}

주요 코드 설명

  • status().isNotFound(), isBadRequest(), isMethodNotAllowed(): 각각 404, 400, 405를 검증하는 이름 있는 검증입니다. isOk()와 같은 계열입니다. 사용법은 Chapter 01의 “MockMvc로 서버 없이 컨트롤러를 확인합니다” 절과 같습니다.
  • header().string("Allow", "GET"): 응답 헤더 Allow의 값을 검증합니다.
  • post("/users"), delete("/users/1"): GET이 아닌 메서드의 요청을 만듭니다.

이 Chapter는 이 밖에 정상 응답 검증과 숫자가 아닌 limit이 400이 되는지까지 모두 8건을 두었고, 컨텍스트 로딩 테스트를 더해 9건이 모두 통과했습니다.

실제 응답으로 확인하기

405 응답을 curl -i로 호출한 결과입니다.

$ curl -i -X POST http://localhost:8080/users
HTTP/1.1 405
Allow: GET
Content-Type: application/json

{"timestamp":"2026-10-18T00:29:07.658Z","status":405,"error":"Method Not Allowed","path":"/users"}

Allow: GET 헤더가 이 경로에서 쓸 수 있는 메서드를 알려 줍니다. 404(직접 만든 응답)는 본문이 없고, 405와 400(프레임워크가 만든 응답)은 JSON 본문이 있다는 차이가 한 화면에서 보입니다.

자주 하는 실수

실수 증상 해결
404와 405를 같은 문제로 봄 경로는 맞는데 메서드를 바꿔야 하는 경우를 놓침 405이면 Allow 헤더 확인
상태 코드 테스트 없이 코드를 수정 약속이 조용히 바뀜 status() 검증 테스트로 고정
400의 원인을 본문에서 찾으려 함 기본 오류 본문에는 이유가 없음 요청 값의 형식과 메서드 인자 타입 확인

확인 문제

  1. GET /users/999가 404인 이유와 GET /nope가 404인 이유는 어떻게 다른가요?
  2. DELETE /users/1을 보내면 이 Chapter의 서버는 어떤 상태 코드를 돌려줄까요? 이유와 함께 예상해 보세요.

답: 1) 전자는 매핑이 맞지만 컨트롤러가 “자원 없음”을 404로 정한 것이고, 후자는 매핑 자체가 없어 프레임워크가 404를 만든 것입니다. 2) /users/{id}에 DELETE를 처리하는 메서드가 없으므로 405이고, 실제로 호출하면 Allow: GET 헤더가 함께 옵니다.

직접 해 보기

  1. curl -i -X POST http://localhost:8080/users로 405 응답의 헤더 Allow를 직접 확인하세요.
  2. GET /users?limit=many를 보내 상태 코드를 확인하세요. 테스트에서는 400인지만 확인했고 본문은 실행해 보지 않았습니다. 본문이 어떤지 직접 관찰해 보세요.
  3. DELETE /users/1도 405인 것을 확인하고, 이 405가 Chapter 05에서 DELETE를 구현하면 어떻게 바뀔지 예측해 보세요.

자주 만나는 오류와 해결 방법

요청이 컨트롤러에 닿기 전에 막히는 오류는 상태 코드가 단서입니다. 이 절에서는 작은 실수 두 가지를 일부러 만들어 어떤 코드가 나오는지 확인합니다. 아래 결과는 이 예제를 한 군데씩 바꿔 테스트를 돌려 얻은 값이고, 바꾼 코드는 되돌렸습니다.

오류 1: 필수 파라미터가 없으면 400

@RequestParam(defaultValue = "10") int limit에서 기본값을 지웠습니다. 쿼리 문자열 없이 GET /users를 부르면 목록이 아니라 400이 나옵니다. 테스트 9건 중 2건이 실패했습니다.

listReturnsAllUsers()
Status expected:<200> but was:<400>
keywordFiltersByName()
No value at JSON path "$"

두 번째 줄은 400의 본문이 비어 있어서 나온 결과입니다. 단서는 파라미터를 생략한 요청만 실패한다는 점입니다. limit을 준 테스트는 통과했습니다. 선택 값에는 required = false 또는 defaultValue가 필요합니다(앞의 “required와 defaultValue” 절).

오류 2: 경로 변수 이름이 다르면 500

@GetMapping("/{id}")를 "/{userId}"로 바꿨는데 메서드 파라미터는 그대로 @PathVariable long id입니다. 테스트 9건 중 3건이 실패했고 응답은 모두 500이었습니다.

getByIdReturnsUser()
Status expected:<200> but was:<500>
unknownIdReturns404()
Status expected:<404> but was:<500>

400이나 404가 아니라 500인 것이 중요합니다. 요청이 잘못된 것이 아니라 서버 코드가 잘못되었다는 신호입니다. 응답 코드만으로는 원인이 드러나지 않으므로 서버 로그의 예외를 봅니다. 경로 문자열의 {...} 이름과 @PathVariable의 이름(또는 파라미터 이름)이 같아야 합니다. 내부 예외의 정확한 이름은 이 실험에서 확인하지 않았고, 테스트가 본 응답 코드만 적었습니다.

상태 코드로 범위를 좁히는 순서

4xx는 요청이나 매핑을, 5xx는 서버 코드를 먼저 의심합니다. 두 오류 모두 Status expected:<200> but was:<...> 형태로 테스트가 알려 주므로, 실제 코드 값(400, 500)부터 확인하세요.

500이 나면 콘솔을 읽는다

경로 변수 이름이 다른 경우처럼 500은 응답 본문에는 단서가 거의 없고, 서버 콘솔에 예외가 출력됩니다. Chapter 01의 “오류 메시지는 맨 아래 Caused by부터 읽습니다” 절에서 익힌 대로 Caused by를 맨 아래부터 읽어 원인 줄을 찾으세요. 이 Chapter의 경우 경로의 {userId}와 메서드 파라미터 id가 이어지지 않는다는 취지의 메시지가 원인입니다.

증상별 점검표

응답 의심할 곳
400 (파라미터를 생략했을 때) @RequestParam의 required, defaultValue
400 (값이 숫자가 아닐 때) 요청 값의 형식, 메서드 인자의 타입
500 (경로 변수를 쓰는 요청) 경로의 {이름}과 @PathVariable
404 경로 오타, 시작 클래스 패키지 밖에 둔 컨트롤러(스캔 범위)
405 요청한 HTTP 메서드와 매핑

같은 증상을 다른 Chapter에서

상태 코드로 원인을 좁히는 방법은 뒤 Chapter에서도 같습니다.

직접 해 보기

  1. 저장소를 복사해 defaultValue를 지우고 GET /users가 400이 되는 것을 재현해 보세요. 되돌리는 것을 잊지 마세요.
  2. 경로 변수 이름을 일부러 틀리게 쓰고, 서버 로그에서 500의 원인이 되는 예외 메시지를 찾아 한 줄로 적어 보세요.
  3. 오류가 났을 때 상태 코드를 먼저 보고 위 점검표에서 의심할 곳을 고르는 연습을 하세요.

용어와 참고 자료

아래 표는 이 Chapter에 나온 용어와 참고한 사이트를 모은 것입니다. 앞 Chapter에서 설명한 용어는 다시 쓰지 않으므로 Chapter 01 프로젝트 시작하기와 Chapter 03 IoC, DI, Bean을 참고하세요.

참고한 자료

HTTP와 REST

용어 설명
HTTP 메서드 요청이 “무엇을 하려는가”를 나타내는 GET, POST, PUT, PATCH, DELETE입니다.
안전(safe) 요청해도 서버의 데이터가 바뀌지 않는 성질입니다. GET이 해당합니다.
멱등(idempotent) 같은 요청을 여러 번 보내도 결과가 한 번 보낸 것과 같은 성질입니다.
상태 코드 응답의 결과를 나타내는 세 자리 숫자입니다. 2xx 성공, 4xx 요청 문제, 5xx 서버 문제입니다.
헤더 요청과 응답에 붙는 부가 정보입니다. Content-Type, Allow 등이 있습니다.
REST 자원을 URL로, 행위를 HTTP 메서드로 표현하는 API 설계 방식입니다.
자원(resource) API가 다루는 대상입니다. 이 Chapter에서는 사용자(/users)입니다.
경로 변수 URL 경로 안의 값입니다. /users/2의 2입니다.
쿼리 문자열 URL의 ?키=값&키=값 부분입니다.

컨트롤러 애노테이션과 타입

용어 설명
@RequestMapping 컨트롤러나 메서드의 요청 경로를 정합니다. 클래스에 붙이면 공통 접두사입니다.
@GetMapping GET 요청을 메서드에 연결합니다.
@RequestParam 쿼리 문자열의 값을 인자로 받습니다. 기본은 필수입니다.
required / defaultValue @RequestParam의 옵션으로, 생략 가능 여부와 기본값입니다.
@PathVariable 경로의 {이름} 부분을 인자로 받습니다.
ResponseEntity 상태 코드, 헤더, 본문을 직접 조립해 반환하는 객체입니다.
Optional 값이 있을 수도 없을 수도 있음을 나타내는 Java 타입입니다.
타입 변환 문자열 "1"을 int나 long으로 바꾸는 스프링의 자동 변환입니다. 실패하면 400입니다.

상태 코드

코드 이름 이 Chapter에서 나온 상황
200 OK 정상 조회
400 Bad Request 값 변환 실패, 필수 파라미터 생략
404 Not Found 없는 id, 매핑 없음
405 Method Not Allowed 경로는 있으나 지원하지 않는 메서드. Allow 헤더에 가능한 메서드
500 Internal Server Error 서버 코드의 문제(경로 변수 이름 불일치)

예제 코드 파일

본문에서 다룬 파일은 예제 저장소의 다음 위치에 있습니다.

대상 링크
컨트롤러 UserController.java
저장소 UserStore.java
응답 객체 User.java
컨트롤러 테스트 UserControllerTests.java

직접 해보기

  1. ./gradlew :examples:ch04-rest-controller:bootRun으로 서버를 켜고 curl -i http://localhost:8080/users/2로 상태 줄, Content-Type, 본문을 “HTTP 요청과 응답 읽기” 절의 표와 하나씩 맞춰 보세요.
  2. GET /users?limit=2, GET /users?keyword=Kim, GET /users?keyword=kim을 보내 결과 수를 비교하고, keyword 필터를 대소문자 무시로 바꾼 뒤 다시 확인해 보세요.
  3. 존재하지 않는 id를 조회해 404를 확인하고, ResponseEntity.status(HttpStatus.NOT_FOUND).body(...)로 본문이 있는 404를 돌려주도록 바꿔 응답 모양을 비교해 보세요.
  4. curl -i -X POST http://localhost:8080/users와 GET /users?limit=many를 보내 405와 400을 확인하고, 405 응답의 Allow 헤더가 무엇을 알려 주는지 적어 보세요.
  5. @RequestParam의 defaultValue를 지우거나 경로 변수 이름을 틀리게 써서 400과 500을 재현한 뒤, “자주 만나는 오류와 해결 방법” 절의 점검표로 상태 코드부터 원인을 좁혀 보세요.

이번 장의 정리

  • HTTP 요청은 메서드, 경로, 헤더, 본문으로, 응답은 상태 코드, 헤더, 본문으로 이루어집니다. GET은 안전하고 멱등하며, POST는 둘 다 아닙니다.
  • REST는 자원을 URL(명사)로, 행위를 HTTP 메서드로 표현하고, 성공과 실패는 상태 코드로 알립니다.
  • 자원을 가리키는 값은 @PathVariable, 선택 조건은 @RequestParam으로 받습니다. @RequestParam은 기본이 필수이므로 선택 값에는 required = false나 defaultValue를 지정합니다.
  • 성공과 실패로 갈리는 메서드는 ResponseEntity로 상태 코드를 정하고, Optional을 map(ResponseEntity::ok)와 orElseGet(404)로 이어 씁니다.
  • 404는 매핑이나 자원이 없을 때, 400은 값 변환에 실패했을 때, 405는 경로는 있고 메서드가 다를 때이며, 이 약속을 MockMvc 테스트로 고정했습니다.
  • 오류는 상태 코드부터 봅니다. 4xx는 요청이나 매핑을, 5xx는 서버 코드와 콘솔의 Caused by를 먼저 의심합니다.

다음 Chapter 05 CRUD API와 DTO에서는 생성, 수정, 삭제를 더하고 요청 DTO와 Service 계층을 나눕니다.

FAQ

자주 묻는 질문

REST API URL에 동사를 넣으면 안 되나요?

보통 URL은 users 같은 자원을 나타내고 조회·생성·수정·삭제는 HTTP 메서드로 표현합니다. 자원 모델로 표현하기 어려운 작업은 팀의 일관된 규칙에 따라 별도 동작 자원을 설계할 수 있습니다.

없는 사용자를 조회하면 200과 빈 본문을 반환해도 되나요?

요청한 단일 자원이 없다는 의미를 분명히 전달하려면 404가 알맞습니다. 목록 조회 결과가 비어 있을 때는 200과 빈 배열을 반환합니다.

400과 404는 어떻게 구분하나요?

숫자여야 할 경로 값이 abc인 것처럼 요청 형식을 해석할 수 없으면 400이고, 형식은 맞지만 해당 자원이 없으면 404입니다.

ResponseEntity는 언제 필요한가요?

응답 본문뿐 아니라 상태 코드나 헤더를 조건에 따라 직접 정해야 할 때 사용합니다.

작성·편집 ToolPado

콘텐츠 유형 Spring Boot 학습 가이드

기술 기준 Spring Boot 4.1.1 · JDK 21

마지막 검토