Fast API - 기초

많은 프레임 워크를 사용해왔지만, 깊이가 부족하다고 항상 생각했다. 이제는 그것들에 대한 깊이를 더 채워보고자 한다.

무엇보다 어떤 질문에 관해서든 이유를 물을 때 바로 답 할 수 있는 실력을 갇기를 원하기 때문이다.

가장 먼저 깊게 파볼 프레임워크는 Fast API이다. 

이유는 Python을 주력으로 하고, 제일 많이 맡아 온 역할이 백앤드이기에, 빠르게 정리하고 깊이를 늘릴 수 있다고 판단했다.

Fast API를 중심으로 확장하며 정리하겠다.

 

기본 개념

 

Fast API는 Python의 async / await 문법을 기반으로 한 비동기 프로그래밍을 지원

-> 이 덕분에 여러 요청을 동시에 처리할 수 있어, 높은 트래픽 상황에서도 빠른 응답을 유지할 수 있다.

 

Flask처럼 동기 프로그램의 경우 한 번에 하나의 작업만 처리하기에 부족

"한 번에 하나의 작업"만 처리하는 구조이기 때문에, 시간이 오래 걸리는 작업(외부 API 호출, DB 대기)이 있으면 그동안 다른 요청은 대기하게 된다.


반면 FastAPI는 비동기(async) 방식을 채택하여, 외부 응답을 기다리는 동안에도 다른 요청을 동시에 처리할 수 있어 → 처리 속도가 빠르고, 서버 리소스 효율이 높다.

프레임워크	인스턴스 생성 방식	예시 코드
FastAPI	app = FastAPI()	from fastapi import FastAPI app = FastAPI()
Flask	app = Flask(name)	from flask import Flask app = Flask(name)
Django	직접 인스턴스 생성 X 프로젝트 구조와 설정 파일로 관리	django-admin startproject ... manage.py runserver

 

스웨거 보유

from fastapi import FastAPI

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


@app.get("/")
async def root():
    return {"message": "Hello World"}


@app.get("/hello/{name}")
async def say_hello(name: str):
    return {"message": f"Hello {name}"}

서버 실행

로컬 실행: ASGI 구현체 중 비동기 웹 서버인 Uvicorn

1. ASGI란?

• ASGI(Asynchronous Server Gateway Interface)는 파이썬 웹 서버와 웹 프레임워크(예: FastAPI, Django) 사이의 "비동기 통신"을 위한 표준 인터페이스
• 기존의 WSGI(Web Server Gateway Interface)는 동기 방식만 지원해서 실시간 처리, 웹소켓, 비동기 요청 등 현대적 웹 기능에 한계

2. Uvicorn이란?

• Uvicorn은 ASGI 표준을 구현한 대표적인 파이썬 비동기 웹 서버
• FastAPI, Starlette, 최신 Django(ASGI 모드) 등과 함께 사용되며, 비동기 처리가 필요한 현대적 웹 서비스에 적합

Flask에서 사용한 Gunicorn은 WSGI 서버

uvicorn main:app --reload

• main = main.py
• app: app=FastAPI(), FastAPI 인스턴스를 생성하는 객체의 변수 이름 
• --reload: 코드 수정시 서버 자동 재시작

http://127.0.0.1:8000/docs 를 통해 자동 문서화

항목	Swagger	ReDoc
기능 목적	개발 및 테스트 중심	문서화 및 배포 중심
디자인	직관적이며 기능 위주 UI	정돈된 문서 스타일 UI
Try it out 기능	있음 → API 직접 테스트 가능	없음 → 읽기 전용 문서
사용자층	주로 개발자	개발자 + 비개발자(기획자 등)
FastAPI 기본 경로	/docs	/redoc
기반 스펙	OpenAPI (Swagger)	OpenAPI (ReDoc 기반)

• /docs (Swagger UI): API를 직접 실행해보며 테스트 가능 → 개발 중에 유용함
• /redoc: 깔끔하게 정리된 문서 제공 → 배포 후 외부 공개용에 적합

Swagger

Paths	각 API 엔드포인트 (GET, POST 등)
Parameters	Path, Query, Header, Cookie 등에 들어가는 파라미터
Request body	요청 시 전송할 JSON 스키마 (pydantic 모델 기반)
Responses	응답 코드별 반환 값 예시 및 스키마
Schemas	전체 API에서 쓰이는 데이터 모델 구조 정의
Try it out	직접 파라미터 입력하고 요청 보내기 가능

 

라우팅

 

정의: 클라이언트로부터 오는 HTTP 요청을 적절한 함수(handler)로 연결하는 것

즉, GET /users/123 요청이 오면 이를 처리할 FastAPI 함수와 연결하는 과정

 

경로 매개변수

• URL 경로의 일부를 변수처럼 사용
• 동적인 리소스를 요청할 때 사용

@app.get("/users/{user_id}")
def get_user(user_id: int):
    return {"user_id": user_id}

• 요청: GET /users/7
• 결과: { "user_id": 7 }

 

쿼리 매개변수

• URL에서 ? 이후에 나오는 key=value 형태의 매개변수

@app.get("/search")
def search_items(q: str = None):
    return {"query": q}

• 요청: GET /search?q=apple 
• 결과: { "query": "apple" }

 

타입 힌트

 

변수나 함수의 매개변수나 반환값에 타입을 명시해주는 문법으로, 코드 가독성 향상 + FastAPI에서는 자동 문서화 및 유효성 검사에 사용

from typing import Dict
from fastapi import FastAPI

app = FastAPI()

@app.post("/create-item/")
def create_item(item: Dict[str, int]):
    return item



from typing import List

@app.post("/items/")
def create_items(items: List[str]):
    return {"received": items}

 

파이썬 데이터 타입

 

1. 기본 자료형

int	1, -5, 100	정수형
float	3.14, -0.1	실수형 (부동소수점)
complex	1+2j	복소수형
bool	True, False	불리언형
str	"hello", 'a'	문자열형

 

2. 시퀀스 타입

list	[1, 2, 3]	가변형 순차 자료형
tuple	(1, 2)	불변형 순차 자료형
range	range(5)	정수 시퀀스 (반복에 사용)

 

3. 매핑 타입

dict

{"a": 1}

키-값 쌍의 집합

 

4. 집합 타입 

set	{1, 2, 3}	중복 없는 집합
frozenset	frozenset([1,2])	불변 집합

  

5. 바이너리 타입

bytes	b"abc"	바이트 데이터
bytearray	bytearray(5)	가변 바이트
memoryview	memoryview(b"abc")	메모리 버퍼 뷰

 

6.  None 타입

NoneType

None

값이 없음을 의미

 

7. 타입 힌트용 타입(typing 모듈)

Any	어떤 타입이든 가능
Union[int, str]	int 또는 문자열 (여러 타입 중 하나)
Optional[int]	int 또는 None (값이 있거나 None)
List[str]	문자열 리스트
Dict[str, int]	문자열-정수 딕셔너리
Tuple[int, str]	고정된 구조의 튜플
Callable[[int,int],int]	두 정수 매개변수를 받고 정수를 반환 (함수 타입)
Literal["A", "B"]	특정 값들만 허용
TypedDict	구조 정의된 딕셔너리
Annotated	타입 + 메타데이터

 

8. 사용자 정의 타입

class User:
    name: str

 

HTTP Method(NO Pydantic) 

 

from fastapi import FastAPI, HTTPException
from typing import Dict, List

app = FastAPI()

# 메모리 상의 가짜 데이터 저장소(지금 DB 없이 하니까)
items_db: Dict[int, Dict[str, str or int or float]] = {}


# 1. POST - 아이템 추가
@app.post("/items/")
def create_item(item: Dict[str, str or int or float]):
    item_id = item.get("id")
    if item_id in items_db:
        raise HTTPException(status_code=400, detail="Item already exists")
    items_db[item_id] = item
    return {"message": "Item created", "item": item}


# 2. GET - 아이템 전체 조회
@app.get("/items/")
def get_all_items():
    return list(items_db.values())


# 3. GET - 특정 아이템 조회
@app.get("/items/{item_id}")
def get_item(item_id: int):
    if item_id not in items_db:
        raise HTTPException(status_code=404, detail="Item not found")
    return items_db[item_id]


# 4. PUT - 아이템 수정
@app.put("/items/{item_id}")
def update_item(item_id: int, updated_item: Dict[str, str or int or float]):
    if item_id not in items_db:
        raise HTTPException(status_code=404, detail="Item not found")
    items_db[item_id] = updated_item
    return {"message": "Item updated", "item": updated_item}


# 5. DELETE - 아이템 삭제
@app.delete("/items/{item_id}")
def delete_item(item_id: int):
    if item_id not in items_db:
        raise HTTPException(status_code=404, detail="Item not found")
    del items_db[item_id]
    return {"message": f"Item {item_id} deleted"}

 

주의점

• 유효성 검사 없음 → 클라이언트가 잘못된 타입을 보내도 서버가 받아버릴 수 있음
• FastAPI의 강력한 기능(문서 자동화, 타입 체크 등)을 충분히 활용하려면 Pydantic 사용을 권장

 

Pydantic

 

Python의 타입 힌트를 기반으로 입력 값의 유효성 검증과 자동 변환, 직렬화, 역직렬화를 도와주는 데이터 모델링 라이브러리

FastAPI는 Pydantic을 사용해서 다음을 자동으로 처리

데이터 유효성 검사(Validation)	클라이언트가 보낸 데이터의 타입, 형식, 필수 여부를 검사	price: float에 문자열 "abc"이 들어오면 오류 반환
데이터 직렬화 (Serialization)	내부 Python 객체를 JSON 등으로 자동 변환	Python의 Item 객체 → JSON 응답으로 변환
데이터 역직렬화 (Parsing)	JSON → Python 객체로 자동 변환	JSON으로 온 {"id": 1} → Item(id=1) 객체 생성
문서화 자동화 (Schema 생성)	Swagger UI(/docs)에서 모델 구조 자동 표시	필드 타입, 필수 여부 등 문서화
기본값 및 필수 필드 관리	선택/필수 필드 구분 가능	name: Optional[str] = None
타입 변환 지원	"10" 같은 문자열 숫자 → int로 자동 변환	age: int에 "10" 넣어도 int 처리

• 직렬화
  • 데이터를 전송하거나 저장할 수 있도록 특정한 포맷(예: JSON, XML, CSV 등)으로 변환하는 과정.
  • 즉, 파이썬 객체와 같은 메모리 상의 데이터를 파일, 데이터베이스, 네트워크 등으로 내보낼 수 있게 일련의 바이트나 문자열로 바꾸는 것을 의미한다. 반대로, 직렬화된 데이터를 다시 파이썬 객체로 복원하는 과정을 역직렬화라고 한다.

항목	Pydantic 사용 (BaseModel)	Pydantic 미사용 (dict, 타입힌트만)
입력값 검증	타입/값 자동 검증, 상세 에러 메시지 반환	수동 검증 필요, 에러 처리 직접 구현
자동 변환/파싱	JSON → 객체 자동 변환	직접 파싱/변환 코드 작성 필요
직렬화/역직렬화	dict(), json() 등으로 객체 변환 자동	수동 변환 필요, 일관성 떨어짐
Swagger 문서 자동화	입력/출력 구조, 제약조건, 예시 자동 반영	단순 타입만 표시, 구조화 어려움
복잡한 구조 지원	중첩, 리스트, 옵션 등 복잡한 구조 쉽게 처리	단일 값/간단 구조만 처리
코드 유지보수/확장성	모델 중심 관리, 재사용/확장 용이	필드 많아지면 코드 복잡, 관리 어려움
에러 응답	422 등 표준화된 에러 및 상세 메시지 자동 반환	500 등 서버 에러, 상세 피드백 어려움
유효성 검증 커스터마이즈	validator, Field 등으로 세밀하게 제어	직접 if문 등으로 처리

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

# 1. 데이터 모델 정의
class Item(BaseModel):
    id: int
    name: str
    price: float

# 2. POST 요청 처리
@app.post("/items/")
def create_item(item: Item):
    return {"message": "Item created", "item": item}

curl -X POST "http://localhost:8000/items/" \
     -H "Content-Type: application/json" \
     -d '{"id": 1, "name": "apple", "price": 3.5}'

{"message":"Item created","item":{"id":1,"name":"apple","price":3.5}}

curl Tset

1. -H "accept: application/json"
   • 설명: 서버에게 "나는 JSON 형식의 응답을 받고 싶다."라고 요청하는 HTTP 헤더
   • 역할: 서버가 여러 가지 데이터 형식(XML, HTML 등)으로 응답할 수 있을 때, 클라이언트가 원하는 형식을 지정하는 역할
2.  -H "Content-Type: application/json"
   • 설명: 서버에게 "내가 보내는 데이터는 JSON 형식이다."라고 알리는 HTTP 헤더
   • 역할: 서버가 요청 본문에 담긴 데이터의 형식을 올바르게 해석할 수 있도록 한다.
3.  -d
   • 설명: curl 명령어에서 -d는 "data"의 약자로, 서버로 보낼 데이터를 지정할 때 사용
   • 역할: POST, PUT 같은 요청에서 본문에 데이터를 담아 보낼 때 사용

curl은 “Client URL”의 줄임말로, 터미널/명령어 기반 HTTP 요청 도구

• REST API를 테스트할 때 매우 유용
• FastAPI 서버에 요청을 직접 날릴 수 있음
• GUI 없이 명령줄에서 빠르게 확인 가능

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

curl -X GET "http://localhost:8000/users/123"

curl -X GET "http://localhost:8000/search"

curl -X POST "http://localhost:8000/items" \
     -H "Content-Type: application/json" \
     -d '{"name": "banana", "price": 1000}'

{"name":"banana","price":1000}

 

Item이 Pydantic 모델 id, name, price가 필드

 

필드 제약조건

제약조건	설명	타입
min_length, max_length	문자열 길이 제한	str
gt, ge, lt, le	숫자 크기 조건(> >= < <=)	int, float
regex	정규표현식으로 문자열 형식 제한	str
min_items, max_items	리스트의 최소/최대 길이 제한	list

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()

class Product(BaseModel):
    name: str = Field(..., min_length=3, max_length=50)
    price: float = Field(..., gt=0)  # 0보다 커야 함
    description: str = Field(default="", max_length=200)
    tags: list[str] = Field(default=[], min_items=1)

@app.post("/products/")
def create_product(product: Product):
    return {"message": "상품 등록 완료", "product": product}

• Field(..., ...) : ...(Ellipsis)는 Python에서 "필수값"을 의미
• Field(default=...) : 기본값 지정
• Field(default_factory=list) : 리스트의 기본값을 빈 리스트로 안전하게 지정

에러: (필수값 누락, price가 0 이하, name이 짧음 등) -> 422 Unprocessable Entity 에러 발생

 

복잡한 데이터형태

 

1. 중첩 모델 (Nested Models) - 복잡한 JSON 구조를 표현할 때 모델 안에 다른 모델을 넣는 방식

개념

• 클래스 안에 다른 Pydantic 모델 클래스 사용
• 재사용성, 가독성, 유지보수

from pydantic import BaseModel
from typing import List

class Address(BaseModel):
    city: str
    zipcode: str

class User(BaseModel):
    name: str
    age: int
    address: Address  # 중첩 사용

요청 시

{
  "name": "Alice",
  "age": 30,
  "address": {
    "city": "Seoul",
    "zipcode": "12345"
  }
}

 

 2. List, Union

• List: 여러 개의 항목을 담는 리스트 구조
• Union: 여러 타입 중 하나를 허용

# List → "hobbies": ["reading", "sports"] 형태 가능

class User(BaseModel):
    name: str
    hobbies: List[str]

# Union → "value": 123 도 되고 "value": "abc" 도 가능

from typing import Union

class Item(BaseModel):
    value: Union[int, str]

 

 

3. 제네릭(Generic)

"아무 타입이나 들어올 수 있음"을 의미

주로 재사용 가능한 유연한 구조 만들 때 사용

관련 타입: TypeVar, Generic

 

• 타입 변수(TypeVar)
  • TypeVar는 타입 힌트에서 "아직 구체적으로 정해지지 않은 타입"을 표현할 때 사용
  • 예를 들어, 함수나 클래스가 여러 타입을 받아야 할 때, 타입의 자리를 미리 예약해두는 역할
  • 왼쪽 T: 실제 코드에서 사용할 타입 변수 이름(타입 힌트로 사용)
  • 오른쪽 "T": 내부적으로 식별자 역할을 하는 문자열(아무 문자열이나 가능하지만, 보통 변수명과 맞춤)

T = TypeVar("T")

 

• 제너릭(Generic) 타입
  • 제너릭은 클래스나 함수를 "타입에 따라 유연하게" 동작하게 만들어준다.
  • 예를 들어, 리스트(List)는 어떤 타입의 값이든 담을 수 있다. → List[int], List[str] 

 

from typing import TypeVar, Generic
from pydantic.generics import GenericModel

T = TypeVar("T")  # 어떤 타입이든 가능

# Response는 어떤 타입의 data든 담을 수 있는 제너릭 모델 
# 실제 사용할 때는 Response[int], Response[str], Response[User] 등으로 구체화해서 사용
class Response(GenericModel, Generic[T]):
    code: int
    data: T

class User(BaseModel):
    id: int
    name: str


@app.get("/user", response_model=Response[User])
def get_user():
    return Response(code=200, data=User(id=1, name="Alice"))
    
# → T가 User로 구체화됨. Response[User]가 되는 구조

{
  "code": 200,
  "data": {
    "id": 1,
    "name": "Alice"
  }
}

 

요청

 

HTTP 요청의 기본 구성

• method: 요청 방식 (GET, POST, PUT, PATCH, DELETE)
• url: 요청 주소 (예: /users/1)
• headers: 요청 헤더 (예: 인증, Content-Type 등)
• body: 요청 본문 (POST, PUT, PATCH 등에서 주로 사용)

 

FastAPI에서 데이터 전달 방식

 

1. GET 요청

• 데이터 전달: URL 경로(Path), 쿼리 매개변수(Query), 헤더(Header)

from fastapi import FastAPI, Query, Path, Header

app = FastAPI()

@app.get("/users/{user_id}")
def read_user(
    user_id: int = Path(..., description="User ID"), 
    q: str = Query(None, description="검색어"),
    token: str = Header(None)
):
    return {"user_id": user_id, "q": q, "token": token}

• user_id: URL 경로에서 추출 (Path)
• q: 쿼리 매개변수에서 추출 (Query)
• token: 헤더에서 추출 (Header)

 

2. POST, PUT, PATCH 요청

• 데이터 전달: 주로 요청 본문(Body)

from fastapi import FastAPI, Body
from pydantic import BaseModel

app = FastAPI()

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

@app.post("/items/")
def create_item(
    item: Item = Body(...), # 본문 필수
    description: str = Body(None) # 본문 선택
):
    return {"item": item, "description": description}

 

구분	방법	예시
경로 매개변수	URL 내 변수	/items/{item_id}
쿼리 매개변수	?key=value	/items?limit=10
요청 본문(JSON)	Pydantic 모델로 받음	POST, PUT에서 주로 사용
폼 데이터	Form 객체 사용	로그인, 회원가입
파일 업로드	File 객체 사용	이미지, 문서 업로드
헤더	Header로 받음	인증 토큰 등
쿠키	Cookie로 받음	세션 처리 등

 

from fastapi import FastAPI, Form, File, Header, Cookie

@app.post("/login")
def login(username: str = Form(...), password: str = Form(...)):
    return {"username": username}

@app.post("/upload")
def upload(file: bytes = File(...)):
    return {"file_size": len(file)}

@app.get("/read-header")
def read_header(user_agent: str = Header(None)):
    return {"User-Agent": user_agent}

 

응답

 

응답 모델

• 응답 모델은 FastAPI에서 API 응답 데이터의 구조와 타입을 명확하게 선언하는 기능
• Pydantic의 BaseModel을 상속받아 응답 데이터의 구조를 미리 정의한다.
• FastAPI의 @app.get, @app.post 등 경로 함수에서 response_model=모델명으로 지정한다.
• 이 모델을 기반으로 응답 데이터의 타입 변환, 유효성 검사, 직렬화, 문서화가 자동으로 이루어진다.
• 모델을 지정하지 않으면 반환된 객체를 그대로 JSON으로 변환하여 클라이언트에 반환하고, 데이터가 노출될 수 있다.

 

구분	단순 response (dict 등)	응답 모델(response_model)
데이터 구조	자유롭게 반환, 타입 제한 없음	명확하게 선언한 구조와 타입으로 반환
검증/변환	없음	타입 변환, 유효성 검사 자동 수행
문서화	자동 문서화 불가	OpenAPI 문서 자동 생성, 스키마 명확
필드 제한	모든 데이터 반환(민감정보 노출 위험)	모델에 정의된 필드만 반환(필요한 정보만 노출)
직렬화	수동 처리 필요	Pydantic이 자동 직렬화(JSON 변환 등)

 

1. 기본 응답 모델

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    id: int
    name: str

@app.get("/user", response_model=User)
def get_user():
    # password는 User 모델에 없음
    return {"id": 1, "name": "Alice", "password": "secret"}

• 실제 반환값에는 password가 있지만, 클라이언트는 아래처럼 받음

{
  "id": 1,
  "name": "Alice"
}

 

2. Generic 응답 모델

• 여러 타입의 데이터를 감싸는 공통 응답 구조를 만들 때 사용
• TypeVar와 GenericModel을 활용해, 다양한 타입의 데이터를 유연하게 처리할 수 있다.

from typing import TypeVar, Generic
from fastapi import FastAPI
from pydantic import BaseModel
from pydantic.generics import GenericModel

app = FastAPI()
T = TypeVar("T")

class Response(GenericModel, Generic[T]):
    code: int
    data: T

class User(BaseModel):
    id: int
    name: str

@app.get("/user", response_model=Response[User])
def get_user():
    return Response(code=200, data=User(id=1, name="Alice"))

{"code": 200, "data": {"id": 1, "name": "Alice"}}

 

3. Union 응답 모델

• 한 엔드포인트에서 여러 타입의 응답을 반환할 수 있도록 정의
• Union을 활용하면, 응답이 여러 모델 중 하나일 수 있음을 명시할 수 있다.

from typing import Union
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class SuccessResponse(BaseModel):
    result: str

class ErrorResponse(BaseModel):
    error: str

@app.get("/result", response_model=Union[SuccessResponse, ErrorResponse])
def get_result(success: bool = True):
    if success:
        return SuccessResponse(result="ok")
    else:
        return ErrorResponse(error="fail")

# /result?success=true 호출 시
{"result": "ok"}

# /result?success=false 호출 시
{"error": "fail"}

 

4. List 응답 모델

• 설명:여러 개의 객체를 리스트로 반환할 때 사용
• response_model=List[Model] 또는 response_model=list[Model]로 지정한다.

from typing import List
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

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

@app.get("/items", response_model=List[Item])
def get_items():
    return [
        {"name": "Book", "price": 10.0},
        {"name": "Pen", "price": 2.5},
    ]

[
  {"name": "Book", "price": 10.0},
  {"name": "Pen", "price": 2.5}
]

 

 

응답 클래스

 

• 응답 클래스는 서버가 클라이언트에게 반환하는 HTTP 응답의 형식(타입)을 정의
• FastAPI에서 response_class 파라미터로 지정하거나, 기본값(JSONResponse)을 사용
• 반환값을 해당 응답 클래스에 맞는 형태(예: JSON, HTML 등)로 자동 변환해 준다.

JSON (기본)	자동 변환	딕셔너리 → JSON
HTML	HTMLResponse	HTML 템플릿 반환
텍스트	PlainTextResponse	일반 텍스트 반환
리다이렉트	RedirectResponse	URL 이동 처리
파일 다운로드	FileResponse	파일 반환
직접 설정	JSONResponse	상태코드, 헤더 수동 설정 가능

 

# JSON
@app.get("/json")
def get_json():
    return {"message": "Hello, JSON!"}
    
# HTML
from fastapi.responses import HTMLResponse

@app.get("/html", response_class=HTMLResponse)
def get_html():
    return "<h1>Hello, HTML!</h1>"
    
    
# Plain Text
from fastapi.responses import PlainTextResponse

@app.get("/text", response_class=PlainTextResponse)
def get_text():
    return "Just plain text"

# Redirect
from fastapi.responses import RedirectResponse

@app.get("/redirect")
def redirect():
    return RedirectResponse(url="/new-location")

 

• 응답 클래스: "이 응답을 어떤 형식(HTML, JSON, 파일 등)으로 줄 것인가?"
• 응답 모델: "이 응답 데이터의 구조(필드, 타입)는 어떻게 생겼는가?"

 

예외처리

 

예외처리를 통해  에러 상황에 대응하고, 에러메시지와 HTTP상태코드로 API 에 대한 신뢰성과 UX를 향상

예외가 발생한 시점에서 프로그램이 바로 종료

-> 서버 API라면 500 에러가 발생할 수 있음

→ FastAPI는 내부적으로 try-except 구문을 사용해 예외가 발생해도 서버가 멈추지 않게 처리한다.

• 개발자가 직접 예외처리를 하거나, 커스텀 예외 핸들러(@app.exception_handler)를 등록해서 에러 메시지와 HTTP 상태코드를 원하는 대로 반환한다.

 

try:
    print("시작")
    result = 10 / 2
except ZeroDivisionError:
    print("0으로 나눌 수 없습니다.")
else:
    print("정상적으로 실행되었습니다:", result)
finally:
    print("무조건 실행됩니다")

 

try	예외 발생 가능성이 있는 코드
except	예외가 발생했을 때 처리할 코드
else	예외가 발생하지 않았을 때 실행되는 코드
finally	예외 발생 여부와 관계없이 항상 실행되는 코드

 

HTTPExecption

from fastapi import FastAPI, HTTPException

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id: int):
    if item_id == 0:
        raise HTTPException(status_code=404, detail="Item not found",headers={"WWW-Authenticate": "Bearer"})
    return {"item_id": item_id}

매개변수	설명
status_code	HTTP 상태 코드 (필수)
detail	에러 상세 메시지 (필수)
headers	추가 응답 헤더 (선택)

 

사용자 정의 예외처리

class NegativeNumberError(Exception):
    pass

def check_positive(n):
    if n < 0:
        raise NegativeNumberError("음수는 허용되지 않습니다.")

try:
    check_positive(-5)
except NegativeNumberError as e:
    print(f"에러 발생: {e}")

 

 

참고

https://fastapi.tiangolo.com/ko/tutorial/response-model

 

지속적으로 업데이트 중인 글입니다.