FastAPI를 사용한 파이썬 웹 개발(CHAPTER 3)

 

📌 CHAPTER 3에서 다루는 내용

• FastAPI의 응답 구조
• pydantic을 활용한 응답 모델 작성
• HTTP 상태 코드와 오류 처리

학습을 마치면 응답의 구성 요소, 응답 모델의 역할,
그리고 FastAPI에서 오류를 처리하는 방법을 이해할 수 있다.

---

3.1 FastAPI의 응답(Response)

응답(Response)은 클라이언트가 API에 요청(Request)을 보낸 후
서버가 처리 결과로 반환하는 데이터다.

FastAPI의 응답은 보통 JSON 형식이며, 다음 두 가지로 구성된다.

1️⃣ 응답 헤더(Header)

요청 상태와 응답 바디에 대한 정보를 전달한다.

• 예시
  • Content-Type: application/json
    → 반환되는 데이터 형식을 클라이언트에게 알려줌

2️⃣ 응답 바디(Body)

서버가 클라이언트에게 실제로 전달하는 데이터다.
응답 바디의 형식은 Content-Type 헤더에 의해 결정된다.

HTTP 상태 코드(Status Code)

HTTP 상태 코드는 요청 처리 결과를 나타내는 짧은 고유 코드다.

상태 코드 분류

• 1XX: 요청을 받음
• 2XX: 요청 성공
• 3XX: 리다이렉트
• 4XX: 클라이언트 오류
• 5XX: 서버 오류

대표적인 상태 코드

• 200 : 성공
• 404 : 요청한 리소스를 찾을 수 없음
• 500 : 서버 내부 오류

📌 중요

• 요청이 실패했는데 2XX를 반환하면 안 된다.
• 서버 오류인데 4XX를 반환해서도 안 된다.

---

3.2 응답 모델(Response Model) 작성

응답 모델이란?

• 서버가 클라이언트에게 반환할 데이터의 형태를 정의하는 모델
• pydantic(BaseModel)을 사용하지만 요청 모델과 목적이 다름
  • 요청 모델: 입력 데이터 검증
  • 응답 모델: 출력 데이터 제한 및 구조화

---

기존 /todo 라우트의 문제점

• todo_list에 저장된 모든 필드(id, item)를 그대로 반환
• 특정 필드만 반환하려면 추가 로직이 필요함

---

response_model의 역할

• 라우트 정의에 response_model을 지정하면
  • 모델에 정의된 필드만 응답에 포함됨
  • 불필요한 데이터(id 등)는 자동으로 제거됨
• 응답 구조를 코드 수정 없이 제어 가능

---

응답 모델 설계

• TodoItem
  • 반환할 단일 todo 항목 모델
  • item 필드만 포함
• TodoItems
  • 여러 개의 TodoItem을 담는 리스트 구조
  • todo 목록 전체 응답용 모델

---

라우트에 응답 모델 적용

• /todo 라우트에 response_model=TodoItems 추가
• 반환 데이터는 기존과 같아도
  • 실제 응답은 응답 모델 기준으로 자동 변환됨

---

응답 결과 변화

• 변경 전
  • id + item 모두 반환
• 변경 후
  • id 제외
  • todo 내용(item)만 배열 형태로 반환

---

응답 모델 사용의 장점

• 추가 로직 없이 응답 데이터 제어 가능
• API 응답 구조가 명확해짐
• Swagger / ReDoc 문서에 응답 형식이 자동 반영됨
• 유지보수 및 확장에 유리

---

정리

• 응답 모델은 API 출력 데이터를 관리하는 핵심 도구
• 요청 모델과 함께 FastAPI에서 반복적으로 사용됨
• 이후 오류 처리와 고급 기능 구현의 기반이 됨

...........

 

요청 모델이 “클라이언트로부터 어떤 데이터를 받을지”를 정의한다면, 응답 모델은 서버가 어떤 형태의 데이터를 반환할지 결정하는 역할을 한다.

 

3.3 오류 처리(Error Handling)

오류 처리는 애플리케이션에서 발생하는 문제를
적절한 상태 코드와 메시지로 클라이언트에게 전달하는 과정이다.

FastAPI에서는 HTTPException 클래스를 사용해 오류를 처리한다.

---

HTTPException 인수

• status_code : 반환할 HTTP 상태 코드
• detail : 클라이언트에게 전달할 메시지
• headers : 선택적 헤더 정보

 

HTTPException 클래스를 사용해 라우트를 변경하면 적절한 응답 코드와 함께 상태 메시지도 반환할 수 있다. 

 

todo.py에서 추출,변경,삭제 라우트를 다음과 같이 변경하자.

from fastapi import APIRouter, Path, HTTPException, status
...
@todo_router.get("/todo/{todo_id}")
async def get_single_todo(todo_id: int = Path(..., title="The ID of the todo to retrieve.")) -> dict:
    for todo in todo_list:
        if todo.id == todo_id:
            return {
                "todo": todo
            }
    raise HTTPException(
        status_code=status.HTTP_404_NOT_FOUND,
        detail="Todo with supplied ID doesn't exist",
    )


@todo_router.put("/todo/{todo_id}")
async def update_todo(todo_data: TodoItem, todo_id: int = Path(..., title="The ID of the todo to be updated.")) -> dict:
    for todo in todo_list:
        if todo.id == todo_id:
            todo.item = todo_data.item
            return {
                "message": "Todo updated successfully."
            }

    raise HTTPException(
        status_code=status.HTTP_404_NOT_FOUND,
        detail="Todo with supplied ID doesn't exist",
    )


@todo_router.delete("/todo/{todo_id}")
async def delete_single_todo(todo_id: int) -> dict:
    for index in range(len(todo_list)):
        todo = todo_list[index]
        if todo.id == todo_id:
            todo_list.pop(index)
            return {
                "message": "Todo deleted successfully."
            }
    raise HTTPException(
        status_code=status.HTTP_404_NOT_FOUND,
        detail="Todo with supplied ID doesn't exist",
    )

 

존재하지 않는 todo를 추출하려고 하면 아래와 같이 404 코드와 메시지가 반환된다.

 

★참고로 요청 성공을 의미하는 기본 상태 코드는 200이니 기억하도록 하자★

---

✨ 정리하기

CHAPTER 3에서는

• FastAPI 응답 구조와 HTTP 상태 코드의 의미를 이해하고
• pydantic을 사용한 응답 모델 작성 방법을 학습했으며
• HTTPException을 활용해 정확한 오류 처리를 구현했다.

이를 통해 클라이언트에게
👉 의미 있는 상태 코드와
👉 일관된 응답 형식을 제공할 수 있게 되었다.

다음 CHAPTER 4에서는
Jinja 템플릿을 활용한 FastAPI UI 구성 방법을 학습할 예정이다.

 

🌱 배운 점

• FastAPI의 응답은 **헤더(Header)와 바디(Body)**로 구성되며, 상태 코드와 함께 클라이언트에게 요청 처리 결과를 전달한다.
• HTTP 상태 코드는 요청의 성공·실패 여부를 명확히 표현하는 중요한 요소이며, 상황에 맞는 코드를 반환하는 것이 REST API 설계의 기본임을 이해했다.
• response_model을 사용하면 pydantic 기반으로 응답 데이터 구조를 제어할 수 있어, 불필요한 데이터 노출을 방지할 수 있다.
• HTTPException을 활용하면 오류 상황을 명확한 상태 코드와 메시지로 처리할 수 있어, 클라이언트 입장에서 API를 더 이해하기 쉬워진다.
• FastAPI에서는 데코레이터 옵션을 통해 기본 응답 코드(200)를 상황에 맞게 변경할 수 있다는 점을 배웠다.

---

✨ 느낀 점

이번 CHAPTER 3 학습을 통해 API 개발에서 “응답을 어떻게 돌려주느냐”가 얼마나 중요한지 체감할 수 있었다.
단순히 데이터만 반환하는 것이 아니라, 응답 모델과 상태 코드를 통해 의미 있는 결과를 전달하는 것이 좋은 API라는 점을 이해하게 되었다. 특히 응답 모델을 사용해 반환 데이터를 깔끔하게 정리할 수 있다는 점이 인상 깊었고, 오류 처리까지 포함한 API 설계가 실무에서 꼭 필요한 요소라는 생각이 들었다.
이번 내용을 바탕으로 이후 챕터에서 UI와 연동되는 FastAPI 애플리케이션을 더 안정적으로 확장할 수 있을 것이라는 자신감도 생겼다.

★참고로 요청 성공을 의미하는 기본 상태 코드는 200이니 기억하도록 하자★