FastAPI 기반 fds_boilerplate

---

https://github.com/ch0992/fds_boilerplate/

📌 1. fds_boilerplate 설계 배경과 구조 목표

✅ 왜 이 프로젝트를 만들었을까?

FastAPI는 경량 웹 프레임워크임에도 불구하고 다음과 같은 장점이 있어, 최근 많은 프로젝트에서 활용되고 있습니다:

• Python 기반의 간단한 문법
• 비동기 처리에 강하고
• 자동으로 Swagger 문서화가 제공됨

하지만 팀 단위 개발을 하다 보면 다음과 같은 불편이 생깁니다:

• 모든 API가 한 곳에 얽혀 있어 도메인 분리 어려움
• 프로젝트를 온보딩하려면 구조부터 파악해야 하는 비용이 큼
• 실제 운영에 맞는 로깅, 인증, 디버깅 환경이 없음

따라서 다음과 같은 기준을 갖고 템플릿을 구성하게 되었습니다.

🧩 설계 목표 (개발/운영 관점)

영역	목표
개발 구조	공통 모듈과 도메인 분리를 통해 모놀리식처럼 개발, 마이크로서비스처럼 배포
실행 환경	.env 기반 환경 구성으로 개발/운영 분리, VSCode 기반 디버깅 친화적 구성
팀 확장성	초보자도 빠르게 이해하고 복붙해서 쓸 수 있도록 표준 흐름 고정

---

🧭 전체 시스템 구조 미리 보기

사용자 요청
    ↓
API Gateway (인증/라우팅)
    ↓
도메인 서비스 호출 (file, data 등)
    ↓
Kafka 전송 / S3 업로드 
    ↓
응답 반환 + 로그 전송

• 하나의 프로젝트 안에서 여러 도메인을 독립 실행 가능하게 만들었고
• 각 도메인은 FastAPI 앱으로 구성되어 있어 단독 테스트와 개발이 가능합니다.

---

📌 2. 프로젝트 디렉토리 구조와 서비스 분리 전략

📁 전체 디렉토리 구조 개요

📦 fds_boilerplate
├── app
│   ├── common
│   └── domains
│       ├── gateway
│       ├── file
│       ├── data
│       └── log
├── infra
├── scripts
├── tests
├── .env
├── docker-compose.yaml
└── requirements.txt

✅ 핵심 구성 요소 설명

디렉토리	설명
app/common	설정, 예외 처리, 인증, 공통 모델 등 모든 도메인에서 공통 사용하는 코드들
app/domains/{도메인}	gateway, file, data, log 등 도메인별 독립 서비스로 분리된 FastAPI 애플리케이션
infra	Helm chart, Kubernetes manifest 등 실제 배포 인프라 구성 관리 영역
scripts	개발 및 실행을 돕는 로컬 실행 스크립트들 포함 (예: run_all_fastapi_local.sh)
tests	테스트 코드 모음 (기본 구조만 제공되어 있으며 도메인별로 작성 필요)
.env	환경별 실행 변수를 정의하는 파일로, 서비스 간 통일된 포트 및 설정 공유

---

📦 도메인 구성의 철학: "모놀리식처럼 개발, MSA처럼 배포"

• 하나의 코드베이스 안에 여러 FastAPI 앱을 두되,
• 실제 실행은 gateway, file, data, log가 각기 다른 포트로 분리 실행되도록 설계했습니다.

예시: 도메인별 포트 구성

gateway → 8000
file    → 8001
data    → 8002
log     → 8003

각 도메인은 main.py를 가지고 있으며,
VSCode에서 launch.json을 통해 단독 실행하거나 모든 앱을 복합 실행할 수 있습니다.

---

📌 3. .env 기반 로컬 실행 환경 구성 및 전체 서비스 기동

✅ 목표

• .env 파일을 통해 실행 설정을 통일
• 개발자가 단일 명령어로 전체 FastAPI 앱을 실행할 수 있도록 구성
• 포트 충돌 방지, 환경별 설정 분리 등을 기본 제공

---

📄 .env 파일 구조

# 공통 실행 변수
ENV=local

# 각 서비스 포트
GATEWAY_PORT=8000
FILE_PORT=8001
DATA_PORT=8002
LOG_PORT=8003

# Kafka, MinIO 등 외부 의존 구성
KAFKA_HOST=localhost:9092
MINIO_ENDPOINT=http://localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin

• 모든 서비스는 이 .env 파일을 기준으로 환경을 가져가도록 되어 있습니다.
• app/common/config.py 파일이 이를 pydantic.BaseSettings 기반으로 파싱합니다.

---

⚙️ config.py 예시 (공통 환경 불러오기)

from pydantic import BaseSettings

class Settings(BaseSettings):
    env: str = "local"
    gateway_port: int = 8000
    file_port: int = 8001
    data_port: int = 8002
    log_port: int = 8003

    kafka_host: str = "localhost:9092"
    minio_endpoint: str = "http://localhost:9000"
    minio_access_key: str = "minioadmin"
    minio_secret_key: str = "minioadmin"

    class Config:
        env_file = ".env"

settings = Settings()

모든 도메인에서 from app.common.config import settings 만 하면 동일한 환경을 공유합니다.

---

▶️ 전체 FastAPI 앱 실행 방법

/scripts 디렉토리 내 run_all_fastapi_local.sh 실행 스크립트를 사용합니다.

예시

$ cd scripts
$ sh run_all_fastapi_local.sh

• 각 서비스가 백그라운드로 실행되며 scripts/*.log 파일로 로그가 저장됩니다.
• 실행이 완료되면 아래와 같이 확인 가능합니다:

$ lsof -i :8000
$ lsof -i :8001
...

---

🧪 단일 서비스만 실행하고 싶다면?

각 도메인에는 main.py가 존재하므로 아래처럼 실행 가능합니다:

$ uvicorn app.domains.file.main:app --reload --port 8001

혹은 launch.json에 설정된 환경을 통해 VSCode 디버깅도 가능합니다 (5편에서 상세 설명).

---

📌 정리

• .env 기반 환경 구성을 통해 서비스 간 통일된 설정 제공
• FastAPI 앱을 한 번에 실행하거나 개별 실행 가능
• 각 도메인은 고유 포트를 사용하여 독립 동작
• config.py 기반으로 모든 서비스에서 설정값 공유 가능

📌 4. Swagger UI 구성과 공통 FastAPI 인스턴스 적용 방법

✅ 목표

• 모든 도메인 API 스펙을 gateway에서 통합하여 Swagger 문서로 자동 제공
• 각 도메인은 자체적으로 FastAPI 인스턴스를 구성하지만, Swagger 문서는 gateway에서만 접근 가능

---

🧱 실제 FastAPI 앱 구성 방식

각 도메인(file, data, log 등)은 도메인별 main.py에서 FastAPI 인스턴스를 직접 생성하고,
라우터·미들웨어·트레이싱·예외처리 등을 통합 적용합니다.

# 예시: app/domains/file/main.py
from fastapi import FastAPI
from dotenv import load_dotenv
from app.domains.file.api.routes import router as file_router
from app.common.config import settings
from app.domains.log.services.common.tracing import init_tracer
from app.domains.log.services.common.sentry import init_sentry
from app.domains.log.services.common.middleware import install_exception_handlers, TraceLoggingMiddleware
from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
import os, logging

# 로그 및 .env 설정 생략

app = FastAPI(
    title="File Service",
    description="File upload/download microservice",
    docs_url=None,  # 도메인 서비스에서는 Swagger UI 비활성화
    redoc_url=None,
    openapi_url=None
)

# Tracing, Sentry, 미들웨어, 라우터 등록 생략

• 각 도메인 서비스는 docs_url, redoc_url, openapi_url을 None으로 설정하여 자체 Swagger UI를 비활성화합니다.

---

🏛️ Gateway에서 Swagger 문서 통합 제공

gateway 서비스(app/domains/gateway/main.py)에서 모든 도메인의 라우터를 통합 등록하고,
Swagger UI(/gateway/docs)를 단일 엔드포인트로 제공합니다.

gateway의 FastAPI 인스턴스는 Swagger UI를 활성화하고,
각 도메인별 라우터를 include_router()로 통합합니다.

# 예시: app/domains/gateway/main.py
from fastapi import FastAPI
from app.domains.file.api.routes import router as file_router
from app.domains.data.api.routes import router as data_router
# ... 기타 도메인 라우터 import

app = FastAPI(
    title="FDS API Gateway",
    description="All domain APIs integrated",
    docs_url="/gateway/docs",
    redoc_url="/gateway/redoc",
    openapi_url="/gateway/openapi.json"
)

# 각 도메인 라우터를 prefix와 함께 등록
app.include_router(file_router, prefix="/file")
app.include_router(data_router, prefix="/data")
# ... 기타 도메인 라우터 등록

---

🔗 API 문서 확인 방법

오직 gateway 서비스에서 /gateway/docs 또는 /gateway/redoc 경로를 통해 모든 도메인 API 문서를 통합 확인할 수 있습니다.

예시:

http://localhost:8000/gateway/docs #Swagger
http://localhost:8000/gateway/redoc #API 문서

---

✅ 구성 전략 요약

• 각 도메인 서비스는 자체 FastAPI 인스턴스를 직접 정의하되, Swagger UI는 비활성화
• gateway 서비스에서만 Swagger 문서를 통합 제공
• 미들웨어, 트레이싱, 예외처리, 라우터 등록은 각 도메인 진입점에서 일괄 처리
• 도메인별 라우터는 gateway에 통합 등록

---

📌 정리

• 도메인별 서비스는 독립적으로 동작하지만, API 문서(Swagger)는 gateway에서만 통합 제공
• gateway의 /gateway/docs에서 전체 API 스펙을 한 번에 확인
• 각 도메인 서비스는 자체적으로 미들웨어, 로깅, 트레이싱, 예외처리 등을 관리

📌 5. 라우팅과 인증 흐름: Gateway 중심 설계 원칙과 인증 모듈 연계

✅ 목표

• Gateway에서 모든 외부 API 요청을 수신하고 인증 후 각 도메인 서비스로 라우팅
• 인증 로직은 공통 모듈로 분리하여 재사용 가능하게 설계

---

🧭 전체 흐름 요약

클라이언트 요청
   ↓
Gateway (JWT 검증 수행)
   ↓
라우팅된 도메인 서비스 (예: file)
   ↓
서비스 로직 수행 후 응답 반환

• 인증은 Gateway에서만 처리하며, 도메인 서비스는 인증된 요청만 처리
• JWT 토큰의 유효성 검사는 Gateway 내 인증 모듈이 담당

---

🧩 인증 처리 구조 (gateway 내부)

예시: /imgplt/auths 호출 시

# app/domains/gateway/api/routes/auth.py
from fastapi import APIRouter, Header, HTTPException, status

router = APIRouter()

@router.get("/imgplt/auths")
def check_auth_token(accessToken: str = Header(...)):
    if accessToken != "VALID_TOKEN":  # 예시용 로직
        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token")
    return {"message": "인증 성공"}

• 실제 구현에서는 accessToken을 workspace 인증 서버로 위임하여 검증할 수 있음
• local/mock 모드로도 설정 가능하도록 .env에 AUTH_MODE를 구분

---

⚙️ 인증 모듈 설정 방식 (AUTH_MODE)

AUTH_MODE=local        # local / remote
AUTH_LOCAL_TOKEN=dev-token
AUTH_SERVER_URL=https://workspace.example.com/auth/verify

• local 모드: 사전 정의된 토큰(AUTH_LOCAL_TOKEN)과 비교
• remote 모드: 실제 인증 서버에 HTTP 요청으로 위임

---

🔀 라우팅 구조의 핵심

• Gateway는 도메인별 라우터를 다음과 같이 prefix를 붙여 등록합니다:

app.include_router(file_router, prefix="/file")
app.include_router(data_router, prefix="/data")

• 모든 경로는 gateway의 /gateway 하위에 위치하게 됩니다:

/gateway/file/upload
/gateway/data/insert

---

📌 정리

• Gateway는 인증과 라우팅을 전담하며, 도메인 서비스는 비즈니스 로직에만 집중
• 인증은 공통 로직으로 구현되며 local/remote 모드 분기 가능
• 도메인 라우터는 Gateway에 통합되어 /gateway/{domain}/ 경로로 통일

📌 6. 파일 업로드 API 구조 해설: S3 + Kafka까지의 비즈니스 흐름

✅ 목표

• 클라이언트가 파일을 업로드하면, 이를 S3에 저장하고 메타데이터는 Kafka로 전송
• 전체 흐름은 Gateway → File 도메인 → MinIO + Kafka로 이어짐

---

🧭 전체 비즈니스 흐름도

Client Request
    ↓
Gateway (/imgplt/upload)
    ↓
AuthModule.verify(accessToken)
    ↓
FileUploadInterface.upload_file()
    ↓
FileUploadService.upload_file()
    ↓
UploadHandlerInterface.handle_upload()
    ↓
UploadHandlerService.handle_upload()
    ↓
S3Client.upload()       →    KafkaProducer.send()
    ↓                          ↓
S3 저장                   메타데이터 전송

---

📂 주요 코드 계층 구성

app/domains/file/
├── api/routes/upload.py         # 엔드포인트 정의
├── services/interfaces/         # 추상 인터페이스 계층
├── services/impl/               # 실제 구현체 (비즈니스 로직)
├── clients/s3_client.py         # MinIO 업로드 처리
├── clients/kafka_producer.py   # Kafka 메시지 전송 처리

• API 요청 처리: upload.py
• 핵심 로직 처리: UploadHandlerService
• 파일 저장 및 Kafka 전송: 각각 전용 클라이언트로 위임

---

🔧 실제 API 사용 예시

요청 형식

curl -X POST http://localhost:8000/gateway/imgplt/upload \
  -H "accessToken: dev-token" \
  -F "file=@sample.jpg" \
  -F "meta={\"table\": \"camera01\", \"ts\": \"2024-01-01 12:00:00\"}" \
  -H "Content-Type: multipart/form-data"

응답 예시

{
  "message": "Upload successful",
  "s3_key": "camera01/20240101/sample.jpg",
  "meta": {
    "table": "camera01",
    "ts": "2024-01-01 12:00:00"
  }
}

---

🧩 설계 포인트

• 비동기 호출: 내부적으로 async def 기반으로 설계되어 높은 동시성 지원
• 의존성 분리: Kafka, S3 클라이언트는 구현체만 바꿔도 동작 가능하게 추상화
• 도메인 책임 분리: Gateway는 인증 및 라우팅만, File 도메인은 업로드 전담

---

📌 정리

• 클라이언트는 /gateway/imgplt/upload에 파일과 메타데이터를 전송
• Gateway는 인증을 확인하고 File 도메인에 요청 위임
• 파일은 S3(MinIO)에 저장, 메타데이터는 Kafka 토픽으로 전송
• 계층별로 역할이 나뉘어 있어 테스트, 유지보수, 교체가 용이

•  

7. 로깅 및 트레이싱 구성: loguru + Sentry 중심의 예외처리 구조 

✅ 목표

• 각 서비스에서 발생하는 모든 예외를 Sentry로 전송하여 장애 추적 가능
• 모든 로그는 loguru 기반 logger로 일자별 파일(app-YYYYMMDD.log) + 콘솔에 기록
• 에러 알림은 Sentry SDK를 통해 조건부(운영/스테이지 환경)로만 전송
• OpenTelemetry(OTEL)는 선택 사항이며, 기본은 Sentry 중심으로 운영
• 서비스별 로그 전송은 fire-and-forget 방식(비동기, 실패해도 비즈니스 영향 無)

---

🧭 예외처리 및 로깅 흐름

FastAPI 앱 시작
    ↓
loguru 기반 TraceLoggingMiddleware 등록 (요청/응답 로깅)
    ↓
예외 발생 시 install_exception_handlers 또는 global_exception_handler 동작
    ↓
- loguru logger로 콘솔 + 일자별 파일 로그 출력
- 운영/스테이지 환경이면 Sentry에 예외 전송

---

⚙️ 예외 처리 방식

1) 모든 예외 → Sentry 기록 여부 및 loguru 로깅

from app.common.logging import logger
import sentry_sdk

@app.exception_handler(Exception)
async def global_exception_handler(request: Request, exc: Exception):
    if USE_SENTRY and SENTRY_DSN:
        sentry_sdk.capture_exception(exc)
    logger.error(f"[Global Exception] {request.method} {request.url} - {exc}", exc_info=True)
    # ... (적절한 응답 반환)

• global handler에서 모든 예외 포착
• 운영/스테이지 환경이면 Sentry로 전송, 항상 loguru로 파일+콘솔 기록

2) 커스텀 예외 및 시스템 예외

• HTTPException, CustomException, 시스템 예외 모두 동일하게 처리
• loguru logger와 Sentry SDK 병행 사용, trace/context 자동 캡처

3) fire-and-forget 로그 전송

• 각 서비스는 send_log_async로 로그를 비동기 전송
• 실패하더라도 서비스 로직과 무관하게 처리됨
• 중앙 로그 서비스는 일자별 파일(total_log/app-YYYYMMDD.log)에 집계

---

📦 환경별 설정 포인트 (.env, config.py, logging.py)

• .env 및 config.py 기준:

if ENV in ["production", "stage"]:
    self.SENTRY_DSN = os.getenv("SENTRY_DSN")
    self.USE_SENTRY = os.getenv("USE_SENTRY", "false").lower() == "true"
else:
    self.SENTRY_DSN = None
    self.USE_SENTRY = False

• logging.py에서 loguru 설정:

from loguru import logger
from datetime import datetime

LOG_PATH = f"logs/app-{datetime.now().strftime('%Y%m%d')}.log"
logger.add(LOG_PATH, rotation="10 MB", retention="7 days", level="INFO")

• 운영/스테이지만 Sentry 활성화, 개발/테스트는 로컬 로그만 기록
• loguru logger는 모든 환경에서 사용, Python 표준 logging 미사용
• OTEL은 필요한 경우에만 활성화

---

📝 로그/예외 처리 포인트 요약

• loguru 기반 logger로 모든 로그 기록 (파일 + 콘솔)
• TraceLoggingMiddleware: 요청/응답 추적용 미들웨어
• install_exception_handlers 또는 @app.exception_handler: 예외 상황에서 Sentry 전송 담당
• FastAPI의 기본 예외 및 런타임 오류 모두 통합 처리 가능
• 서비스 간 로그 전송은 send_log_async 기반 비동기 처리

---

📌 정리

• 모든 예외는 공통 핸들러에서 수집되고, 조건 충족 시 Sentry로 전송
• Sentry 설정은 .env와 config.py에 따라 분기되며, 운영 환경 중심으로 사용
• loguru 기반 로그 시스템으로 일자별 파일 + 콘솔 출력
• 로그 전송은 비동기(fire-and-forget) 방식으로 운영 서비스와 완전히 분리되어 동작
• OpenTelemetry는 선택 사항이며 기본 예외 추적은 Sentry 중심으로 구현