Flask를 실무 흐름으로 이해하기
Flask로 작고 명시적인 Python 웹 서비스를 만듭니다. 라우팅, Blueprint 구조화, 설정 분리, SQLAlchemy 연동, 테스트, WSGI 배포까지 실무 흐름으로 정리했습니다. 이 가이드는 개념을 나열하기보다, 실제 프로젝트에서 판단해야 하는 순서대로 내용을 따라갈 수 있게 구성했습니다.
Python 마이크로 웹 프레임워크 가이드
Flask 완전 가이드
Flask로 작고 명시적인 Python 웹 서비스를 만듭니다. 라우팅, Blueprint 구조화, 설정 분리, SQLAlchemy 연동, 테스트, WSGI 배포까지 실무 흐름으로 정리했습니다.
가이드 사용법
백엔드 / 시스템 개발
문법보다 요청이 들어와 검증, 처리, 저장, 응답으로 이어지는 경계를 먼저 잡습니다.
구조 다이어그램
글로 읽은 내용을 머릿속에 오래 남기려면 먼저 흐름을 그림으로 잡는 편이 좋습니다. 아래 두 그림은 Flask를 학습할 때 계속 되돌아볼 수 있는 기준 지도입니다.
학습 흐름
다이어그램 렌더링 중…
아키텍처 관점
다이어그램 렌더링 중…
Flask란?
Flask를 처음 펼칠 때는 세부 명령보다 큰 그림이 먼저입니다. 이 섹션에서는 앞으로 배울 개념들이 어떤 문제를 풀기 위해 등장했는지부터 잡아봅니다.
Flask는 필요한 기능을 직접 선택해 조립하는 Python 마이크로 웹 프레임워크입니다. Django처럼 관리자, ORM, 인증을 기본 포함하지 않기 때문에 작은 API 서버, 내부 도구, 빠른 프로토타입에 잘 맞습니다. 대신 프로젝트가 커질수록 디렉터리 구조, 설정, 확장 라이브러리 선택 기준을 명확히 잡아야 합니다.
| 구분 | Flask | Django |
|---|---|---|
| 철학 | 작고 명시적인 코어 | batteries included |
| 구조 | Blueprint와 확장으로 직접 구성 | 프로젝트/app 구조 기본 제공 |
| 데이터 | SQLAlchemy 등 선택 | ORM 기본 포함 |
| 적합한 상황 | 작은 API, 마이크로서비스, 빠른 실험 | 관리자/인증/ORM이 필요한 제품형 서비스 |
프로젝트 설정
여기서는 프로젝트 설정을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.
Flask는 최소 코드로 바로 실행할 수 있지만, 실무에서는 app factory 구조로 시작하는 편이 좋습니다. 테스트와 설정 분리가 쉬워지고, 여러 환경에서 같은 앱을 안전하게 만들 수 있습니다.
BASH
uv venv
source .venv/bin/activate
uv pip install flask gunicorn pytest
mkdir -p app tests
touch app/__init__.py app/routes.py tests/test_app.py
flask --app app run --debug라우팅
여기서는 라우팅을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.
Flask 라우트는 함수와 URL을 직접 연결합니다. 작은 예제에서는 단일 파일도 가능하지만, API가 늘어나면 라우트 함수가 비즈니스 로직을 모두 품지 않도록 service 계층을 분리해야 합니다.
app/__init__.pyPYTHON
from flask import Flask, jsonify, request
def create_app() -> Flask:
app = Flask(__name__)
@app.get("/health")
def health():
return {"status": "ok"}
@app.post("/items")
def create_item():
payload = request.get_json(silent=True) or {}
name = payload.get("name")
if not name:
return jsonify({"error": "name is required"}), 400
return jsonify({"id": 1, "name": name}), 201
return appBlueprint 구조
여기서는 Blueprint 구조을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.
Blueprint는 Flask 앱을 기능 단위로 나누는 기본 도구입니다. users, auth, admin, api처럼 경계를 나누면 URL 등록, 테스트, 유지보수가 쉬워집니다.
app/users.pyPYTHON
from flask import Blueprint, jsonify
bp = Blueprint("users", __name__, url_prefix="/users")
@bp.get("/")
def list_users():
return jsonify([
{"id": 1, "name": "Ada"},
{"id": 2, "name": "Linus"},
])app/__init__.pyPYTHON
from flask import Flask
from .users import bp as users_bp
def create_app() -> Flask:
app = Flask(__name__)
app.register_blueprint(users_bp)
return app설정 분리
여기서는 설정 분리을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.
운영 코드에서 secret, database url, debug 값을 하드코딩하면 안 됩니다. 환경변수를 읽어 설정 객체를 만들고, 테스트에서는 별도 설정을 주입하세요.
app/config.pyPYTHON
import os
class Config:
SECRET_KEY = os.getenv("SECRET_KEY", "dev-only")
DATABASE_URL = os.getenv("DATABASE_URL", "sqlite:///app.db")
JSON_SORT_KEYS = False
class TestConfig(Config):
TESTING = True
DATABASE_URL = "sqlite:///:memory:"SQLAlchemy 연동
여기서는 SQLAlchemy 연동을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.
Flask 자체는 ORM을 포함하지 않습니다. Flask-SQLAlchemy를 사용하면 앱 컨텍스트와 SQLAlchemy 세션을 편하게 연결할 수 있습니다. 모델과 라우트를 분리하고, 트랜잭션 실패 시 rollback 기준을 명확히 두세요.
BASH
uv pip install flask-sqlalchemyapp/models.pyPYTHON
from flask_sqlalchemy import SQLAlchemy
db = SQLAlchemy()
class User(db.Model):
id = db.Column(db.Integer, primary_key=True)
email = db.Column(db.String(120), unique=True, nullable=False)
name = db.Column(db.String(80), nullable=False)
def to_dict(self) -> dict:
return {"id": self.id, "email": self.email, "name": self.name}테스트
여기서는 테스트을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.
Flask는 test_client를 기본 제공합니다. 네트워크를 띄우지 않고 요청/응답, 상태 코드, JSON body를 검증할 수 있습니다.
tests/test_app.pyPYTHON
from app import create_app
def test_health():
app = create_app()
client = app.test_client()
res = client.get("/health")
assert res.status_code == 200
assert res.get_json() == {"status": "ok"}
def test_create_item_requires_name():
app = create_app()
client = app.test_client()
res = client.post("/items", json={})
assert res.status_code == 400
assert "error" in res.get_json()WSGI 배포
여기서는 WSGI 배포을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.
개발 서버는 운영용이 아닙니다. 운영에서는 Gunicorn 같은 WSGI 서버 뒤에 Nginx나 Cloud Run, container platform을 두고 timeout, worker 수, 로그 포맷, health check를 관리해야 합니다.
BASH
gunicorn "app:create_app()" \
--bind 0.0.0.0:8000 \
--workers 2 \
--timeout 30 \
--access-logfile -Flask 실무 설계
Flask 실무 설계은 선택지가 갈리는 지점입니다. 표를 기준으로 각 방법의 쓰임새와 운영상의 차이를 비교해두면 이후 판단이 훨씬 쉬워집니다.
Flask는 자유도가 높은 만큼 app factory, Blueprint, config, extension 초기화 경계를 명확히 잡아야 합니다. 작은 파일 하나로 시작하더라도 route, service, model, config를 분리할 기준을 미리 정하는 것이 중요합니다.
| 결정 지점 | 확인 질문 | 실무 기준 |
|---|---|---|
| 경계 | Flask 코드에서 바뀌기 쉬운 부분은 어디인가? | 입출력, 설정, 외부 연동, 핵심 규칙을 분리합니다. |
| 상태 | 상태가 어디서 생성되고 어디서 사라지는가? | 상태 소유자와 수명 주기를 코드로 드러냅니다. |
| 장애 | 실패했을 때 호출자는 무엇을 받는가? | timeout, fallback, error contract를 먼저 정합니다. |
Flask 운영 기준
이 섹션은 Flask 운영 기준을 실무 관점에서 정리합니다. 개념을 외우기보다, 어떤 상황에서 이 기준을 꺼내 쓸지에 초점을 맞춰보세요.
운영에서는 Gunicorn worker 수, request timeout, reverse proxy header, structured logging, health check, secret 주입 방식을 관리해야 합니다.
Flask 검증 전략
Flask 검증 전략은 선택지가 갈리는 지점입니다. 표를 기준으로 각 방법의 쓰임새와 운영상의 차이를 비교해두면 이후 판단이 훨씬 쉬워집니다.
Flask 테스트는 test_client, fixture 기반 app factory, config override, error response contract를 함께 검증해야 합니다.
| 품질 축 | 검증 방법 | 완료 기준 |
|---|---|---|
| 정확성 | 정상/실패 케이스를 자동화합니다. | 핵심 시나리오가 재현 가능하게 통과합니다. |
| 회귀 방지 | 버그 수정 시 동일 케이스를 테스트로 남깁니다. | 같은 장애가 다시 배포되지 않습니다. |
| 운영성 | 로그, 메트릭, 알림을 확인합니다. | 문제가 생겼을 때 원인 추적 경로가 있습니다. |