[FastAPI 2일차] Type Hints, 상태 코드, 에러 처리

Type Hints 💡

Type Hints는 변수, 함수, 데이터의 의도된 타입을 코드에 명시하는 문법입니다.
FastAPI의 자동 검증, 자동 문서화 기능은 모두 Type Hints를 기반으로 동작합니다.

 

Type Hints의 역할

• 코드 가독성 향상
• IDE 자동 완성 및 오류 사전 탐지 가능
• Pydantic, FastAPI 런타임 검증 기반

 

- 기본 Type Hints 문법

name: str = "apple" 
price: int = 1000 
ratio: float = 0.5 
is_active: bool = True 

score: int | float

 

 

Type Hints는 Python 실행 자체에는 영향을 주지 않는 문법 기능입니다.

 

- 함수에서의 Type Hints

def add(a: int, b: int) -> int: 
	return a + b

 

입력값과 반환값의 타입을 명확하게 표현할 수 있습니다.

 

- 컬렉션 타입 Type Hints

names: list[str] = ["a", "b"] 
scores: dict[str, int] = {"math": 90} 

users: list[dict[str, int | str]] = [ 
	{"id": 1, "name": "alex"}, 
 	   {"id": 2, "name": "bob"}, 
	]

 

리스트와 딕셔너리 내부 구조까지 명확히 표현할 수 있습니다.

 

- Optional Type Hints

Optional Type은 값이 있을 수도 있고 없을 수도 있는 타입입니다.

name: str | None = None

 

---

Request Body

Query와 Path는 URL 기반 입력입니다.
JSON 데이터는 Request Body를 통해 전달합니다.

 

Pydantic 

Pydantic은 데이터 검증과 파싱을 담당하는 라이브러리이며 FastAPI의 핵심 구성 요소입니다.

 

사용 목적

• Request Body(JSON) 검증
• Response 구조 명확화

 

Pydantic 기본 모델

from pydantic import BaseModel 

class Item(BaseModel): 
	name: str 
    price: int

 

item = Item(name="apple", price=1000) 
item.model_dump() 
Item.model_validate({"name": "apple", "price": 1000}) 
Item(name="apple", price="cheap")

 

잘못된 타입 입력 시 자동 검증 오류가 발생합니다.

---

Field를 이용한 검증 강화

from pydantic import BaseModel, Field 

class Item(BaseModel): 
	name: str = Field(..., min_length=2)
    	price: int = Field(..., ge=0)

 

문자열 길이와 숫자 범위를 제한할 수 있습니다.

---

FastAPI에서 Request Body 사용

@app.post("/items") 
def create_item(item: Item): 
	return item

 

Request Body는 자동으로 Pydantic 모델 객체로 변환됩니다.

 

기본값과 선택 필드

class Item(BaseModel): 
	name: str 
    	price: int description: str | None = None 
    	is_active: bool = True

 

필수 필드와 선택 필드를 명확히 구분할 수 있습니다.

 

중첩 모델

class User(BaseModel): 
	id: int 
	name: str 
    
class Order(BaseModel): 
	user: User 
    	amount: int

@app.post("/orders") 
def create_order(order: Order): 
	return order

 

JSON 구조를 그대로 모델로 표현할 수 있습니다.

 

Response Model

@app.post("/items", response_model=Item) 
def create_item(item: Item): 
	return { 
    	"name": "apple", 
        "price": 1000, 
        "category": "fruit" 
    	}

 

Response Model은 응답 구조를 고정하고 불필요한 필드를 자동으로 제거하며 응답 검증을 수행합니다.

---

상태 코드(HTTP Status Code)

상태 코드는 서버가 요청을 어떻게 처리했는지를 숫자로 표현하는 값입니다.

@app.post("/items", status_code=201) 
def create_item(item: Item): 
	return item

 

201은 리소스 생성 성공을 의미합니다.

 

---

에러 처리(Error Handling)

FastAPI는 의도한 형태의 HTTP 에러 응답을 반환할 수 있도록 지원합니다.

from fastapi import HTTPException 

raise HTTPException(
	status_code=404, 
    detail="Item not found"
)

 

에러 상황을 정상적인 HTTP 응답 구조로 변환합니다.