🛠 Flask로 웹 서비스 만들기 – GarbageGuard 기반 실전 정리
ISO 14001 기반 건설 현장 폐기물 관리 시스템인 GarbageGuard를 개발하며 배운 Flask 핵심 개념과 구조를 정리했습니다. 실전 중심으로 Flask의 흐름을 이해하고 싶은 분들께 도움이 되길 바랍니다.
🔍 Flask란?
- Python 기반의 마이크로 웹 프레임워크
- 경량, 유연성, 빠른 개발 속도
- Django와 다르게 사용자가 구조를 직접 설계 가능
🧱 Flask 기본 구조 vs 실전 프로젝트 구조 비교
Flask는 기본적으로 단순한 구조를 가지고 있지만, 실제 프로젝트에서는 기능이 많아지면서 구조를 확장하게 됩니다.
아래는 기본적인 구조와 GarbageGuard 프로젝트에서 실제 사용한 구조를 비교한 내용입니다.
📦 기본 Flask 구조 (튜토리얼 기준)
my_flask_app/
├── app.py # 메인 서버 코드
├── templates/ # HTML 템플릿 (Jinja2)
│ └── index.html
├── static/ # 정적 파일 (CSS, JS, 이미지 등)
│ ├── css/
│ ├── js/
│ └── img/
└── requirements.txt # 필요한 패키지 목록
📌 특징:
- 소규모 프로젝트나 학습용에 적합
- 라우팅, 로직, 데이터 처리가 모두 app.py에 몰려 있음
🛠 GarbageGuard 구조 (실전 프로젝트 기준)
GarbageGuard/
├── app.py # 서버 진입점 (Flask 인스턴스 실행)
├── run_ngrok.py # 외부 접속 테스트용 ngrok 실행
├── train_codd.py # CODD 데이터셋 학습 스크립트
├── yolo11n.pt # 학습된 모델 가중치
├── yolov8n.pt # 기본 YOLOv8 가중치
│
├── .venv1/ # 가상환경
├── calculators/ # 탄소 배출량 계산기 관련 모듈
├── config/ # 환경 설정 (경로, 변수 등)
├── datasets/ # 학습용 데이터셋 저장소
├── db/ # DB 연결 및 쿼리 처리 (ex. MySQL 연동)
├── routes/ # 라우팅만 분리
├── services/ # 업로드, YOLO 분석, 통계 처리 등 핵심 로직
├── utils/ # 보조 모듈 (ex. 이미지 분석, 파일처리)
├── test_images/ # 테스트 이미지 저장 폴더
├── uploads/ # 업로드된 이미지 저장 경로
├── templates/ # 사용자 UI용 HTML 템플릿
├── static/ # 정적 자산 (CSS, JS, 이미지 등)
│ ├── css/
│ ├── js/
│ └── img/
├── requirements.txt # 전체 패키지 목록
└── README.md # 프로젝트 설명 문서
📌 특징:
- 역할별 폴더 분리
- ML 모델 연동, DB 처리, API 관리가 나누기
🎯 핵심 비교 요약
| 항목 | 기본 구조 | 실전 구조 (GarbageGuard) |
|---|---|---|
| 규모 | 소규모 프로젝트 | 중~대규모 기능 포함 프로젝트 |
| app.py 역할 | 모든 기능 몰빵 | 진입점 역할만, 나머지는 분리 |
| 라우팅 관리 | app.py 내부에서 직접 작성 | routes/ 폴더에 분리 |
| 로직 처리 | app.py에 직접 구현 | services/, utils/로 분리 |
| 정적 리소스 | static/ | static/ (같음) |
| 템플릿 | templates/ | templates/ (같음) |
Flask는 기본 구조가 단순해서 입문에 좋지만,
서비스/유틸/DB/라우터 등 분리 구조을 하여 관리하기
편하게 만들어 보았습니다.
⚙️ Flask 서버 실행 방법
패키지 설치
pip install -r requirements.txt
서버 실행
python app.py
브라우저에서 접속
🔄 Flask 요청 처리 흐름
[브라우저 요청]
↓
[Flask 라우팅 (@app.route)]
↓
[서비스 로직 실행 (YOLO 분석, DB 저장 등)]
↓
[HTML 템플릿 or JSON 응답]
↓
[결과 사용자에게 표시]
📌 예시: 이미지 업로드 → YOLO 분석 → 결과 출력
@app.route('/upload', methods=['POST'])
def upload():
file = request.files['file']
filename = secure_filename(file.filename)
filepath = os.path.join(app.config['UPLOAD_FOLDER'], filename)
file.save(filepath)result_img, result_data = analyze_image(filepath) # YOLO 처리
return render_template('result.html', result=result_data, image_path=filename)HTML 예시 (templates/index.html)
<form action="/upload" method="POST" enctype="multipart/form-data">
<input type="file" name="file" />
<button type="submit">업로드</button>
</form>업로드
🧠 구조 확장 팁 (모듈 분리)
규모가 커지면 다음과 같이 구조 분리:
GarbageGuard/
├── app.py
├── services/
│ └── upload_service.py
├── utils/
│ └── image_analysis.py
├── db/
│ └── db_manager.py
유지보수와 협업을 위한 코드 분리:
라우터, 로직, DB 함수 각각 분리해서 사용
🧩 사용하며 든 생각
- 파일 경로 관리,
url_for()잘 써야 정적 리소스 문제 없음 - Jinja2 템플릿 문법에 익숙해지면 HTML 효율 증가
- YOLO 모델 연동 시 구조 잘 잡으면 성능 Bottleneck 줄임
- 디버깅은
print,logging, Flask 디버그 모드 적극 활용
✍️ 마무리
Flask는 단순하면서도 유연해서 실전 프로젝트 구조 설계에 최적입니다.
YOLO 같은 머신러닝 모델 연동에도 무리 없고, HTML/CSS/JS까지 연계하면
강력한 웹 서비스를 빠르게 구축할 수 있습니다.
다음 포스트에서는 Flask + MySQL 연동, Chart.js 시각화, YOLOv8 모델 결과 처리 등을 이어서 다룰 예정입니다!
👉 GitHub: https://github.com/MinGiTae/GarbageGuard
굿굿~