Python Flask 실전 가이드: 개념, 설치, API 서버와 배포

Python Flask의 개념과 특징, Django·FastAPI 비교, 설치, 라우팅, 템플릿, 정적 파일, GET/POST 처리, JSON API 서버, 프로젝트 구조, Blueprint, DB 연동, 환경변수, 인증, 에러 처리, 로깅, 배포와 Docker 활용까지 정리했습니다.

Python Flask는 가볍고 유연한 웹 프레임워크로, 웹사이트, REST API, 관리자 페이지, AI 서비스 백엔드, 내부 업무 시스템 구축에 널리 활용됩니다. 이 글에서는 Flask의 개념, 설치 방법, 프로젝트 구조, API 서버 구축, 데이터베이스 연동, 배포, 실무 활용법까지 한 번에 정리합니다.

1. Flask란?

Flask는 Python으로 웹 애플리케이션과 API 서버를 만들기 위한 마이크로 웹 프레임워크입니다.

여기서 “마이크로”라는 말은 기능이 부족하다는 뜻이 아닙니다. 오히려 Flask는 핵심 기능만 단단하게 제공하고, 나머지는 개발자가 필요한 도구를 직접 선택할 수 있게 해줍니다.

Flask가 기본으로 제공하는 대표 기능은 다음과 같습니다.

URL 라우팅
HTTP 요청과 응답 처리
HTML 템플릿 렌더링
쿠키와 세션 처리
에러 핸들링
확장 기능 연동 구조

Flask 공식 문서는 현재 3.1.x 버전을 기준으로 제공되고 있으며, PyPI 기준 최신 릴리스는 Flask 3.1.3입니다. Flask는 Python 3.9 이상을 지원합니다.

2. Flask의 특징

2.1 가볍고 단순하다

Flask는 처음 배우기 쉽습니다.

간단한 API 서버는 몇 줄의 코드로도 만들 수 있습니다.

from flask import Flask

app = Flask(__name__)

@app.route("/")
def home():
    return "Hello, Flask!"

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

이 코드만으로 웹 서버가 실행됩니다. 작은 씨앗에서 숲이 자라듯, Flask 프로젝트는 처음에는 작게 시작해 점점 기능을 붙여갈 수 있습니다.

2.2 자유도가 높다

Django가 “완성형 아파트 단지”라면, Flask는 “설계 가능한 작업실”에 가깝습니다.

데이터베이스, 인증, 관리자 페이지, API 문서화 도구 등을 개발자가 직접 선택합니다.

예를 들어 다음 조합이 가능합니다.

ORM: SQLAlchemy
인증: Flask-Login, JWT
API 문서: Swagger, OpenAPI
마이그레이션: Flask-Migrate
배포: Gunicorn, uWSGI, Nginx, Docker

2.3 API 서버 개발에 적합하다

Flask는 REST API 서버를 만들 때 자주 사용됩니다.

특히 다음과 같은 시스템에 적합합니다.

사내 업무용 API
관리자 백엔드
AI 모델 추론 API
RAG 시스템 API
크롤링 결과 제공 API
간단한 데이터 조회 서비스
마이크로서비스 백엔드

3. Flask와 Django, FastAPI 비교

구분	Flask	Django	FastAPI
성격	경량 웹 프레임워크	풀스택 웹 프레임워크	고성능 API 프레임워크
장점	단순함, 자유도, 확장성	관리자 페이지, ORM, 인증 기본 제공	비동기 처리, OpenAPI 자동 문서화
단점	구조를 직접 설계해야 함	무겁게 느껴질 수 있음	초보자에게 타입 힌트 개념 필요
적합한 용도	API, 소규모 웹, 내부 시스템	대형 웹서비스, CMS, 관리자 시스템	고성능 API, AI API, 비동기 서비스

Flask는 “가볍게 시작해서 필요한 만큼 확장하는 방식”에 강합니다. 그래서 프로토타입, PoC, 사내 도구, AI 백엔드 서버에 특히 잘 어울립니다.

4. Flask 설치 방법

4.1 Python 설치 확인

먼저 Python이 설치되어 있는지 확인합니다.

python --version

또는 macOS, Linux에서는 다음 명령을 사용할 수 있습니다.

python3 --version

Flask 3.1.x는 Python 3.9 이상을 지원하므로, 가능하면 최신 Python 버전을 사용하는 것이 좋습니다.

4.2 프로젝트 폴더 생성

mkdir flask-demo
cd flask-demo

4.3 가상환경 생성

macOS / Linux

python3 -m venv venv
source venv/bin/activate

Windows

python -m venv venv
venv\Scripts\activate

가상환경을 사용하는 이유는 프로젝트마다 패키지 버전을 분리하기 위해서입니다.

4.4 Flask 설치

pip install Flask

설치 확인:

flask --version

PyPI 기준 Flask 설치 명령은 pip install Flask이며, 최신 릴리스는 Flask 3.1.3입니다.

5. 첫 번째 Flask 앱 만들기

프로젝트 폴더에 app.py 파일을 생성합니다.

from flask import Flask

app = Flask(__name__)

@app.route("/")
def index():
    return "Hello, Flask!"

@app.route("/about")
def about():
    return "This is Flask example page."

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

실행:

python app.py

브라우저에서 접속:

http://127.0.0.1:5000

6. Flask 라우팅 이해하기

라우팅은 사용자가 접속한 URL에 따라 어떤 함수를 실행할지 연결하는 기능입니다.

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

@app.route("/users")
def users():
    return "User List"

동적 URL도 만들 수 있습니다.

@app.route("/users/<username>")
def user_profile(username):
    return f"Hello, {username}"

예를 들어 /users/kim으로 접속하면 Hello, kim이 출력됩니다.

7. HTML 템플릿 사용하기

Flask는 Jinja2 템플릿 엔진을 사용합니다.

프로젝트 구조:

flask-demo/
├── app.py
└── templates/
    └── index.html

app.py

from flask import Flask, render_template

app = Flask(__name__)

@app.route("/")
def index():
    username = "Kim"
    return render_template("index.html", name=username)

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

templates/index.html

<!DOCTYPE html>
<html>
<head>
    <title>Flask Example</title>
</head>
<body>
    <h1>Hello, {{ name }}</h1>
</body>
</html>

Flask는 HTML과 Python 데이터를 자연스럽게 연결할 수 있습니다.

8. 정적 파일 사용하기

CSS, JavaScript, 이미지 파일은 보통 static 폴더에 저장합니다.

flask-demo/
├── app.py
├── templates/
│   └── index.html
└── static/
    ├── style.css
    └── main.js

HTML에서 CSS 연결:

<link rel="stylesheet" href="{{ url_for('static', filename='style.css') }}">

9. GET, POST 요청 처리

Flask는 HTTP 메서드별 요청 처리가 쉽습니다.

from flask import Flask, request

app = Flask(__name__)

@app.route("/search")
def search():
    keyword = request.args.get("q")
    return f"Search keyword: {keyword}"

@app.route("/login", methods=["POST"])
def login():
    username = request.form.get("username")
    password = request.form.get("password")
    return f"Login user: {username}"

GET 요청 예시:

/search?q=flask

POST 요청은 로그인, 회원가입, 게시글 작성 등에 사용됩니다.

10. JSON API 서버 만들기

Flask는 REST API 서버로도 많이 사용됩니다.

from flask import Flask, jsonify, request

app = Flask(__name__)

users = [
    {"id": 1, "name": "Kim"},
    {"id": 2, "name": "Lee"}
]

@app.route("/api/users", methods=["GET"])
def get_users():
    return jsonify(users)

@app.route("/api/users", methods=["POST"])
def create_user():
    data = request.get_json()
    new_user = {
        "id": len(users) + 1,
        "name": data["name"]
    }
    users.append(new_user)
    return jsonify(new_user), 201

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

테스트:

curl http://127.0.0.1:5000/api/users

POST 요청:

curl -X POST http://127.0.0.1:5000/api/users \
-H "Content-Type: application/json" \
-d '{"name":"Park"}'

11. Flask 프로젝트 구조 추천

작은 프로젝트는 app.py 하나로도 충분합니다. 하지만 실무에서는 기능별로 파일을 분리하는 것이 좋습니다.

flask-project/
├── app/
│   ├── __init__.py
│   ├── routes/
│   │   └── user_routes.py
│   ├── models/
│   │   └── user.py
│   ├── services/
│   │   └── user_service.py
│   └── templates/
├── config.py
├── requirements.txt
└── run.py

역할은 다음과 같습니다.

폴더/파일	역할
`routes`	URL 라우팅 관리
`models`	데이터베이스 모델
`services`	비즈니스 로직
`templates`	HTML 템플릿
`config.py`	환경설정
`run.py`	실행 진입점

12. Blueprint로 기능 분리하기

Flask의 Blueprint는 기능별 라우터를 분리하는 도구입니다.

app/routes/user_routes.py

from flask import Blueprint, jsonify

user_bp = Blueprint("user", __name__)

@user_bp.route("/users")
def users():
    return jsonify([
        {"id": 1, "name": "Kim"},
        {"id": 2, "name": "Lee"}
    ])

app/__init__.py

from flask import Flask
from app.routes.user_routes import user_bp

def create_app():
    app = Flask(__name__)
    app.register_blueprint(user_bp, url_prefix="/api")
    return app

run.py

from app import create_app

app = create_app()

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

접속:

http://127.0.0.1:5000/api/users

Blueprint를 사용하면 프로젝트가 커져도 코드가 덜 엉킵니다. 케이블 정리함 같은 존재입니다.

13. 데이터베이스 연동

Flask에서 데이터베이스를 사용할 때는 보통 SQLAlchemy를 많이 사용합니다.

설치:

pip install flask-sqlalchemy

예시:

from flask import Flask, jsonify
from flask_sqlalchemy import SQLAlchemy

app = Flask(__name__)

app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///app.db"
app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False

db = SQLAlchemy(app)

class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(100), nullable=False)

@app.route("/init-db")
def init_db():
    db.create_all()
    return "Database initialized"

@app.route("/users")
def get_users():
    users = User.query.all()
    return jsonify([
        {"id": user.id, "name": user.name}
        for user in users
    ])

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

SQLite는 테스트용으로 좋고, 실무에서는 MySQL, PostgreSQL을 많이 사용합니다.

14. 환경변수 관리

실무에서는 비밀번호, DB 주소, API 키를 코드에 직접 넣으면 안 됩니다.

.env 파일을 사용합니다.

설치:

pip install python-dotenv

.env

FLASK_ENV=development
SECRET_KEY=my-secret-key
DATABASE_URL=sqlite:///app.db

config.py

import os
from dotenv import load_dotenv

load_dotenv()

class Config:
    SECRET_KEY = os.getenv("SECRET_KEY")
    SQLALCHEMY_DATABASE_URI = os.getenv("DATABASE_URL")

환경변수는 애플리케이션의 금고입니다. 코드 저장소에 비밀키를 그대로 올리는 일은 반드시 피해야 합니다.

15. Flask에서 인증 구현하기

Flask에서 인증은 여러 방식으로 구현할 수 있습니다.

15.1 세션 기반 인증

웹사이트 로그인에 적합합니다.

대표 확장:

pip install flask-login

주요 개념:

로그인 상태 유지
세션 관리
로그인 필요 페이지 보호
로그아웃 처리

15.2 JWT 기반 인증

REST API 서버나 모바일 앱 백엔드에 적합합니다.

대표 확장:

pip install flask-jwt-extended

JWT 방식은 서버가 세션을 직접 저장하지 않고, 클라이언트가 토큰을 보관하는 구조입니다.

16. Flask 에러 처리

사용자가 잘못된 URL로 접근했을 때 직접 에러 페이지를 만들 수 있습니다.

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

@app.errorhandler(500)
def server_error(error):
    return {"error": "Internal server error"}, 500

API 서버에서는 HTML보다 JSON 형태의 에러 응답을 주는 것이 좋습니다.

17. Flask 로깅

실무 서버에서는 로그가 매우 중요합니다.

import logging

logging.basicConfig(level=logging.INFO)

@app.route("/")
def index():
    app.logger.info("Index page accessed")
    return "Hello Flask"

로그로 확인할 수 있는 정보:

API 요청 시간
에러 발생 위치
사용자 요청 파라미터
외부 API 호출 결과
DB 처리 시간

장애가 났을 때 로그는 블랙박스입니다.

18. Flask 배포 구조

개발 단계에서는 다음 방식으로 실행합니다.

python app.py

하지만 운영 환경에서는 Flask 내장 서버를 그대로 사용하지 않습니다. 일반적으로 아래 구조를 사용합니다.

Client
  ↓
Nginx
  ↓
Gunicorn
  ↓
Flask App
  ↓
Database

Gunicorn 설치:

pip install gunicorn

실행:

gunicorn -w 4 -b 0.0.0.0:8000 run:app

Nginx는 외부 요청을 받고, Gunicorn은 Python 애플리케이션을 실행합니다.

19. Docker로 Flask 실행하기

requirements.txt

Flask
gunicorn

Dockerfile

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:8000", "run:app"]

빌드:

docker build -t flask-app .

실행:

docker run -p 8000:8000 flask-app

Docker를 사용하면 개발 환경과 운영 환경의 차이를 줄일 수 있습니다.

20. Flask 실무 활용 사례

20.1 사내 관리자 시스템

Flask는 사내 관리자 페이지를 빠르게 만들 때 좋습니다.

예:

사용자 관리
로그 조회
배치 작업 실행
통계 대시보드
파일 업로드 관리

20.2 REST API 서버

프론트엔드 React, Vue, Next.js와 연동하는 API 서버로 활용할 수 있습니다.

예:

React / Next.js
  ↓
Flask REST API
  ↓
MySQL / PostgreSQL

20.3 AI 모델 API 서버

머신러닝 모델을 Flask API로 감싸서 서비스할 수 있습니다.

@app.route("/predict", methods=["POST"])
def predict():
    data = request.get_json()
    text = data["text"]

    result = {
        "input": text,
        "label": "positive",
        "score": 0.92
    }

    return jsonify(result)

AI 모델, RAG 시스템, 문서 요약, 이미지 분석 API 서버에도 Flask를 활용할 수 있습니다.

20.4 크롤링 결과 제공 서버

크롤러가 수집한 데이터를 DB에 저장하고, Flask API로 조회할 수 있습니다.

예:

뉴스 수집 결과 API
보안 위협 인텔리전스 API
가격 모니터링 API
로그 분석 결과 API

21. Flask 개발 시 주의할 점

21.1 프로젝트 구조를 초기에 잡아야 한다

Flask는 자유도가 높기 때문에 구조를 아무렇게나 만들면 금방 복잡해집니다.

초기부터 다음을 분리하는 것이 좋습니다.

라우터
서비스 로직
데이터베이스 모델
설정 파일
공통 유틸
에러 핸들러

21.2 보안 설정을 신경 써야 한다

주의해야 할 항목:

debug=True 운영 환경 사용 금지
SECRET_KEY 노출 금지
SQL Injection 방지
XSS 방지
CORS 정책 관리
인증 토큰 만료 시간 설정
파일 업로드 확장자 검증

21.3 대규모 서비스에는 설계가 필요하다

Flask 자체는 가볍지만, 대규모 서비스에서는 다음 요소가 필요합니다.

Gunicorn 워커 수 조정
Nginx 리버스 프록시
Redis 캐시
Celery 비동기 작업
DB 커넥션 풀
모니터링
로그 수집
CI/CD 배포 자동화

22. Flask 추천 패키지

목적	패키지
ORM	Flask-SQLAlchemy
DB 마이그레이션	Flask-Migrate
로그인	Flask-Login
JWT 인증	Flask-JWT-Extended
CORS	Flask-CORS
폼 처리	Flask-WTF
API 문서	Flasgger, flask-smorest
환경변수	python-dotenv
배포	Gunicorn
비동기 작업	Celery
캐시	Redis

23. Flask 학습 로드맵

1단계: 기본 개념

HTTP 요청과 응답
URL 라우팅
GET, POST
JSON 응답
HTML 템플릿

2단계: 웹 애플리케이션 구축

템플릿 분리
정적 파일 관리
폼 처리
세션 처리
에러 페이지

3단계: API 서버 구축

REST API 설계
JSON 요청 처리
상태 코드 관리
인증 토큰
API 문서화

4단계: 데이터베이스 연동

SQLite
MySQL
PostgreSQL
SQLAlchemy
마이그레이션

5단계: 운영 배포

Gunicorn
Nginx
Docker
환경변수
로그 관리
모니터링

24. Flask 예제 프로젝트 아이디어

초보자라면 다음 프로젝트를 만들어보면 좋습니다.

24.1 Todo API

기능:

할 일 등록
할 일 목록 조회
할 일 수정
할 일 삭제

학습 포인트:

REST API
JSON
CRUD
SQLite

24.2 게시판

기능:

글 작성
글 목록
글 상세
글 수정
글 삭제

학습 포인트:

템플릿
데이터베이스
폼 처리
페이지 라우팅

24.3 로그인 시스템

기능:

회원가입
로그인
로그아웃
내 정보 조회

학습 포인트:

세션
비밀번호 해시
인증 처리
접근 권한 제어

24.4 AI 문장 분석 API

기능:

문장 입력
감정 분석
결과 JSON 반환

학습 포인트:

AI 모델 연동
API 서버
JSON 처리
외부 라이브러리 연동

25. 결론

Flask는 Python 웹 개발을 시작하기에 매우 좋은 프레임워크입니다.

가볍고 단순하지만, 확장성을 갖추고 있어 작은 API 서버부터 실무용 백엔드 시스템까지 만들 수 있습니다.

Flask의 핵심 장점은 다음과 같습니다.

배우기 쉽다
코드가 직관적이다
자유도가 높다
REST API 개발에 적합하다
AI, 데이터, 자동화 시스템과 잘 어울린다
Docker, Nginx, Gunicorn과 함께 실무 배포가 가능하다

다만 자유도가 높은 만큼 프로젝트 구조와 보안, 배포 설계를 개발자가 직접 신경 써야 합니다.

정리하면 Flask는 “작게 시작해서 크게 키울 수 있는 Python 웹 프레임워크”입니다. Python으로 웹 서버, API 서버, AI 백엔드, 사내 업무 시스템을 만들고 싶다면 Flask는 여전히 좋은 선택지입니다.

목차

1. Flask란?

2. Flask의 특징

2.1 가볍고 단순하다

2.2 자유도가 높다

2.3 API 서버 개발에 적합하다

3. Flask와 Django, FastAPI 비교

4. Flask 설치 방법

4.1 Python 설치 확인

4.2 프로젝트 폴더 생성

4.3 가상환경 생성

4.4 Flask 설치

5. 첫 번째 Flask 앱 만들기

6. Flask 라우팅 이해하기

7. HTML 템플릿 사용하기

8. 정적 파일 사용하기

9. GET, POST 요청 처리

10. JSON API 서버 만들기

11. Flask 프로젝트 구조 추천

12. Blueprint로 기능 분리하기

13. 데이터베이스 연동

14. 환경변수 관리

15. Flask에서 인증 구현하기

15.1 세션 기반 인증

15.2 JWT 기반 인증

16. Flask 에러 처리

17. Flask 로깅

18. Flask 배포 구조

19. Docker로 Flask 실행하기

20. Flask 실무 활용 사례

20.1 사내 관리자 시스템

20.2 REST API 서버

20.3 AI 모델 API 서버

20.4 크롤링 결과 제공 서버

21. Flask 개발 시 주의할 점

21.1 프로젝트 구조를 초기에 잡아야 한다

21.2 보안 설정을 신경 써야 한다

21.3 대규모 서비스에는 설계가 필요하다

22. Flask 추천 패키지

23. Flask 학습 로드맵

1단계: 기본 개념

2단계: 웹 애플리케이션 구축

3단계: API 서버 구축

4단계: 데이터베이스 연동

5단계: 운영 배포

24. Flask 예제 프로젝트 아이디어

24.1 Todo API

24.2 게시판

24.3 로그인 시스템

24.4 AI 문장 분석 API

25. 결론

댓글