اگر می‌خواهی با پایتون یک وب‌اپلیکیشن واقعی بسازی و نمی‌دانی از کجا شروع کنی، Flask ساده‌ترین و سبک‌ترین نقطه ورود است. در این آموزش Flask در پایتون، از نصب و ساخت اولین مسیر تا قالب‌های Jinja2، دریافت داده از فرم، ساختار پروژه و اجرای نهایی روی سرور را قدم‌به‌قدم پیش می‌رویم؛ همه بر پایه نسخه پایدار Flask 3.1. در پایان یک وب‌اپ کارا داری و می‌دانی Flask برای چه پروژه‌هایی بهتر از FastAPI یا Django است.

آموزش Flask در پایتون؛ چه چیزی یاد می‌گیری و چرا مهم است؟

Flask یک فریم‌ورک وب مینیمال (microframework) برای پایتون است؛ هسته‌ای کوچک دارد که با افزونه‌ها گسترش می‌یابد. در این آموزش از نصب و مسیردهی (routing) تا قالب Jinja2، دریافت فرم، Blueprint و اجرای production را می‌بینی. با آشنایی مقدماتی با پایتون، در کمتر از یک ساعت اولین وب‌اپ خودت را می‌سازی. ادامه بده تا مرحله‌به‌مرحله اجرا کنیم.

فهرست مطالب

پیش‌نیازها و نصب Flask 3
اولین اپ Flask؛ مسیر و سلام دنیا
قالب‌ها با Jinja2 و ارسال داده به صفحه
دریافت داده از کاربر (GET و POST)
ساختار پروژه و Blueprint
چرا Flask در برابر FastAPI و Django؟
اجرا و انتشار روی سرور
اشتباهات و خطاهای رایج
سوالات متداول
جمع‌بندی

پیش‌نیازها و نصب Flask

به پایتون ۳.۱۰ یا بالاتر نیاز داری (Flask 3.1 حداقل پایتون ۳.۹ را پشتیبانی می‌کند، اما ۳.۱۱+ توصیه می‌شود). بهترین کار، ساختن محیط مجازی برای هر پروژه است تا وابستگی‌ها جدا بماند.

python -m venv .venv

# ویندوز:
.venv\Scripts\activate
# مک و لینوکس:
source .venv/bin/activate

pip install "flask>=3.1"
pip show flask  # نسخه نصب‌شده، مثلاً 3.1.3

flask: خود فریم‌ورک که Werkzeug (وب سرور توسعه) و Jinja2 (قالب) را هم می‌آورد.
محیط مجازی: جلوگیری از تداخل نسخه‌ها بین پروژه‌ها.
ویرایشگر: VS Code با افزونه Pylance برای تکمیل خودکار.

اولین اپ Flask؛ مسیر و سلام دنیا

یک فایل به نام app.py بساز. تابعی که با دکوراتور @app.route علامت می‌خورد، هر بار بازدید آدرس مربوطه اجرا می‌شود و مقدار برگشتی همان پاسخ HTTP است.

# app.py
from flask import Flask

app = Flask(__name__)

@app.route("/")
def home():
    return "<h1>سلام دنیا از Flask!</h1>"

@app.get("/about")
def about():
    return {"name": "TooAI", "framework": "Flask"}

@app.get("/user/<name>")
def user(name):
    return f"کاربر: {name}"

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

flask --app app run --debug
# یا ساده‌تر:
python app.py

# http://127.0.0.1:5000/        -> سلام دنیا
# http://127.0.0.1:5000/about   -> خروجی JSON
# http://127.0.0.1:5000/user/ali

@app.route: مسیر را به تابع view وصل می‌کند.
@app.get و @app.post: میان‌بر تعیین متد HTTP (از Flask 2.0).
بازگشت دیکشنری: Flask خودش آن را به JSON تبدیل می‌کند.
<name>: پارامتر پویا در مسیر URL.

قالب‌ها با Jinja2 و ارسال داده به صفحه

برای جدا کردن HTML از منطق پایتون از render_template استفاده کن. قالب‌ها در پوشه templates/ قرار می‌گیرند و Jinja2 به‌طور پیش‌فرض خروجی را امن (autoescape) می‌کند.

<!-- templates/index.html -->
<!DOCTYPE html>
<html lang="fa" dir="rtl">
<head><meta charset="utf-8"><title>{{ title }}</title></head>
<body>
  <h1>{{ title }}</h1>
  <ul>
  {% for post in posts %}
    <li>{{ post }}</li>
  {% endfor %}
  </ul>
</body>
</html>

# app.py (بخش اضافه‌شده)
from flask import render_template

@app.get("/posts")
def posts():
    return render_template(
        "index.html",
        title="آخرین مطالب",
        posts=["آموزش Flask", "آموزش FastAPI", "آموزش Pytest"],
    )

{{ }}: نمایش مقدار متغیر.
{% %}: منطق قالب مثل حلقه و شرط.
autoescape: جلوگیری از تزریق HTML/JS؛ برای محتوای امن از |safe استفاده کن.

اگر می‌خواهی خروجی‌ات به سبک API و با مستندسازی خودکار باشد، می‌توانی آموزش FastAPI در پایتون را هم ببینی.

دریافت داده از کاربر (GET و POST)

داده‌های کوئری با request.args و داده‌های فرم با request.form خوانده می‌شوند. برای فرم‌ها هرگز مستقیم به دیتابیس ننویس؛ اعتبارسنجی را جدی بگیر.

from flask import request, redirect, url_for

@app.get("/search")
def search():
    q = request.args.get("q", "")
    return f"جست‌وجو برای: {q}"

@app.post("/contact")
def contact():
    email = request.form.get("email", "").strip()
    if "@" not in email:
        return "ایمیل نامعتبر", 400
    return redirect(url_for("home"))

curl -X POST http://127.0.0.1:5000/contact \
  -d "email=test@tooai.ir"

request.args: پارامترهای آدرس (?q=...).
request.form: فیلدهای ارسالی با متد POST.
url_for: ساخت آدرس از نام تابع؛ از هاردکد کردن URL پرهیز کن.

ساختار پروژه و Blueprint

وقتی تعداد مسیرها زیاد شد، همه را در یک فایل ننویس. با Blueprint اپ را به بخش‌های مستقل (مثل auth و blog) تقسیم کن و سپس ثبتشان کن.

# blog.py
from flask import Blueprint, render_template

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

@bp.get("/")
def index():
    return render_template("blog.html")

# app.py (با factory pattern)
from flask import Flask
from blog import bp as blog_bp

def create_app():
    app = Flask(__name__)
    app.config["SECRET_KEY"] = "کلید-مخفی-تصادفی"
    app.register_blueprint(blog_bp)
    return app

url_prefix: یک پیشوند مشترک به همه مسیرهای Blueprint می‌دهد.
Factory pattern: create_app() تست و پیکربندی محیط را ساده می‌کند.
SECRET_KEY: برای امضای session و فرم‌ها الزامی است؛ آن را در متغیر محیطی نگه دار.

چرا Flask در برابر FastAPI و Django؟

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

معیار	Flask	FastAPI	Django
سبک‌وزنی و انعطاف	زیاد	متوسط	کم (باتری‌همراه)
async بومی	محدود (Flask 3 تا حدی)	عالی	پشتیبانی جزئی
مستندسازی خودکار API	خیر	بله (Swagger)	با DRF
مناسب برای	سایت‌های ساده و متوسط	API و سرویس AI	اپ‌های بزرگ و CMS

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

اجرا و انتشار روی سرور

وب سرور توسعه Flask برای production نیست. آن را با یک WSGI سرور production جایگزین کن: روی لینوکس Gunicorn و روی ویندوز Waitress.

pip install waitress  # ویندوز
waitress-serve --host=0.0.0.0 --port=8000 app:app

# لینوکس:
pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:8000 app:app

گزینه‌های امنیتی: در production مقدار debug=False باشد و پیام خطا به کاربر نشان داده نشود.
پروکسی: جلوی اپ معمولاً Nginx یا یک reverse proxy می‌گذارند.
متغیرهای محیطی: رمزها و کلیدها را از کد جدا و در محیط سرور تعریف کن.

اشتباهات و خطاهای رایج

TemplateNotFound: پوشه templates/ باید کنار فایل اپ باشد؛ نام پوشه را تغییر نده.
Method Not Allowed (۴۰۵): مسیر با @app.get تعریف شده اما فرم با POST می‌فرستد؛ متدها را هماهنگ کن.
اجرای سرور توسعه در production: ناامن و کند است؛ از WSGI سرور واقعی استفاده کن.
هاردکد کردن URL و SECRET_KEY: از url_for و متغیرهای محیطی استفاده کن.
فراموش کردن محیط مجازی: نصب پکیج در محیط جهانی باعث تداخل نسخه‌ها می‌شود.

سوالات متداول

آیا برای یادگیری Flask به دانش پیشرفته پایتون نیاز دارم؟

نه. آشنایی با توابع، دیکشنری و import کافی است؛ بقیه را در مسیر پروژه یاد می‌گیری.

Flask بهتر است یا FastAPI؟

برای API پرسرعت و async، FastAPI؛ برای سایت‌های ساده و رندر سمت سرور، Flask ساده‌تر است. انتخاب را به نوع پروژه گره بزن، نه به محبوبیت.

چطور داده را در دیتابیس ذخیره کنم؟

معمولاً با Flask-SQLAlchemy. برای یادگیری پایه‌ها، ابتدا SQLAlchemy خالص را تمرین کن و بعد افزونه Flask را اضافه کن.

چطور فرم‌ها را امن کنم؟

از اعتبارسنجی سمت سرور، تمپلیت‌های امن Jinja2 با autoescape و در صورت نیاز افزونه‌هایی مثل Flask-WTF برای محافظت CSRF استفاده کن.

تفاوت `flask run` با `app.run()` چیست؟

هر دو سرور توسعه را اجرا می‌کنند؛ flask run از CLI استفاده می‌کند و برای debug یا تعیین اپ مناسب‌تر است.

آیا Flask برای پروژه‌های بزرگ کافی است؟

بله، اگر با Blueprint و factory pattern سازمان‌دهی کنی. اما برای اپ‌های بسیار بزرگ و CMS، Django ساختار آماده بیشتری می‌دهد.

جمع‌بندی

برای شروع کار با Flask این چک‌لیست را مرور کن:

محیط مجازی بساز و flask>=3.1 را نصب کن.
اولین مسیر را با @app.get بنویس و اجرا کن.
قالب‌ها را با render_template و Jinja2 جدا کن.
ورودی کاربر را با request.args و request.form و اعتبارسنجی بگیر.
پروژه را با Blueprint و create_app() سازمان بده.
برای production از Gunicorn یا Waitress استفاده کن و debug را خاموش نگه دار.
برای تست‌نویسی خودکار به آموزش Pytest در پایتون سر بزن.

حالا یک وب‌اپ واقعی داری؛ قدم بعدی افزودن دیتابیس، احراز هویت و استقرار روی دامنه است.

آموزش Flask در پایتون؛ ساخت اولین وب‌اپ از صفر تا اجرا