[FastAPI 2일차] 📘 FastAPI 라우팅과 응답 구조 마스터 가이드 2/2 (250528)

📘 FastAPI 라우팅과 응답 구조 마스터 가이드

---

이 글은 FastAPI를 활용한 실전 API 개발에서 라우팅 구조화, 정규표현식 검증, 요청 및 응답 처리, 파일 업로드/다운로드까지의 전 과정을 정리한 내용입니다. 특히 APIRouter와 Pydantic을 중심으로 코드 설계와 Swagger 문서화 품질을 향상시키는 방법에 대해 다룹니다.

1. 📱 정규 표현식과 패턴 검증

• 휴대폰 번호 형식(010-XXXX-XXXX)을 정규표현식으로 검증.
• \d{4} 표현으로 0~9 숫자 4자리 제약을 설정.
• Query와 Path 파라미터에서 조건부 유효성 검사 가능.

💡 실전 팁: 숫자 자리수 외에도 startswith, min_length, max_length 등 조건 조합 가능.

2. 🛠️ FastAPI 요청 처리 방식

• Pydantic 모델 없이 단일 값만 받을 경우 Body(embed=True)로 처리 가능.
• 쿼리/패스/바디 각각의 데이터 수신 방식 명확히 구분해야 함.
• Request Body로 받는 값은 Swagger에서 JSON 형태로 입력됨.

✅ embed=True 사용 시 JSON 키 이름이 모델 속성과 일치해야 함.

3. 📁 FastAPI 프로젝트 구조 관리하기

3.1 프로젝트 분리 필요성

• main.py에 모든 API 작성 시 확장성 부족.
• Django의 앱 구조처럼 논리적 단위로 나누는 것이 유지보수에 효과적.

3.2 폴더 및 파일 구조화

• 예: user/routers.py, item/routers.py 등으로 분할.
• 각 라우터 모듈에서는 APIRouter() 객체를 생성하여 API 등록.

from fastapi import APIRouter
router = APIRouter()

@router.get("/items")
def get_items():
    return [{"name": "item1"}]

3.3 main.py 연결 구조

• 각각의 router를 main.py에서 include_router로 등록.

from item.routers import router as item_router
from user.routers import router as user_router

app.include_router(item_router, prefix="/api/v1/items", tags=["items"])
app.include_router(user_router, prefix="/api/v1/users", tags=["users"])

4. 🖼️ FastAPI에서 이미지와 파일 처리하기

4.1 이미지 업로드

• UploadFile을 이용한 multipart/form-data 업로드 처리 가능

from fastapi import UploadFile, File

@router.post("/upload")
def upload_image(image: UploadFile = File(...)):
    return {"filename": image.filename, "content_type": image.content_type}

4.2 HTML 및 Plain 텍스트 응답

• HTML: HTMLResponse 사용
• Plain 텍스트: Response(media_type="text/plain") 사용

4.3 파일 다운로드 처리

• FileResponse로 이미지 등 파일 반환 가능
• Content-Disposition 헤더로 자동 다운로드 가능

from fastapi.responses import FileResponse

@app.get("/download")
def download():
    return FileResponse("images/pizza.jpg", headers={
        "Content-Disposition": "attachment; filename=pepperoni.jpg"
    })

5. ✅ 응답 타입 명시 및 검증

5.1 Pydantic 모델로 응답 구조 지정

class NowResponse(BaseModel):
    now: datetime

@app.get("/now", response_model=NowResponse)
def get_now():
    return {"now": datetime.now()}

• 응답 데이터가 문서에 미리 반영됨 → Swagger UI 가독성 향상
• 잘못된 타입 반환 시 자동 검증

5.2 JSONResponse 활용

• 응답 데이터 직접 변환 필요 시 사용

from fastapi.responses import JSONResponse

@app.get("/custom")
def custom():
    return JSONResponse(content={"message": "Hello"})

5.3 파일 다운로드 시 사용자 경험 개선

• 브라우저에서 파일 다운로드가 자동으로 되도록 하려면 HTTP 헤더 Content-Disposition에 attachment 값을 설정해야 함.
• 파일명 변경도 가능하여 UX 측면에서 유리함.

return FileResponse("path/to/image.jpg", headers={
    "Content-Disposition": "attachment; filename=custom_name.jpg"
})

💡 주의: 다운로드 기능은 FastAPI의 기능이라기보다 브라우저의 처리 방식이며, 서버는 응답 헤더 설정만 제공.

5.4 응답 데이터에 대한 타입 보장 및 오류 방지

• BaseModel을 활용하면 응답 데이터의 타입을 명확히 선언할 수 있음.
• 반환 값이 잘못된 타입일 경우 FastAPI가 에러를 발생시켜 디버깅에 용이.
• 클라이언트와의 데이터 타입 약속을 명시적으로 유지 가능.

💡 예: datetime을 반환해야 할 API에서 문자열이나 숫자가 반환되면 검증 에러 발생.

5.5 타입 힌트로 API 문서 자동화 극대화

• response_model=MyModel 선언은 Swagger 문서에 자동으로 응답 예시를 생성.
• 타입 힌트를 통해 API의 입력/출력 구조를 명확히 표현할 수 있어 유지보수에 유리.
• 복잡한 응답 구조도 명확하게 시각화되어 API 소비자 입장에서 큰 도움 제공.

@app.get("/users", response_model=List[User])
def list_users():
    return [User(id=1, name="Alice"), User(id=2, name="Bob")]

📌 응답 모델은 단순 리스트 외에도 중첩된 구조, Optional, Union 타입 등도 표현 가능.

✅ 요약 정리

• APIRouter로 API 라우팅을 논리적 단위로 구조화 가능.
• Prefix, tags 설정으로 Swagger 문서 품질 향상.
• UploadFile, FileResponse로 파일 업로드/다운로드 처리.
• BaseModel로 요청/응답 데이터 유효성 검사 가능.
• HTML/PlainText/JSON 다양한 형식의 응답 가능.
• response_model + 타입 힌트로 API 문서 자동화 품질 향상.

💡 FastAPI는 개발자의 설계 의도를 Swagger에 그대로 반영해주기 때문에, 구조적으로 깔끔하게 설계해두는 것이 문서화 품질에도 직결됩니다.