홈

FastAPI-fastkit

FastAPI-fastkit: Python과 FastAPI를 처음 접하는 분들을 위한 빠르고 쓰기 쉬운 스타터 키트

이 프로젝트는 Python과 FastAPI를 처음 접하는 사용자가 Python 기반 웹 앱 개발에 필요한 환경을 더 빠르게 갖출 수 있도록 만들어졌습니다.

이 프로젝트는 SpringBoot initializer와 Python Django의 django-admin CLI에서 영감을 받았습니다.

번역 상태

이 문서의 원본은 영어 (en)입니다. 언어 선택기에 표시되는 다른 언어는 부분 번역 상태이거나 페이지별로 영어 원문이 대신 표시될 수 있습니다. 각 언어의 실제 번역 진행 상황은 번역 현황 페이지를 참고하세요.

주요 기능

⚡ 즉시 FastAPI 프로젝트 생성: Python Django의 django-admin 기능에서 영감을 받아 FastAPI 워크스페이스와 프로젝트를 빠르게 생성
✨ 대화형 프로젝트 빌더: 데이터베이스, 인증, 캐싱, 모니터링 등을 단계별로 안내하고, 선택한 구성을 바탕으로 코드를 자동 생성
🎨 보기 좋은 CLI 출력: rich library 기반의 깔끔한 CLI 경험
📋 표준 기반 FastAPI 프로젝트 템플릿: 모든 FastAPI-fastkit 템플릿은 Python 표준과 FastAPI의 일반적인 사용 패턴을 바탕으로 구성
🔍 자동화된 템플릿 품질 보증: 주간 자동 테스트로 모든 템플릿이 정상 동작하고 최신 상태를 유지하도록 보장
🚀 다양한 프로젝트 템플릿: async CRUD, Docker, PostgreSQL 등 다양한 사용 사례에 맞춘 사전 구성 템플릿 제공
📦 다중 패키지 매니저 지원: 선호하는 Python 패키지 매니저(pip, uv, pdm, poetry)를 선택 가능

설치

Python 환경에 FastAPI-fastkit을 설치하세요.

$ pip install FastAPI-fastkit
---> 100%

사용법

새 FastAPI 프로젝트 워크스페이스 환경을 즉시 생성

이제 FastAPI-fastkit으로 새 FastAPI 프로젝트를 아주 빠르게 시작할 수 있습니다.

다음 명령으로 새 FastAPI 프로젝트 워크스페이스를 즉시 생성하세요:

$ fastkit init
Enter the project name: my-awesome-project
Enter the author name: John Doe
Enter the author email: john@example.com
Enter the project description: My awesome FastAPI project

           Project Information
┌──────────────┬────────────────────────────┐
│ Project Name │ my-awesome-project         │
│ Author       │ John Doe                   │
│ Author Email │ john@example.com           │
│ Description  │ My awesome FastAPI project │
└──────────────┴────────────────────────────┘

Available Stacks and Dependencies:
           MINIMAL Stack
┌──────────────┬───────────────────┐
│ Dependency 1 │ fastapi           │
│ Dependency 2 │ uvicorn           │
│ Dependency 3 │ pydantic          │
│ Dependency 4 │ pydantic-settings │
└──────────────┴───────────────────┘

           STANDARD Stack
┌──────────────┬───────────────────┐
│ Dependency 1 │ fastapi           │
│ Dependency 2 │ uvicorn           │
│ Dependency 3 │ sqlalchemy        │
│ Dependency 4 │ alembic           │
│ Dependency 5 │ pytest            │
│ Dependency 6 │ pydantic          │
│ Dependency 7 │ pydantic-settings │
└──────────────┴───────────────────┘

             FULL Stack
┌──────────────┬───────────────────┐
│ Dependency 1 │ fastapi           │
│ Dependency 2 │ uvicorn           │
│ Dependency 3 │ sqlalchemy        │
│ Dependency 4 │ alembic           │
│ Dependency 5 │ pytest            │
│ Dependency 6 │ redis             │
│ Dependency 7 │ celery            │
│ Dependency 8 │ pydantic          │
│ Dependency 9 │ pydantic-settings │
└──────────────┴───────────────────┘

Select stack (minimal, standard, full): minimal

Available Package Managers:
                   Package Managers
┌────────┬────────────────────────────────────────────┐
│ PIP    │ Standard Python package manager            │
│ UV     │ Fast Python package manager                │
│ PDM    │ Modern Python dependency management        │
│ POETRY │ Python dependency management and packaging │
└────────┴────────────────────────────────────────────┘

Select package manager (pip, uv, pdm, poetry) [uv]: uv
Do you want to proceed with project creation? [y/N]: y
FastAPI project will deploy at '~your-project-path~'

╭──────────────────────── Info ────────────────────────╮
│ ℹ Injected metadata into setup.py                    │
╰──────────────────────────────────────────────────────╯
╭──────────────────────── Info ────────────────────────╮
│ ℹ Injected metadata into config file                 │
╰──────────────────────────────────────────────────────╯

        Creating Project:
       my-awesome-project
┌───────────────────┬───────────┐
│ Component         │ Collected │
│ fastapi           │ ✓         │
│ uvicorn           │ ✓         │
│ pydantic          │ ✓         │
│ pydantic-settings │ ✓         │
└───────────────────┴───────────┘

Creating virtual environment...

╭──────────────────────── Info ────────────────────────╮
│ ℹ venv created at                                    │
│ ~your-project-path~/my-awesome-project/.venv         │
│ To activate the virtual environment, run:            │
│                                                      │
│     source                                           │
│ ~your-project-path~/my-awesome-project/.venv/bin/act │
│ ivate                                                │
╰──────────────────────────────────────────────────────╯

Installing dependencies...
⠙ Setting up project environment...Collecting <packages~>

---> 100%

╭─────────────────────── Success ───────────────────────╮
│ ✨ Dependencies installed successfully                │
╰───────────────────────────────────────────────────────╯
╭─────────────────────── Success ───────────────────────╮
│ ✨ FastAPI project 'my-awesome-project' has been      │
│ created successfully and saved to                     │
│ ~your-project-path~!                                  │
╰───────────────────────────────────────────────────────╯
╭──────────────────────── Info ────────────────────────╮
│ ℹ To start your project, run 'fastkit runserver' at  │
│ newly created FastAPI project directory              │
╰──────────────────────────────────────────────────────╯

이 명령은 Python 가상 환경까지 포함된 새 FastAPI 프로젝트 작업 공간을 만들어 줍니다.

대화형 모드로 프로젝트 생성 ✨ NEW!

보다 복잡한 프로젝트의 경우, 대화형 모드를 사용해 지능형 기능 선택과 함께 단계별로 FastAPI 애플리케이션을 구성하세요:

$ fastkit init --interactive

⚡ FastAPI-fastkit Interactive Project Setup ⚡

📋 Basic Project Information
Enter the project name: my-fullstack-project
Enter the author name: John Doe
Enter the author email: john@example.com
Enter the project description: Full-stack FastAPI project with PostgreSQL and JWT

🧱 Architecture Preset
Pick a project layout. Press Enter to accept the recommended default.
  1. minimal           - Smallest viable FastAPI app
  2. single-module     - Everything in one module (prototypes / scripts)
  3. classic-layered   - api/routes + crud + schemas + core (à la fastapi-default)
  4. domain-starter    - Domain-oriented src/app/domains/<concept>/ (recommended)

Select architecture preset: [4]

🗄️ Database Selection
Select database (PostgreSQL, MySQL, MongoDB, Redis, SQLite, None):
  1. PostgreSQL - PostgreSQL database with SQLAlchemy
  2. MySQL - MySQL database with SQLAlchemy
  3. MongoDB - MongoDB with motor async driver
  4. Redis - Redis for caching and session storage
  5. SQLite - SQLite database for development
  6. None - No database

Select database: 1

🔐 Authentication Selection
Select authentication (JWT, OAuth2, FastAPI-Users, Session-based, None):
  1. JWT - JSON Web Token authentication
  2. OAuth2 - OAuth2 with password flow
  3. FastAPI-Users - Full featured user management
  4. Session-based - Cookie-based sessions
  5. None - No authentication

Select authentication: 1

⚙️ Background Tasks Selection
Select background tasks (Celery, Dramatiq, None):
  1. Celery - Distributed task queue
  2. Dramatiq - Fast and reliable task processing
  3. None - No background tasks

Select background tasks: 1

💾 Caching Selection
Select caching (Redis, fastapi-cache2, None):
  1. Redis - Redis caching
  2. fastapi-cache2 - Simple caching for FastAPI
  3. None - No caching

Select caching: 1

📊 Monitoring Selection
Select monitoring (Loguru, OpenTelemetry, Prometheus, None):
  1. Loguru - Simple and powerful logging
  2. OpenTelemetry - Observability framework
  3. Prometheus - Metrics and monitoring
  4. None - No monitoring

Select monitoring: 3

🧪 Testing Framework Selection
Select testing framework (Basic, Coverage, Advanced, None):
  1. Basic - pytest + httpx for API testing
  2. Coverage - Basic + code coverage
  3. Advanced - Coverage + faker + factory-boy for fixtures
  4. None - No testing framework

Select testing framework: 2

🛠️ Additional Utilities
Select utilities (comma-separated numbers, e.g., 1,3,4):
  1. CORS - Cross-Origin Resource Sharing
  2. Rate-Limiting - Request rate limiting
  3. Pagination - Pagination support
  4. WebSocket - WebSocket support

Select utilities: 1

🚀 Deployment Configuration
Select deployment option:
  1. Docker - Generate Dockerfile
  2. docker-compose - Generate docker-compose.yml (includes Docker)
  3. None - No deployment configuration

Select deployment option: 2

📦 Package Manager Selection
Select package manager (pip, uv, pdm, poetry): uv

📝 Custom Packages (optional)
Enter custom package names (comma-separated, press Enter to skip):

📋 Project Configuration Summary
┌─────────────────────┬───────────────────────────────────────────────────────────────────────────┐
│ Setting             │ Value                                                                     │
├─────────────────────┼───────────────────────────────────────────────────────────────────────────┤
│ Project Name        │ my-fullstack-project                                                      │
│ Author              │ John Doe                                                                  │
│ Email               │ john@example.com                                                          │
│ Description         │ Full-stack FastAPI project with PostgreSQL and JWT                        │
│ Architecture Preset │ domain-starter — Domain-oriented: src/app/domains/<concept>/ (recommended)│
│ Database            │ PostgreSQL                                                                │
│ Authentication      │ JWT                                                                       │
│ Async Tasks         │ Celery                                                                    │
│ Caching             │ Redis                                                                     │
│ Monitoring          │ Prometheus                                                                │
│ Testing             │ Coverage                                                                  │
│ Utilities           │ CORS                                                                      │
│ Package Manager     │ uv                                                                        │
└─────────────────────┴───────────────────────────────────────────────────────────────────────────┘

Total dependencies to install: 18

Proceed with project creation? [Y/n]: y

╭──────────────────────── Info ────────────────────────╮
│ ℹ Injected metadata into pyproject.toml              │
╰──────────────────────────────────────────────────────╯
╭─────────────────────── Success ───────────────────────╮
│ ✨ Generated dependency file with 18 packages         │
╰───────────────────────────────────────────────────────╯
╭──────────────────────── Info ────────────────────────╮
│ ℹ Preserving template-shipped main.py for preset     │
│ 'domain-starter'.                                    │
╰──────────────────────────────────────────────────────╯
╭─────────────────────── Success ───────────────────────╮
│ ✨ Generated Docker deployment files                  │
╰───────────────────────────────────────────────────────╯
╭────────────────────── Warning ────────────────────────╮
│ ⚠ Preset compatibility                               │
│ fastapi-domain-starter's shipped src/app/main.py is  │
│ preserved. The selections below need manual wiring   │
│ there (CORS is already wired — set                   │
│ BACKEND_CORS_ORIGINS in .env to activate it).        │
│ Affected selections (packages installed, but no      │
│ dynamic main.py edits applied for the                │
│ 'domain-starter' preset): Prometheus                 │
╰───────────────────────────────────────────────────────╯
╭─────────────────────── Success ───────────────────────╮
│ ✨ Generated configuration files for selected stack   │
╰───────────────────────────────────────────────────────╯

Creating virtual environment...
Installing dependencies...

----> 100%

╭─────────────────────── Success ───────────────────────╮
│ ✨ FastAPI project 'my-fullstack-project' from        │
│ 'fastapi-domain-starter' has been created!            │
╰───────────────────────────────────────────────────────╯

대화형 모드가 제공하는 기능:

아키텍처 프리셋 선택 (minimal / single-module / classic-layered / domain-starter) — 적절한 베이스 템플릿과 프로젝트 레이아웃을 결정
데이터베이스, 인증, 백그라운드 작업, 캐싱, 모니터링 등에 대한 가이드형 선택
선택한 기능에 대한 자동 코드 생성 — 프리셋에 따라 동작 방식이 다름 (minimal / single-module 은 main.py 재생성, classic-layered / domain-starter 는 템플릿 제공 main.py 보존하며 설정 모듈만 추가)
프리셋 인지형 Docker 생성 — 생성된 Dockerfile 의 CMD 가 해당 프리셋의 실제 진입점 (src.main:app 또는 src.app.main:app) 을 가리킴
자동 pip 호환성을 갖춘 스마트 의존성 관리
프리셋이 자동 연결할 수 없는 선택에 대해 수동 연결 안내를 출력하는 기능 검증
생성된 pyproject.toml 에 식별 마커 주입 (description 마커 + [tool.fastapi-fastkit] 테이블) — 이후 is_fastkit_project() 가 생성된 프로젝트를 식별 가능

FastAPI 프로젝트에 새 라우트 추가

FastAPI-fastkit 은 FastAPI 프로젝트 확장을 쉽게 만들어 줍니다.

다음 명령으로 FastAPI 프로젝트에 새 라우트 엔드포인트를 추가하세요:

$ fastkit addroute user my-awesome-project
                       Adding New Route
┌──────────────────┬──────────────────────────────────────────┐
│ Project          │ my-awesome-project                       │
│ Route Name       │ user                                     │
│ Target Directory │ ~your-project-path~                      │
└──────────────────┴──────────────────────────────────────────┘

Do you want to add route 'user' to project 'my-awesome-project'? [Y/n]: y

╭──────────────────────── Info ────────────────────────╮
│ ℹ Updated main.py to include the API router          │
╰──────────────────────────────────────────────────────╯
╭─────────────────────── Success ───────────────────────╮
│ ✨ Successfully added new route 'user' to project     │
│ `my-awesome-project`                                  │
╰───────────────────────────────────────────────────────╯

구조화된 FastAPI 데모 프로젝트를 즉시 배치

구조화된 FastAPI 데모 프로젝트로 시작할 수도 있습니다.

데모 프로젝트는 다양한 기술 스택과 함께 간단한 item CRUD 엔드포인트가 구현된 형태로 제공됩니다.

다음 명령으로 구조화된 FastAPI 데모 프로젝트를 즉시 배치하세요:

$ fastkit startdemo
Enter the project name: my-awesome-demo
Enter the author name: John Doe
Enter the author email: john@example.com
Enter the project description: My awesome FastAPI demo
Deploying FastAPI project using 'fastapi-default' template
Template path:
/~fastapi_fastkit-package-path~/fastapi_project_template/fastapi-default

           Project Information
┌──────────────┬─────────────────────────┐
│ Project Name │ my-awesome-demo         │
│ Author       │ John Doe                │
│ Author Email │ john@example.com        │
│ Description  │ My awesome FastAPI demo │
└──────────────┴─────────────────────────┘

       Template Dependencies
┌──────────────┬───────────────────┐
│ Dependency 1 │ fastapi           │
│ Dependency 2 │ uvicorn           │
│ Dependency 3 │ pydantic          │
│ Dependency 4 │ pydantic-settings │
│ Dependency 5 │ python-dotenv     │
└──────────────┴───────────────────┘

Available Package Managers:
                   Package Managers
┌────────┬────────────────────────────────────────────┐
│ PIP    │ Standard Python package manager            │
│ UV     │ Fast Python package manager                │
│ PDM    │ Modern Python dependency management        │
│ POETRY │ Python dependency management and packaging │
└────────┴────────────────────────────────────────────┘

Select package manager (pip, uv, pdm, poetry) [uv]: uv
Do you want to proceed with project creation? [y/N]: y
FastAPI template project will deploy at '~your-project-path~'

---> 100%

╭─────────────────────── Success ───────────────────────╮
│ ✨ Dependencies installed successfully                │
╰───────────────────────────────────────────────────────╯
╭─────────────────────── Success ───────────────────────╮
│ ✨ FastAPI project 'my-awesome-demo' from             │
│ 'fastapi-default' has been created and saved to       │
│ ~your-project-path~!                                  │
╰───────────────────────────────────────────────────────╯

사용 가능한 FastAPI 데모 목록을 보려면 다음 명령을 실행하세요:

$ fastkit list-templates
                              Available Templates
┌────────────────────────┬───────────────────────────────────────────────────────┐
│ fastapi-custom-response│ Async Item Management API with Custom Response System │
│ fastapi-mcp            │ FastAPI MCP Project                                   │
│ fastapi-domain-starter │ FastAPI Domain Starter                                │
│ fastapi-dockerized     │ Dockerized FastAPI Item Management API                │
│ fastapi-empty          │ Minimal FastAPI Template                              │
│ fastapi-async-crud     │ Async Item Management API Server                      │
│ fastapi-psql-orm       │ Dockerized FastAPI Item Management API with           │
│                        │ PostgreSQL                                            │
│ fastapi-default        │ Simple FastAPI Project                                │
│ fastapi-single-module  │ FastAPI Single Module Template                        │
└────────────────────────┴───────────────────────────────────────────────────────┘

문서

종합적인 가이드와 자세한 사용법은 문서를 참고하세요:

📚 사용자 가이드 - 자세한 설치 및 사용 가이드
🎯 튜토리얼 - 초보자를 위한 단계별 튜토리얼
📖 CLI 레퍼런스 - 전체 명령어 레퍼런스
🔍 템플릿 품질 보증 - 자동화된 테스트 및 품질 기준

🚀 템플릿 기반 튜토리얼

사전 구축된 템플릿으로 실전 사용 사례를 통해 FastAPI 개발을 학습하세요:

📖 핵심 튜토리얼

기본 API 서버 만들기 - fastapi-default 템플릿으로 첫 FastAPI 서버 만들기
비동기 CRUD API 만들기 - fastapi-async-crud 템플릿으로 고성능 비동기 API 개발
도메인 지향 프로젝트 - 현재 권장 기본값인 fastapi-domain-starter 템플릿으로 중간 규모 API 구축

🗄️ 데이터베이스 및 인프라

데이터베이스 통합 - fastapi-psql-orm 템플릿으로 PostgreSQL + SQLAlchemy 활용
Docker 기반 배포 - fastapi-dockerized 템플릿으로 프로덕션 배포 환경 구성

⚡ 고급 기능

커스텀 응답 처리 및 고급 API 설계 - fastapi-custom-response 템플릿으로 엔터프라이즈급 API 구축
MCP 통합 - fastapi-mcp 템플릿으로 AI 모델과 통합된 API 서버 만들기

각 튜토리얼은 다음을 제공합니다:

✅ 실용적인 예제 - 실제 프로젝트에서 바로 사용할 수 있는 코드
✅ 단계별 가이드 - 초보자도 따라가기 쉬운 자세한 설명
✅ 모범 사례 - 업계 표준 패턴과 보안 고려 사항
✅ 확장 방법 - 프로젝트를 한 단계 더 발전시키는 가이드

기여

커뮤니티의 기여를 환영합니다! FastAPI-fastkit은 Python과 FastAPI 입문자를 돕기 위해 설계되었으며, 여러분의 기여는 큰 변화를 만들 수 있습니다.

기여할 수 있는 항목

🚀 새로운 FastAPI 템플릿 - 다양한 사용 사례를 위한 템플릿 추가
🐛 버그 수정 - 안정성과 신뢰성 개선
📚 문서화 - 가이드, 예제, 번역 개선
🧪 테스트 - 테스트 커버리지 확장 및 통합 테스트 추가
💡 기능 - 새로운 CLI 기능 제안 및 구현

기여 시작하기

FastAPI-fastkit에 기여를 시작하려면 다음 가이드를 참고하세요:

개발 환경 설정 - 개발 환경 설정에 대한 완전한 가이드
코드 가이드라인 - 코딩 표준 및 모범 사례
CONTRIBUTING.md - 종합 기여 가이드
CODE_OF_CONDUCT.md - 프로젝트 원칙과 커뮤니티 기준
SECURITY.md - 보안 지침 및 신고 방법

FastAPI-fastkit이 지향하는 것

FastAPI-fastkit은 Python과 FastAPI를 처음 접하는 사용자에게 빠르고 쓰기 쉬운 스타터 키트를 제공하는 것을 목표로 합니다.

이 아이디어는 FastAPI 입문자가 처음부터 차근차근 학습할 수 있도록 돕자는 취지에서 출발했으며, FastAPI 0.111.0 버전 업데이트에서 추가된 FastAPI-cli 패키지가 지닌 실전적 의미와도 맥락을 같이합니다.

오랫동안 FastAPI를 사용해 온 사람으로서, FastAPI 개발자 tiangolo가 밝힌 멋진 동기를 조금이나마 현실로 옮기는 데 도움이 되는 프로젝트를 만들고 싶었습니다.

FastAPI-fastkit은 다음과 같은 가치를 제공해 "첫 시작"과 "실전에 쓸 수 있는 애플리케이션" 사이의 간극을 메우고자 합니다:

즉각적인 생산성 — 초기 설정의 복잡성에 압도될 수 있는 신규 사용자에게 즉시 생산성을 제공
모범 사례 — 모든 템플릿에 모범 사례가 내장되어 있어, 사용자가 올바른 FastAPI 패턴을 학습하는 데 도움
확장 가능한 기반 — 초보자에서 전문가로 성장함에 따라 함께 확장되는 기반
커뮤니티 주도 템플릿 — 실제 FastAPI 사용 패턴을 반영한 커뮤니티 중심 템플릿

다음 단계

FastAPI-fastkit을 시작할 준비가 되셨다면, 아래 순서대로 진행해 보세요:

🚀 빠른 시작

설치: FastAPI-fastkit 설치
퀵 스타트: 5분 안에 첫 프로젝트 만들기
입문 튜토리얼: 단계별 상세 튜토리얼

📚 심화 학습

프로젝트 생성: 다양한 스택으로 프로젝트 생성
라우트 추가: 프로젝트에 API 엔드포인트 추가
템플릿 사용: 사전 구축된 프로젝트 템플릿 사용

🛠️ 기여

FastAPI-fastkit에 기여하고 싶으신가요?

개발 환경 설정: 개발 환경 설정
코드 가이드라인: 코딩 표준 및 모범 사례 준수
기여 가이드라인: 종합 기여 가이드

🔍 레퍼런스

CLI 레퍼런스: 전체 CLI 명령 레퍼런스
템플릿 품질 보증: 자동화된 테스트 및 품질 기준
FAQ: 자주 묻는 질문
GitHub 저장소: 소스 코드 및 이슈 트래킹

라이선스

이 프로젝트는 MIT 라이선스 하에 제공됩니다 — 자세한 내용은 LICENSE 파일을 참고하세요.