FastAPI 서버개발, 경로 동작 함수 만들기

FastAPI는 Python으로 작성된 현대적이고 빠른 웹 프레임워크로, API 서버 개발에 매우 유용합니다. 이 글에서는 FastAPI를 사용하여 경로 동작 함수를 만드는 방법에 대해 상세히 알아보겠습니다. 이 강좌는 FastAPI를 처음 접하는 개발자뿐만 아니라 경로와 동작 함수 작성을 개선하고자 하는 개발자에게도 유익할 것입니다.

1. FastAPI 소개

FastAPI는 Starlette(비동기 웹 프레임워크)와 Pydantic(데이터 유효성 검사 및 설정 관리)을 기반으로 구축되었습니다. 주로 RESTful API를 구축하는 데 사용되며, 다음과 같은 장점이 있습니다:

  • 성능: FastAPI는 매우 빠르며, Python의 비동기 기능을 통해 높은 성능을 제공합니다.
  • 유효성 검사: Pydantic을 통해 요청 및 응답에 대한 엄격한 데이터 유효성 검사를 수행할 수 있습니다.
  • 즉각적인 문서화: Swagger UI와 ReDoc을 사용하여 자동으로 API 문서 생성이 가능합니다.
  • 비동기 프로그래밍 지원: 비동기/동기 프로그래밍을 모두 지원해 빠른 데이터를 처리할 수 있습니다.

2. FastAPI 설치하기

FastAPI 프레임워크를 설치하려면 pip를 통해 간단히 설치할 수 있습니다. 아래 명령어를 사용하여 FastAPI와 uvicorn(ASGI 서버)을 설치하세요: 

pip install fastapi uvicorn

3. 간단한 FastAPI 서버 만들기

FastAPI 애플리케이션을 만들기 위해 가장 먼저 해야 할 일은 FastAPI 클래스를 인스턴스화하는 것입니다. 아래의 코드는 “Hello, World!”를 반환하는 기본적인 FastAPI 서버 예제입니다. 

from fastapi import FastAPI

app = FastAPI()

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

3.1. 서버 실행하기

위 코드를 my_app.py라는 파일로 저장한 후, 다음과 같은 명령어로 서버를 실행합니다: 

uvicorn my_app:app --reload

이제 브라우저에서 http://127.0.0.1:8000를 열면 “Hello, World!” 메시지를 확인할 수 있습니다.

4. 경로와 HTTP 메서드

FastAPI에서는 다양한 HTTP 메서드를 사용하여 경로를 정의할 수 있습니다. 주로 사용되는 메서드는 다음과 같습니다:

  • GET: 데이터 조회
  • POST: 데이터 생성
  • PUT: 데이터 업데이트
  • DELETE: 데이터 삭제

4.1. GET 메서드 사용하기

GET 메서드를 사용하여 특정 경로에 대한 요청을 처리하는 예제를 살펴보겠습니다. 아래 코드는 /items/{item_id} 경로에 대한 GET 요청을 처리합니다. 

@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "query": q}

이 코드는 /items/1?q=example와 같은 요청을 처리하며, 응답은 다음과 같습니다: 

{"item_id": 1, "query": "example"}

4.2. POST 메서드 사용하기

POST 메서드는 서버에 새로운 데이터를 생성하는 데 사용됩니다. 다음 예제에서는 새 아이템을 추가하는 POST 요청을 처리합니다. 

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = None

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

클라이언트에서 application/json 포맷으로 데이터를 전송하면 FastAPI는 자동으로 데이터를 검증하고 파싱하여 item으로 전달합니다.

4.3. PUT 메서드 사용하기

PUT 메서드는 기존 데이터를 업데이트하는 데 사용됩니다. 아래 코드는 특정 아이템을 업데이트하는 예제입니다. 

@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    return {"item_id": item_id, "updated_item": item}

4.4. DELETE 메서드 사용하기

DELETE 메서드는 특정 아이템을 삭제하는 데 사용됩니다. 다음 코드는 특정 아이템을 삭제하는 경로를 정의합니다. 

@app.delete("/items/{item_id}")
async def delete_item(item_id: int):
    return {"message": f"Item with id {item_id} deleted"}

5. 경로 동작 함수 파라미터

FastAPI의 경로 동작 함수에서는 입력 파라미터를 다양하게 정의할 수 있습니다. FastAPI는 자동으로 요청 본문, 쿼리 매개변수, 경로 매개변수를 검증합니다.

  • 경로 매개변수: 경로의 경로 변수에 대응하는 파라미터입니다.
  • 쿼리 매개변수: URL의 쿼리 문자열에 따라 전달되는 파라미터입니다.
  • 본문 데이터: POST, PUT 요청과 함께 전송되는 데이터

5.1. 쿼리 파라미터 예제

@app.get("/items/")
async def read_items(q: str = None):
    return {"query": q}

5.2. 본문 파라미터 예제

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

6. 데이터 검증 및 설정 관리

FastAPI는 편리한 데이터 검증을 위해 Pydantic 모델을 활용합니다. 모델 클래스는 데이터 유효성 검사 및 설정 관리를 가능하게 합니다.

6.1. Pydantic 모델 정의하기

from pydantic import BaseModel

class User(BaseModel):
    name: str
    email: str
    age: int = None

6.2. 모델 사용 예제

@app.post("/users/")
async def create_user(user: User):
    return {"name": user.name, "email": user.email}

7. API 문서 자동 생성

FastAPI는 Swagger UI와 ReDoc을 지원하여 API 문서를 자동으로 생성합니다. Swagger UI는 http://127.0.0.1:8000/docs에서 조회할 수 있으며, ReDoc은 http://127.0.0.1:8000/redoc에서 조회할 수 있습니다. FastAPI는 IO-bound 작업을 처리하기 위해 asyncio를 사용하여 비동기적인 코드를 작성하는 것이 가능합니다.

8. FastAPI 프로젝트 구조

일반적인 FastAPI 프로젝트 구조는 다음과 같습니다: 

my_fastapi_app/
├── app/
│   ├── main.py
│   ├── models.py
│   ├── routers/
│   └── services/
└── requirements.txt

이 구조는 더 큰 규모의 FastAPI 애플리케이션에서 유용하며, 각 구성요소를 분리하여 유지보수를 용이하게 합니다.

9. 결론

FastAPI는 매우 강력하고 직관적인 웹 프레임워크로, 쉬운 API 개발과 데이터 검증을 가능하게 합니다. 본 강좌에서는 FastAPI의 기본적인 경로 동작 함수를 만드는 방법을 배웠습니다. FastAPI를 사용하면 빠르고 효율적인 백엔드 서버 개발이 가능하니, 실무에 적용해 보시기를 추천합니다.

재능있는 개발자가 되기를 응원하며, 더 많은 정보를 원하시면 FastAPI 공식 문서를 참조하시기 바랍니다.