Flask 프로젝트 구조 설계 가이드
Flask는 경량 웹 프레임워크로서, 규모가 큰 애플리케이션보다는 중소 규모의 서비스 개발에 적합합니다. 이에 따라 공식적인 프로젝트 구조 표준은 없지만, 유지보수성과 확장성을 고려한 추천 구조를 제시합니다.
블루프린트 기반 모듈화 설계
블루프린트는 Flask에서 기능을 모듈 단위로 분리하고 재사용 가능한 구조를 제공합니다. 블루프린트는 자체적으로 라우팅을 관리하며, 최종적으로 app에 등록되어 통합됩니다.
from flask import Flask, Blueprint
# 메인 애플리케이션 생성
main_app = Flask(__name__)
# 주문 관련 블루프린트 정의
order_module = Blueprint('order', __name__, url_prefix='/api/order')
@order_module.before_request
def setup_context():
g.request_id = 'req_12345' # 요청 마다 설정되는 컨텍스트 값
@order_module.route('/status')
def order_status():
return f"요청 식별자: {g.request_id}"
# 블루프린트 등록
main_app.register_blueprint(order_module)
블루프린트를 사용하면 여러 파일 간의 순환 의존성 문제를 피할 수 있으며, 각 모듈이 독립적으로 개발되고 테스트될 수 있습니다.
다중 파일 기반 프로젝트 구조 예시
기본 구조 (작은 규모 프로젝트)
project-root/
├── src/
│ ├── __init__.py # Flask 앱 생성 및 블루프린트 등록
│ ├── views/
│ │ ├── auth.py # 인증 관련 라우트
│ │ └── user.py # 사용자 관련 라우트
│ ├── models.py # 데이터베이스 모델
│ └── utils.py # 공통 유틸리티 함수
├── manage.py # 애플리케이션 실행 스크립트
└── templates/ # HTML 템플릿
└── index.html
src/__init__.py 예시:
from flask import Flask
from .views.auth import auth_bp
from .views.user import user_bp
def create_app():
app = Flask(__name__)
app.register_blueprint(auth_bp)
app.register_blueprint(user_bp)
return app
manage.py 예시:
from src import create_app
app = create_app()
if __name__ == '__main__':
app.run(debug=True)
확장 가능한 구조 (중간 규모 이상)
project-root/
├── src/
│ ├── __init__.py
│ ├── api/
│ │ ├── __init__.py # API 블루프린트 집합
│ │ ├── v1/
│ │ │ ├── __init__.py # v1 버전 블루프린트
│ │ │ ├── auth.py
│ │ │ └── orders.py
│ │ └── v2/
│ │ ├── __init__.py
│ │ └── users.py
│ ├── core/
│ │ ├── __init__.py
│ │ ├── middleware.py # 전역 미들웨어
│ │ └── exceptions.py
│ └── config.py # 설정 관리
├── manage.py
└── static/
└── css/
이 구조에서는 각 기능 영역(예: api/v1, api/v2)이 별도의 패키지로 분리되며, 전체 앱은 src/__init__.py에서 모든 블루프린트를 조합하여 생성합니다.
G 객체의 역할과 사용 방법
G 객체는 현재 요청에 한해 유효한 전역 변수 저장소입니다. 다른 전역 변수와 차별화되는 점은 다음과 같습니다:
g는 각 요청마다 새로 생성됨 → 동일한 요청 내에서만 접근 가능request와 유사하지만,g는 사용자가 직접 정의한 컨텍스트 데이터를 보관하는 용도로 특화됨session과 달리, 클라이언트 사이의 상태 유지 불가 (쿠키 기반)
주요 목적
- 상태 전달:
before_request에서 계산된 값을g에 저장해, 이후 뷰 함수에서 사용 - 코드 정제:
request객체를 오염시키지 않음 → 명확한 책임 분리 - 성능 최적화: 요청 종료 시 자동 삭제 → 메모리 누수 방지
실습 예제
from flask import Flask, g, request
app = Flask(__name__)
app.config['DEBUG'] = True
@app.before_request
def load_user_info():
token = request.headers.get('Authorization')
if token and token.startswith('Bearer '):
user_id = verify_token(token[7:])
g.current_user = user_id # 요청 범위 내 전역 변수 설정
else:
g.current_user = None
@app.route('/profile')
def show_profile():
user = g.current_user
if user:
return f"사용자: {user}"
return "인증되지 않은 사용자", 401
여기서 g.current_user는 before_request에서 설정되었으며, show_profile 뷰 함수에서도 안전하게 접근 가능합니다.
✅ 참고:
g는 요청 스코프 내에서만 유효하므로, 비동기 처리나 쓰레드 환경에서는 주의 필요