라우트(경로 작업, path operation)를 어떻게 정의합니까?

Question

Accepted Answer

FastAPI에서 **경로 작업(path operation)**은 라우트입니다. 즉, HTTP 메서드 데코레이터(`@app.get`, `@app.post` 등)로 장식된 함수로, 특정 경로에 대한 요청을 처리합니다. 함수의 반환값은 자동으로 JSON으로 직렬화됩니다.

## 각 HTTP 메서드에 대한 라우트 정의

```python
from fastapi import FastAPI
app = FastAPI()

@app.get("/items")                # GET /items
def list_items():
    return [{"id": 1}, {"id": 2}]  # dict/list → 자동으로 JSON 직렬화됨

@app.get("/items/{item_id}")      # GET /items/5 — 경로 매개변수
def get_item(item_id: int):        # 타입 힌트가 "5" → int로 변환(및 검증)합니다
    return {"id": item_id}

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

@app.put("/items/{item_id}")      # PUT, PATCH, DELETE도 같은 방식으로 동작합니다
@app.delete("/items/{item_id}")
def delete_item(item_id: int):
    return {"deleted": item_id}
```

각 데코레이터는 HTTP 메서드 + 경로를 핸들러에 매핑합니다. 함수 이름은 자유롭게 지을 수 있으며, 라우트를 정의하는 것은 데코레이터입니다. 반환된 dict/list/Pydantic 모델은 자동으로 JSON으로 직렬화되므로 수동 `json.dumps`가 필요 없습니다.

## 겹치는 경로에서는 순서가 중요합니다

```python
@app.get("/users/me")            # ✅ 구체적인 라우트를 먼저
def read_me(): ...
@app.get("/users/{user_id}")     # 동적 라우트는 나중에 — 아니면 "me"가 {user_id}에 매칭됨
def read_user(user_id: int): ...
```

FastAPI는 선언 순서대로 라우트를 매칭하므로, 정적 경로를 동적 경로보다 먼저 배치하세요.

## 작업 메타데이터 (문서를 구동함)

```python
@app.get("/items", tags=["items"], summary="List items", status_code=200)
def list_items(): ...
```

데코레이터 매개변수(`tags`, `summary`, `status_code`, `response_model`)는 동작을 구성하고 자동 생성되는 문서를 풍부하게 만듭니다.

## 왜 중요한가

경로 작업은 모든 FastAPI 애플리케이션의 기초입니다. API의 엔드포인트와 요청 처리 방식을 정의하기 때문입니다.

HTTP 메서드별 데코레이터 패턴, 반환값이 자동으로 JSON으로 직렬화된다는 점(보일러플레이트 없음), 매개변수의 타입 힌트가 변환과 validation을 구동한다는 점, 그리고 겹치는 경로에서 라우트 순서가 중요하다는 점을 이해하는 것은 어떤 엔드포인트를 구축하든 필수적인 일상 지식입니다.

또한 데코레이터 메타데이터는 FastAPI의 자동 문서를 구동하여, 라우트를 문서와 직접 연결합니다.

이것은 FastAPI에서 가장 먼저, 가장 근본적으로 익혀야 할 내용입니다.