개발 환경 구성과 필수 라이브러리 선정

Flask 는 파이썬 언어로 제작된 유연한 웹 프레임워크로, 최소한의 코드로부터 시작하여 필요한 기능을 확장해 나갈 수 있는 특징을 가지고 있습니다. 안정적인 백엔드 서비스를 신속하게 구축하기 위해 다음과 같은 전제 조건과 도구들이 필요합니다.

• 런타임: Python 3.8 이상 버전 권장 (Anaconda 또는 venv 사용 시 가상 환경 격리 필수)
• 저장소: MySQL 최신 안정판
• 핵심 확장 모듈:
  • ORM 연동: Flask-SQLAlchemy
  • 스키마 마이그레이션: Flask-Migrate
  • 데이터 직렬화: Flask-Marshmallow
  • 임시 세션 저장: Flask-Session
  • 비동기 통신: Flask-SocketIO
  • 주기적 작업 처리: APScheduler

가상 환경을 생성하고 활성화한 후, 다음 명령어를 통해 패키지들을 설치합니다.

# 가상 환경 설정 예시
conda create -n web_core py=3.8
conda activate web_core

# 핵심 의존성 패키지 로드
pip install flask sqlalchemy migrate marshmallow apscheduler session socketio
pip install pymysql  # MySQL 드라이버 추가 필요

또한, 나중에 인증 처리나 RESTful API 규격화가 필요할 경우 werkzeug, WTForms 등의 패키지를 상황에 따라 추가하는 것이 효율적입니다. 설치 시 주의할 점은 일부 배포판이 패키지 이름의 대소문자를 엄격하게 구분하지는 않지만, Linux 기반 환경에서는 명령어 실행 시 문맥에 맞는 정확한 입력이 요구된다는 것입니다.

모듈 중심의 프로젝트 구조 설계

유지보수성을 높이기 위해 기능별로 파일을 분리하여 계층화를 진행합니다. 각 디렉토리의 역할을 명확히 하되, 확장성을 고려하여 폴더명을 일반적으로 통용되는 네이밍 컨벤션을 따릅니다.

-- src              # 소스코드 루트 디렉토리
    |-- core         # 핵심 로직 모듈 (Package)
        |-- settings # 설정 파일 모음
        |-- db       # 데이터베이스 연결 로직
        |-- utils    # 공통 유틸리티 함수
        |-- models   # 엔티티 정의 (ORM 매핑)
        |-- apis     # 외부 인터페이스 (View/Handler)
        |-- __init__.py  # 앱 팩토리 포함
    |-- resources    # 정적 자산 및 템플릿
        |-- static   
        |-- templates
    |-- migrations   # 스키마 변경 이력
    |-- run.py       # 서버 진입점

위 구조와 같이 비즈니스 로직을 포함하는 core 패키지를 독립적으로 분리하고, 환경 변수나 외부 자원 관련 설정은 별도의 설정 클래스로 추상화해야 합니다.

다중 데이터베이스 지원 설정 클래스 구현

운영 환경과 개발 환경을 분리하고, 서로 다른 용도의 데이터베이스(관리용, 운영용)를 동시에 사용할 수 있도록 설정 클래스를 상속 계층구조로 만듭니다.

# src/core/settings/base_settings.py
from flask.config import Config

class BaseConfig(Config):
    """기본 설정 상수 정의"""
    ENVIRONMENT = 'production'
    
    # 암호화 키 설정
    PRIVATE_KEY = os.environ.get('APP_SECRET', 'default_secret_key')
    
    # 주요 데이터베이스 정보
    MAIN_DB_USER = 'root'
    MAIN_DB_PASS = 'secure_password_123'
    MAIN_DB_NAME = 'operational_data'
    DB_HOST = 'localhost'
    DB_PORT = 3306
    
    # ORM URI 구성
    SQLALCHEMY_DATABASE_URI = (
        f'mysql+pymysql://{MAIN_DB_USER}:{MAIN_DB_PASS}@{DB_HOST}:{DB_PORT}/{MAIN_DB_NAME}'
        '?charset=utf8mb4&connect_timeout=5'
    )
    
    # 부가적인 데이터베이스 바인딩 (다중 DB 연결 시 활용)
    SQLALCHEMY_BINDS = {
        'admin_db': f'mysql+pymysql://{MAIN_DB_USER}:{MAIN_DB_PASS}@{DB_HOST}:{DB_PORT}/admin_portal'
    }

class DevelopmentConfig(BaseConfig):
    DEBUG = True
    TESTING = False

class ProductionConfig(BaseConfig):
    DEBUG = False
    TESTING = False

데이터베이스 인스턴스를 물리적으로 생성할 때는 한글 인코딩 오차를 방지하기 위해 utf8mb4 문자셋을 명시적으로 지정해야 합니다.

CREATE DATABASE IF NOT EXISTS operational_data 
CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

CREATE DATABASE IF NOT EXISTS admin_portal 
CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

애플리케이션 팩토리 패턴 적용

Flask 애플리케이션 인스턴스는 전역 변수로 생성하지 않고, 호출 시점에 생성되도록 설계하는 것이 테스트 및 확장에 유리합니다. __init__.py 파일 내부에서 설정을 주입하고 확장기를 등록하는 팩토리 함수를 작성합니다.

# src/core/__init__.py
import os
from flask import Flask
from .settings import DevelopmentConfig, ProductionConfig

def get_config_class():
    """현재 환경에 맞는 설정 클래스 반환"""
    mode = os.getenv('APP_MODE', 'dev')
    return DevelopmentConfig if mode == 'dev' else ProductionConfig

def init_flask_app(config_class=None):
    """플라스크 인스턴스 생성 및 기본 확장기 활성화"""
    cfg = config_class or get_config_class()
    
    application = Flask(__name__)
    application.config.from_object(cfg)
    
    # 여기서 ORM, 세션 등 초기화가 수행됨
    # example: db.init_app(application)
    
    return application

최종 진입점인 run.py 파일에서는 위 팩토리 함수를 사용하여 서버를 구동합니다. 이를 통해 동일한 코드베이스에서도 환경별 설정 차이를 손쉽게 관리할 수 있습니다.

# src/run.py
from core import init_flask_app

def main():
    flask_app = init_flask_app()
    
    if __name__ == '__main__':
        flask_app.run(host='0.0.0.0', port=5000)