آموزش فلسک در پایتون

اولین باری که با فلاسک روبرو شدم، با تردید بود. تازه چند ماهی روی جنگو کار کرده بودم و به ابزارهای آماده‌اش عادت کرده بودم؛ پنل مدیریت، ORM، مهاجرت و همه‌چیز از پیش ساخته‌شده. فلاسک برایم شبیه یک قدم عقب به‌نظر می‌رسید؛ یک کتابخانه‌ی کوچک که همه‌چیز را از شما می‌خواهد خودتان بسازید. یک پروژه‌ی کوچک اما تصمیمم را عوض کرد: یک API سبک که قرار بود فقط چند endpoint داشته باشد و با چند صد رکورد کار کند. جنگو برای آن پروژه مثل بیل مکانیکی برای جابه‌جایی یک گلدان بود؛ فلاسک اما دقیقاً همان اندازه‌ای بود که لازم داشتم. در این مقاله، همان مسیری را می‌روم که با تازه‌کارها طی می‌کنم: از نصب و اولین اپ تا مسیرها، قالب‌ها، دیتابیس، API و استقرار در محیط تولید — با همان تجربه‌ای که در پروژه‌های واقعی به آن رسیده‌ام.

فلاسک چیست و چه نیازی را برطرف می‌کند؟

اگر با مفاهیم پایه‌ی پایتون آشنا نیستید، اول آموزش پایتون از صفر را بخوانید. اما اگر پایتون را می‌شناسید، فلاسک یک «میکروفریم‌ورک» وب است. کلمه‌ی میکرو، به کوچک‌بودن کد آن اشاره دارد، نه به کوچک‌بودن کاربردش. فلاسک هسته‌ای سبک دارد که فقط مسیرها، مدیریت درخواست و قالب‌ها را در خود دارد. برای هر چیز دیگری — از اتصال دیتابیس تا احراز هویت — کتابخانه‌ی جداگانه انتخاب می‌کنید.

این فلسفه، دو پیامد مهم دارد. سمت روشن: شما کنترل کامل دارید و پروژه هر چه بزرگ‌تر می‌شود، دقیقاً با همان اجزایی که خودتان انتخاب کرده‌اید پیش می‌رود. سمت تاریک: در پروژه‌های بزرگ، مجبورید خودتان تصمیم بگیرید چه چیزی مناسب است، و این تصمیم‌گیری برای تازه‌کار می‌تواند فلج‌کننده باشد.

در تجربه‌ی من، فلاسک در سه سناریو انتخاب اول است:

• API و سرویس‌های کوچک: وقتی قرار است فقط چند endpoint داشته باشید و حجم منطق کسب‌وکار پایین است.
• پروژه‌هایی که می‌خواهید از پایه بسازید: بعضی تیم‌ها می‌خواهند ساختار را کامل خودشان تعریف کنند، نه این‌که در چارچوب دیگری اسیر شوند.
• پروژه‌های یادگیری: برای کسی که می‌خواهد بفهمد زیر پوسته‌ی یک فریم‌ورک وب چه می‌گذرد، فلاسک بهترین انتخاب است — چون همه‌چیز جلوی چشم شماست.

فلاسک به شما یاد می‌دهد چگونه وب بسازید، نه این‌که فقط از ابزارش استفاده کنید؛ برای شروع، این تفاوت قیمت دارد و برای کسی که بعداً بخواهد با هر چارچوبی کار کند، سرمایه است.

فلاسک یا جنگو؛ انتخاب درست برای پروژه

این سوال را در مشاوره‌ها زیاد می‌شنوم و جوابم همیشه یک چیز است: به اندازه‌ی پروژه نگاه کنید، نه به محبوبیت چارچوب. تفصیل این مقایسه را در آموزش جنگو برای مبتدیان از منظر جنگو باز کرده‌ام، ولی اینجا خلاصه‌ی معیارها را می‌گویم:

قاعده‌ی عملی من: اگر حجم مدل‌های داده‌ی شما کمتر از پنج است و منطق کسب‌وکار پیچیده نیست، فلاسک انتخاب بهتری است. اگر تعداد مدل‌ها از ده عبور می‌کند و نیاز به پنل مدیریت سریع دارید، جنگو منطقی‌تر است. تجربه‌ی من می‌گوید در انتخاب اشتباه، معمولاً پروژه‌ی فلاسکی که به اندازه‌ی جنگو بزرگ شده، در ماه ششم به آشفتگی می‌رسد — چون ساختارش را کسی از ابتدا طراحی نکرده بود.

نصب فلاسک و اولین اپ

مثل هر پروژه‌ی پایتونی، از یک محیط مجازی شروع کنید. اگر با این مفهوم آشنا نیستید، در آموزش پایتون از صفر توضیح داده‌ام. سپس:

python -m venv venv
source venv/bin/activate        # در ویندوز: venv\Scripts\activate

pip install flask
pip freeze > requirements.txt

حالا یک فایل app.py بسازید:

from flask import Flask

app = Flask(__name__)

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

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

با اجرای python app.py، سرور توسعه روی http://127.0.0.1:5000/ بالا می‌آید. اگر پیام Hello, Flask! را دیدید، همه‌چیز درست است. یک نکته‌ی مهم که در پروژه‌های واقعی بارها به آن تأکید کرده‌ام: سرور توسعه هرگز برای محیط تولید مناسب نیست. برای تولید، از Gunicorn یا uWSGI پشت Nginx استفاده کنید — همین یک تصمیم، جلوی بسیاری از مشکلات کارایی و امنیت را می‌گیرد.

مسیرها و ویوها: قلب فلاسک

در فلاسک، «مسیر» (Route) نگاشتی است از یک URL به یک تابع پایتونی. دکوراتور @app.route این نگاشت را تعریف می‌کند:

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

@app.route("/about")
def about():
    return "About Us"

@app.route("/user/<username>")
def user_profile(username):
    return f"Profile of {username}"

پارامترهای مسیر، به‌طور خودکار به تابع ویو پاس داده می‌شوند. حتی می‌توانید نوع پارامتر را تعیین کنید:

@app.route("/post/<int:post_id>")
def post_detail(post_id):
    return f"Post ID: {post_id}"

در پروژه‌های واقعی، وقتی تعداد مسیرها زیاد می‌شود، توصیه می‌کنم از url_for استفاده کنید به‌جای هارد‌کد کردن URL:

from flask import url_for

url_for("user_profile", username="ali")  # /user/ali

این کار، مزیت بزرگی دارد: اگر بعداً مسیر را تغییر دهید، همه‌ی جاهایی که به آن اشاره کرده‌اید خودکار به‌روز می‌شوند — درست مثل تابع get_permalink در وردپرس که در توابع وردپرس برای ساخت لینک و URL توضیح داده‌ام.

قالب‌ها و Jinja2: لایه‌ی نمایش

برگرداندن یک رشته از ویو، برای تست خوب است ولی برای پروژه‌ی واقعی، به قالب نیاز دارید. فلاسک از موتور قالب Jinja2 استفاده می‌کند که شبیه به قالب‌های جنگو ولی قدرتمندتر است. ساختار پوشه‌ها به این شکل است:

myapp/
├── app.py
└── templates/
    ├── base.html
    └── post.html

یک قالب پایه بسازید:

<!-- templates/base.html -->
<!DOCTYPE html>
<html>
<head>
  <title>{% block title %}My Site{% endblock %}</title>
</head>
<body>
  <header>
    <a href="{{ url_for("home") }}">Home</a>
  </header>
  <main>
    {% block content %}{% endblock %}
  </main>
</body>
</html>

و قالب اختصاصی که از آن ارث‌بری می‌کند:

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

{% block title %}{{ post.title }}{% endblock %}

{% block content %}
  <h1>{{ post.title }}</h1>
  <div>{{ post.body }}</div>
{% endblock %}

و در ویو:

from flask import render_template

@app.route("/post/<slug>")
def post_detail(slug):
    post = get_post_by_slug(slug)
    return render_template("post.html", post=post)

Jinja2 از فیلترها و توابع کمکی نیز پشتیبانی می‌کند که کار با متن و داده را آسان می‌کند. یک نکته‌ی امنیتی مهم: Jinja2 به‌طور پیش‌فرض متغیرها را escape می‌کند و جلوی XSS را می‌گیرد. اگر با مفهوم امنیت در PHP آشنا هستید، امنیت در PHP همان اصول را با جزئیات بیشتری توضیح می‌دهد — فقط در فلاسک، این محافظت پیش‌فرض فعال است.

در فلاسک، قالب‌ها فقط نمایش نمی‌دهند؛ خط دفاعی اول در برابر XSS هستند، اگر و فقط اگر از escape پیش‌فرض خارج نشوید.

مدیریت درخواست و فرم‌ها

فلاسک به‌طور پیش‌فرض ابزاری برای مدیریت فرم ندارد. برای فرم‌های ساده، از شیء request استفاده می‌کنید:

from flask import request, redirect, url_for, flash

@app.route("/contact", methods=["GET", "POST"])
def contact():
    if request.method == "POST":
        name = request.form.get("name", "").strip()
        email = request.form.get("email", "").strip()
        message = request.form.get("message", "").strip()

        if not name or not email or not message:
            flash("All fields are required.", "error")
        else:
            save_message(name, email, message)
            flash("Message received.", "success")
            return redirect(url_for("contact"))

    return render_template("contact.html")

برای فرم‌های پیچیده‌تر، کتابخانه‌ی Flask-WTF را نصب می‌کنم که اعتبارسنجی و محافظت CSRF را به‌طور خودکار انجام می‌دهد:

pip install flask-wtf

from flask_wtf import FlaskForm
from wtforms import StringField, TextAreaField, SubmitField
from wtforms.validators import DataRequired, Email

class ContactForm(FlaskForm):
    name = StringField("Name", validators=[DataRequired()])
    email = StringField("Email", validators=[DataRequired(), Email()])
    message = TextAreaField("Message", validators=[DataRequired()])
    submit = SubmitField("Send")

تجربه‌ی من: در پروژه‌های واقعی، این کتابخانه ماه‌ها کار را ذخیره می‌کند. اگر با مفهوم CSRF در بستر دیگری آشنا هستید، در ساخت فرم تماس با PHP نمونه‌ی معادلش را به شکل دستی پیاده کرده‌ام.

کار با دیتابیس: Flask-SQLAlchemy

فلاسک به‌طور پیش‌فرض ORM ندارد. رایج‌ترین انتخاب، SQLAlchemy است که با پکیج Flask-SQLAlchemy یکپارچه می‌شود:

pip install flask-sqlalchemy

سپس در کد:

from flask import Flask
from flask_sqlalchemy import SQLAlchemy

app = Flask(__name__)
app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///site.db"
db = SQLAlchemy(app)

class Post(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    title = db.Column(db.String(200), nullable=False)
    body = db.Column(db.Text, nullable=False)

    def __repr__(self):
        return f"<Post {self.title}>"

و برای ساخت جدول‌ها:

with app.app_context():
    db.create_all()

حالا می‌توانید رکوردها را با کد پایتونی بسازید:

post = Post(title="Hello", body="First post")
db.session.add(post)
db.session.commit()

posts = Post.query.all()

مفهوم ORM در فلاسک، همان است که در ORM چیست و چگونه کار با دیتابیس را ساده می‌کند به‌طور عمومی توضیح داده‌ام. اما یک هشدارِ تجربی: در پروژه‌های بزرگ، SQLAlchemy می‌تواند کوئری‌های ناخواسته‌ای بسازد که برای تازه‌کار پنهان است. مشکل کلاسیک N+1 در رابطه‌های پیچیده، در ماه دوم یا سوم خودش را نشان می‌دهد. برای مقیاس‌پذیری، با joinedload و selectinload آشنا شوید — همان درسی که در بهینه‌سازی کوئری‌های وردپرس با کدنویسی معادلش را در بستر PHP دیده‌ام.

ساخت API با فلاسک

یکی از پرکاربردترین کاربردهای فلاسک، ساخت API است. برای این کار، کتابخانه‌ی Flask-RESTful یا روش ساده‌ی برگرداندن JSON را می‌توانید استفاده کنید:

from flask import jsonify

@app.route("/api/posts", methods=["GET"])
def api_posts():
    posts = Post.query.all()
    return jsonify([
        {"id": p.id, "title": p.title, "body": p.body}
        for p in posts
    ])

@app.route("/api/posts", methods=["POST"])
def api_create_post():
    data = request.get_json()
    post = Post(title=data["title"], body=data["body"])
    db.session.add(post)
    db.session.commit()
    return jsonify({"id": post.id}), 201

همین چند خط کد، یک API ساده‌ی CRUD می‌سازد. اگر با مفهوم API آشنا نیستید، API چیست و چه کاربردی دارد پیش‌نیاز خوبی است. برای پروژه‌های API-محور، دو ابزار که در تجربه‌ی خودم مؤثر بوده‌اند: Marshmallow برای اعتبارسنجی و سریالایز، و Flask-JWT-Extended برای احراز هویت مبتنی بر توکن.

احراز هویت و مدیریت نشست

فلاسک به‌طور پیش‌فرض، سیستم احراز هویت کامل ندارد. کتابخانه‌ی استاندارد برای این کار Flask-Login است:

pip install flask-login

from flask_login import LoginManager, login_required, current_user

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

@app.route("/dashboard")
@login_required
def dashboard():
    return f"Welcome, {current_user.username}"

نکته‌ی مهم در پروژه‌های واقعی: SECRET_KEY را در app.config از فایل تنظیمات یا متغیرهای محیطی بخوانید، نه هارد‌کد در کد. اگر این مقدار فاش شود، تمام نشست‌های کاربران شما در معرض خطر قرار می‌گیرند. همین قاعده در پروژه‌های وردپرسی هم صادق است — اصولی که در امنیت در PHP برای آن توضیح داده‌ام، مستقیماً در فلاسک هم به‌کار می‌آید.

ساختار پروژه‌ی حرفه‌ای با Blueprints

وقتی پروژه‌ی فلاسکی از چند فایل عبور می‌کند، همه‌چیز در یک app.py جمع‌کردن، به آشفتگی می‌انجامد. راه‌حل استاندارد، استفاده از Blueprints است — قطعه‌قطعه کردن مسیرها در فایل‌های جدا:

myapp/
├── app.py
├── blog/
│   ├── __init__.py
│   ├── routes.py
│   └── models.py
├── auth/
│   ├── __init__.py
│   └── routes.py
└── templates/
    ├── blog/
    └── auth/

سپس در هر بلوپرینت:

# blog/__init__.py
from flask import Blueprint

blog_bp = Blueprint("blog", __name__, url_prefix="/blog")

from . import routes

# blog/routes.py
from . import blog_bp

@blog_bp.route("/")
def index():
    return "Blog Index"

و در فایل اصلی:

from blog import blog_bp
app.register_blueprint(blog_bp)

این ساختار، همان چیزی است که در بلندمدت پروژه را زنده نگه می‌دارد. اگر با ساختار افزونه‌ی وردپرس آشنا هستید، همان تفکیک لایه‌ها در ساختار فایل‌های یک افزونه استاندارد وردپرس را در فلاسک با Blueprints می‌بینید.

استقرار فلاسک در محیط تولید

سرور توسعه‌ی فلاسک، برای تولید ساخته نشده است. برای محیط واقعی، معمولاً این ترکیب را انتخاب می‌کنم:

pip install gunicorn

gunicorn -w 4 -b 127.0.0.1:8000 app:app

این دستور، چهار worker موازی راه‌اندازی می‌کند که هر یک، یک کپی از اپلیکیشن را سرو می‌کند. سپس Nginx به‌عنوان reverse proxy، درخواست‌های کاربر را به این workerها هدایت می‌کند. اگر با پروژه‌های PHP آشنا هستید، این ترکیب شبیه به PHP-FPM + Nginx است که در بهینه‌سازی سرور برای وردپرس توضیح داده‌ام — فقط در پایتون، worker ها خودشان را در حافظه نگه می‌دارند، پس مدیریت منابع متفاوت است.

سه نکته‌ی مهم در استقرار که در پروژه‌های واقعی به آن‌ها رسیده‌ام:

• محیط مجازی را روی سرور بسازید: هرگز پکیج‌ها را روی محیط سراسری سرور نصب نکنید.
• متغیرهای محیطی برای تنظیمات حساس: SECRET_KEY، DATABASE_URL و دیگر مقادیر حساس را از محیط بخوانید، نه از کد.
• لاگ متمرکز: لاگ‌های Gunicorn و اپلیکیشن را در یک مسیر مشخص جمع کنید. در دیباگ مشکلات تولید، همین یک تصمیم، ساعت‌ها صرفه‌جویی می‌کند.

اشتباهاتی که در پروژه‌های واقعی دیده‌ام

در بازبینی پروژه‌های فلاسکی، این اشتباهات را زیاد دیده‌ام و هر کدام، یک درس عملی است:

• نگه‌داشتن debug=True در تولید: این تنظیم، کد را در هر تغییر ری‌لود می‌کند و صفحه‌ی خطای تعاملی نمایش می‌دهد که می‌تواند به مهاجم اطلاعات بدهد. در تولید، حتماً خاموشش کنید.
• استفاده از request.form بدون اعتبارسنجی: request.form["key"] اگر کلید نباشد، KeyError می‌دهد و صفحه‌ی ۵۰۰ نمایش می‌دهد. همیشه از request.form.get("key", default) استفاده کنید.
• نبودِ CSRF در فرم‌ها: در پروژه‌هایی که Flask-WTF استفاده نکرده بودند، فرم‌ها بدون توکن CSRF بودند. این خطا در سایت‌های کوچک خودش را نشان نمی‌دهد ولی در سایت‌های پربازدید می‌تواند فاجعه بسازد.
• کوئری‌های N+1 در رابطه‌ها: وقتی یک رابطه‌ی یک-به-چند را در قالب‌ها پیمایش می‌کنید، ممکن است به‌ازای هر رکورد، یک کوئری جدا به دیتابیس برود. برای جلوگیری، از joinedload استفاده کنید.
• قرار دادن منطق کسب‌وکار در ویوها: ویو باید فقط درخواست را بپذیرد و پاسخ را برگرداند. منطق پیچیده را در لایه‌های جدا (Services) بگذارید — همان تفکیکی که در آموزش شی‌گرایی در PHP روی اهمیتش تأکید کرده‌ام.
• نداشتن تست خودکار: فلاسک ابزار تست داخلی دارد. اگر پروژه‌ای بدون تست جلو برود، بعد از چند ماه هر تغییر ریسک شکستن چیزی را دارد. حتی چند تست ساده، ارزشش را دارد.
• نادیده گرفتن migration دیتابیس: برخلاف جنگو، فلاسک به‌طور پیش‌فرض migration ندارد. با Flask-Migrate این کار را اضافه کنید، وگرنه بعد از تغییر مدل، مدیریت دیتابیس تولید به کابوس تبدیل می‌شود.

یک توصیه‌ی عملی از تجربه: قبل از شروع پروژه‌ی فلاسکی، ساختار پوشه‌ها را از همان ابتدا طراحی کنید. حتی اگر پروژه‌ی کوچکی است، با Blueprints شروع کنید. تغییر ساختار در پروژه‌ی بزرگ، بسیار گران‌تر از طراحی درست در همان روز اول است. اگر با گیت در پروژه‌های وب آشنا هستید، گیت در پروژه‌های وردپرسی همان انضباط نسخه‌بندی را نشان می‌دهد که در فلاسک هم باید رعایت شود — با یک شاخه برای هر ویژگی، و مرج فقط بعد از تست.

سخن آخر

فلاسک، برای کسی که از جنگو می‌آید، در ابتدا «کمتر» به نظر می‌رسد؛ ولی بعد از چند پروژه، آدم می‌فهمد که همین «کمتر»، در جای درستش، «دقیق‌تر» است. سه نکته‌ی مهم که در این مقاله به آن‌ها رسیدیم: اول، انتخاب بین فلاسک و جنگو باید بر اساس اندازه‌ی پروژه انجام شود، نه محبوبیت چارچوب — انتخاب درست، هزینه‌ی نگهداری را در بلندمدت به‌شدت پایین می‌آورد؛ دوم، فلاسک برای API و سرویس‌های کوچک، گزینه‌ی بی‌نظیری است چون سبک و خوانا می‌ماند؛ سوم، آزادی فلاسک، مسئولیت می‌آورد — اگر در همان روز اول ساختار Blueprints و مدیریت تنظیمات را جدی نگیرید، در ماه ششم پروژه به آشفتگی می‌رسد.

اگر امروز می‌خواهید شروع کنید، سه کار کوچک پیشنهاد می‌کنم: یک محیط مجازی بسازید، فلاسک را نصب کنید، و یک API کوچک با دو یا سه endpoint بسازید — فقط برای تمرین. همین پروژه‌ی ساده، شبیه‌ترین تجربه به پروژه‌ی واقعی است. اگر تجربه‌ای از انتخاب فلاسک یا جنگو برای پروژه‌های خودتان دارید، یا اگر با یکی از اشتباهات این فهرست روبرو شده‌اید، در دیدگاه‌ها بنویسید؛ همین نکته‌های میدانی، برای خواننده‌ی بعدی از هر مستند رسمی ارزشمندتر است. 🌶️