[파이썬] FastAPI - 타입 힌트(Type hint)

시작에 앞서

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

---

이전 내용

[파이썬] FastAPI - 라우팅

---

타입 힌트(Type hint)

 

타입 힌트는 프로그래밍에서 변수나 함수의 에상 타입을 명시적으로 표시하는 기술이다.

FastAPI는 파이썬의 타입 힌트를 사용하여 요청을 검증하고, 적절한 데이터가 요청과 응답에 사용되도록 돕는다. 이 기능을 통해 개발자는 별도의 검증 로직을 작성하지 않고도 안정적인 API를 구축할 수 있다.

---

기본 타입 힌트

 

FastAPI에서 경로 매개변수나 쿼리 매개변수에 타입 힌트를 추가하면, 해당 타입에 맞지 않는 요청은 자동으로 거부된다. 또한, 매개변수에 기본값을 설정하여 선택적으로 만들 수 있다.

★ 경로 매개변수나 쿼리 매개변수 관련 글은 이전 포스팅 참고

 

from fastapi import FastAPI #FastAPI 라이브러리 import

app = FastAPI() # FastAPI 인스턴스 생성

# 경로 매개변수 사용 예제
@app.get("/items/{item_id}")
def read_items(item_id: int): #q는 기본값이 None인 쿼리 매개변수
	return {"item_id": item_id}
    
# 쿼리 매개변수 사용 예제
@app.get("/getdata/")
def read_items(data: str = "funcoding") # data의 기본값은 'funcoding'
	return {"data": data}
    
# 실행: uviconr main:app --reload

▶ 테스트 방법 및 결과

• http://127.0.0.1:8000/items/123으로 접속하면 {"item_id":123} 출력
• http://127.0.0.1:8000/items/fun 같이 item_id에 해당하는 데이터를 정수(int) 타입이 아닌 다른 데이터 타입으로 넣으면 에러 발생
• http://127.0.0.1:8000/getdata/?data=somquery 와 같이 data 쿼리 매개변수를 넣으면 {"data":"somequery"} 출력
• http://127.0.0.1:8000/getdata/ 와 같이 dtaa 쿼리 매개변수를 넣지 않으면 기본값으로 { "data":"funcoding"} 출력
• http://127.0.0.1:8000/getdata/?data=1.1 과 같이 data 쿼리 매개변수를 넣으면 {"data":1.1} 출력 *1.1이 문자열(str)이 될 수도 있기 때문에 문자열로 인지하여 정상 처리

---

고급 타입 힌트

 

FastAPI는 typing 모듈에서 제공하는 List, Dict 같은 고급 타입 힌트를 사용하여 요청 데이터를 쉽게 다룰 수 있다.

from fastapi import FastAPI, Query #FastAPI 라이브러리 import
from typing import List, Dict

app = FastAPI()

# List 데이터 타입을 쿼리 매개변수로 받는 라우트 예제
@app.get("/items/")
def read_items(q: List[int] = Query([])): # 빈 리스트를 기본값으로 설정
	return {"q": q}

# Dict 데이터 타입을 요청 바디로 받는 라우트 예제
@app.post("/create-item/")
def create_item(item: Dict[str, int]):
	return item

# 실행: uvicorn main:app --reload

 

Query는 쿼리 매개변수의 기본값을 설정하는 데 사용되며, 유효성 검사 및 메타데이터 선언에도 사용된다.

Query([]) 는 해당 쿼리 매개변수가 필수가 아님을 나타내고, 기본값으로 빈 리스트를 제공한다. Dict와 달리 List 타입 힌트의 경우에는 List[int] = Query([])와 같이 반드시 Query() 관련 구문을 함께 넣어주어야 타입 힌트 유효성 검사가 항상 동작한다.

 

[테스트]

• List 타입의 데이터를 쿼리 매개변수로 사용하려면, 각 항목에 대해 쿼리 매개변수를 반복해서 명시해야 한다.
• curl을 사용하여 q 쿼리 매개변수와 함께 여러 값을 리스트로 전송

curl "http://127.0.0.1:8000/items/?q=1&q=2&q=3"

쿼리 매개변수로 전달한 리스트 [1,2,3]이 {"q":[1,2,3]} 형태로 JSON 응답을 받을 수 있다.

 

 

• http://127.0.0.1:8000/create-item/ 주소에 HTTP POST 요청을 전송할 때는 curl 명령어를 사용해야 한다.

curl -X POST "http://127.0.0.1:8000/create-item/" -H "accept:application/json" -H "Content-Type: application/json" -d "{\"name\": 1}"

위 명령을 실행하면 서버는 {"name":1} 형태의 요청 바디를 받고, 그대로 응답으로 반환한다.

---

타입 힌트로 사용 가능한 데이터 타입

 

• 기본 데이터 타입

- int: 정수

- float: 부동소수점 숫자

- str: 문자열

- bool: 불리언(True or False)

• 컬렉션 타입

- List: 변경 가능한 순서가 있는 컬렉션

- Tuple: 변경 불가능한 순서가 있는 컬렉션

- Dict: 키-값 쌍을 갖는 컬렉션

- Set: 중복 없는 항목의 컬렉션

• 특수 타입

- None: 아무런 값을 갖지 않음

- Any: 모든 타입을 허용, 타입 검사를 무시하고자 할 때 사용

• typing 모듈의 고급 타입

- Optional: 값이 있거나 None 일 수 있는 타입

- Union: 여러 타입 중 하나일 수 있는 값

- Callable: 호출 가능한 객체(함수 등)를 나타냄

- Iterable: 반복 가능한 객체를 나타냄

- Sequence: 시퀀스 타입을 나타냄

• 사용자 정의 타입

- 클래스나 다른 타입 힌트를 사용하여 사용자 정의 타입을 생성할 수 있음

---

다음 내용

[파이썬] FastAPI - HTTP 메서드, Pydantic