김신건의 로그 - 위키 / flask

[Flask] Application Factory Pattern

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Application Factory 는 Flask 앱 인스턴스를 함수 안에서 생성 하는 패턴입니다. 모듈 스코프에 app = Flask(__name__) 를 두는 대신 create_app(config_name) 함수를 정의해 반환합니다.

이 패턴은 사실상 모든 non-trivial Flask 프로젝트의 표준 입니다.

왜 필요한가

1. 여러 앱 인스턴스

테스트: 각 테스트가 독립된 앱 인스턴스 (config, DB)
여러 환경: dev/staging/prod 를 코드 변경 없이 config 만 바꿔 인스턴스화
멀티-테넌시: 한 프로세스 안에서 여러 앱

2. 순환 import 회피

모듈 스코프 app 은 확장 (extension) 초기화 시점 문제:

# BAD: 순환 import
# app.py
from flask import Flask
from myapp.models import User    # 이 파일이 app 을 import 하면 순환

app = Flask(__name__)

Factory 패턴은 create_app 안에서 import 하여 우회.

3. Extension 지연 초기화

db = SQLAlchemy() 를 모듈 스코프에, db.init_app(app) 을 factory 안에 두어 여러 앱과 조합 가능.

4. Blueprint 등록 지점 명확화

Factory 함수 하나가 앱 조립의 유일한 진입점. 어디서 무엇이 등록되는지 명확.

기본 구조

myapp/
├── src/
│   └── myapp/
│       ├── __init__.py       # create_app
│       ├── config.py
│       ├── extensions.py     # db, migrate, login 등 인스턴스
│       ├── models.py
│       ├── auth/
│       │   └── routes.py     # Blueprint
│       ├── main/
│       │   └── routes.py     # Blueprint
│       └── cli.py            # 커스텀 CLI 명령
├── migrations/
├── tests/
├── wsgi.py                   # 진입점
└── pyproject.toml

1. Config

# myapp/config.py
import os

class Config:
    SECRET_KEY = os.environ["SECRET_KEY"]
    SQLALCHEMY_DATABASE_URI = os.environ["DATABASE_URL"]
    SESSION_COOKIE_SECURE = True
    SESSION_COOKIE_HTTPONLY = True
    SESSION_COOKIE_SAMESITE = "Lax"

class DevelopmentConfig(Config):
    DEBUG = True
    SESSION_COOKIE_SECURE = False

class TestingConfig(Config):
    TESTING = True
    SQLALCHEMY_DATABASE_URI = "sqlite:///:memory:"
    WTF_CSRF_ENABLED = False

class ProductionConfig(Config):
    pass

def get_config(name: str = "production") -> type[Config]:
    return {
        "development": DevelopmentConfig,
        "testing": TestingConfig,
        "production": ProductionConfig,
    }[name]

2. Extensions

# myapp/extensions.py
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate
from flask_login import LoginManager
from flask_wtf.csrf import CSRFProtect
from flask_caching import Cache

db = SQLAlchemy()
migrate = Migrate()
login = LoginManager()
csrf = CSRFProtect()
cache = Cache()

3. Factory 함수

# myapp/__init__.py
from flask import Flask
from myapp.config import get_config
from myapp.extensions import db, migrate, login, csrf, cache

def create_app(config_name: str = "production") -> Flask:
    app = Flask(__name__, instance_relative_config=True)
    app.config.from_object(get_config(config_name))

    _init_extensions(app)
    _register_blueprints(app)
    _register_error_handlers(app)
    _register_cli(app)
    _register_shell_context(app)

    return app

def _init_extensions(app: Flask) -> None:
    db.init_app(app)
    migrate.init_app(app, db)
    login.init_app(app)
    csrf.init_app(app)
    cache.init_app(app, config={"CACHE_TYPE": "RedisCache"})

    login.login_view = "auth.login"

    @login.user_loader
    def load_user(user_id: str):
        from myapp.models import User
        return db.session.get(User, int(user_id))

def _register_blueprints(app: Flask) -> None:
    from myapp.auth.routes import bp as auth_bp
    from myapp.main.routes import bp as main_bp
    from myapp.api.v1 import bp as api_v1_bp

    app.register_blueprint(auth_bp, url_prefix="/auth")
    app.register_blueprint(api_v1_bp, url_prefix="/api/v1")
    app.register_blueprint(main_bp)

def _register_error_handlers(app: Flask) -> None:
    from flask import jsonify

    @app.errorhandler(404)
    def not_found(e):
        return jsonify(error="not_found"), 404

    @app.errorhandler(500)
    def server_error(e):
        return jsonify(error="server_error"), 500

def _register_cli(app: Flask) -> None:
    from myapp.cli import seed_db, clear_cache

    app.cli.add_command(seed_db)
    app.cli.add_command(clear_cache)

def _register_shell_context(app: Flask) -> None:
    @app.shell_context_processor
    def make_context():
        from myapp.models import User, Item
        return {"db": db, "User": User, "Item": Item}

4. WSGI 진입점

# wsgi.py
import os
from myapp import create_app

config_name = os.environ.get("FLASK_ENV", "production")
app = create_app(config_name)

if __name__ == "__main__":
    app.run()

gunicorn myapp:create_app() 또는 gunicorn wsgi:app.

`flask` CLI 통합

export FLASK_APP="myapp:create_app('development')"
flask run
flask db migrate -m "add users"
flask db upgrade
flask seed-db --count 100

또는 .flaskenv (python-dotenv):

FLASK_APP=myapp:create_app('development')

Blueprint 순서 관리

Blueprint 등록 순서가 URL 매칭 순서에 영향 (같은 URL 이 여러 blueprint 에 걸릴 때 첫 번째 승리):

# 순서 중요
app.register_blueprint(auth_bp, url_prefix="/auth")   # 먼저: /auth/*
app.register_blueprint(main_bp)                        # 나중: 나머지

여러 앱 인스턴스 (테스트)

# tests/conftest.py
import pytest
from myapp import create_app
from myapp.extensions import db

@pytest.fixture
def app():
    app = create_app("testing")
    with app.app_context():
        db.create_all()
        yield app
        db.session.remove()
        db.drop_all()

@pytest.fixture
def client(app):
    return app.test_client()

각 테스트가 완전히 격리된 앱을 갖음.

App Context 관리

Extension 초기화 이후 current_app, db 를 사용하려면 app context 필요:

with app.app_context():
    db.create_all()          # 스크립트, 마이그레이션 등
    User(email="a@b.com").insert()

Request 안에서는 자동으로 활성. Background thread 나 CLI 에서는 명시 필요.

Shell context

@app.shell_context_processor
def make_context():
    return {"db": db, "User": User}

이후 flask shell 실행 시 자동으로 이 변수들이 REPL 에 노출.

함정

[!WARNING] Extension 을 모듈 스코프에서 app 을 참조하면 안 됨. db = SQLAlchemy(app) 은 factory 패턴에서 못 쓸 방식. db = SQLAlchemy() + db.init_app(app).

[!CAUTION] Blueprint import 를 모듈 상단이 아니라 factory 안에서. 순환 import 회피의 핵심.

[!WARNING] 여러 앱에서 db.session 공유. Flask-SQLAlchemy 는 앱 컨텍스트별로 세션 관리. Threading 이나 background 에서 잘못 쓰면 오염.

[!IMPORTANT] Config class 상속 순서. TestingConfig(Config) 는 부모의 SECRET_KEY 를 상속. 테스트에서 명시적 값 override.

[!CAUTION] app.config.from_object 는 대문자 필드만. 소문자는 무시. 관용 지키기.

[Flask] Blueprints

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Blueprint 는 Flask 앱을 여러 모듈로 나누는 표준 도구입니다. 라우트, 정적파일, 템플릿, before/after hook, error handler 를 그룹화해 create_app 에서 조립합니다. Django 의 app, Rails 의 engine 유사.

왜 필요한가

모듈 분리: 인증, API, 관리자 등 도메인별 파일 분리
URL prefix: /api/v1/*, /admin/* 등 서브트리 관리
재사용: 여러 프로젝트에서 공통 blueprint 재사용
테스트 격리: blueprint 단위 테스트

기본 사용

정의

# myapp/auth/routes.py
from flask import Blueprint, request, jsonify

bp = Blueprint(
    "auth",
    __name__,
    url_prefix="/auth",
    template_folder="templates",
    static_folder="static",
)

@bp.post("/login")
def login():
    ...
    return jsonify({"token": "..."})

@bp.post("/logout")
def logout():
    ...
    return "", 204

@bp.get("/me")
def me():
    ...
    return jsonify({"user": ...})

등록

# myapp/__init__.py
from flask import Flask
from myapp.auth.routes import bp as auth_bp
from myapp.main.routes import bp as main_bp

def create_app():
    app = Flask(__name__)
    app.register_blueprint(auth_bp)
    app.register_blueprint(main_bp)
    return app

Endpoint 이름은 blueprint.endpoint 형식:

url_for("auth.login")     # /auth/login
url_for("main.index")     # /

Blueprint 생성 인자

Blueprint(
    name="auth",                    # endpoint prefix
    import_name=__name__,           # root 위치 추정
    url_prefix="/auth",             # 모든 route 앞에
    subdomain=None,                 # 서브도메인
    template_folder="templates",    # blueprint 별 템플릿
    static_folder="static",         # blueprint 별 정적
    static_url_path="/auth-static", # 정적 URL
    root_path=None,
    url_defaults=None,
)

register_blueprint 옵션

app.register_blueprint(auth_bp, url_prefix="/api/auth")   # override
app.register_blueprint(auth_bp, url_prefix="/v2/auth", name="auth_v2")  # 두 번 등록

같은 blueprint 를 다른 prefix 로 여러 번 등록도 가능 (버전 라우팅).

Blueprint hook

Blueprint 는 자기만의 lifecycle hook 을 가짐.

bp = Blueprint("api", __name__)

@bp.before_request
def api_before():
    if not request.headers.get("X-API-Key"):
        abort(401)

@bp.after_request
def api_after(response):
    response.headers["X-API-Version"] = "1.0"
    return response

@bp.errorhandler(404)
def api_not_found(e):
    return {"error": "not found"}, 404

@bp.errorhandler(Exception)
def api_error(e):
    return {"error": str(e)}, 500

이 hook 은 이 blueprint 의 라우트에만 적용.

Nested Blueprint (Flask 2.0+)

Blueprint 안에 blueprint 를 등록.

api_bp = Blueprint("api", __name__, url_prefix="/api")
users_bp = Blueprint("users", __name__, url_prefix="/users")

@users_bp.get("/<int:id>")
def get_user(id):
    return f"user {id}"

api_bp.register_blueprint(users_bp)
app.register_blueprint(api_bp)

# 최종 URL: /api/users/1
# endpoint: api.users.get_user

주의: 중첩 시 endpoint 이름이 . 로 연결됩니다.

프로젝트 구조 예시

myapp/
├── src/
│   └── myapp/
│       ├── __init__.py           # create_app
│       ├── auth/
│       │   ├── __init__.py
│       │   ├── routes.py          # bp = Blueprint("auth", ...)
│       │   ├── forms.py
│       │   └── templates/
│       │       └── auth/
│       │           └── login.html
│       ├── api/
│       │   ├── __init__.py
│       │   ├── v1/
│       │   │   ├── __init__.py
│       │   │   ├── users.py       # bp_users = Blueprint("users", ...)
│       │   │   └── items.py
│       │   └── v2/
│       │       └── users.py
│       └── admin/
│           └── routes.py

create_app 에서 blueprint 조립:

def create_app():
    app = Flask(__name__)
    app.config.from_object("myapp.config.Config")

    # DB, extensions
    db.init_app(app)

    # Blueprints
    from myapp.auth.routes import bp as auth_bp
    from myapp.api.v1.users import bp as api_users_bp
    from myapp.api.v1.items import bp as api_items_bp
    from myapp.admin.routes import bp as admin_bp

    api_v1 = Blueprint("api_v1", __name__, url_prefix="/api/v1")
    api_v1.register_blueprint(api_users_bp)
    api_v1.register_blueprint(api_items_bp)

    app.register_blueprint(auth_bp)
    app.register_blueprint(api_v1)
    app.register_blueprint(admin_bp)

    return app

Blueprint 안에서 url_for

같은 blueprint 내 상대 참조 (.endpoint):

@bp.get("/login")
def login():
    return redirect(url_for(".dashboard"))  # 같은 blueprint 의 dashboard

@bp.get("/dashboard")
def dashboard():
    return "..."

다른 blueprint 참조:

url_for("main.index")
url_for("api_v1.users.get_user", id=1)

Template folder 규칙

Blueprint 의 template_folder="templates" 는 blueprint 경로 상대. 예를 들어 myapp/auth/templates/ 는:

render_template("auth/login.html") -> myapp/auth/templates/auth/login.html
앱 전체 templates/ 와 병합

관용: blueprint 명 하위 폴더 (templates/auth/) 로 격리해 이름 충돌 방지.

Static folder 규칙

bp = Blueprint("auth", __name__, static_folder="static", static_url_path="/auth-static")

접근 URL: /auth-static/logo.png -> myapp/auth/static/logo.png
url_for("auth.static", filename="logo.png") 로 생성

Blueprint 로 재사용 가능한 컴포넌트

Blueprint 를 별도 패키지로 배포 (예: flask-user-auth 라이브러리):

# my_pkg/blueprint.py
from flask import Blueprint

user_bp = Blueprint("user", __name__, url_prefix="/user", template_folder="templates")

@user_bp.get("/profile")
def profile():
    ...

사용:

from my_pkg.blueprint import user_bp
app.register_blueprint(user_bp)

Flask-Login, Flask-Admin 등 많은 extension 이 blueprint 로 동작.

CLI Command (Blueprint 별)

import click

@bp.cli.command("seed")
@click.argument("count", type=int)
def seed(count):
    for _ in range(count):
        db.session.add(User(...))
    db.session.commit()
    click.echo(f"Seeded {count} users.")

flask auth seed 100

함정

[!WARNING] Blueprint 이름 중복 하면 AssertionError. 여러 번 등록하려면 name= override.

[!CAUTION] Endpoint 이름 접두어. url_for("index") 는 어떤 blueprint 의 것인지 모호. url_for("main.index") 처럼 명시.

[!WARNING] Circular import. Blueprint 파일이 from myapp import db 하고 myapp/__init__.py 가 blueprint 를 import 하면 순환. create_app 안에서 import 하는 관용으로 해결.

[!IMPORTANT] Blueprint 별 config. Blueprint 자체는 config 를 못 가짐. current_app.config 로 접근.

[!CAUTION] Nested blueprint 의 URL 계산. url_prefix 가 chain 되어 예상보다 깊어질 수 있음. flask routes 로 확인.

[Flask] Deployment (WSGI, Gunicorn, uWSGI, Docker)

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Flask 는 WSGI 앱. 프로덕션 배포는 WSGI 서버 (Gunicorn, uWSGI, gevent) + 리버스 프록시 (Nginx, ALB) + 컨테이너 (Docker) + 오케스트레이터 (Kubernetes/ECS) 계층으로 구성됩니다. 내장 개발 서버 (app.run) 은 절대 프로덕션 노출 금지.

구성 계층

[Client]
   ↓ HTTPS
[Load Balancer / CDN (ALB, CloudFront, Nginx)]
   ↓ HTTP
[WSGI 서버 (Gunicorn / uWSGI)]
   ↓ 프로세스 워커
[Flask WSGI 앱]

왜 개발 서버는 안 되는가

app.run(debug=True) 는 Werkzeug 개발 서버.

Single-threaded (기본): 동시 요청 처리 불가
debug=True 는 원격 코드 실행 취약점
성능 최적화 안 됨
Graceful shutdown 미지원
FLASK_DEBUG=1 + PIN 없이 노출 = 서버 완전 장악 가능

Gunicorn (권장)

pre-fork 워커 모델. Python WSGI 서버의 사실상 표준.

pip install gunicorn

gunicorn myapp:create_app\(\) \
  --workers 4 \
  --worker-class sync \
  --bind 0.0.0.0:8000 \
  --timeout 60 \
  --graceful-timeout 30 \
  --keep-alive 5 \
  --max-requests 10000 \
  --max-requests-jitter 100 \
  --access-logfile - \
  --error-logfile - \
  --log-level info

Worker 수

일반 공식: workers = 2 * cores + 1 (I/O bound). 조정 후 실제 부하로 조정.

메모리도 고려: 각 worker 는 프로세스 -> 앱 메모리 × workers.

Worker class

sync (기본): 요청당 하나. 표준.
gthread: 각 worker 안에 여러 스레드. I/O bound 유리.
gevent: 그린 스레드 (monkey patching). 매우 많은 동시 연결.
eventlet: gevent 유사.

gunicorn myapp:create_app\(\) --worker-class gthread --workers 4 --threads 4
# 총 동시 요청 = 4 * 4 = 16

Timeout

--timeout 60: worker 가 60초 응답 못 하면 kill. 정상값이지만 큰 파일 다운로드/업로드는 늘리기.
--graceful-timeout 30: SIGTERM 후 in-flight 요청 완료 대기.

max-requests

메모리 leak 완화. worker 가 N 요청 처리 후 재시작.

--max-requests 10000 --max-requests-jitter 100

Jitter 는 재시작 시점 랜덤화로 동시 재시작 방지.

uWSGI (대안)

기능 방대, 설정 복잡. 대규모 배포에서 여전히 쓰임.

# uwsgi.ini
[uwsgi]
module = myapp:create_app()
processes = 4
threads = 2
socket = 0.0.0.0:8000
harakiri = 60          # timeout
max-requests = 5000
vacuum = true
die-on-term = true

uwsgi --ini uwsgi.ini

Pros: 매우 많은 튜닝 옵션, 여러 언어 지원 Cons: 배우기 어려움, 최근 커뮤니티 활성도 감소 (Gunicorn 우세)

리버스 프록시 (Nginx)

upstream flask_app {
    server 127.0.0.1:8000;
    keepalive 32;
}

server {
    listen 443 ssl http2;
    server_name app.example.com;

    ssl_certificate /etc/ssl/cert.pem;
    ssl_certificate_key /etc/ssl/key.pem;

    client_max_body_size 10M;
    keepalive_timeout 65;

    location /static/ {
        alias /var/www/myapp/static/;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    location / {
        proxy_pass http://flask_app;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_read_timeout 60s;
    }
}

ProxyFix (X-Forwarded-* 신뢰)

리버스 프록시 뒤에서 실제 client IP, scheme (http/https), host 를 제대로 인식하려면:

from werkzeug.middleware.proxy_fix import ProxyFix

app.wsgi_app = ProxyFix(
    app.wsgi_app,
    x_for=1,        # X-Forwarded-For 신뢰 개수
    x_proto=1,      # X-Forwarded-Proto
    x_host=1,       # X-Forwarded-Host
    x_prefix=1,     # X-Forwarded-Prefix (subpath)
)

x_for=1: 프록시 하나만 신뢰. 여러 프록시 (ALB + CloudFront) 는 개수 증가.
이 미들웨어 없이는 request.remote_addr 이 프록시 IP 만 반환.
잘못 신뢰하면 IP 스푸핑 가능. 실제 신뢰할 프록시 개수 정확히.

Docker

기본 Dockerfile

FROM python:3.12-slim

WORKDIR /app

RUN apt-get update && apt-get install -y --no-install-recommends \
    libpq-dev gcc && \
    rm -rf /var/lib/apt/lists/*

COPY pyproject.toml uv.lock ./
RUN pip install --no-cache-dir uv && \
    uv sync --frozen --no-dev

COPY src /app/src

RUN useradd -m -u 1000 app && chown -R app:app /app
USER app

EXPOSE 8000

CMD ["uv", "run", "gunicorn", \
     "myapp:create_app()", \
     "--workers", "4", \
     "--bind", "0.0.0.0:8000", \
     "--access-logfile", "-", \
     "--error-logfile", "-"]

Multi-stage build

FROM python:3.12-slim AS builder
WORKDIR /app
RUN pip install uv
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev

FROM python:3.12-slim
WORKDIR /app
RUN apt-get update && apt-get install -y --no-install-recommends libpq5 && rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/.venv /app/.venv
COPY src /app/src
ENV PATH="/app/.venv/bin:$PATH"

RUN useradd -m -u 1000 app && chown -R app:app /app
USER app

CMD ["gunicorn", "myapp:create_app()", "--workers", "4", "--bind", "0.0.0.0:8000"]

Kubernetes 배포

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 3
  selector:
    matchLabels: {app: myapp}
  template:
    metadata:
      labels: {app: myapp}
    spec:
      terminationGracePeriodSeconds: 60
      containers:
        - name: app
          image: myrepo/myapp:1.0
          ports: [{containerPort: 8000}]
          env:
            - name: SECRET_KEY
              valueFrom:
                secretKeyRef: {name: myapp-secrets, key: secret-key}
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef: {name: myapp-secrets, key: db-url}
          resources:
            requests: {cpu: 500m, memory: 512Mi}
            limits: {cpu: 2, memory: 2Gi}
          livenessProbe:
            httpGet: {path: /health/live, port: 8000}
            initialDelaySeconds: 30
            periodSeconds: 10
          readinessProbe:
            httpGet: {path: /health/ready, port: 8000}
            periodSeconds: 5
          lifecycle:
            preStop:
              exec:
                command: ["sleep", "5"]

Health check endpoint:

@app.get("/health/live")
def live():
    return "ok"

@app.get("/health/ready")
def ready():
    try:
        db.session.execute(text("SELECT 1"))
        return "ok"
    except Exception:
        return "not ready", 503

Signal handling

Gunicorn signal:

SIGTERM: graceful shutdown (기본 K8s 종료)
SIGINT (Ctrl+C): graceful shutdown
SIGQUIT: 즉시 종료
SIGHUP: reload workers

terminationGracePeriodSeconds > gunicorn --graceful-timeout 이어야 in-flight 요청 완료.

로깅

구조화 로그 (JSON)

import logging
from pythonjsonlogger import jsonlogger

def setup_logging(app):
    handler = logging.StreamHandler()
    handler.setFormatter(jsonlogger.JsonFormatter(
        "%(asctime)s %(name)s %(levelname)s %(message)s"
    ))
    app.logger.addHandler(handler)
    app.logger.setLevel(logging.INFO)

Gunicorn access log 도 커스터마이제이션:

# gunicorn.conf.py
import json

def json_access_log_format(record):
    return json.dumps({
        "method": record.request_line.split()[0],
        "path": record.request_line.split()[1],
        "status": record.status_code,
        "response_time": record.response_time,
    })

# gunicorn --access-logformat '{}' --logger-class 'gunicorn.glogging.Logger'

Sentry, OpenTelemetry

import sentry_sdk
from sentry_sdk.integrations.flask import FlaskIntegration
from sentry_sdk.integrations.sqlalchemy import SqlalchemyIntegration

sentry_sdk.init(
    dsn="https://xxx@sentry.io/yyy",
    integrations=[FlaskIntegration(), SqlalchemyIntegration()],
    traces_sample_rate=0.1,
    profiles_sample_rate=0.1,
)

정적 파일

프로덕션에서 Flask 가 정적 파일 서빙하지 마세요. Nginx 나 CDN (CloudFront) 에서 서빙.

Whitenoise (덜 권장, 소규모):

from whitenoise import WhiteNoise
app.wsgi_app = WhiteNoise(app.wsgi_app, root="static/")

환경 변수 & Secrets

class Config:
    SECRET_KEY = os.environ["SECRET_KEY"]
    DATABASE_URL = os.environ["DATABASE_URL"]

Kubernetes Secret, AWS Secrets Manager, Vault 등에서 주입. Docker 이미지에 secret 굽지 마세요.

성능 튜닝 체크리스트

Worker 수 = 2×CPU + 1 부터 시작, 부하 관찰 후 조정
--max-requests 로 memory leak 완화
DB connection pool: SQLALCHEMY_ENGINE_OPTIONS 에 pool_size, max_overflow, pool_recycle
정적 파일은 CDN/Nginx
캐시 ([[flask-extensions|Flask-Caching]]) Redis
N+1 쿼리 해결: SQLAlchemy joinedload, selectinload
Gzip: Nginx 에서 활성화 (Flask 에서 X)
HTTP/2: Nginx 에서 종단

함정

[!WARNING] app.run(debug=True) 프로덕션 노출 금지. RCE 취약점.

[!CAUTION] ProxyFix 개수 신중하게. 잘못 신뢰하면 IP 스푸핑. 실제 프록시 개수 정확히.

[!WARNING] Sync worker 로 sync DB + sync HTTP client 사용 시 요청당 한 워커 점유. 동시 처리량이 (workers × threads) 한계. gthread 나 gevent 로 확장.

[!IMPORTANT] Graceful shutdown 순서: LB 에서 제거 -> in-flight 요청 완료 -> DB 세션 정리 -> 프로세스 종료. K8s preStop sleep 5 은 LB 등록 해제 대기.

[!CAUTION] 정적 파일을 Flask 로 서빙하면 앱이 병목. Gunicorn worker 하나가 CSS/JS 다운로드 처리하는 낭비. Nginx / CloudFront.

[Flask] Extensions (SQLAlchemy, Login, Migrate, WTF, ...)

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Flask Extension 은 코어에 없는 기능 (DB, 인증, 마이그레이션, 캐시 등) 을 표준 인터페이스로 통합하는 서드파티 패키지입니다. ext.init_app(app) 패턴이 관용이며, [[flask-app-factory|application factory]] 와 자연스럽게 조합됩니다.

주요 extension 을 한 페이지에서 소개하고 실전 초기화 코드 를 정리합니다.

초기화 패턴 (extensions.py)

# myapp/extensions.py
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate
from flask_login import LoginManager
from flask_wtf.csrf import CSRFProtect
from flask_caching import Cache
from flask_cors import CORS
from flask_limiter import Limiter
from flask_limiter.util import get_remote_address

db = SQLAlchemy()
migrate = Migrate()
login = LoginManager()
csrf = CSRFProtect()
cache = Cache()
cors = CORS()
limiter = Limiter(key_func=get_remote_address)

# myapp/__init__.py
from myapp.extensions import db, migrate, login, csrf, cache, cors, limiter

def create_app():
    app = Flask(__name__)
    app.config.from_object("myapp.config.Config")

    db.init_app(app)
    migrate.init_app(app, db)
    login.init_app(app)
    csrf.init_app(app)
    cache.init_app(app, config={"CACHE_TYPE": "RedisCache"})
    cors.init_app(app, resources={r"/api/*": {"origins": "*"}})
    limiter.init_app(app)

    return app

핵심: extension 은 모듈 스코프에 인스턴스만 만들고, 앱 초기화는 create_app 안에서 init_app 으로. 이렇게 해야 여러 앱 인스턴스, 테스트에 유리.

Flask-SQLAlchemy 3.x

Flask 앱과 SQLAlchemy ORM 통합. Flask-SQLAlchemy 3.0+ 은 SQLAlchemy 2.0 async 스타일 API 지원.

설정

# config.py
class Config:
    SQLALCHEMY_DATABASE_URI = "postgresql+psycopg://user:pass@host:5432/db"
    SQLALCHEMY_ECHO = False
    SQLALCHEMY_ENGINE_OPTIONS = {
        "pool_size": 10,
        "max_overflow": 20,
        "pool_pre_ping": True,      # 연결 stale 감지
        "pool_recycle": 3600,       # 1시간마다 재연결
    }

모델

# models.py
from myapp.extensions import db
from sqlalchemy.orm import Mapped, mapped_column
from datetime import datetime

class User(db.Model):
    __tablename__ = "users"

    id: Mapped[int] = mapped_column(primary_key=True)
    email: Mapped[str] = mapped_column(unique=True, index=True)
    password_hash: Mapped[str]
    created_at: Mapped[datetime] = mapped_column(default=datetime.utcnow)

    def __repr__(self):
        return f"<User {self.email}>"

쿼리 (SQLAlchemy 2.0 style)

from sqlalchemy import select

@app.get("/users/<int:id>")
def get_user(id):
    user = db.session.get(User, id)
    if not user:
        abort(404)
    return {"email": user.email}

@app.get("/users/")
def list_users():
    stmt = select(User).where(User.created_at > since).order_by(User.email)
    users = db.session.scalars(stmt).all()
    return [{"email": u.email} for u in users]

@app.post("/users/")
def create_user():
    user = User(email=request.json["email"], password_hash=hash(request.json["password"]))
    db.session.add(user)
    db.session.commit()
    return {"id": user.id}, 201

트랜잭션

try:
    db.session.add(user)
    db.session.commit()
except Exception:
    db.session.rollback()
    raise

또는 context manager:

with db.session.begin():
    db.session.add(user)
    # commit 자동

Flask-Migrate

Alembic 을 Flask 앱에 통합.

pip install Flask-Migrate

flask db init                          # migrations/ 폴더 생성 (초기 1회)
flask db migrate -m "add users table"  # 자동 diff
flask db upgrade                        # DB 적용
flask db downgrade                      # 롤백
flask db history                        # 히스토리

Flask-Migrate 는 SQLAlchemy 모델을 스캔해 마이그레이션 파일 자동 생성. 완벽하지 않으니 반드시 검토.

세션 기반 인증. 자세한 것은 [[flask-sessions|Flask Sessions]] 참조.

class User(UserMixin, db.Model):
    ...

@login.user_loader
def load_user(user_id):
    return db.session.get(User, int(user_id))

@app.post("/login")
def login():
    user = User.query.filter_by(email=request.form["email"]).first()
    if user and check_password(request.form["password"], user.password_hash):
        login_user(user, remember=True)
        return redirect(url_for("dashboard"))
    return "invalid", 401

login_view, login_message, session_protection 등 설정 가능.

Flask-WTF

폼 정의 + CSRF.

from flask_wtf import FlaskForm
from wtforms import StringField, PasswordField
from wtforms.validators import DataRequired, Email, Length

class LoginForm(FlaskForm):
    email = StringField("이메일", validators=[DataRequired(), Email()])
    password = PasswordField("비밀번호", validators=[DataRequired(), Length(min=8)])

@app.route("/login", methods=["GET", "POST"])
def login():
    form = LoginForm()
    if form.validate_on_submit():
        # POST + CSRF valid + fields valid
        user = authenticate(form.email.data, form.password.data)
        if user:
            login_user(user)
            return redirect(url_for("dashboard"))
        form.email.errors.append("Invalid credentials")
    return render_template("login.html", form=form)

템플릿:

<form method="post">
  {{ form.hidden_tag() }}
  {{ form.email.label }} {{ form.email() }}
  {% for error in form.email.errors %}<span>{{ error }}</span>{% endfor %}
  {{ form.password.label }} {{ form.password() }}
  <button>Login</button>
</form>

Flask-Caching

메모리 / Redis / Memcached 캐시.

cache = Cache(config={"CACHE_TYPE": "RedisCache", "CACHE_REDIS_URL": "redis://localhost:6379"})

@app.get("/expensive/<int:id>")
@cache.cached(timeout=60, key_prefix=lambda: f"expensive:{request.view_args['id']}")
def expensive(id):
    result = heavy_computation(id)
    return {"result": result}

@app.get("/items")
@cache.memoize(300)
def list_items():
    return {"items": db.session.scalars(select(Item)).all()}

# 수동 삭제
cache.delete_memoized(list_items)

CACHE_TYPE

"SimpleCache": 인메모리 (단일 프로세스, dev 용)
"RedisCache": Redis (권장)
"MemcachedCache"
"FileSystemCache"
"NullCache": 캐시 안 함 (테스트)

Flask-CORS

Cross-Origin Resource Sharing.

CORS(app, resources={
    r"/api/*": {
        "origins": ["https://app.example.com"],
        "methods": ["GET", "POST", "PUT", "DELETE"],
        "allow_headers": ["Content-Type", "Authorization"],
        "supports_credentials": True,
    }
})

또는 데코레이터 단위:

from flask_cors import cross_origin

@app.get("/public")
@cross_origin()
def public():
    return "public"

Flask-JWT-Extended

JWT 인증 (세션 대신).

from flask_jwt_extended import JWTManager, create_access_token, jwt_required, get_jwt_identity

app.config["JWT_SECRET_KEY"] = "your-jwt-secret"
jwt = JWTManager(app)

@app.post("/login")
def login():
    if authenticate(...):
        token = create_access_token(identity=user_id, expires_delta=timedelta(hours=1))
        return {"access_token": token}
    return "unauth", 401

@app.get("/protected")
@jwt_required()
def protected():
    return {"user_id": get_jwt_identity()}

Refresh token, blocklist, cookie mode 등 지원.

Flask-Limiter

Rate limiting.

limiter = Limiter(key_func=get_remote_address, default_limits=["200 per day", "50 per hour"])
limiter.init_app(app)

@app.get("/expensive")
@limiter.limit("10 per minute")
def expensive():
    ...

@app.get("/exempt")
@limiter.exempt
def health():
    return "ok"

Redis 를 storage 로 하면 다중 프로세스에서도 정확한 카운트:

Limiter(
    storage_uri="redis://localhost:6379",
    key_func=get_remote_address,
)

Flask-Smorest / Flask-RESTX (OpenAPI)

FastAPI 스타일 OpenAPI 자동화 to Flask:

from flask_smorest import Api, Blueprint
from marshmallow import Schema, fields

app.config["API_TITLE"] = "My API"
app.config["API_VERSION"] = "v1"
app.config["OPENAPI_VERSION"] = "3.0.3"

api = Api(app)
bp = Blueprint("items", "items", url_prefix="/items")

class ItemSchema(Schema):
    id = fields.Int()
    name = fields.Str(required=True)

@bp.route("/")
class ItemList(MethodView):
    @bp.response(200, ItemSchema(many=True))
    def get(self):
        return db.session.scalars(select(Item)).all()

    @bp.arguments(ItemSchema)
    @bp.response(201, ItemSchema)
    def post(self, data):
        item = Item(**data)
        db.session.add(item)
        db.session.commit()
        return item

api.register_blueprint(bp)

Swagger UI 자동 생성 (/docs).

Flask-Talisman (보안 헤더)

CSP, HSTS 등 자동 삽입:

from flask_talisman import Talisman

Talisman(app,
    force_https=True,
    strict_transport_security=True,
    content_security_policy={
        "default-src": "'self'",
        "img-src": "* data:",
        "script-src": ["'self'", "cdn.example.com"],
    },
)

함정

[!WARNING] ext.init_app 을 여러 번 호출하면 예상 밖 동작. 앱 인스턴스마다 한 번만.

[!CAUTION] Flask-SQLAlchemy 3.x 는 Query 스타일 API deprecation. User.query.all() 대신 db.session.execute(select(User)).scalars().all(). Marshaling 유의.

[!WARNING] Flask-Migrate 자동 마이그레이션은 완벽하지 않음. 컬럼 rename, 데이터 변환 등 수동 처리 필요.

[!IMPORTANT] Cache invalidation. @cache.cached 는 뷰 인자를 무시하고 URL 만 사용. @cache.memoize 는 함수 인자 포함. 잘못 선택하면 데이터 leak.

[!CAUTION] Rate limiter 는 프록시 뒤에서 remote_addr 을 잘못 인식. ProxyFix 미들웨어 + key_func 를 X-Forwarded-For 신뢰 함수로.

[Flask] Request & Response

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Flask Request/Response 는 Werkzeug 의 Request / Response 래퍼를 확장한 것입니다. Thread-local 프록시 flask.request 로 뷰 함수 어디서든 현재 요청에 접근하고, return 값을 자동으로 Response 로 변환합니다.

Request 객체

기본 속성

from flask import request

@app.post("/inspect")
def inspect():
    # URL & method
    method = request.method              # "POST"
    url = request.url                    # "http://.../inspect?x=1"
    path = request.path                  # "/inspect"
    full_path = request.full_path        # "/inspect?x=1"

    # Query string
    q = request.args.get("q", default="")
    tags = request.args.getlist("tag")   # 여러 값

    # JSON body
    data = request.get_json(silent=True)     # 실패 시 None
    data_or_error = request.get_json()       # 실패 시 400

    # Form (application/x-www-form-urlencoded, multipart/form-data)
    name = request.form.get("name")

    # 파일 업로드
    upload = request.files.get("file")
    if upload:
        upload.save(f"/tmp/{upload.filename}")

    # 원본 body
    raw = request.data                    # bytes
    text = request.get_data(as_text=True) # str

    # Headers
    ua = request.headers.get("User-Agent")

    # Cookies
    sid = request.cookies.get("session")

    # 원격
    remote_addr = request.remote_addr

    # 프록시 뒤에서는
    forwarded_for = request.headers.get("X-Forwarded-For")

    return {"ok": True}

JSON body

data = request.get_json()             # 실패 시 400
data = request.get_json(silent=True)  # 실패 시 None
data = request.get_json(force=True)   # Content-Type 무시

silent=True 를 기본으로 하고 자체 검증하는 편이 안전.

Form 과 파일

@app.post("/upload")
def upload():
    file = request.files.get("upload")
    if not file:
        return {"error": "no file"}, 400
    if not file.filename:
        return {"error": "empty filename"}, 400

    from werkzeug.utils import secure_filename
    filename = secure_filename(file.filename)   # 보안 처리
    file.save(f"/uploads/{filename}")
    return {"filename": filename}

secure_filename: 슬래시, 유니코드, 특수문자 제거. 절대 raw filename 을 파일 경로에 쓰지 마세요.

Multipart 여러 파일

@app.post("/uploads")
def uploads():
    files = request.files.getlist("files")
    for f in files:
        f.save(f"/uploads/{secure_filename(f.filename)}")
    return {"count": len(files)}

큰 요청 제한

app.config["MAX_CONTENT_LENGTH"] = 10 * 1024 * 1024   # 10 MB

초과 시 413 자동 반환. 파일 업로드 서버에서 반드시 설정.

Response 반환 형식

Flask 는 뷰 함수의 return 값을 유연하게 해석합니다.

문자열

@app.get("/")
def index():
    return "Hello"                   # 200, text/html
    # 또는
    return "Hello", 201              # status code
    # 또는
    return "Hello", 201, {"X-A": "1"}  # + headers

Dict / list (JSON 자동)

@app.get("/api")
def api():
    return {"key": "value"}          # 200 application/json
    # 또는
    return [1, 2, 3]                 # 200 application/json
    # 또는
    return {"key": "value"}, 201, {"X-Custom": "yes"}

Flask 2.0+ 는 dict/list 자동 jsonify. 이전에는 jsonify() 명시 필요.

`jsonify()`

from flask import jsonify

@app.get("/api")
def api():
    return jsonify({"key": "value"})           # 200
    return jsonify(key="value", n=42)          # kwargs 형태
    return jsonify(["a", "b"])                 # array

jsonify() 는 application/json Content-Type 을 명시적으로 설정. datetime, Decimal, UUID 등도 자동 직렬화 (Flask 3.x 개선).

`make_response`

세밀한 응답 제어:

from flask import make_response

@app.get("/custom")
def custom():
    resp = make_response({"data": 123})
    resp.status_code = 201
    resp.headers["X-Custom"] = "value"
    resp.set_cookie("session", "abc", httponly=True, secure=True, samesite="Lax")
    return resp

Response 객체 직접

from flask import Response

@app.get("/xml")
def xml():
    return Response(
        "<xml><a>1</a></xml>",
        mimetype="application/xml",
        status=200,
    )

리디렉트

from flask import redirect, url_for

@app.get("/old")
def old():
    return redirect(url_for("new"), code=308)   # 기본 302

@app.get("/new")
def new():
    return "new page"

301: Moved Permanently (SEO 영향)
302: Found (기본, 임시)
307: Temporary Redirect (method 유지)
308: Permanent Redirect (method 유지, SEO 영향)

abort

from flask import abort

@app.get("/secret/<int:id>")
def secret(id):
    if not authorized():
        abort(403, description="Forbidden")
    if not exists(id):
        abort(404)
    return "..."

abort 는 HTTPException 서브클래스 raise. errorhandler 로 커스텀 처리:

@app.errorhandler(404)
def not_found(e):
    return {"error": "not found"}, 404

@app.errorhandler(Exception)
def any_error(e):
    return {"error": str(e)}, 500

Streaming Response

from flask import stream_with_context, Response

@app.get("/stream")
def stream():
    def generate():
        for i in range(100):
            yield f"chunk {i}\n"
    return Response(stream_with_context(generate()), mimetype="text/plain")

stream_with_context 는 generator 안에서 request 접근을 유지. 안 쓰면 request context 이탈.

Server-Sent Events (SSE)

@app.get("/events")
def events():
    def stream_events():
        while True:
            data = get_next_event()
            yield f"data: {json.dumps(data)}\n\n"
            time.sleep(1)
    return Response(stream_with_context(stream_events()), mimetype="text/event-stream")

File Download

from flask import send_file, send_from_directory

@app.get("/download/<name>")
def download(name):
    return send_file(
        f"/data/{name}.pdf",
        as_attachment=True,
        download_name=f"{name}.pdf",
        mimetype="application/pdf",
    )

@app.get("/uploads/<path:filename>")
def uploaded(filename):
    return send_from_directory("/uploads/", filename)

send_from_directory 는 path traversal 방지 (.. 차단).

Before/After Request

@app.before_request
def before_each_request():
    g.request_id = str(uuid.uuid4())
    g.start = time.time()

@app.after_request
def after_each_request(response):
    duration = time.time() - g.start
    response.headers["X-Duration"] = f"{duration:.3f}"
    response.headers["X-Request-ID"] = g.request_id
    return response

@app.teardown_request
def teardown(exc):
    if exc:
        logger.exception(exc)

before_request: 요청 처리 전. 인증, DB 세션 시작.
after_request: 응답 반환 전. 헤더 추가, 로깅.
teardown_request: request context 종료 시 (예외 여부 무관). 리소스 정리.

Blueprint 는 자기만의 before_request / after_request 가능:

@bp.before_request
def before_bp():
    ...

Response class 커스터마이제이션

class ApiResponse(Response):
    default_mimetype = "application/json"

app.response_class = ApiResponse

함정

[!WARNING] request.form vs request.get_json(). Content-Type 에 따라 다름. 클라이언트가 잘못 보내면 실패. 양쪽 지원 시 명시 코드.

[!CAUTION] stream_with_context 안 쓰면 generator 안에서 request 접근 시 오류. 스트리밍 시 필수.

[!WARNING] 파일 업로드 filename 은 신뢰 불가. 반드시 secure_filename + 확장자 화이트리스트.

[!IMPORTANT] get_json(silent=True) 를 기본으로. 실패 시 400 자동 대신 앱에서 처리하는 편이 유연.

[!CAUTION] send_file 절대 경로 사용. 상대 경로는 flask app root 기준으로 오해. 명확히 절대 경로.

[Flask] Routing (URL Rules, Converters, url_for)

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Flask Routing 은 Werkzeug 의 Rule 시스템에 기반한 URL 매핑입니다. 데코레이터 (@app.route, @app.get, …) 로 URL 패턴을 뷰 함수에 연결하고, converter 로 세그먼트 파싱, url_for 로 역방향 URL 생성을 지원합니다.

기본 데코레이터

@app.route("/")
def index():
    return "Home"

@app.route("/about", methods=["GET"])
def about():
    return "About"

# Flask 2.0+ method-specific
@app.get("/hello")
def hello():
    return "hi"

@app.post("/items/")
def create_item():
    return "created"

@app.put("/items/<int:id>")
def update_item(id):
    return f"updated {id}"

@app.delete("/items/<int:id>")
def delete_item(id):
    return "", 204

URL Converters

URL 세그먼트를 파라미터로 변환. <converter:name> 형식.

Converter	매칭	예시
`string` (기본)	슬래시 제외 문자열	`/user/<name>`
`int`	양의 정수	`/user/<int:id>`
`float`	음/양 실수	`/rate/<float:v>`
`path`	슬래시 포함 문자열	`/files/<path:filepath>`
`uuid`	UUID 형식	`/orders/<uuid:oid>`
`any(a,b,c)`	나열된 값 중 하나	`/lang/<any(en,ko,ja):lang>`

@app.get("/user/<name>")
def show_user(name: str):
    return f"User {name}"

@app.get("/post/<int:id>")
def show_post(id: int):
    return f"Post #{id}"

@app.get("/files/<path:filepath>")
def show_file(filepath: str):
    return f"File: {filepath}"

@app.get("/api/<any(v1,v2):version>/users")
def api_users(version: str):
    return f"API {version}"

int:id 는 /post/abc 를 404 로 처리 (매칭 실패).

Custom Converter

from werkzeug.routing import BaseConverter

class ListConverter(BaseConverter):
    def to_python(self, value: str):
        return value.split("+")

    def to_url(self, values: list) -> str:
        return "+".join(str(v) for v in values)

app.url_map.converters["list"] = ListConverter

@app.get("/tags/<list:tags>")
def by_tags(tags: list[str]):
    return {"tags": tags}
# GET /tags/python+web+api  ->  tags = ["python", "web", "api"]

Trailing Slash

Flask 는 URL 을 두 가지로 정규화:

@app.get("/projects/")  # 슬래시 있음 (canonical)
def projects():
    return "..."

@app.get("/about")       # 슬래시 없음 (canonical)
def about():
    return "..."

/projects/ 정의 -> /projects 접근 시 308 redirect 로 /projects/ 로
/about 정의 -> /about/ 접근 시 404

Trailing slash 를 통일해서 관리하는 것이 관용.

url_for (역방향 URL 생성)

뷰 함수 이름으로 URL 생성. 하드코딩 회피.

from flask import url_for

@app.get("/")
def index():
    return f'<a href="{url_for("user", name="kim")}">Kim</a>'
    # 결과: <a href="https://shinkeonkim.com/user/kim">Kim</a>

@app.get("/user/<name>")
def user(name):
    return f"Hi {name}"

url_for 인자

url_for("user", name="kim")                    # /user/kim
url_for("user", name="kim", _external=True)    # https://example.com/user/kim
url_for("user", name="kim", _anchor="section") # /user/kim#section
url_for("user", name="kim", _scheme="https")   # scheme 강제
url_for("static", filename="css/main.css")     # /static/css/main.css

Blueprint URL

Blueprint 안에서는 bp_name.endpoint:

url_for("auth.login")     # blueprint "auth" 의 login 뷰
url_for(".sub_route")     # 현재 blueprint 내 상대 참조

여러 rule 을 한 뷰에

@app.route("/")
@app.route("/home")
def index():
    return "home"

혹은 명시적:

def index():
    return "home"

app.add_url_rule("/", endpoint="index", view_func=index)
app.add_url_rule("/home", endpoint="index", view_func=index)

Endpoint 이름 커스터마이제이션

@app.route 는 뷰 함수명을 endpoint 이름으로 사용. 다른 이름을 원하면:

@app.route("/", endpoint="root")
def home():
    return "..."

url_for("root")   # /

Class-based view 나 여러 blueprint 에서 같은 함수를 라우팅할 때 필요.

Subdomain routing

app.config["SERVER_NAME"] = "example.com:5000"

@app.get("/", subdomain="<user>")
def user_home(user):
    return f"{user}'s subdomain"

# alice.example.com:5000/  ->  user = "alice"

SERVER_NAME 필수. Wildcard DNS 설정 필요.

Redirect / Abort

from flask import redirect, url_for, abort

@app.get("/old")
def old():
    return redirect(url_for("new"), code=308)

@app.get("/secret")
def secret():
    if not authorized():
        abort(403)
    return "secret"

@app.get("/user/<int:id>")
def user(id):
    if not exists(id):
        abort(404, description="User not found")
    return "..."

URL Map 조회

print(app.url_map)
# Map([
#   <Rule '/static/<filename>' (HEAD, GET, OPTIONS) -> static>,
#   <Rule '/' (HEAD, GET, OPTIONS) -> index>,
#   ...
# ])

CLI:

flask routes
# Endpoint    Methods  Rule
# --------    -------  ----
# index       GET      /
# user        GET      /user/<name>
# static      GET      /static/<path:filename>

Method Override

REST 폼에서 PUT/DELETE 를 흉내내려면 _method 필드 + 미들웨어:

from werkzeug.middleware.method_override import MethodOverride
app.wsgi_app = MethodOverride(app.wsgi_app)

HTML 폼:

<form method="post" action="/items/1">
  <input type="hidden" name="_method" value="DELETE">
  <button>Delete</button>
</form>

Regular Expression 라우팅

기본 converter 로 부족하면 custom regex converter:

from werkzeug.routing import BaseConverter

class RegexConverter(BaseConverter):
    def __init__(self, url_map, *items):
        super().__init__(url_map)
        self.regex = items[0]

app.url_map.converters["regex"] = RegexConverter

@app.get("/pattern/<regex(r'[A-Z]{3}-\d{4}'):code>")
def by_code(code: str):
    return f"code {code}"

함정

[!WARNING] Trailing slash 정책을 프로젝트 전체에서 통일. 반반 섞이면 관용 지식 무너지고 SEO 도 나쁨.

[!CAUTION] Endpoint 충돌. 같은 endpoint 이름을 다른 URL 에 붙이면 예상 밖 동작. Blueprint 로 격리.

[!WARNING] url_for 는 request context 필요. 뷰 함수 밖에서 호출 시 app.test_request_context() 필요.

[!IMPORTANT] _external=True + SERVER_NAME 없으면 절대 URL 이 request 헤더 기반. 프록시 뒤 배포 시 ProxyFix 미들웨어로 X-Forwarded-* 신뢰.

[!CAUTION] path: converter 는 슬래시 포함. 뒷 세그먼트가 다른 라우트를 삼킴. URL map 순서에 유의.

[Flask] Sessions & Cookies

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Flask Session 은 요청 간 상태를 유지하는 방법입니다. 기본 구현은 서명된 쿠키 (secure cookie) 로 클라이언트에 저장 (server-less). Flask-Session extension 으로 서버 저장소 (Redis, DB) 로 전환 가능.

from flask import Flask, session

app = Flask(__name__)
app.secret_key = "your-secret-key"   # 반드시 설정!

@app.get("/login")
def login():
    session["user_id"] = 42
    session["email"] = "a@b.com"
    return "logged in"

@app.get("/me")
def me():
    if "user_id" not in session:
        return "not logged in", 401
    return {
        "user_id": session["user_id"],
        "email": session.get("email"),
    }

@app.get("/logout")
def logout():
    session.clear()
    return "logged out"

어떻게 작동하는가

Flask 가 session dict 을 JSON 직렬화
secret_key 로 HMAC 서명 (itsdangerous)
Base64 인코딩 후 쿠키에 저장
다음 요청에서 쿠키 -> 서명 검증 -> 원본 dict 복원

핵심: 데이터는 클라이언트에 저장. 서버는 저장 안 함. 하지만 서명 이므로 클라이언트가 값을 조작할 수 없음 (검증 실패).

장단점

Pros:

서버 상태 없음 (수평 확장 자유)
Redis/DB 인프라 불필요

Cons:

암호화 아님 (서명만): 클라이언트가 세션 값을 읽을 수 있음 (수정만 못 함)
크기 제한: 브라우저 쿠키 크기 상한 (~4 KB)
매 요청 전체 전송: 큰 세션은 대역폭 부담
취소 불가: 서명된 쿠키는 만료 전까지 유효. 서버에서 개별 세션 강제 로그아웃 불가

결론: 소량 (user_id, csrf_token) 만 저장. 큰 데이터는 서버 세션.

Session 설정

from datetime import timedelta

app.config.update(
    SECRET_KEY="your-secret-key",
    SESSION_COOKIE_NAME="session",
    SESSION_COOKIE_DOMAIN=None,          # 자동
    SESSION_COOKIE_PATH="/",
    SESSION_COOKIE_HTTPONLY=True,        # XSS 방어 (필수)
    SESSION_COOKIE_SECURE=True,          # HTTPS 만 (프로덕션)
    SESSION_COOKIE_SAMESITE="Lax",       # CSRF 방어 ("Lax" or "Strict")
    PERMANENT_SESSION_LIFETIME=timedelta(days=14),
)

permanent session

기본 세션은 브라우저 종료 시 만료. permanent=True 로 lifetime 을 명시:

@app.get("/login")
def login():
    session.permanent = True
    session["user_id"] = 42
    return "..."

이제 PERMANENT_SESSION_LIFETIME (기본 31일) 만큼 유지.

Flask-Session (서버측 세션)

큰 데이터, 강제 로그아웃, 암호화된 세션을 원하면 서버측 저장.

pip install Flask-Session redis

from flask import Flask
from flask_session import Session
import redis

app = Flask(__name__)
app.config.update(
    SESSION_TYPE="redis",
    SESSION_REDIS=redis.from_url("redis://localhost:6379/0"),
    SESSION_KEY_PREFIX="sess:",
    SESSION_PERMANENT=True,
    PERMANENT_SESSION_LIFETIME=timedelta(days=14),
    SESSION_USE_SIGNER=True,          # 세션 ID 서명 (탈취 감지)
    SESSION_COOKIE_HTTPONLY=True,
    SESSION_COOKIE_SECURE=True,
)

Session(app)

이제 세션 데이터는 Redis 에, 쿠키에는 세션 ID 만.

SESSION_TYPE 옵션

"redis": Redis 저장 (권장)
"memcached": Memcached
"filesystem": 로컬 파일 (단일 인스턴스만)
"mongodb": MongoDB
"sqlalchemy": DB

서버측 세션의 강제 로그아웃

특정 세션 ID 를 서버에서 삭제하면 즉시 로그아웃:

redis_client.delete(f"sess:{session_id}")

request.cookies 로 읽기, response.set_cookie 로 설정.

from flask import make_response

@app.get("/set-cookie")
def set_cookie():
    resp = make_response("cookie set")
    resp.set_cookie(
        "user_pref",
        "dark_mode",
        max_age=86400 * 30,           # 30일
        expires=None,                 # max_age 우선
        path="/",
        domain=None,
        secure=True,                  # HTTPS
        httponly=True,                # JS 접근 불가 (XSS 방어)
        samesite="Lax",               # CSRF 방어
    )
    return resp

@app.get("/read-cookie")
def read_cookie():
    return {"pref": request.cookies.get("user_pref", "light")}

@app.get("/delete-cookie")
def delete_cookie():
    resp = make_response("deleted")
    resp.delete_cookie("user_pref")
    return resp

SameSite 정책

CSRF 방어의 핵심.

값	의미
`Strict`	Cross-site 요청에 쿠키 안 감. 완전 격리
`Lax` (기본)	최상위 navigation (링크 클릭) 은 허용, 그 외 cross-site 차단
`None`	항상 전송. `Secure=True` 필수

관용:

일반 앱: Lax
강한 보안 (은행): Strict
Third-party 임베드 (iframe) 필요: None + Secure

CSRF 방어

세션이 있는 앱은 CSRF 취약. 방어 방식:

CSRF token (Flask-WTF): 폼마다 서명된 토큰 삽입, 서버가 검증
SameSite cookie: Lax / Strict (필수 조합)
Origin/Referer 헤더 검증 (부가)

Flask-WTF CSRF

from flask_wtf import CSRFProtect

csrf = CSRFProtect(app)

폼 템플릿:

<form method="post">
  {{ form.csrf_token }}     <!-- 또는 form.hidden_tag() 가 자동 -->
  ...
</form>

AJAX (JSON POST) 는 헤더로:

fetch("/api", {
  method: "POST",
  headers: {"X-CSRFToken": csrfToken},
  body: JSON.stringify({...}),
});

from flask_login import LoginManager, UserMixin, login_user, logout_user, current_user, login_required

login_manager = LoginManager(app)
login_manager.login_view = "auth.login"

class User(UserMixin):
    def __init__(self, id: int, email: str):
        self.id = id
        self.email = email

@login_manager.user_loader
def load_user(user_id: str) -> User | None:
    return db.query(User).get(int(user_id))

@app.post("/login")
def login():
    user = authenticate(request.form["email"], request.form["password"])
    if user:
        login_user(user, remember=True)
        return redirect(url_for("dashboard"))
    return "invalid credentials", 401

@app.get("/dashboard")
@login_required
def dashboard():
    return f"Hello, {current_user.email}"

@app.post("/logout")
@login_required
def logout():
    logout_user()
    return redirect(url_for("login"))

Flask-Login 은 내부적으로 session 을 사용해 사용자 ID 저장. user_loader 가 매 요청마다 DB 에서 사용자 로드.

Session 크기 제한 확인

import sys

@app.before_request
def check_session_size():
    if sys.getsizeof(dict(session)) > 3800:   # 4 KB 근사 상한
        session.clear()
        abort(500, "Session too large")

민감하지 않지만 조작 방지가 필요한 값 (예: 방문 카운터):

from itsdangerous import URLSafeTimedSerializer

serializer = URLSafeTimedSerializer(app.secret_key, salt="visit-counter")

@app.get("/set")
def set_():
    resp = make_response("...")
    token = serializer.dumps({"count": 5})
    resp.set_cookie("counter", token, httponly=True)
    return resp

@app.get("/get")
def get_():
    token = request.cookies.get("counter")
    try:
        data = serializer.loads(token, max_age=86400)
    except Exception:
        data = None
    return {"data": data}

함정

[!WARNING] secret_key 를 소스에 하드코딩 금지. 환경변수 또는 Secrets Manager. 유출 시 서명 위조 -> 세션 탈취.

[!CAUTION] 세션 쿠키는 서명만, 암호화 아님. session["email"] 을 클라이언트가 base64 디코드해 읽을 수 있음. 민감 정보 (전화, 주소) 저장 금지.

[!WARNING] SESSION_COOKIE_SECURE=True 인 상태에서 개발 시 HTTP 로컬 접근하면 세션 안 됨. .env 로 dev/prod 분리.

[!IMPORTANT] 강제 로그아웃 불가 (secure cookie 방식). 필요하면 Flask-Session (Redis) 로 이관.

[!CAUTION] CSRF 토큰 없이 폼 처리 금지. Flask-WTF 사용 강력 권장.

[!WARNING] SameSite=None 은 Secure=True 없이는 브라우저가 무시. 크로스 오리진 임베드 필요 시 두 옵션 함께.

[Flask] Templates (Jinja2)

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Flask Templates 는 Jinja2 템플릿 엔진의 Flask 통합입니다. render_template() 로 컨텍스트 (변수) 를 넘겨 HTML/텍스트를 렌더링하고, template inheritance, macro, filter 등으로 재사용 가능한 UI 를 구축합니다.

서버 사이드 렌더링 (SSR) 이 필요한 앱 (관리자 페이지, SEO 중요 페이지, HTMX 앱) 에서 여전히 강력. React/Vue SPA 로 완전히 대체할 필요 없는 경우 많음.

Hello World

# app.py
from flask import Flask, render_template

app = Flask(__name__)

@app.get("/user/<name>")
def user(name):
    return render_template("user.html", name=name, items=[1, 2, 3])

<!-- templates/user.html -->
<!DOCTYPE html>
<html>
<body>
  <h1>Hello, {{ name }}</h1>
  <ul>
    {% for item in items %}
      <li>{{ item }}</li>
    {% endfor %}
  </ul>
</body>
</html>

Jinja2 문법

변수 출력

{{ variable }}
{{ user.name }}
{{ user["email"] }}
{{ items[0] }}
{{ func(arg) }}
{{ user.get("name", "unknown") }}

Filter (변수 변환)

{{ name | upper }}                     <!-- 대문자 -->
{{ text | truncate(100) }}             <!-- 100자 자르기 -->
{{ date | dateformat("%Y-%m-%d") }}    <!-- 날짜 포맷 -->
{{ list | join(", ") }}                <!-- 배열을 문자열로 -->
{{ dict | tojson }}                    <!-- JSON 직렬화 -->
{{ text | safe }}                      <!-- HTML escape 안 함 -->
{{ number | round(2) }}                <!-- 소수점 -->
{{ url | urlencode }}

커스텀 filter:

@app.template_filter("reverse")
def reverse_filter(s: str) -> str:
    return s[::-1]

# 템플릿: {{ "hello" | reverse }}  ->  olleh

Control Flow

{% if user %}
  Hi, {{ user.name }}
{% elif guest %}
  Hi, guest
{% else %}
  Please log in.
{% endif %}

{% for item in items %}
  <li>{{ loop.index }}: {{ item }}</li>
{% else %}
  <p>No items.</p>
{% endfor %}

loop.index (1-based), loop.index0 (0-based), loop.first, loop.last, loop.length.

Comment

{# 이것은 렌더링되지 않는 주석 #}

Whitespace 제어

{%- for x in xs %}         <!-- 앞 공백 제거 -->
  {{ x }}
{% endfor -%}              <!-- 뒷 공백 제거 -->

Template Inheritance

<!-- templates/base.html -->
<!DOCTYPE html>
<html>
<head>
  <title>{% block title %}Default Title{% endblock %}</title>
</head>
<body>
  <nav>{% include "_nav.html" %}</nav>
  <main>
    {% block content %}{% endblock %}
  </main>
  <footer>{% block footer %}Default footer{% endblock %}</footer>
</body>
</html>

<!-- templates/user.html -->
{% extends "base.html" %}

{% block title %}{{ name }}의 페이지{% endblock %}

{% block content %}
  <h1>{{ name }}</h1>
  <ul>
    {% for item in items %}
      <li>{{ item }}</li>
    {% endfor %}
  </ul>
{% endblock %}

super() 로 부모 블록 확장

{% block content %}
  {{ super() }}
  <p>추가 컨텐츠</p>
{% endblock %}

include vs extends

{% extends %}: 부모 템플릿 상속 (block override)
{% include %}: 파일 삽입 (context 공유)

Macro

함수처럼 재사용 가능한 템플릿 조각.

<!-- templates/_macros.html -->
{% macro render_field(field, label=None) %}
<div class="form-group">
  <label>{{ label or field.label }}</label>
  {{ field(class="form-control") }}
  {% if field.errors %}
    <ul class="errors">
      {% for error in field.errors %}<li>{{ error }}</li>{% endfor %}
    </ul>
  {% endif %}
</div>
{% endmacro %}

<!-- templates/register.html -->
{% from "_macros.html" import render_field %}

<form method="post">
  {{ render_field(form.email, "이메일") }}
  {{ render_field(form.password) }}
  <button>가입</button>
</form>

Context Processor

모든 템플릿에서 접근 가능한 전역 변수 주입.

@app.context_processor
def inject_globals():
    return {
        "current_user": get_current_user(),
        "site_name": "MySite",
        "now": datetime.utcnow(),
    }

이제 어느 템플릿에서든 {{ current_user }}, {{ site_name }} 사용 가능.

Blueprint 도 자기만의 context processor:

@bp.app_context_processor
def bp_context():
    return {"key": "value"}

Autoescape (XSS 방어)

기본 활성화. {{ user_input }} 은 HTML escape.

<!-- user.name = "<script>alert(1)</script>" -->
<p>{{ user.name }}</p>
<!-- 렌더링: <p>&lt;script&gt;alert(1)&lt;/script&gt;</p> -->

| safe 는 escape 를 해제. 신뢰할 만한 HTML 만 (예: 관리자가 CMS 에 넣은 것).

{{ trusted_html | safe }}

Markup 객체를 파이썬에서 직접:

from markupsafe import Markup
return render_template("...", html=Markup("<b>bold</b>"))

URL 생성

<a href="{{ url_for('index') }}">Home</a>
<a href="{{ url_for('user', name=user.name) }}">Profile</a>
<link rel="stylesheet" href="{{ url_for('static', filename='css/main.css') }}">

Blueprint:

<a href="{{ url_for('auth.login') }}">Login</a>

Flash Messages

한 번만 노출되는 사용자 알림.

from flask import flash

@app.post("/login")
def login():
    if success:
        flash("로그인되었습니다", category="success")
    else:
        flash("실패했습니다", category="error")
    return redirect(url_for("index"))

{% with messages = get_flashed_messages(with_categories=true) %}
  {% for category, message in messages %}
    <div class="alert alert-{{ category }}">{{ message }}</div>
  {% endfor %}
{% endwith %}

CSRF Token (Flask-WTF)

<form method="post">
  {{ form.hidden_tag() }}     <!-- CSRF 토큰 자동 삽입 -->
  ...
</form>

Extension 없이 수동으로 하려면:

<form>
  <input type="hidden" name="csrf_token" value="{{ session.csrf_token }}">
  ...
</form>

세션에 CSRF 토큰을 발급하고 form 처리 시 검증.

Set / Assign

{% set price = item.price * 1.1 %}
<p>세금 포함: {{ price }}</p>

{% set nav %}
  <a href="/">홈</a>
  <a href="/about">소개</a>
{% endset %}
<nav>{{ nav | safe }}</nav>

Template Rendering 성능

Jinja2 는 템플릿을 파이썬 코드로 컴파일 후 실행. 첫 렌더링 시 컴파일. Flask 는 개발 모드에서 파일 변경 감지, 프로덕션은 캐시.

app.jinja_env.cache_size = 400   # 기본 100
app.jinja_env.auto_reload = False  # 프로덕션 필수

Extension (자주 쓰이는)

Jinja2 built-in: if, for, set, include, extends, block, macro, import, from, with, filter, endfilter
jinja2.ext.do: {% do list.append(x) %} (side effect)
jinja2.ext.loopcontrols: {% break %}, {% continue %}
jinja2.ext.i18n: gettext 통합

app.jinja_env.add_extension("jinja2.ext.do")

HTMX / Alpine 조합

Jinja2 + HTMX (혹은 Alpine.js) 는 SPA 대비 훨씬 단순한 인터랙션 앱을 만들 수 있음:

<button hx-get="/api/count" hx-target="#count">Refresh</button>
<span id="count">{{ count }}</span>

서버가 partial HTML 을 반환하면 HTMX 가 target 만 교체.

@app.get("/api/count")
def count():
    return render_template("_count.html", count=get_count())

_count.html:

<span id="count">{{ count }}</span>

함정

[!WARNING] | safe 남용은 XSS 취약점. 사용자 입력에 절대 붙이지 않기.

[!CAUTION] autoescape 해제 파일. .html, .htm, .xml, .xhtml 은 기본 autoescape 활성. 그 외는 활성 안 됨. select_autoescape 로 명시 관리.

[!WARNING] get_flashed_messages 는 한 번만 소비. 다시 렌더링하면 메시지 사라짐. 저장 필요하면 별도.

[!IMPORTANT] 템플릿에서 heavy computation 금지. DB 쿼리, 파일 IO 등은 뷰에서 미리. 템플릿은 렌더링만.

[!CAUTION] Template caching. Jinja2 cache_size 를 넘으면 LRU 로 축출. 큰 앱은 늘리기.

[Flask] Testing

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Flask Testing 은 앱 인스턴스를 직접 감싸 HTTP 요청을 시뮬레이션하는 workflow 입니다. app.test_client() (Werkzeug) 로 라우팅/뷰/미들웨어까지 실제 실행하고 응답을 검증합니다. HTTP 서버 없이 프로세스 내부에서 수행되어 매우 빠릅니다.

기본 사용

def test_index():
    app = create_app("testing")
    client = app.test_client()

    resp = client.get("/")
    assert resp.status_code == 200
    assert resp.get_json() == {"hello": "world"}

pytest 통합

# conftest.py
import pytest
from myapp import create_app
from myapp.extensions import db

@pytest.fixture
def app():
    app = create_app("testing")
    with app.app_context():
        db.create_all()
        yield app
        db.session.remove()
        db.drop_all()

@pytest.fixture
def client(app):
    return app.test_client()

@pytest.fixture
def runner(app):
    return app.test_cli_runner()

# tests/test_users.py
def test_create_user(client):
    resp = client.post("/users/", json={"email": "a@b.com", "password": "secret123"})
    assert resp.status_code == 201
    data = resp.get_json()
    assert data["email"] == "a@b.com"

def test_get_user(client):
    resp = client.get("/users/1")
    assert resp.status_code == 200

HTTP 요청 API

# GET with query
client.get("/items/", query_string={"q": "search"})

# POST JSON
client.post("/items/", json={"name": "foo"})

# POST form
client.post("/login", data={"email": "a@b.com", "password": "secret"})

# POST multipart (파일)
from io import BytesIO

client.post(
    "/upload",
    data={"file": (BytesIO(b"file content"), "test.txt")},
    content_type="multipart/form-data",
)

# Headers
client.get("/protected", headers={"Authorization": "Bearer token"})

# Cookies
client.set_cookie("localhost", "session", "abc")
resp = client.get("/me")

Response 검증

def test_response(client):
    resp = client.get("/api")

    assert resp.status_code == 200
    assert resp.mimetype == "application/json"

    # JSON body
    data = resp.get_json()
    assert data["key"] == "value"

    # Raw body
    assert b"success" in resp.data
    text = resp.get_data(as_text=True)

    # Headers
    assert resp.headers["X-Custom"] == "value"

    # Cookies
    assert "session" in resp.headers.get("Set-Cookie", "")

Session 조작

def test_session(client):
    with client.session_transaction() as sess:
        sess["user_id"] = 1

    resp = client.get("/me")
    assert resp.status_code == 200

session_transaction context 안에서 세션을 조작하고, 이후 요청에 세션이 반영됨.

test_request_context

Request context 를 수동으로 열기 (뷰 함수 밖에서 request, url_for 등 접근):

def test_url_for(app):
    with app.test_request_context("/hello?q=world"):
        assert request.path == "/hello"
        assert request.args["q"] == "world"
        assert url_for("index") == "/"

test_cli_runner (CLI 명령 테스트)

def test_seed_cli(runner):
    result = runner.invoke(args=["seed-db", "--count", "10"])
    assert result.exit_code == 0
    assert "Seeded 10" in result.output

DB 격리 패턴

패턴 1: fresh schema per test

@pytest.fixture
def app():
    app = create_app("testing")
    with app.app_context():
        db.create_all()
        yield app
        db.drop_all()

빠르지만 테스트 간 오염 위험 (fixture 로 매번 clear 필요).

패턴 2: Transaction rollback per test

@pytest.fixture
def app():
    app = create_app("testing")
    with app.app_context():
        db.create_all()
        yield app
        db.drop_all()

@pytest.fixture
def db_session(app):
    connection = db.engine.connect()
    transaction = connection.begin()
    session = db.session
    session.bind = connection

    yield session

    transaction.rollback()
    connection.close()

각 테스트 후 rollback -> 완벽 격리.

패턴 3: SQLite in-memory

class TestingConfig(Config):
    SQLALCHEMY_DATABASE_URI = "sqlite:///:memory:"

가장 빠름. 하지만 PostgreSQL-specific 기능 (JSONB, LATERAL, …) 은 테스트 불가.

패턴 4: testcontainers

from testcontainers.postgres import PostgresContainer

@pytest.fixture(scope="session")
def postgres():
    with PostgresContainer("postgres:16") as p:
        yield p.get_connection_url()

@pytest.fixture(scope="session")
def app(postgres):
    os.environ["DATABASE_URL"] = postgres
    app = create_app("testing")
    ...

프로덕션 DB 와 동일한 환경. Docker 필요.

Authentication 테스트

Flask-Login 사용 시:

@pytest.fixture
def logged_in_user(client, app):
    with app.app_context():
        user = User(email="test@example.com", password_hash=hash("secret"))
        db.session.add(user)
        db.session.commit()
        user_id = user.id

    with client.session_transaction() as sess:
        sess["_user_id"] = str(user_id)
        sess["_fresh"] = True

    return user_id

def test_dashboard(client, logged_in_user):
    resp = client.get("/dashboard")
    assert resp.status_code == 200

Mocking

unittest.mock 활용:

from unittest.mock import patch

def test_external_call(client):
    with patch("myapp.services.external_api.post") as mock_post:
        mock_post.return_value.json.return_value = {"status": "ok"}
        resp = client.post("/webhook", json={"event": "..."})
        assert resp.status_code == 200
        mock_post.assert_called_once()

Flask-Caching 무효화

class TestingConfig(Config):
    CACHE_TYPE = "NullCache"    # 캐시 안 함

또는 fixture 로 clear:

@pytest.fixture(autouse=True)
def clear_cache(app):
    from myapp.extensions import cache
    cache.clear()

Async view 테스트 (Flask 2.0+)

async def test_async_view(client):
    resp = await client.get("/async")   # httpx-like
    assert resp.status_code == 200

Flask 는 async view 지원이 제한적. pytest-asyncio 조합.

Coverage

pip install pytest-cov
pytest --cov=myapp --cov-report=term-missing --cov-report=html

pyproject.toml:

[tool.pytest.ini_options]
testpaths = ["tests"]

[tool.coverage.run]
branch = true
source = ["myapp"]
omit = ["*/migrations/*", "wsgi.py"]

[tool.coverage.report]
fail_under = 80
show_missing = true

E2E 테스트 (실제 서버)

Selenium/Playwright 로 브라우저 자동화:

import pytest
from playwright.sync_api import Page
from myapp import create_app
from threading import Thread

@pytest.fixture(scope="session")
def live_server():
    app = create_app("testing")
    server = make_server("127.0.0.1", 5000, app)
    thread = Thread(target=server.serve_forever)
    thread.start()
    yield "http://127.0.0.1:5000"
    server.shutdown()
    thread.join()

def test_home_page(page: Page, live_server):
    page.goto(f"{live_server}/")
    assert page.title() == "My App"

함정

[!WARNING] App context / request context 혼동. test_request_context 는 request 시뮬레이션, app_context 는 앱 활성화. DB 조작은 앱 컨텍스트 필요.

[!CAUTION] db.session.remove() 안 하면 다음 테스트로 세션 leak. teardown fixture 에서 반드시.

[!WARNING] CSRF 비활성화. 테스트 시 WTF_CSRF_ENABLED = False. 활성이면 매 폼 테스트마다 토큰 발급 필요.

[!IMPORTANT] Fixture scope. DB migrations 는 session scope, transaction rollback 은 function scope. 잘못 조합하면 매우 느림.

[!CAUTION] 환경 변수 leak. 테스트에서 os.environ 을 조작하면 다른 테스트 영향. monkeypatch.setenv 사용.

[Python] Flask

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Flask 는 Armin Ronacher 가 2010년 발표한 WSGI 기반 Python 마이크로프레임워크 입니다. Pallets Projects 가 유지관리하고, 2026년 현재 Flask 3.x + Werkzeug 3.x + Jinja2 3.x 조합이 표준입니다.

핵심 철학: “작은 코어 + 유연한 확장”. 라우팅, 요청/응답, 템플릿 렌더링만 코어에 두고 DB, 인증, 폼, 마이그레이션 등은 extension 으로 조합.

왜 Flask 인가

최소 진입: 5줄로 서버 실행
명시적: 마술 (auto-discovery, convention over configuration) 이 적어 디버깅 쉬움
거대한 생태계: 20년 축적된 extension, 스택오버플로 자료
테스트 용이: test_client() 로 앱 인스턴스 직접 테스트
Jinja2: SSR 강력, HTMX/Alpine 조합에 잘 맞음

Hello World

pip install flask

# app.py
from flask import Flask

app = Flask(__name__)

@app.get("/")
def hello():
    return {"hello": "world"}

@app.get("/users/<int:user_id>")
def get_user(user_id):
    return {"id": user_id}

if __name__ == "__main__":
    app.run(debug=True)

python app.py
# 또는
flask --app app run --debug

아키텍처

┌─────────────────┐
│   Gunicorn/uWSGI │  ← WSGI server (prefork workers)
└────────┬────────┘
         ↓ WSGI
┌─────────────────┐
│      Flask      │  ← 라우팅, before/after hooks, context
└────────┬────────┘
         ↓
┌─────────────────┐
│    Werkzeug     │  ← Request/Response, routing, debug tools
└────────┬────────┘
         ↓
┌─────────────────┐
│     Jinja2      │  ← 템플릿 (선택)
└─────────────────┘

핵심 개념

WSGI

Web Server Gateway Interface (PEP 3333). Sync 인터페이스. def app(environ, start_response) -> Iterable[bytes]. Flask 인스턴스가 WSGI 앱.

FastAPI (ASGI) 와 근본적으로 다름: WSGI 는 async 지원이 제한적이고 한 프로세스가 요청 하나만 처리.

App Context / Request Context

Flask 는 thread-local (실제로는 LocalStack) 을 사용해 request context 와 application context 를 관리. 전역처럼 보이는 request, session, current_app, g 는 사실 스택 위 객체 프록시.

from flask import request, session, current_app, g

@app.get("/me")
def me():
    print(request.args)          # query params
    print(session.get("user"))   # session
    print(current_app.config)    # 앱 config
    g.request_id = "..."         # request-scoped 저장소
    return "..."

request: 현재 요청 (path, method, args, form, files, headers, cookies)
session: 클라이언트 sessions (기본은 서명 쿠키)
current_app: 현재 앱 인스턴스 (blueprint 안에서 유용)
g: 요청 스코프 임시 저장소 (DB session 등)

Blueprint

라우트를 모듈로 분할. 자세한 것은 [[flask-blueprints|Flask Blueprints]] 참조.

Extension

Flask 는 코어에 없는 기능을 extension 으로 제공. Flask-SQLAlchemy, Flask-Login, Flask-Migrate, Flask-WTF, Flask-CORS, Flask-Caching, …

프로젝트 구조 (실전)

myapp/
├── src/
│   └── myapp/
│       ├── __init__.py       # create_app()
│       ├── config.py         # Config class
│       ├── extensions.py     # db = SQLAlchemy(), login = LoginManager(), ...
│       ├── models.py         # SQLAlchemy models
│       ├── auth/             # Blueprint
│       │   ├── __init__.py
│       │   ├── routes.py
│       │   └── forms.py
│       ├── main/
│       │   └── routes.py
│       └── templates/
│           └── base.html
├── migrations/               # Flask-Migrate (Alembic)
├── tests/
├── pyproject.toml
└── wsgi.py                   # 진입점

create_app (Application Factory)

# myapp/__init__.py
from flask import Flask
from myapp.extensions import db, migrate, login

def create_app(config_name: str = "production") -> Flask:
    app = Flask(__name__)
    app.config.from_object(f"myapp.config.{config_name.capitalize()}Config")

    db.init_app(app)
    migrate.init_app(app, db)
    login.init_app(app)

    from myapp.auth.routes import bp as auth_bp
    from myapp.main.routes import bp as main_bp
    app.register_blueprint(auth_bp, url_prefix="/auth")
    app.register_blueprint(main_bp)

    return app

자세한 것은 [[flask-app-factory|Flask App Factory]] 참조.

라우팅 요약

@app.route("/", methods=["GET", "POST"])
@app.get("/items/<int:id>")           # 3.x 편의
@app.post("/items/")
@app.put("/items/<int:id>")
@app.delete("/items/<int:id>")

Converters: <int:x>, <float:x>, <uuid:x>, <path:x>, <string:x> (기본).

자세한 것은 [[flask-routing|Flask Routing]] 참조.

Request 처리

from flask import request

@app.post("/echo")
def echo():
    # JSON body
    data = request.get_json()

    # Form data
    name = request.form.get("name")

    # Query
    q = request.args.get("q", default="")

    # 파일
    f = request.files.get("upload")
    if f:
        f.save(f"/tmp/{f.filename}")

    return {"received": data}

자세한 것은 [[flask-request-response|Flask Request/Response]] 참조.

응답

from flask import make_response, jsonify, redirect, url_for

@app.get("/")
def index():
    return jsonify({"hello": "world"})   # JSON

@app.get("/plain")
def plain():
    return "text response", 200, {"X-Custom": "yes"}

@app.get("/redirect")
def to_home():
    return redirect(url_for("index"))

@app.get("/custom")
def custom():
    resp = make_response({"ok": True})
    resp.set_cookie("session", "abc", httponly=True, secure=True)
    return resp

Templates (Jinja2)

from flask import render_template

@app.get("/user/<name>")
def user(name):
    return render_template("user.html", name=name, items=[1, 2, 3])

<!-- templates/user.html -->
{% extends "base.html" %}
{% block content %}
  <h1>Hello, {{ name }}</h1>
  <ul>
    {% for item in items %}<li>{{ item }}</li>{% endfor %}
  </ul>
{% endblock %}

자세한 것은 [[flask-templates|Flask Templates]] 참조.

Session

from flask import session

app.secret_key = "your-secret-key"   # 필수

@app.get("/login")
def login():
    session["user_id"] = 42
    return "logged in"

@app.get("/me")
def me():
    return {"user_id": session.get("user_id")}

기본 세션은 서명 쿠키 (itsdangerous). 자세한 것은 [[flask-sessions|Flask Sessions]] 참조.

Async (Flask 2.0+)

Flask 는 sync 지향이지만 async def view 를 제한적으로 지원:

@app.get("/async")
async def async_view():
    await asyncio.sleep(0.1)
    return "done"

내부적으로 async view 를 sync 스레드에서 실행 (asgiref.sync.async_to_sync). 비동기 이점 없음. 진짜 async 앱은 FastAPI, Quart, Starlette 사용.

Extension 목록 (핵심)

Extension	역할
Flask-SQLAlchemy	ORM 통합
Flask-Migrate	Alembic 마이그레이션
Flask-Login	세션 기반 인증
Flask-WTF	폼 + CSRF
Flask-Caching	서버측 캐시
Flask-CORS	CORS 헤더
Flask-JWT-Extended	JWT 인증
Flask-Limiter	Rate limiting
Flask-RESTful / Flask-Smorest	REST API 유틸
Flask-Session	서버측 세션 (Redis 등)
Flask-Talisman	보안 헤더
Flask-Admin	관리자 UI

자세한 것은 [[flask-extensions|Flask Extensions]] 참조.

개발 vs 프로덕션

# 개발
flask --app app run --debug

# 프로덕션 (Gunicorn)
gunicorn myapp:create_app() --workers 4 --bind 0.0.0.0:8000

절대 app.run(debug=True) 로 프로덕션 배포 금지. 내장 서버는 개발용, debug=True 는 임의 코드 실행 취약점.

자세한 것은 [[flask-deployment|Flask Deployment]] 참조.

최근 (Flask 3.x) 변화

Python 3.9+ 만 지원
route 대신 method-specific 데코레이터 (@app.get, @app.post, …)
Blueprint 의 url_prefix 오버라이드 개선
typing 관련 개선
DEBUG 모드 개선
Werkzeug 3.x: signature 검증 강화, HTTP/2 방향 준비 (실제 http/2 지원은 미정)

Flask vs FastAPI

축	Flask	FastAPI
비동기	Sync 중심 (제한적 async)	Async first
타입 검증	수동 (Flask-WTF, marshmallow)	자동 (Pydantic)
OpenAPI 자동	X (Flask-Smorest 등 추가)	O
성능 (async)	낮음	높음
생태계	20년, 방대	신생 (2018+), 성장 중
템플릿 (SSR)	Jinja2 통합	별도 설치 필요
학습 곡선	완만	완만
관용	Blueprint 파일 분할	APIRouter

FastAPI 로 대체할 것인가: 새 REST API 프로젝트는 FastAPI 유리. 서버-사이드 렌더링 (Jinja2) 중심 웹앱은 Flask 여전히 우세. 기존 Flask 서비스 마이그레이션은 비용 정당화 필요.

함정

[!WARNING] app.run(debug=True) 를 프로덕션에 노출 금지. Werkzeug debugger 는 원격 코드 실행 취약. 반드시 Gunicorn/uWSGI.

[!CAUTION] thread-local 컨텍스트 함정. request 스코프 데이터는 g. 함수 전역에 저장하면 request 간 leak.

[!WARNING] async def view 는 진짜 async 가 아님. 성능 이점 없음. 진짜 async 필요하면 FastAPI/Quart.

[!IMPORTANT] Extension 초기화 순서. db.init_app(app) 는 create_app 안에서. 앱 생성 시점 전에 하면 여러 앱 인스턴스 문제.

[!CAUTION] JSON 응답의 datetime, UUID. Flask 3.x 는 자동 지원 확대, 하지만 일부 케이스 직접 처리 필요.

김신건의 로그 - 위키 / flask

[Flask] Application Factory Pattern

정의

왜 필요한가

1. 여러 앱 인스턴스

2. 순환 import 회피

3. Extension 지연 초기화

4. Blueprint 등록 지점 명확화

기본 구조

1. Config

2. Extensions

3. Factory 함수

4. WSGI 진입점

flask CLI 통합

Blueprint 순서 관리

여러 앱 인스턴스 (테스트)

App Context 관리

Shell context

함정

관련 위키

[Flask] Blueprints

정의

왜 필요한가

기본 사용

정의

등록

Blueprint 생성 인자

register_blueprint 옵션

Blueprint hook

Nested Blueprint (Flask 2.0+)

프로젝트 구조 예시

Blueprint 안에서 url_for

Template folder 규칙

Static folder 규칙

Blueprint 로 재사용 가능한 컴포넌트

CLI Command (Blueprint 별)

함정

관련 위키

[Flask] Deployment (WSGI, Gunicorn, uWSGI, Docker)

정의

구성 계층

왜 개발 서버는 안 되는가

Gunicorn (권장)

Worker 수

Worker class

Timeout

max-requests

uWSGI (대안)

리버스 프록시 (Nginx)

ProxyFix (X-Forwarded-* 신뢰)

Docker

기본 Dockerfile

Multi-stage build

Kubernetes 배포

Signal handling

로깅

구조화 로그 (JSON)

Sentry, OpenTelemetry

정적 파일

환경 변수 & Secrets

성능 튜닝 체크리스트

함정

관련 위키

[Flask] Extensions (SQLAlchemy, Login, Migrate, WTF, ...)

정의

초기화 패턴 (extensions.py)

Flask-SQLAlchemy 3.x

설정

모델

쿼리 (SQLAlchemy 2.0 style)

트랜잭션

Flask-Migrate

Flask-Login

Flask-WTF

Flask-Caching

CACHE_TYPE

Flask-CORS

Flask-JWT-Extended

Flask-Limiter

Flask-Smorest / Flask-RESTX (OpenAPI)

`flask` CLI 통합

`jsonify()`

`make_response`