Flask چیست؟ ساخت یک API ساده با فلسک در کمتر از ۳۰ دقیقه

Flask یک فریمورک سبک و مینیمال برای توسعه وب با زبان پایتون است که به دلیل سادگی، انعطاف‌پذیری و یادگیری سریع، گزینه‌ای محبوب میان برنامه‌نویسان تازه‌کار و حرفه‌ای محسوب می‌شود. برخلاف فریمورک‌های سنگین‌تر مانند Django، فلسک هیچ اجبار خاصی در ساختار پروژه، دیتابیس یا ابزارهای جانبی ندارد و به توسعه‌دهنده اجازه می‌دهد تنها با چند خط کد یک API یا وب‌سرویس ساده راه‌اندازی کند. این ویژگی‌ها باعث شده Flask به انتخابی مناسب برای پروژه‌های کوچک، نمونه‌سازی سریع، و آموزش مفاهیم پایه توسعه وب تبدیل شود.

در این مطلب، با اصول اولیه Flask آشنا می‌شوید و قدم‌به‌قدم یک API ساده را در کمتر از ۳۰ دقیقه پیاده‌سازی خواهید کرد.

نصب و راه‌اندازی اولیه

برای شروع کار با Flask، تنها به پایتون و یک ویرایشگر نیاز دارید. مراحل زیر را دنبال کنید تا پروژه‌ی خود را آماده کنید:

۱. نصب Flask با pip

اگر پایتون را از قبل نصب کرده‌اید، کافی‌ست دستور زیر را در ترمینال یا CMD اجرا کنید:

pip install flask

برای اطمینان از نصب موفق، می‌توانید نسخه‌ی Flask را بررسی کنید:

python -m flask --version

۲. ساخت پوشه پروژه

یک پوشه جدید برای پروژه ایجاد کنید. مثلاً:

mkdir flask_api_demo
cd flask_api_demo

درون این پوشه، یک فایل اصلی به نام app.py بسازید:

touch app.py

۳. ایجاد محیط مجازی (اختیاری ولی توصیه‌شده)

برای مدیریت وابستگی‌ها، بهتر است از محیط مجازی استفاده کنید:

python -m venv venv
source venv/bin/activate  # در لینوکس یا مک
venv\Scripts\activate     # در ویندوز

سپس Flask را در همین محیط نصب کنید تا وابستگی‌ها محدود به پروژه باشند.

۴. ساختار اولیه فایل `app.py`

در فایل app.py، کد زیر را بنویسید تا یک سرور ساده راه‌اندازی شود:

from flask import Flask

app = Flask(__name__)

@app.route('/')
def home():
    return 'سلام، Flask آماده است!'

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

اجرای این فایل باعث می‌شود یک سرور محلی روی پورت ۵۰۰۰ راه‌اندازی شود. حالا می‌توانید در مرورگر به آدرس http://localhost:5000 بروید و پیام خوش‌آمد را ببینید.

ساخت اولین API

در این بخش، یک API ساده با Flask می‌سازیم که بتواند به درخواست‌های GET و POST پاسخ دهد. هدف این است که بدون پیچیدگی، منطق پایه‌ی یک وب‌سرویس را درک و اجرا کنیم.

۱. تعریف یک route ساده برای GET

در فایل app.py، یک مسیر جدید تعریف می‌کنیم که پیام خوش‌آمد را برمی‌گرداند:

from flask import Flask

app = Flask(__name__)

@app.route('/hello', methods=['GET'])
def hello():
    return {'message': 'سلام! این یک API ساده با Flask است.'}

با اجرای برنامه و مراجعه به آدرس http://localhost:5000/hello، پاسخ JSON را مشاهده خواهید کرد.

۲. افزودن route برای POST

اکنون یک مسیر جدید اضافه می‌کنیم که داده‌ای را از کاربر دریافت کرده و پردازش کند:

from flask import request

@app.route('/echo', methods=['POST'])
def echo():
    data = request.get_json()
    name = data.get('name', 'کاربر ناشناس')
    return {'message': f'سلام {name}! داده‌ی شما دریافت شد.'}

برای تست این مسیر، می‌توانید از ابزار Postman یا دستور curl استفاده کنید:

curl -X POST http://localhost:5000/echo -H "Content-Type: application/json" -d '{"name": "Ali"}'

پاسخ باید چیزی شبیه به این باشد:

{"message": "سلام Ali! داده‌ی شما دریافت شد."}

۳. اجرای سرور

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

python app.py

اگر debug=True فعال باشد، هر تغییری در کد به‌صورت خودکار اعمال خواهد شد.

ساختار پیشنهادی برای پروژه‌های کوچک با Flask

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

چرا به ساختار نیاز داریم؟

در مراحل ابتدایی یادگیری Flask، ممکن است تمام کدها را در یک فایل بنویسید (مثلاً app.py). این روش برای تست‌های سریع و نمونه‌سازی اولیه مناسب است، اما به‌محض اینکه تعداد routeها، مدل‌ها، فایل‌های پیکربندی یا وابستگی‌ها افزایش یابد، مدیریت پروژه دشوار می‌شود. ساختاردهی مناسب باعث می‌شود:

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

ساختار پیشنهادی پوشه‌ها و فایل‌ها

در ادامه، یک ساختار پیشنهادی برای پروژه‌های کوچک تا متوسط با Flask ارائه می‌شود. این ساختار قابل توسعه بوده و می‌تواند پایه‌ای برای پروژه‌های بزرگ‌تر نیز باشد:

flask_api_demo/
│
├── app.py                  # نقطه ورود اصلی برنامه
├── routes/
│   └── api.py              # تعریف مسیرهای API
├── models/
│   └── user.py             # تعریف مدل‌های داده (در صورت استفاده از ORM)
├── config.py               # تنظیمات و پیکربندی پروژه
├── utils/
│   └── helpers.py          # توابع کمکی و عمومی
├── requirements.txt        # لیست وابستگی‌ها برای نصب با pip
└── README.md               # توضیحات پروژه برای توسعه‌دهندگان

توضیح اجزای ساختار

app.py: این فایل نقطه شروع اجرای برنامه است. معمولاً شامل تعریف اولیه Flask، بارگذاری تنظیمات، ثبت Blueprintها و اجرای سرور است.
routes/api.py: در این فایل مسیرهای مختلف API تعریف می‌شوند. استفاده از Blueprint در این بخش توصیه می‌شود تا بتوان مسیرها را به‌صورت ماژولار مدیریت کرد.
models/user.py: اگر از SQLAlchemy یا هر ORM دیگری استفاده می‌کنید، مدل‌های داده در این پوشه تعریف می‌شوند. این تفکیک باعث می‌شود منطق داده از منطق کنترل جدا باشد.
config.py: شامل تنظیمات عمومی پروژه مانند کلیدهای امنیتی، آدرس دیتابیس، حالت debug و سایر پارامترهای قابل تنظیم است. می‌توان از کلاس‌های مختلف برای محیط‌های توسعه، تست و تولید استفاده کرد.
utils/helpers.py: توابع کمکی مانند اعتبارسنجی داده‌ها، تبدیل فرمت‌ها یا تولید توکن‌ها در این فایل قرار می‌گیرند. این بخش به کاهش تکرار کد کمک می‌کند.
requirements.txt: لیستی از کتابخانه‌های مورد نیاز پروژه که با دستور pip install -r requirements.txt قابل نصب هستند.
README.md: توضیحاتی درباره نحوه نصب، اجرا، تست و توسعه پروژه. این فایل برای همکاری تیمی و مستندسازی بسیار حیاتی است.

استفاده از Blueprint برای مدیریت مسیرها

یکی از قابلیت‌های مهم Flask، استفاده از Blueprint برای تقسیم‌بندی مسیرها و منطق برنامه است. با استفاده از Blueprint می‌توان بخش‌های مختلف پروژه را به‌صورت ماژولار تعریف کرد. مثال ساده‌ای از تعریف یک Blueprint:

# routes/api.py
from flask import Blueprint, jsonify

api = Blueprint('api', __name__)

@api.route('/ping', methods=['GET'])
def ping():
    return jsonify({'message': 'پروژه فعال است!'})

و در فایل app.py:

from flask import Flask
from routes.api import api

app = Flask(__name__)
app.register_blueprint(api, url_prefix='/api')

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

با این ساختار، مسیر /api/ping فعال خواهد بود و پاسخ JSON برمی‌گرداند.

افزودن قابلیت‌های کاربردی به API

تا اینجا یک API ساده با مسیرهای GET و POST ساختیم. حالا وقت آن است که قابلیت‌های حرفه‌ای‌تری به آن اضافه کنیم تا بتواند در پروژه‌های واقعی مورد استفاده قرار گیرد. این بخش به شما کمک می‌کند تا با مفاهیم پایه‌ای مانند دریافت داده‌های JSON، ارسال پاسخ‌های ساخت‌یافته، مدیریت خطاها و استفاده از توابع داخلی Flask آشنا شوید.

دریافت داده‌های JSON از کاربر

در مسیرهای POST، معمولاً داده‌هایی از سمت کلاینت (مثلاً فرم یا اپلیکیشن موبایل) به سرور ارسال می‌شود. Flask این داده‌ها را به‌راحتی از طریق شیء request دریافت می‌کند. مثال:

from flask import request

@app.route('/submit', methods=['POST'])
def submit():
    data = request.get_json()
    username = data.get('username')
    age = data.get('age')
    return {'message': f'کاربر {username} با سن {age} ثبت شد.'}

در این مثال، داده‌های JSON شامل username و age از درخواست استخراج شده و در پاسخ استفاده می‌شوند. اگر داده‌ای ارسال نشود یا ناقص باشد، می‌توان مقدار پیش‌فرض یا پیام خطا تعریف کرد.

ارسال پاسخ JSON با `jsonify`

اگرچه می‌توان پاسخ‌ها را به‌صورت دیکشنری پایتون بازگرداند، استفاده از jsonify توصیه می‌شود تا پاسخ‌ها به‌درستی فرمت شوند و هدرهای مناسب HTTP تنظیم شوند:

from flask import jsonify

@app.route('/status', methods=['GET'])
def status():
    return jsonify({
        'status': 'فعال',
        'version': '1.0.0',
        'author': 'Hesam'
    })

این روش باعث می‌شود پاسخ‌ها در مرورگر یا ابزارهایی مانند Postman به‌صورت ساخت‌یافته نمایش داده شوند.

مدیریت خطاها با `@app.errorhandler`

در پروژه‌های واقعی، مدیریت خطاها اهمیت زیادی دارد. Flask امکان تعریف هندلر برای انواع خطاها را فراهم می‌کند. مثلاً برای خطای ۴۰۴:

@app.errorhandler(404)
def not_found(error):
    return jsonify({'error': 'صفحه مورد نظر یافت نشد.'}), 404

همچنین می‌توان خطاهای سفارشی برای اعتبارسنجی داده‌ها یا محدودیت‌های دسترسی تعریف کرد.

استفاده از `request.args` برای دریافت پارامترهای URL

در مسیرهای GET، گاهی نیاز است داده‌هایی از URL دریافت شوند. مثلاً:

@app.route('/greet', methods=['GET'])
def greet():
    name = request.args.get('name', 'مهمان')
    return jsonify({'message': f'سلام {name} عزیز!'})

در این مثال، اگر کاربر به آدرس /greet?name=علی مراجعه کند، پیام شخصی‌سازی‌شده دریافت خواهد کرد.

محدود کردن روش‌های HTTP

برای امنیت و وضوح بیشتر، بهتر است مسیرها فقط به روش‌های مورد نظر پاسخ دهند. مثلاً:

@app.route('/delete', methods=['DELETE'])
def delete_item():
    return jsonify({'message': 'آیتم حذف شد.'})

اگر کاربر با روش GET یا POST به این مسیر درخواست بفرستد، Flask به‌طور خودکار خطای ۴۰۵ (Method Not Allowed) را برمی‌گرداند.

Curl and Postman Icons

تست و بررسی API با Postman و curl

پس از ساخت مسیرهای مختلف در Flask، مرحله‌ی مهم بعدی تست و اعتبارسنجی عملکرد API است. بدون تست دقیق، نمی‌توان از صحت پاسخ‌ها، مدیریت خطاها، یا تعامل درست با کلاینت‌ها مطمئن شد. در این بخش، با دو ابزار رایج برای تست API آشنا می‌شوید: Postman و curl. هر دو ابزار به شما امکان ارسال درخواست‌های HTTP و مشاهده‌ی پاسخ‌ها را می‌دهند، اما هرکدام مزایا و کاربردهای خاص خود را دارند.

تست با Postman: رابط گرافیکی قدرتمند برای توسعه‌دهندگان

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

مراحل تست با Postman:

نصب و اجرا: ابتدا Postman را از postman.com دانلود و نصب کنید.
ساخت درخواست جدید:
- روی گزینه‌ی "New" کلیک کرده و "Request" را انتخاب کنید.
- نامی برای درخواست انتخاب کرده و آن را در یک مجموعه (Collection) ذخیره کنید.
تنظیم نوع درخواست:
- در بالای صفحه، نوع درخواست را انتخاب کنید (GET ،POST ،DELETE و غیره).
- آدرس مسیر را وارد کنید، مثلاً: http://localhost:5000/echo
ارسال داده در POST:
- به تب "Body" بروید.
- گزینه‌ی "raw" را انتخاب کرده و فرمت را روی "JSON" تنظیم کنید.
- داده‌ی مورد نظر را وارد کنید:
```
{
  "name": "Hesam"
}
```
مشاهده پاسخ:
- روی "Send" کلیک کنید.
- پاسخ JSON را در بخش پایین مشاهده خواهید کرد.
- اگر خطایی رخ دهد، Postman جزئیات آن را نمایش می‌دهد.

مزایای Postman:

رابط گرافیکی مناسب برای افراد مبتدی
امکان ذخیره‌ی درخواست‌ها و مجموعه‌ها
قابلیت تست خودکار و نوشتن اسکریپت‌های اعتبارسنجی
پشتیبانی از احراز هویت، هدرهای سفارشی، و توکن‌ها

تست با curl: ابزار خط فرمانی سریع و سبک

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

مثال‌های کاربردی با curl:

ارسال درخواست GET:
```
curl http://localhost:5000/hello
```

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

curl -X POST http://localhost:5000/echo \
     -H "Content-Type: application/json" \
     -d '{"name": "Hesam"}'

ارسال درخواست با پارامتر URL:
```
curl "http://localhost:5000/greet?name=Hesam"
```

مزایای curl:

سبک و سریع، بدون نیاز به نصب رابط گرافیکی
مناسب برای اسکریپت‌نویسی و تست خودکار در محیط‌های لینوکسی
قابل استفاده در CI/CD و تست‌های خط فرمانی

نکات مهم در تست API

همیشه نوع درخواست (GET ،POST، و غیره) را با دقت انتخاب کنید.
مطمئن شوید که هدر Content-Type برای درخواست‌های POST روی application/json تنظیم شده باشد.
در صورت دریافت خطا، پیام‌های وضعیت HTTP (مانند ۴۰۰، ۴۰۴، ۵۰۰) را بررسی کنید.
برای تست مسیرهای محافظت‌شده، از توکن‌ها یا احراز هویت استفاده کنید.

نکات امنیتی و بهینه‌سازی در توسعه API با Flask

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

امنیت در فلسک

جلوگیری از اجرای کدهای خطرناک

یکی از مهم‌ترین تهدیدها در توسعه API، اجرای کدهای مخرب از سمت کاربر است. برای جلوگیری از این خطر:

هیچ‌گاه داده‌های دریافتی از کاربر را مستقیماً در eval() یا exec() استفاده نکنید.
ورودی‌ها را اعتبارسنجی کنید، مخصوصاً اگر قرار است در دیتابیس ذخیره شوند یا در منطق برنامه استفاده شوند.
از کتابخانه‌هایی مانند marshmallow یا pydantic برای اعتبارسنجی ساختار داده‌ها استفاده کنید.

محدود کردن روش‌های HTTP و مسیرهای حساس

برای جلوگیری از سوءاستفاده از مسیرهای API:

فقط روش‌های مورد نیاز را فعال کنید. مثلاً اگر مسیر /delete فقط برای حذف است، آن را محدود به DELETE کنید.
مسیرهای حساس مانند /admin یا /config را با احراز هویت محافظت کنید.
از پاسخ‌های عمومی برای خطاها استفاده کنید تا اطلاعات داخلی پروژه فاش نشود.

مدیریت خطاها و پاسخ‌های مناسب

پاسخ‌های دقیق و کنترل‌شده به خطاها، هم امنیت را افزایش می‌دهند و هم تجربه کاربر را بهبود می‌بخشند:

از @app.errorhandler برای مدیریت خطاهای رایج مانند ۴۰۰، ۴۰۴، و ۵۰۰ استفاده کنید.
در پاسخ‌های خطا، اطلاعات فنی یا traceback را نمایش ندهید.
برای خطاهای سفارشی، پیام‌های واضح و قابل فهم ارائه دهید.

مثال:

@app.errorhandler(400)
def bad_request(error):
    return jsonify({'error': 'درخواست نامعتبر است.'}), 400

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

برای جلوگیری از تداخل وابستگی‌ها و افزایش امنیت:

همیشه از محیط مجازی (venv) استفاده کنید.
تنظیمات حساس مانند کلیدهای API، رمز پایگاه داده، و حالت debug را در فایل config.py یا فایل .env ذخیره کنید.
از کتابخانه python-dotenv برای بارگذاری تنظیمات از فایل .env استفاده کنید.

مثال فایل .env:

FLASK_ENV=production
SECRET_KEY=your-secret-key
DATABASE_URL=sqlite:///data.db

بهینه‌سازی عملکرد و پاسخ‌دهی

برای افزایش سرعت و کارایی API:

از کش‌کردن پاسخ‌ها برای مسیرهای پرکاربرد استفاده کنید.
اگر از دیتابیس استفاده می‌کنید، کوئری‌ها را بهینه کنید و از ایندکس‌ها بهره ببرید.
در صورت نیاز، از WSGI سرورهایی مانند Gunicorn یا uWSGI برای اجرای Flask در محیط تولید استفاده کنید.

محدود کردن دسترسی و نرخ درخواست‌ها

برای جلوگیری از حملات DDoS یا سوءاستفاده از API:

از کتابخانه‌هایی مانند Flask-Limiter برای محدود کردن تعداد درخواست‌ها در بازه زمانی مشخص استفاده کنید.
مسیرهای عمومی را با محدودیت‌های IP یا توکن محافظت کنید.
در صورت نیاز، از احراز هویت مبتنی بر توکن (JWT) استفاده کنید.

جمع‌بندی

در این آموزش، با فریمورک Flask به‌عنوان یکی از ساده‌ترین و منعطف‌ترین ابزارهای توسعه وب در پایتون آشنا شدیم. قدم‌به‌قدم یک API کاربردی ساختیم، مسیرهای GET و POST را پیاده‌سازی کردیم، داده‌های JSON را دریافت و پردازش کردیم، ساختار پروژه را بهینه کردیم، و در نهایت با ابزارهایی مانند Postman و curl عملکرد API را بررسی کردیم.

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

آشنایی با Flask-Restful برای ساخت APIهای ماژولارتر
استفاده از SQLAlchemy برای مدیریت پایگاه داده
پیاده‌سازی احراز هویت با JWT و مدیریت نشست‌ها
تست‌نویسی با pytest و پوشش‌دهی مسیرهای مختلف
استقرار پروژه روی سرورهای واقعی با Gunicorn ،Nginx و Docker

برای یادگیری کامل و دقیق Flask، بهترین منبع، مستندات رسمی آن است که با جزئیات کامل، مثال‌های کاربردی، و توضیحات مرحله‌به‌مرحله ارائه شده است. این مستندات شامل راهنمای نصب، ساختار پروژه، مدیریت مسیرها، قالب‌ها، دیتابیس، تست‌نویسی، و توسعه API می‌باشد.