프로젝트 소개

이 저장소는 스타트업에서의 프로덕션 경험을 바탕으로 한 FastAPI 모범 사례와 관례를 선별하여 정리한 것입니다. 라이브러리나 프레임워크가 아니라 코드 예제와 아키텍처 지침을 담은 문서 자료입니다. 주요 주제는 다음과 같습니다. - 프로젝트 구조: Netflix의 Dispatch에서 영감을 받은 도메인 기반 레이아웃으로, 각 모듈이 자체 router, schemas, models, services, dependencies, constants, config, utils, exceptions를 포함합니다. - 비동기 라우트: I/O 집약적 작업과 CPU 집약적 작업을 처리하는 방법에 대한 지침. FastAPI가 동기 라우트를 스레드풀에서 실행하는 방식과 비동기 라우트에서 블로킹 작업이 이벤트 루프를 멈추게 할 수 있는 이유를 설명합니다. - Pydantic 사용: 검증을 위해 Pydantic을 광범위하게 사용하고, 일관된 datetime 직렬화를 위한 커스텀 전역 베이스 모델을 만들며, BaseSettings를 모듈별로 분리합니다. - 의존성: 주입 이상의 용도로 FastAPI 의존성을 사용하여 요청 검증, 의존성 체이닝, 요청 범위 캐싱 활용, 비동기 의존성 선호 등을 다룹니다. - 기타 관례: REST 관례 따르기, FastAPI 응답 직렬화 동작 이해하기, 동기 SDK를 스레드풀에서 실행하기, BackgroundTasks와 실제 작업 큐 중 선택하기, ValueError를 ValidationError로 변환하기, 기본적으로 문서 숨기기, 데이터베이스 네이밍 관례 설정하기, Alembic 마이그레이션 사용하기, ruff 채택하기 등이 포함됩니다. 이 저장소에는 AI 에이전트를 위해 동일한 규칙을 기계 판독 가능한 형식으로 담은 AGENTS.md 파일도 포함되어 있으며, 버전 매트릭스, Do/Don't 블록, 안티패턴 체크리스트를 제공합니다. README의 중국어 간체 번역도 제공됩니다.