[파이썬] FastAPI - 예외 처리(exception handling)

시작에 앞서

해당 내용은 <가장 빠른 풀스택을 위한 Flask & FastAPI>, Dave Lee 지음. BJ Public 출판.
내용을 토대로 작성되었습니다. 보다 자세한 사항은 해당 교재를 참고하시기 바랍니다.

---

이전 내용

[파이썬] FastAPI - 요청

---

예외 처리(exception handling)

 

예외 처리: 프로그래밍에서 발생할 수 있는 예상치 못한 에러 또는 예외 상황에 대처하는 프로세스.

 

◆ 기본 예외 처리 (try/except 문법)

try 블록 안에서 실행되는 코드에서 예외가 발생하면 except 블록으로 제어가 가능하고 해당 블록의 코드가 실행된다.

from fastapi import FastAPI, HTTPException

app = FastAPI()

# '/items/{item_id}' 경로에 대한 GET 요청을 처리하는 경로 연산 정의
@app.get("/items/{item_id}")
def read_item(item_id: int):
    # 예외가 발생할 가능성이 있는 코드를 try 블록 안에 작성
    try:
        # item_id가 음수인 경우 ValueError 발생
        if item_id < 0:
            raise ValueError("음수는 허용되지 않습니다")
    except ValueError as e:
        # 발생한 ValueError를 HTTPException 으로 변환하여 처리
        # 클라이언트에게 상태 코드 400과 에러 메시지 반환
        raise HTTPException(status_code=400, detail=str(e))

    return {"item_id": item_id}

▶ read_item() 함수는 클라이언트로부터 item_id를 매개변수로 받아 들임.

item_id가 음수일 경우 ValueError가 발생하고, 이는 즉시 HTTPException으로 처리.

FastAPI는 클라이언트에게 400 Bad Request 상태 코드와 함께 에러 메시지 "음수는 허용되지 않습니다." 전달

 

[테스트]

curl -X GET "http://127.0.0.1:8000/items/-1"

---

◆ HTTPException 클래스

FastAPI는 HTTPException 클래스를 활용하여 API에서 발생하는 예외를 클라이언트에게 명확하게 알릴 수 있도록 도와준다.

이를 통해 발생할 수 있는 다양한 에러 상황에 대해 HTTP 상태 코드와 에러 메시지를 정의하고 반환할 수 있다.

from fastapi import FastAPI, HTTPException

app = FastAPI()

# '/items/{item_id}' 경로에 대한 GET 요청을 처리하는 경로 연산 정의
@app.get("/items/{item_id}")
def read_item(item_id: int):
    # 특정 조건(여기서는 item_id가 52일 때) 에러를 발생시키고자할 때 사용
    if item_id == 52:
    	# 클라이언트에게 404 Not Found 상태 코드와 "Item Not Found" 메시지 반환
    	raise HTTPException(status_code=404, detail="Item Not Found")
    # 위의 조건에 해당하지 않는 경우, 정상적으로 아이템 정보 반환
    return {"item_id": item_id}

• status_code(HTTP 상태 코드): 클라이언트에게 요청의 성공, 실패 또는 그 외의 상태를 알려주는 중요한 지표
• detail: 클라이언트에게 반환할 상세 메시지 (사용자가 이해할 수 있는 에러 정보 제공)
• headers: 응답과 함께 전달할 HTTP 헤더 설정하여 클라이언트에게 추가 정보 제공

 

[테스트]

curl -X GET "http://127.0.0.1:8000/items/52"

---

★ 예외 처리에서 raise

raise는 파이썬에서 예외를 발생시키기 위해 사용하는 키워드이다.

프로그램 실행 중 특정 조건에서 표준 흐름을 중단하고 예외 처리 루틴을 시작할 때 raise 구문을 사용한다.

 

HTTPException 을 raise 하는 이유는 FastAPI에서 예외 상황을 처리하고 클라이언트에게 적절한 HTTP 상태 코드와 에러 메시지를 전달하기 위함이다.

예외를 발생시키면 FastAPI가 이를 감지하고 정의된 예외 처리기를 호출하여 사용자에게 지정된 응답을 반환한다. 이 메커니즘을 사용함으로써 API는 예기치 못한 동작이나 에러에 대해 명확한 피드백을 제공할 수 있다.

이는 API의 신뢰성과 사용자 경험을 향상시키는 데 중요한 역할을 한다.

---

HTTP 헤더

 

HTTP 헤더: 클라이언트와 서버 간의 통신에서 추가적인 정보를 제공하는 중요한 역할을 한다.

해당 설정을 위해서는 세부적인 HTTP 프로토콜 스펙에 대한 깊은 이해가 필요하다.

 

[HTTPException에서 사용할 수 있는 일반적인 헤더 예시]

 

1) WWW-Authenticate 헤더

raise HTTPException(
	status_code=401,
    detail="Not authenticated",
    headers={"WWW-Authenticate": "Bearer"}
)
# 클라이언트에게 어떤 인증 방식을 사용해야 하는지 알려줌.
# 주로 401 Unauthorized 응답과 함께 사용

 

2) Retry-After 헤더

raise HTTPException(
	status_code=429,
    detail="Too Many Requests",
    headers={"Retry-After": "120"}
)
# 클라이언트가 서비스에 대한 요청을 너무 많이 보냈을 때,
# 일정 시간 이후에 다시 시도하라는 지시 전달

 

3) X-Rate-Limit 헤더

raise HTTPException(
	status_code=429,
    detail="Rate limit exceeded",
    headers={"X-Rate-Limit": "100"}
)
# 사용자가 한정된 시간 내에 요청할 수 있는 최대 횟수를 알려줌

 

4) X-Error 헤더

raise HTTPException(
	status_code=500,
    detail="Interval Server Error",
    headers={"X-Error": "Database connection failed"}
)
# 내부 서버 에러 발생 시, 에러의 세부 사항을 클라이언트에게 전달

 

5) Cache-Control 헤더

raise HTTPException(
	status_code=200,
    detail="Response Information",
    headers={"Cache-Control": "no-cache"}
)
# 클라이언트에게 해당 응답을 캐시하지 말라는 지시
# 데이터가 실시간으로 갱신되어야 할 때 유용

 

6) Location 헤더

raise HTTPException(
	status_code=201,
    detail="New item created",
    headers={"Location": "/items/5"}
)
# 새로 생성된 리소스의 URI를 클라이언트에게 제공
# 주로 201 Created 응답에서 사용

 

[HTTPException 의 status_code 에서 주로 설정하는 HTTP 상태 코드 값]

• 200 OK: 요청이 성공적으로 처리됨
• 201 Created: 요청이 성공적으로 처리되어 새 리소스가 생성됨
• 400 Bad Request: 서버가 요청을 이해하지 못함
• 401 Unauthorized: 인증이 필요한 페이지를 요청함
• 403 Forbidden: 서버가 요청을 이해했으나 승인을 거부함
• 404 Not Found: 서버가 요청한 리소스를 찾을 수 없음
• 500 Internal Server Error: 서버 내부 에러가 발생함

---

다음 내용