🧭 Path Parameters

FastAPI에서 Path Parameter는 URL 경로 자체에 변수를 포함해 동적으로 다른 리소스를 처리하기 위한 핵심 기능이다.

---

📚 1. 어원으로 시작하기

개념은 언제나 이름부터 이해하면 가장 빠르다.

• Path : 경로
• Parameter : 매개변수

컴퓨터에서 파일을 찾을 때

/home/user/file.txt

처럼 “어디로 가야 하는지”를 경로(Path)로 표현하듯, 웹에서도 특정 리소스를 찾기 위해 URL 경로를 사용한다.

그리고 그 경로 안에 변할 수 있는 값을 넣는 것이 바로 Path Parameter다.

---

💡 비유로 이해하기

Path Parameter는 Python의 문자열 포맷팅과 거의 같은 개념이다.

name = "철수"
print(f"Hello {name}")

중괄호 안의 {name} 위치에 값이 들어가듯,

/users/{user_id}

여기서 {user_id} 자리에 실제 값이 들어온다.

---

🧪 2. 직접 체험하기

말로만 보면 감이 안 온다. 가장 단순한 예제부터 바로 실행해보자.

📄 예제 코드

from fastapi import FastAPI

app = FastAPI()

# {item_id} 가 Path Parameter다
@app.get("/items/{item_id}")
async def read_item(item_id):
    return {"item_id": item_id}

여기서 중요한 포인트는 딱 두 가지다.

• URL 경로에 {item_id}가 있다
• 함수 매개변수 이름도 item_id로 동일하다

---

🌐 실행 후 테스트

서버를 실행한 뒤 브라우저에서 아래 주소들에 접속해보자.

• /items/abc → {"item_id": "abc"}
• /items/123 → {"item_id": "123"}
• /items/jeff → {"item_id": "jeff"}

URL의 {item_id} 위치에 무엇을 넣든, 그 값이 그대로 함수의 매개변수로 전달된다.

👉 URL 경로 = 함수 인자 전달 통로

---

🧠 3. 이론과 핵심 내용 설명

3.1 타입 선언과 자동 변환

지금까지의 예제에서는 item_id가 문자열로 들어왔다.

하지만 FastAPI에서는 타입 힌트를 사용하면 이 값이 자동으로 변환된다.

📄 타입을 명시한 예제

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

이제 item_id는 문자열이 아니라 정수(int)로 처리된다.

• /items/3 → {"item_id": 3}

---

⚙️ 자동 변환(Parsing)의 장점

일반적인 웹 프레임워크라면 보통 이런 코드가 필요하다.

item_id = int(item_id)

하지만 FastAPI에서는

타입 힌트 한 줄로 "변환 + 검증"까지 모두 자동으로 처리된다.

---

3.2 자동 데이터 검증

타입을 선언하면, 잘못된 값이 들어왔을 때도 FastAPI가 알아서 처리한다.

아래 요청을 보내보자.

/items/foo

item_id는 int로 선언되어 있는데, 문자열 "foo"가 들어왔다.

이 경우 FastAPI는

• 함수를 실행하지 않고
• 자동으로 에러 응답을 반환한다

📌 반환되는 에러 예시

{
  "detail": [
    {
      "type": "int_parsing",
      "loc": ["path", "item_id"],
      "msg": "Input should be a valid integer",
      "input": "foo"
    }
  ]
}

---

3.3 자동 문서 생성

타입 힌트 하나만 추가했을 뿐인데, API 문서까지 자동으로 바뀐다.

• Swagger UI : /docs
• ReDoc : /redoc

문서 화면에서 확인할 수 있는 변화:

• Path Parameter 입력 칸 자동 생성
• item_id가 int 타입으로 표시
• 잘못된 값 입력 시 즉시 에러 확인 가능

---

3.4 Path Operation의 순서

Path Parameter를 쓰다 보면 “왜 이 엔드포인트가 안 타지?” 같은 상황을 한 번쯤 겪는다. 대부분의 경우 원인은 경로(Path) 매칭 순서다.

FastAPI는 경로를 위에서 아래로 차례대로 확인하면서 “가장 먼저 매칭되는” 라우트를 선택한다. 즉, 선언 순서가 곧 우선순위다.

---

✅ 핵심 규칙

• 고정 경로(static path) 는 동적 경로(dynamic path) 보다 항상 위에 있어야 한다.
• 동적 경로가 위에 있으면, 고정 경로 요청도 “변수로 받아버리는” 일이 생긴다.

---

✅ 올바른 예시 (고정 → 동적)

from fastapi import FastAPI

app = FastAPI()

# ✅ 고정 경로 먼저
@app.get("/users/me")
async def read_user_me():
    return {"user_id": "현재 로그인한 사용자"}

# ✅ 동적 경로는 나중에
@app.get("/users/{user_id}")
async def read_user(user_id: str):
    return {"user_id": user_id}

이 상태에서 요청을 보내면 의도대로 동작한다.

• /users/me → read_user_me() 실행
• /users/123 → read_user() 실행 (user_id="123")

---

❌ 잘못된 예시 (동적 → 고정)

from fastapi import FastAPI

app = FastAPI()

# ❌ 동적 경로가 먼저
@app.get("/users/{user_id}")
async def read_user(user_id: str):
    return {"user_id": user_id}

# ❌ 고정 경로가 나중
@app.get("/users/me")
async def read_user_me():
    return {"user_id": "현재 로그인한 사용자"}

이 경우 /users/me 요청이 들어오면…

• FastAPI는 위에서부터 매칭한다.
• /users/{user_id} 는 /users/me 와도 매칭된다.
• 그래서 user_id="me" 로 해석해버린다.

즉, 결과가 이렇게 된다:

• /users/me → read_user() 실행 (의도와 다름)

---

🔥 “순서” 문제가 특히 치명적인 이유

이건 단순히 “결과가 이상하다”에서 끝나지 않는다.

• 고정 경로에서만 처리해야 하는 로직(권한 체크, 특별 응답 등)이
• 동적 경로로 흡수되어버리면
• 보안/권한/비즈니스 로직이 틀어질 수 있다

그래서 실무에서는 이 순서 규칙을 거의 “규칙”이 아니라 “법”처럼 다룬다.

---

✅ 실전 팁: 고정 경로를 “먼저” 모아두기

라우터를 설계할 때 아래처럼 “고정”을 먼저 모아두면 실수가 확 줄어든다.

# ✅ users 관련 고정 라우트
@app.get("/users/me")
async def me(): ...

@app.get("/users/admin")
async def admin(): ...

# ✅ 마지막에 users 동적 라우트
@app.get("/users/{user_id}")
async def user(user_id: str): ...

---

추가 핵심: 같은 경로를 중복 정의하면?

결론부터 말하면 하면 안된다.
FastAPI에서 같은 메서드 + 같은 경로를 두 번 정의하면, 사실상 “뒤에 있는 건 의미가 없기 때문”.

from fastapi import FastAPI

app = FastAPI()

@app.get("/users")
async def read_users():
    return ["철수", "영희"]

@app.get("/users")
async def read_users2():
    return ["훈이", "짱구"]

이런 코드는 보는 사람을 헷갈리게 만들고 유지보수도 최악이다.
(환경/버전에 따라 라우트 등록 시점 처리 방식이 다를 수 있어 더 위험하다)

✅ 같은 경로를 다르게 처리하고 싶다면 보통 아래 중 하나로 해결한다.

• 메서드를 다르게: GET /users vs POST /users
• 경로를 다르게: /users vs /users/v2
• 쿼리 파라미터로 분기: /users?type=...
• 아예 라우팅 구조를 재설계

---

3.5 Enum으로 값 제한하기 (선택 가능한 값만 받기)

Path Parameter는 기본적으로 어떤 문자열이든 받을 수 있다.
그런데 실무에서는 “정해진 값만 허용하고 싶은” 경우가 많다.

예를 들어 모델 이름이 아래 3개 중 하나만 가능하다고 하자.

• alexnet
• resnet
• lenet

이럴 때 Python의 Enum을 쓰면:

• 허용된 값만 받게 할 수 있고
• 잘못된 값이 들어오면 자동으로 422 에러가 나며
• 문서(/docs)에서 드롭다운처럼 선택 가능한 형태로 보인다

---

✅ Enum 예제

from enum import Enum
from fastapi import FastAPI

class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"

app = FastAPI()

@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
    if model_name is ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}

    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN all the images"}

    return {"model_name": model_name, "message": "Have some residuals"}

✅ Enum을 쓰면 얻는 것

• 유효한 값만 허용 (그 외 값은 자동으로 에러)
• /docs에서 선택 가능한 값 목록이 UI로 표시됨
• 코드에서 if model_name is ModelName.alexnet 처럼 안전하게 비교 가능

📌 언제 쓰면 좋을까?

• 상태 값: pending / running / done
• 카테고리: news / blog / notice
• 권한: admin / user / guest
• 타입: image / video / text

“범위가 정해진 값”이면 Enum을 사용하자

---

3.6 슬래시(/)를 포함하는 Path Parameter

일반적으로 Path Parameter는 슬래시(/)를 경계로 끊긴다.
즉, 기본 형태에서는 아래처럼 “한 덩어리”만 받는다.

• /files/a/b/c.txt 에서 {file_path} 는 보통 a까지만 받는다

그런데 파일 경로처럼 슬래시 포함 전체 경로를 통째로 받고 싶은 경우가 있다.
이때 FastAPI는 :path 컨버터를 제공한다.

✅ :path 예제

from fastapi import FastAPI

app = FastAPI()

@app.get("/files/{file_path:path}")
async def read_file(file_path: str):
    return {"file_path": file_path}

이제 아래 요청이 가능해진다.

• /files/home/jay/myfile.txt
  → {"file_path": "home/jay/myfile.txt"}

⚠️ 슬래시로 시작하는 경로는?

만약 실제로 /home/jay/myfile.txt 처럼 “슬래시로 시작하는 경로”를 그대로 넘기고 싶다면 URL은 이렇게 된다:

• /files//home/jay/myfile.txt

중간에 슬래시가 하나 더 들어가는 이유는:

• /files/ 뒤에 Path Parameter 값이 들어가는데
• 그 값 자체가 / 로 시작하니까
• 결과적으로 // 처럼 보이게 되는 것

---

✅ 자주 쓰이는 케이스

• 파일 다운로드/조회 API
• S3 key 처럼 “경로 형태 문자열”을 그대로 받는 API
• CDN/스토리지 프록시 라우트

---

🔚 마무리

Path Parameter는 단순히 “URL에서 값 받기”가 아니다.
FastAPI에서는

• 타입 힌트로 자동 변환
• 타입 힌트로 자동 검증
• 문서에서 자동 UI 생성
• Enum으로 값 제한
• :path로 경로 통째로 받기

까지 한 번에 이어진다.

즉, Path Parameter를 잘 쓰면
API 설계가 더 안전해지고 문서까지 깔끔해진다.