مقدمه: آماده‌سازی محیط کار

۱. بک‌اند چیست و FastAPI کجای کار است

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

FastAPI یک چارچوب پایتونی برای ساختن همین API‌هاست. سه ویژگی آن را محبوب کرده است:

• از راهنمای نوع پایتون (type hints) استفاده می‌کند: همان int و str | None که در دوره پیشرفته دیدید، اینجا داده ورودی را خودکار تبدیل و بررسی می‌کند.
• برای هر API یک مستند زنده می‌سازد که در مرورگر باز می‌شود و می‌توان همان‌جا درخواست فرستاد.
• از پایه برای async ساخته شده است و هزاران درخواست هم‌زمان را با یک فرایند پاسخ می‌دهد.

۲. پایتون و محیط مجازی

نسخه ۳٫۱۲ یا بالاتر پایتون را از python.org نصب کنید. در ویندوز، هنگام نصب گزینه Add python.exe to PATH را حتماً تیک بزنید. بعد در ترمینال بررسی کنید:

python --version
Python 3.13.5

هر جلسه این دوره پوشه خودش و فایل requirements.txt خودش را دارد. کتابخانه‌ها را هرگز روی پایتون اصلی سیستم نصب نکنید؛ برای هر جلسه یا پروژه یک محیط مجازی بسازید:

cd S02-fastapi-first-steps
python -m venv .venv
.venv\Scripts\activate            # Windows
source .venv/bin/activate         # Linux / macOS
pip install -r requirements.txt

بعد از فعال شدن محیط، نام آن در ابتدای خط ترمینال دیده می‌شود: (.venv). هر بار که ترمینال تازه‌ای باز می‌کنید، باید دوباره فعالش کنید.

۳. ویرایشگر VS Code

VS Code را نصب کنید و این افزونه‌ها را اضافه کنید:

• Python (از Microsoft): اجرا، اشکال‌زدایی و انتخاب محیط مجازی.
• Pylance: بررسی نوع‌ها هنگام نوشتن. در این دوره خیلی به کارتان می‌آید، چون همه کدها راهنمای نوع دارند.
• SQLite Viewer: دیدن محتوای فایل‌های .db بدون نصب برنامه جداگانه.

پوشه یک جلسه را با File → Open Folder باز کنید و از پایین پنجره، مفسر پایتون را روی محیط مجازی همان پوشه بگذارید.

۴. Bruno: میز کار API

در این دوره به جای مرورگر، با برنامه‌ای به نام Bruno به API درخواست می‌فرستیم. در Bruno روش (GET، POST و...)، نشانی، هدرها و بدنه JSON را می‌نویسید، دکمه ارسال را می‌زنید و کد وضعیت و پاسخ را می‌بینید.

دلیل انتخاب Bruno این است که هر مجموعه درخواست، یک پوشه از فایل‌های متنی ساده با پسوند .bru است. این پوشه کنار کد پروژه در Git قرار می‌گیرد و به حساب کاربری نیازی ندارد. از جلسه دوم، پروژه هر جلسه یک پوشه bruno/ دارد. اگر با Postman آشنا هستید، آن هم کار می‌کند.

برای باز کردن یک مجموعه: Open Collection را بزنید، پوشه bruno پروژه را انتخاب کنید و از بالا سمت راست، محیط local را برگزینید.

meta {
  name: Get course 1
  type: http
  seq: 3
}

get {
  url: {{baseUrl}}/courses/1
  body: none
  auth: none
}

tests {
  test("status is 200", function() {
    expect(res.status).to.equal(200);
  });
}

هر فایل .bru یک درخواست است. {{baseUrl}} یک متغیر محیط است و بخش tests بعد از هر اجرا کد وضعیت را بررسی می‌کند.

۵. SQLite و در صورت نیاز PostgreSQL

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

سرورهای واقعی معمولاً از PostgreSQL استفاده می‌کنند. خوشبختانه با SQLAlchemy برای رفتن از SQLite به PostgreSQL فقط باید نشانی اتصال را عوض کرد. PostgreSQL را مستقیم روی ویندوز ۱۱ یا اوبونتوی خودتان نصب می‌کنیم و بعد مثل یک سرویس در پس‌زمینه اجرا می‌شود. روش نصب قدم‌به‌قدم در فصل پنجم آمده است و تا آن وقت لازم نیست کاری بکنید.

۶. اولین سرور

برای اطمینان از اینکه همه چیز درست نصب شده است، اولین برنامه FastAPI را اجرا کنید:

import uvicorn
from fastapi import FastAPI

app = FastAPI(title='Training Center API', version='0.1.0')


@app.get('/')
def home() -> dict[str, str]:
    return {'message': 'Welcome to the Training Center API'}


@app.get('/about')
def about() -> dict[str, str | int]:
    """This docstring appears in /docs."""
    return {'institute': 'Kadoos', 'city': 'Rasht', 'sessions': 16}


if __name__ == '__main__':
    uvicorn.run('app:app', reload=True)

اولین سرور: نمونه S02-fastapi-first-steps/01_first_app/app.py

cd S02-fastapi-first-steps/01_first_app
python app.py
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

حالا این سه نشانی را در مرورگر باز کنید:

• http://127.0.0.1:8000/ : پاسخ JSON برنامه.
• http://127.0.0.1:8000/docs : رابط Swagger. روی هر endpoint بزنید، Try it out و بعد Execute را انتخاب کنید.
• http://127.0.0.1:8000/redoc : همان مستند، برای خواندن.

۷. نقشه راه دوره

۸. خلاصه فصل