راهنمای شروع کار با جنگو

ورژن 2.2

ترجمه‌ای آزاد همراه با کمی توضیحات بیشتر از سایت رسمی پروژه جنگو

نوشتن اولین پروژه جنگو: بخش اول

بیاید با مثال‌ها جلو بریم.

در این آموزش ما قدم به قدم سعی می‌کنیم که یک وب‌اپلیکیشن نظرسنجی ایجاد کنیم.

این پروژه شامل دو بخش می‌شه:

  • یک سایت عمومی که مردم می‌تونن نظرسنجی‌ها رو ببینن و به‌شون رای بدن.
  • یک بخش مدیریت، که به شما این امکان رو می‌ده که نظرسنجی‌ها رو اضافه، ویرایش و حذف کنید.

امیدوارم که شما قبلا جنگو رو نصب کرده باشید. اگر مطمئن نیستید که جنگو رو نصب کردید یا نه می‌تونید دستور زیر رو در خط فرمان سیستم‌عامل‌تون بزنید:

python -m django --version

اگر جنگو نصب باشه، شما ورژن نصب شده اون رو می‌بینید، اگر نه ارور “No module named django” روی صفحه ظاهر می‌شه.

این آموزش برای جنگو نسخه ۲.۲ و پایتون نسخه ۳.۵ یا بالاتر نوشته شده. اگر ورژن جنگو شما متفاوته، می‌تونید با استفاده از این آموزش آخرین نسخه جنگو رو نصب کنید.

ایجاد پروژه

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

django-admin startproject mysite

این کد برای شما پوشه mysite رو در پوشه‌ای که هستید ایجاد می‌کنه.

نکته:
از انتخاب اسم‌های رزرو شده توسط جنگو یا پایتون برای پروژه‌تون اجتناب کنید. این به این معنی هست که شما نباید اسم پروژه‌تون رو django (که یک اسم رزرو شده توسط جنگو هست) یا test (که توسط پایتون رزرو شده) بگذارید. این باعث سردرگمی جنگو برای اجرا پروژه می‌شه.

این کد کجا باید اجرا بشه؟
اگر شما قبلا از PHP خام استفاده می‌کردید (که هیچ فریم‌ورک مدرنی رو شامل نمی‌شه) ااحتمالا فکر می‌کنید که کدتون رو باید در ریشه وب‌سرور قرار بدید. (یک‌جایی مثل /var/www). در جنگو، شما نباید چنین کاری بکنید. این اصلا ایده خوبی نیست که هیچ‌کدوم از این کدها رو در پوشه root وب‌سرورتون قرار بدید. چون این ریسک رو ایجاد می‌کنه که مردم کدهای شما رو در وب ببینند و این ممکن هست که خطرات امنیتی ایجاد کنه.
کدتون رو در خارج از root وب‌سرور قرار بدید. مثلا جایی مثل /home/mycode.

بیاید ببینیم دستور startproject چی ساخته:

mysite/
    manage.py
    mysite/
        __init__.py
        settings.py
        urls.py
        wsgi.py

این فایل‌ها:

  • پوشه بیرونی mysite/ فقط یک نگه‌دارنده برای کدها و فایل‌ها پروژه‌تون هست. اسم‌ش اهمیتی برای جنگو نداره. می‌تونید تغییرش بدید.

  • فایل manage.py: یک ابزار خط فرمان هست که اجازه می‌ده به شکل‌های مختلفی با جنگو تعامل داشته باشید.

  • پوشه داخلی mysite/ درواقع یک پکیج پایتونی برای پروژه‌تون هست. اسم‌ش مهمه پس. برای استفاده از فایل‌های درون‌ش باید با استفاده از اسم‌ش، فایل‌ها رو ایمپورت کنید. (مثلا mysite.urls)

  • فایل mysite/init.py: یک فایل خالی هست که به پایتون می‌گه این پوشه یک پکیج پایتونی هست. اگر در پایتون تازه‌کار هستید، درمورد پکیج‌ها در وب جستجو کنید.

  • فایل mysite/settings.py: حاوی تمام تنظیمات و پیکربندی‌های پروژه جنگو شماست. در ادامه می‌بینیم که با این فایل چه کارهایی می‌شه انجام داد.

  • فایل mysite/urls.py: اعلام کننده آدرس‌های پروژه شماست. یک فهرست محتوا از وبسایت شما.

  • فایل mysite/wsgi.py: برای دیپلوی کردن پروژه جنگو شما استفاده می‌شه. زمانی که توسعه پروژه‌تون تموم شده و می‌خواهید پروژه رو به صورت آنلاین در وب منتشر کنید.


سرور توسعه جنگو

بیاید مطمئن بشیم که پروژه‌مون کار می‌کنه. برید به پوشه خارجی mysite/ و این دستور رو اجرا کنید:

python manage.py runserver

حالا خروجی زیر رو می‌بینید:

Performing system checks...

System check identified no issues (0 silenced).

You have unapplied migrations; your app may not work properly until they are applied.
Run 'python manage.py migrate' to apply them.

September 10, 2019 - 15:50:53
Django version 2.2, using settings 'mysite.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

نکته:
هشداری که راجع به اعمال نشدن migrationها و اپلیکیشن‌ها می‌ده رو فعلا نادیده بگیرید. ما بعدا وقتی به سراغ کار با دیتابیس می‌ریم این هشدار رو رفع می‌کنیم.

شما سرور توسعه جنگو، که یک وب‌سرور سبک هست که با پایتون نوشته شده، رو روشن کردید. این وب‌سرور همراه با جنگو هست تا وقتی که هنوز پروژه‌تون کامل نشده شما بتونید چیزها رو سریع‌تر توسعه بدید؛ بدون این‌که نیاز باشه وب‌سرورهایی مثل Apache رو کانفیگ کنید.

زمان خوبی هست که به این نکته توجه کنید: هرگز از این وب‌سرور برای محصول نهایی‌تون استفاده نکنید. این وب‌سرور فقط تا زمانی که دارید برنامه‌تون رو توسعه می‌دید مفید هست. (کار ما نوشتن فریم‌ورک برای وب هست، نه وب‌سرورها)

حالا که سرور اجرا شده، آدرس http://127.0.0.1:8000/ رو در مرورگرتون باز کنید. صفحه “Congratulations!” رو همراه با یک موشک که پرتاب می‌شه می‌بینید. این یعنی که هه‌چیز داره کار می‌کنه!

تغییر پورت:
به طور پیش‌فرض دستور runserver سرور توسعه رو روی آی‌پی داخلی و پورت ۸۰۰۰ اجرا می‌کنه.
اگر شما می‌خواهید پورت پیش‌فرض سرور رو تغییر بدید، می‌تونید از دستور زیر استفاده کنید. مثلا دستور زیر سرور رو روی پورت ۸۰۸۰ اجرا می‌کنه:
python manage.py runserver 8080
همچنین اگر می‌خواهید که آی‌پی پیش‌فرض سرور رو تغییر بدید، می‌تونید اون رو همراه با پورت در دستور اجرا کنید. برای مثال برای اجرا روی همه آی‌پی‌ها موجود - برای زمانی که می‌خواهید کارتون رو روی کامپیوترهای دیگه‌ی داخل شبکه هم نشون بدید - می‌تونید از این دستور استفاده کنید.python manage.py runserver 0:8000 که 0 کوتاه شده 0.0.0.0 هست.

تازه‌سازی خودکار runserver:
سرور توسعه به صورت خودکار برای هر درخواست اگر نیاز باشه، کدها رو مجددا بارگذاری می‌کنه. به این معنی که برای هر تغییر نیاز به ری‌استارت سرور ندارید. اما برای بعضی از تغییرات مثل اضافه کردن فایل، نمی‌شه از ری‌استارت چشم‌پوشی کرد و باید سرور رو ری‌استارت کنید در این‌طور مواقع.



ساخت اپ نظرسنجی

حالا همه‌چیز - «یک پروژه» - آماده‌ست. بیاید کار رو شروع کنیم.

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

تفاوت پروژه‌ها و اپ‌ها
چه فرقی بین یک پرو‌ژه با یک اپ (برنامه) وجود داره؟ یک اپ یک وب‌اپلیکیشن هست که یک‌کاری انجام می‌ده - مثلا یک‌سیستم وبلاگ یا یک دیتابیس از اطلاعات عمومی یا حتی یک اپ نظرسنجی. درحالی که یک پروژه مجموعه از تنظیمات و اپ‌های مختلف برای یک وب‌سایت خاص هست. یک پروژه می‌تونه چندین اپ داشته باشه. یک اپ می‌تونه در چندین پروژه باشه.

در این آموزش ما اپ نظرسنجی‌مون رو درست کنار manage.py می‌سازیم. به این خاطر که به عنوان یک ماژول اصلی اضافه بشه و نه یک زیر ماژول از mysite. برای ساخت اپ‌تون مطمئن بشید که توی همون پوشه‌ای هستید که manage.py هم هست و این دستور رو تایپ کنید.

python manage.py startapp polls

این یک پوشه به اسم polls خواهد ساخت که شبیه به چیزی مثل این هست:

polls/
    __init__.py
    admin.py
    apps.py
    migrations/
        __init__.py
    models.py
    tests.py
    views.py

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


اولین ویو رو بنویسید

بیاید اولین ویو رو بنویسیم. فایل polls/views.py رو باز کنید و این کد رو درش قرار بدید.

polls/views.py:

from django.http import HttpResponse


def index(request):
    return HttpResponse("Hello, world. You're at the polls index.")

این ساده‌ترین ویو ممکن در جنگو هست! برای فراخوانی یک ویو ما نیاز داریم که به یک آدرس (URL) متصل‌ش کنیم و برای این کار ما به یک URLConf نیاز داریم.

برای ساخت یک URLConf در پوشه‌ی polls یک فایل به نام urls.py بسازید. پوشه‌ی اپ‌تون باید این‌طوری باشه:

polls/
    __init__.py
    admin.py
    apps.py
    migrations/
        __init__.py
    models.py
    tests.py
    urls.py
    views.py

در polls/urls.py این کدها رو قرار بدید:

polls/urls.py:

from django.urls import path

from . import views

urlpatterns = [
    path('', views.index, name='index'),
]

قدم بعدی این هست که در mysite/urls.py بگیم URLconf موجود در polls.urls هم بررسی بشه. برای این‌کار django.urls.include رو ایمپورت می‌کنیم و در لیست urlpatterns هم تابع include() رو اضافه می‌کنیم. یعنی:

mysite/urls.py:

from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path('polls/', include('polls.urls')),
    path('admin/', admin.site.urls),
]

تابع ()include این امکان رو می‌ده که از الگوهای آدرس دیگه‌ای هم استفاده کنید. روش کار به این صورت هست که جنگو وقتی داره آدرس‌ها رو بررسی می‌کنه، بخشی پایه الگو رو نگه می‌داره و بقیه آدرس رو برای URLconfs موجود در تابع ()include برای پردازش‌های بعدی ارسال می‌کنه. به طور مثال فرض کنید کاربر آدرس mysite.com/polls/12 رو درخواست کنه. جنگو به الگوی '/polls’ می‌رسه، اون رو نگه می‌داره و 12 رو برای URLconfs موجود در polls/urls.py ارسال می‌کنه تا ویو مربوطه نمایش داده بشه.

ایده پشت ()include این هست که آدرس‌های ساده و قابل جداسازی ایجاد کنه. زمانی که نظرسنجی‌ها الگوی آدرس خودشون (polls/urls.py) رو دارن، می‌تونن در آدرس‌ “/polls/” یا آدرس “/fun_polls/” یا “/content/polls/” یا هر آدرس پایه دیگه‌ای قرار داده بشن و اپ شما همچنان کار بکنه.

چه زمانی از ()include استفاده می‌کنیم؟
هر زمان می‌خواستید از الگوهای آدرس دیگه‌ای هم استفاده کنید باید از ()include استفاده کنید. تنها استثنا admin.site.urls هست.

حالا شما یک ویو index رو به یک الگو آدرس سیم‌کشی کردید. بیاید ببینیم کار می‌کنه یا نه. این دستور رو بزنید:

python manage.py runserver

به http://localhost:8000/polls/ در مرورگرتون برید. شما باید نوشته “Hello, world. You’re at the polls index.” که در تابع ویو index تعریف کرده بودید رو ببینید.

صفحه پیدا نشد؟
اگر اروری گرفتید، حواس‌تون باشه که شما باید به آدرس http://localhost:8000/polls برید و نه http://localhost:8000.

تابع**()path** چهار آرگومان به عنوان ورودی می‌گیره. که دوتا از اون‌ها ضروری هستند: **مسیر** و **ویو** و دوتا از اون‌ها به صورت اختیاری هستند: **kwargs** و **نام**. الان زمان مناسبی هست تا یک نگاهی به این آرگومان‌ها و کارشون داشته باشیم.

تابع ()path آرگومان: route یا مسیر

آرگومان route یک رشته شامل یک الگو آدرس هست. زمانی که یک درخواست پردازش می‌شع، جنگو از اولین الگو موجود در urlpatterns شروع می‌کنه و در لیست به پایین حرکت می‌کنه، آدرس درخواست شده رو با تک‌تک الگوها مقایسه می‌کنه تا زمانی که الگو مورد نظر رو پیدا کنه.

الگوها، پارامترهای GET و POST رو جستجو نمی‌کنن، یا نام دامنه رو. برای مثال در یک درخواست برای https://www.example.com/myapp/ در جنگو URLconf به /myapp نگاه می‌کنه. همچنین در یک درخواست برای https://www.example.com/myapp/?page=3 هم، URLconf باز به /myapp نگاه می‌کنه.


تابع ()path آرگومان: view

زمانی که جنگو الگو آدرس مورد نظر رو پیدا می‌کنه، تابع ویو مخصوص‌ش رو همراه با یک شئ ** HttpRequest** به عنوان آرگومان اول و هر مقدار استخراج شده به عنوان کی‌وردهای آرگومانی فراخوانی می‌کنه. ما خیلی زود یک مثال از این بخش نشون می‌دیم تا درکش ساده‌تر بشه.


تابع ()path آرگومان: kwargs

کی‌وردهای ارگومانی می‌تونن در یک دیشکنری به تابع ویو مورد نظر ارسال بشن. ما در این آموزش، این امکان جنگو رو پوشش نمی‌دیم.


تابع ()path آرگومان: name یا نام

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

زمانی که شما با درخواست‌ها و پاسخ‌های پایه آشنا شدید، بخش دوم این آموزش رو برای شروع کار با پایگاه‌داده مطالعه کنید!