🚀 FastAPI 백엔드 개발 기초 가이드

Hyeonio_o·2025년 6월 14일

FastAPI httpx import

BackEnd

목록 보기

2/9

👉 미니 프로젝트로 ChatGPT API를 사용한 "모두의 레시피"를 만들면서 어려웠던 점을 요약해보았습니다.

📚 목차

필수 라이브러리 Import 이해하기
FastAPI 애플리케이션 기본 설정
HTTP 클라이언트 라이브러리 (requests vs httpx)
데이터 검증 및 보안
마무리

1. 필수 라이브러리 Import 이해하기

📦 모듈별 상세 설명

FastAPI 핵심 모듈들

모듈	역할	실무 활용도
`FastAPI`	메인 애플리케이션 클래스	⭐⭐⭐⭐⭐
`Request`	HTTP 요청 객체 처리	⭐⭐⭐⭐
`Form`	HTML 폼 데이터 처리	⭐⭐⭐
`HTTPException`	HTTP 에러 처리	⭐⭐⭐⭐⭐
`Cookie`	쿠키 데이터 처리	⭐⭐⭐
`Depends`	의존성 주입	⭐⭐⭐⭐⭐

응답 관련 모듈들

🌐 HTMLResponse: HTML 형태 응답 (웹페이지 반환)
🔄 RedirectResponse: 페이지 리다이렉션 (로그인 후 메인으로 이동)
📊 JSONResponse: JSON 형태 응답 (API 데이터 반환)

템플릿과 정적 파일

🎨 Jinja2Templates: HTML 템플릿 엔진 (Django 템플릿과 유사)
📁 StaticFiles: CSS, JS, 이미지 등 정적 파일 서빙

CORS 미들웨어

🔐 CORSMiddleware: 다른 도메인 간 통신 허용 설정

2. FastAPI 애플리케이션 기본 설정

🛠️ CORS 미들웨어 설정

# CORS 미들웨어 설정
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],           # 모든 도메인 허용
    allow_credentials=True,        # 인증 정보 포함 요청 허용
    allow_methods=["*"],          # 모든 HTTP 메서드 허용
    allow_headers=["*"],          # 모든 헤더 허용
)

🔍 CORS란?

Cross-Origin Resource Sharing의 줄임말로, 웹 보안 정책입니다.

설정	설명	개발환경	운영환경
`allow_origins`	허용할 도메인	`["*"]`	`["https://myapp.com"]`
`allow_credentials`	인증정보 포함 요청	`True`	`True`
`allow_methods`	허용 HTTP 메서드	`["*"]`	`["GET", "POST"]`
`allow_headers`	허용 헤더	`["*"]`	필요한 헤더만

⚠️ 보안 주의사항: 실제 배포 시에는 allow_origins를 특정 도메인으로 제한하세요!

🎯 정적 파일 서빙 설정

# 정적 파일 사용 설정
app.mount("/static", StaticFiles(directory="static"), name="static")

🎨 HTML 템플릿 엔진 설정

# HTML 템플릿 경로 설정
templates = Jinja2Templates(directory="templates")

🔧 템플릿 사용법

@app.get("/")
async def read_root(request: Request):
    return templates.TemplateResponse("index.html", {
        "request": request,           # 필수 파라미터
        "title": "홈페이지",          # 템플릿 변수
        "user": "김개발자"           # 템플릿 변수
    })

templates/index.html:

<!DOCTYPE html>
<html>
<head>
    <title>{{ title }}</title>
</head>
<body>
    <h1>안녕하세요, {{ user }}님!</h1>
</body>
</html>

3. HTTP 클라이언트 라이브러리 (requests vs httpx)

🔄 requests vs httpx 완벽 비교

특징	requests	httpx	실무 추천도
동기 지원	✅ 완벽 지원	✅ 완벽 지원	⭐⭐⭐⭐⭐
비동기 지원	❌ 미지원	✅ 완벽 지원	⭐⭐⭐⭐⭐
HTTP/2 지원	❌ 미지원	✅ 완벽 지원	⭐⭐⭐⭐
현대적인 API	⚠️ 오래된 설계	✅ 최신 설계	⭐⭐⭐⭐⭐
성능	보통	우수	⭐⭐⭐⭐
FastAPI 호환성	제한적	완벽	⭐⭐⭐⭐⭐

📝 동기 HTTP 클라이언트 사용법

requests 사용 예시

import requests

# 기본 GET 요청
def get_user_info_sync(user_id: int):
    """동기 방식으로 사용자 정보 조회"""
    response = requests.get(f"https://api.example.com/users/{user_id}")
    
    if response.status_code == 200:
        return response.json()
    else:
        return {"error": f"사용자 조회 실패: {response.status_code}"}

# POST 요청 (JSON 데이터)
def create_user_sync(user_data: dict):
    """동기 방식으로 사용자 생성"""
    response = requests.post(
        "https://api.example.com/users",
        json=user_data,
        headers={"Content-Type": "application/json"}
    )
    return response.json()

httpx 동기 사용 예시

import httpx

# httpx로 동기 요청 (requests와 거의 동일한 API)
def get_user_info_sync_httpx(user_id: int):
    """httpx로 동기 방식 사용자 정보 조회"""
    with httpx.Client() as client:
        response = client.get(f"https://api.example.com/users/{user_id}")
        
        if response.status_code == 200:
            return response.json()
        else:
            return {"error": f"사용자 조회 실패: {response.status_code}"}

⚡ 비동기 HTTP 클라이언트 사용법 (httpx만 지원)

import httpx
import asyncio

# 비동기 GET 요청
async def get_user_info_async(user_id: int):
    """비동기 방식으로 사용자 정보 조회"""
    async with httpx.AsyncClient() as client:
        response = await client.get(f"https://api.example.com/users/{user_id}")
        
        if response.status_code == 200:
            return response.json()
        else:
            return {"error": f"사용자 조회 실패: {response.status_code}"}

# 비동기 POST 요청
async def create_user_async(user_data: dict):
    """비동기 방식으로 사용자 생성"""
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://api.example.com/users",
            json=user_data,
            headers={"Content-Type": "application/json"}
        )
        return response.json()

# 여러 요청 동시 처리
async def get_multiple_users(user_ids: list):
    """여러 사용자 정보를 동시에 조회"""
    async with httpx.AsyncClient() as client:
        tasks = [
            client.get(f"https://api.example.com/users/{user_id}") 
            for user_id in user_ids
        ]
        
        # 모든 요청을 동시에 실행
        responses = await asyncio.gather(*tasks)
        
        return [
            response.json() if response.status_code == 200 else None
            for response in responses
        ]

🚀 FastAPI에서 HTTP 클라이언트 활용

외부 API 호출하는 엔드포인트 예시

from fastapi import FastAPI
import httpx

app = FastAPI()

# 동기 방식 (간단한 작업용)
@app.get("/user/{user_id}")
def get_external_user(user_id: int):
    """외부 API에서 사용자 정보 조회 (동기)"""
    with httpx.Client() as client:
        response = client.get(f"https://jsonplaceholder.typicode.com/users/{user_id}")
        
        if response.status_code == 200:
            return {"success": True, "data": response.json()}
        else:
            return {"success": False, "error": "사용자를 찾을 수 없습니다"}

# 비동기 방식 (권장)
@app.get("/user-async/{user_id}")
async def get_external_user_async(user_id: int):
    """외부 API에서 사용자 정보 조회 (비동기)"""
    async with httpx.AsyncClient() as client:
        response = await client.get(f"https://jsonplaceholder.typicode.com/users/{user_id}")
        
        if response.status_code == 200:
            return {"success": True, "data": response.json()}
        else:
            return {"success": False, "error": "사용자를 찾을 수 없습니다"}

# 복잡한 외부 API 연동 예시
@app.get("/weather/{city}")
async def get_weather(city: str):
    """날씨 API 연동 예시"""
    async with httpx.AsyncClient() as client:
        # 실제로는 API 키가 필요합니다
        response = await client.get(
            f"https://api.openweathermap.org/data/2.5/weather",
            params={
                "q": city,
                "appid": "YOUR_API_KEY",
                "units": "metric",
                "lang": "kr"
            }
        )
        
        if response.status_code == 200:
            weather_data = response.json()
            return {
                "city": weather_data["name"],
                "temperature": weather_data["main"]["temp"],
                "description": weather_data["weather"][0]["description"]
            }
        else:
            return {"error": "날씨 정보를 가져올 수 없습니다"}

🎯 실무에서의 선택 기준

requests를 사용해야 하는 경우

✅ 간단한 스크립트나 배치 작업
✅ 동기 처리만 필요한 경우
✅ 기존 레거시 코드와의 호환성이 중요한 경우

httpx를 사용해야 하는 경우 (권장)

✅ FastAPI 애플리케이션 개발
✅ 비동기 처리가 필요한 경우
✅ HTTP/2 지원이 필요한 경우
✅ 최신 기능과 성능이 중요한 경우

4. 데이터 검증 및 보안

🧹 텍스트 정리 함수

def clean_text(text: str) -> str:
    """텍스트에서 HTML 태그 제거 및 특수문자 처리"""
    if not text:
        return ""
    
    # 1️⃣ HTML 엔티티 디코딩
    text = html.unescape(text)
    
    # 2️⃣ HTML 태그 제거
    text = re.sub(r'<[^>]+>', '', text)
    
    # 3️⃣ 연속된 공백을 하나로 변경
    text = re.sub(r'\s+', ' ', text)
    
    # 4️⃣ 앞뒤 공백 제거
    text = text.strip()
    
    return text

🛡️ XSS 공격 방지 과정

단계	처리 내용	예시
HTML 엔티티 디코딩	`<` → `<`	`<script>` → `<script>`
HTML 태그 제거	모든 태그 삭제	`<script>alert()</script>` → `alert()`
공백 정규화	연속 공백 통합	`안녕 하세요` → `안녕 하세요`
공백 제거	앞뒤 불필요한 공백 제거	`텍스트` → `텍스트`

✅ 입력 검증 함수

def validate_recipe_input(title: str, content: str) -> None:
    """레시피 입력 데이터 검증"""
    
    # 🧹 텍스트 정리
    title = clean_text(title) if title else ""
    content = clean_text(content) if content else ""
    
    # 📝 필수값 검증
    if not title:
        raise HTTPException(
            status_code=400,
            detail="❌ 레시피 제목을 입력해주세요"
        )
    
    if not content:
        raise HTTPException(
            status_code=400,
            detail="❌ 레시피 내용을 입력해주세요"
        )
    
    # 📏 길이 제한 검증
    if len(title) > 200:
        raise HTTPException(
            status_code=400,
            detail="❌ 제목은 200자 이내로 입력해주세요"
        )
    
    if len(content) > 10000:
        raise HTTPException(
            status_code=400,
            detail="❌ 내용은 10,000자 이내로 입력해주세요"
        )

📊 검증 규칙 요약

항목	규칙	에러 코드	메시지
제목 필수	빈 값 불허	400	"레시피 제목을 입력해주세요"
내용 필수	빈 값 불허	400	"레시피 내용을 입력해주세요"
제목 길이	200자 이내	400	"제목은 200자 이내로 입력해주세요"
내용 길이	10,000자 이내	400	"내용은 10,000자 이내로 입력해주세요"

🎯 마무리

💡 핵심 개념 요약

개념	설명	실무 중요도
체계적인 Import	모듈을 용도별로 정리하여 가독성 향상	⭐⭐⭐
CORS 설정	프론트엔드-백엔드 간 안전한 통신	⭐⭐⭐⭐⭐
정적 파일 서빙	CSS, JS 등 정적 자원 효율적 제공	⭐⭐⭐⭐
템플릿 엔진	동적 HTML 생성으로 사용자 경험 향상	⭐⭐⭐
HTTP 클라이언트	외부 API 연동 (httpx 권장)	⭐⭐⭐⭐⭐
의존성 주입	코드 재사용성과 테스트 용이성 확보	⭐⭐⭐⭐⭐
데이터 검증	XSS 방지와 데이터 무결성 보장	⭐⭐⭐⭐⭐

🛠️ 실무 프로젝트 아이디어

날씨 대시보드
- OpenWeatherMap API 연동
- 여러 도시 날씨 동시 조회
- 실시간 업데이트 기능
소셜 미디어 집계기
- 여러 SNS API 동시 호출
- 데이터 통합 및 분석
- 캐싱 전략 구현
마이크로서비스 게이트웨이
- 여러 내부 서비스 API 라우팅
- 로드 밸런싱 및 헬스체크
- API 응답 시간 모니터링

Hyeonio_o

이전 포스트

🧠 Python 데이터 구조 알아보기: 리스트, 튜플, 딕셔너리, 집합

다음 포스트

🚀 FastAPI 백엔드 개발 기초 가이드

BackEnd

📚 목차

1. 필수 라이브러리 Import 이해하기

📦 모듈별 상세 설명

FastAPI 핵심 모듈들

응답 관련 모듈들

템플릿과 정적 파일

CORS 미들웨어

2. FastAPI 애플리케이션 기본 설정

🛠️ CORS 미들웨어 설정

🔍 CORS란?

🎯 정적 파일 서빙 설정

🎨 HTML 템플릿 엔진 설정

🔧 템플릿 사용법

3. HTTP 클라이언트 라이브러리 (requests vs httpx)

🔄 requests vs httpx 완벽 비교

📝 동기 HTTP 클라이언트 사용법

requests 사용 예시

httpx 동기 사용 예시

⚡ 비동기 HTTP 클라이언트 사용법 (httpx만 지원)

🚀 FastAPI에서 HTTP 클라이언트 활용

외부 API 호출하는 엔드포인트 예시

🎯 실무에서의 선택 기준

requests를 사용해야 하는 경우

httpx를 사용해야 하는 경우 (권장)

4. 데이터 검증 및 보안

🧹 텍스트 정리 함수

🛡️ XSS 공격 방지 과정

✅ 입력 검증 함수

📊 검증 규칙 요약

🎯 마무리

💡 핵심 개념 요약

🛠️ 실무 프로젝트 아이디어

🧠 Python 데이터 구조 알아보기: 리스트, 튜플, 딕셔너리, 집합

🌳 Git Branch 완벽 가이드: 협업의 필수 도구 마스터하기

0개의 댓글