Name	Name	Last commit message	Last commit date
parent directory ..
README.md	README.md

Python 앱 샘플

사용자가 게시물을 생성, 조회, 업데이트, 삭제하고, 댓글을 추가하고, 게시물에 좋아요/취소할 수 있는 간단한 소셜 네트워킹 서비스(SNS)를 위한 완전한 FastAPI 백엔드 구현입니다.

🏗️ 아키텍처 개요

프레임워크: Python 3.12+를 사용한 FastAPI
데이터베이스: SQLite (sns_api.db)
API 문서화: Swagger UI + OpenAPI 3.1 사양
CORS: 교차 출처 요청 활성화
데이터 검증: 포괄적인 검증을 포함한 Pydantic 모델

📁 프로젝트 구조

python/
├── main.py              # FastAPI 애플리케이션 진입점
├── models.py            # Pydantic 데이터 모델 및 스키마
├── database.py          # SQLite 데이터베이스 작업
├── openapi.yaml         # OpenAPI 3.0.1 사양
├── sns_api.db          # SQLite 데이터베이스 파일 (자동 생성)
├── README.md           # 이 문서
└── .venv/              # 가상 환경 (설정 중 생성)

🚀 빠른 시작

전제 조건

준비를 위해 README 문서를 참조하세요.

1. 환경 설정

먼저 $REPOSITORY_ROOT 환경 변수를 설정하세요.

# bash/zsh
REPOSITORY_ROOT=$(git rev-parse --show-toplevel)

# PowerShell
$REPOSITORY_ROOT = git rev-parse --show-toplevel

그런 다음 python 디렉터리로 이동하고 가상 환경을 생성하세요:

cd $REPOSITORY_ROOT/complete/python

가상 환경 생성

# uv 사용 (권장)
uv venv .venv

# 표준 Python 사용 (대안)
python -m venv .venv

2. 가상 환경 활성화

# Linux/macOS에서
source .venv/bin/activate

# Windows Command Prompt에서
.venv\Scripts\activate

3. 종속성 설치

# uv 사용 (권장)
uv pip install fastapi uvicorn python-multipart pyyaml

# pip 사용 (대안)
pip install fastapi uvicorn python-multipart pyyaml

4. OpenAPI 사양 복사

상위 디렉터리에서 OpenAPI 사양을 복사하세요.

# Linux/macOS에서
cp ../openapi.yaml .

# Windows Command Prompt에서
xcopy ..\openapi.yaml .

5. 애플리케이션 실행

개발 서버 시작

uvicorn main:app --host 0.0.0.0 --port 8000 --reload

애플리케이션은 다음에서 사용할 수 있습니다:

API 기본 URL: http://localhost:8000/api/
Swagger UI: http://localhost:8000/docs
OpenAPI 사양: http://localhost:8000/openapi.json

📊 데이터베이스 스키마

애플리케이션은 다음 테이블을 포함한 SQLite를 사용합니다:

Posts 테이블

id (TEXT, PRIMARY KEY) - UUID
username (TEXT, NOT NULL) - 작성자 사용자명
content (TEXT, NOT NULL) - 게시물 내용
created_at (TEXT, NOT NULL) - ISO 타임스탬프
updated_at (TEXT, NOT NULL) - ISO 타임스탬프

Comments 테이블

id (TEXT, PRIMARY KEY) - UUID
post_id (TEXT, NOT NULL) - posts에 대한 외래 키
username (TEXT, NOT NULL) - 작성자 사용자명
content (TEXT, NOT NULL) - 댓글 내용
created_at (TEXT, NOT NULL) - ISO 타임스탬프
updated_at (TEXT, NOT NULL) - ISO 타임스탬프

Likes 테이블

post_id (TEXT, NOT NULL) - posts에 대한 외래 키
username (TEXT, NOT NULL) - 좋아요를 누른 사용자
liked_at (TEXT, NOT NULL) - ISO 타임스탬프
기본 키: (post_id, username)

🔌 API 엔드포인트

게시물

GET /api/posts - 모든 게시물 목록
POST /api/posts - 새 게시물 생성
GET /api/posts/{postId} - 특정 게시물 가져오기
PATCH /api/posts/{postId} - 게시물 업데이트
DELETE /api/posts/{postId} - 게시물 삭제

GET /api/posts/{postId}/comments - 게시물의 댓글 목록
POST /api/posts/{postId}/comments - 댓글 생성
GET /api/posts/{postId}/comments/{commentId} - 특정 댓글 가져오기
PATCH /api/posts/{postId}/comments/{commentId} - 댓글 업데이트
DELETE /api/posts/{postId}/comments/{commentId} - 댓글 삭제

POST /api/posts/{postId}/likes - 게시물 좋아요
DELETE /api/posts/{postId}/likes?username={username} - 게시물 좋아요 취소

🧪 API 테스트

cURL 사용

게시물 생성

curl -X POST "http://localhost:8000/api/posts" \
  -H "Content-Type: application/json" \
  -d '{"username": "john_doe", "content": "Hello World! This is my first post."}'

모든 게시물 가져오기

curl -X GET "http://localhost:8000/api/posts"

댓글 추가

curl -X POST "http://localhost:8000/api/posts/{POST_ID}/comments" \
  -H "Content-Type: application/json" \
  -d '{"username": "jane_smith", "content": "Great post!"}'

게시물 좋아요

curl -X POST "http://localhost:8000/api/posts/{POST_ID}/likes" \
  -H "Content-Type: application/json" \
  -d '{"username": "alice_johnson"}'

Swagger UI 사용

http://localhost:8000/docs로 이동
모든 API 엔드포인트를 대화형으로 탐색하고 테스트
요청/응답 스키마 및 예제 보기

📝 데이터 모델

요청 모델

NewPostRequest: {username: str, content: str}
UpdatePostRequest: {username: str, content: str}
NewCommentRequest: {username: str, content: str}
UpdateCommentRequest: {username: str, content: str}
LikeRequest: {username: str}

응답 모델

Post: 메타데이터와 개수를 포함한 전체 게시물 객체
Comment: 메타데이터를 포함한 전체 댓글 객체
LikeResponse: 타임스탬프를 포함한 좋아요 확인

⚙️ 구성

환경 변수

애플리케이션은 기본 설정을 사용하지만 사용자 정의할 수 있습니다:

데이터베이스: SQLite 파일 sns_api.db (자동 생성)
호스트: 0.0.0.0 (모든 인터페이스)
포트: 8000
CORS: 모든 출처에 대해 활성화

프로덕션 고려사항

프로덕션 배포를 위해서는 다음을 고려하세요:

데이터베이스: PostgreSQL 또는 MySQL로 전환
환경 변수: 민감한 구성에 사용
보안: 인증 및 권한 추가
CORS: 특정 도메인으로 제한
로깅: 구조화된 로깅 구현
모니터링: 상태 확인 및 메트릭 추가

🛠️ 개발

파일 구성

main.py: FastAPI 앱 구성, 미들웨어 및 라우트 정의
models.py: 데이터 검증 및 직렬화를 위한 Pydantic 모델
database.py: SQLite 작업, 연결 관리 및 CRUD 함수

코드 스타일

프로젝트는 다음을 따릅니다:

Python PEP 8 스타일 가이드라인
FastAPI 모범 사례
함수형 프로그래밍 패턴
전체적인 타입 힌트
포괄적인 오류 처리

새 기능 추가

models.py에서 Pydantic 모델 정의
database.py에서 데이터베이스 작업 추가
main.py에서 API 엔드포인트 생성
필요한 경우 OpenAPI 사양 업데이트

🐛 문제 해결

일반적인 문제

포트 이미 사용 중: --port 8001로 포트 변경
가상 환경 문제: rm -rf .venv && uv venv .venv로 재생성
데이터베이스 잠김: 애플리케이션의 모든 실행 인스턴스 중지
가져오기 오류: 가상 환경이 활성화되어 있는지 확인

디버그 모드

추가 로깅과 함께 실행:

uvicorn main:app --host 0.0.0.0 --port 8000 --reload --log-level debug

📚 추가 리소스

면책조항: 이 문서는 GitHub Copilot에 의해 현지화되었습니다. 따라서 실수가 포함될 수 있습니다. 부적절하거나 잘못된 번역을 발견하면 issue를 생성해 주세요.

FilesExpand file tree

python

Directory actions

More options