Первое приложение в Django: startapp с нуля за 15 минут

К концу этого материала у вас будет рабочее приложение внутри Django-проекта: команда startapp создаст структуру папок, вы подключите приложение в настройках, опишете первую модель, прогоните миграции и увидите её в админке. На всё уйдёт 10–15 минут, если проект уже создан. Разбираем на Django 5.x — на версиях 4.2 и 3.2 команды те же, разница только в мелочах, о которых скажу отдельно.

Что нужно иметь до начала

Приложение (app) не создаётся в вакууме — оно живёт внутри проекта. Проверьте, что у вас есть:

• Python 3.10 или новее (Django 5.x не запустится на 3.9 и ниже).
• Установленный Django. Проверить: python -m django --version — должна вывестись строка вида 5.1.4.
• Уже созданный проект — папка с файлом manage.py. Если проекта ещё нет, создайте: django-admin startproject myproject . (точка в конце важна — она не плодит лишнюю вложенную папку).
• Активированное виртуальное окружение, в котором установлен Django. Если в терминале в начале строки нет имени окружения в скобках — сначала активируйте его.

Дальше все команды выполняются из папки, где лежит manage.py.

Проект и приложение — не одно и то же

Новички часто путают эти два понятия. Проект — это вся конфигурация сайта: настройки, список подключённых приложений, корневой файл маршрутов. Приложение — это модуль с конкретной функцией: блог, каталог, корзина. Один проект содержит много приложений, и одно приложение теоретически можно переносить между проектами.

Шаг 1. Создаём приложение

Из папки с manage.py выполните:

python manage.py startapp blog

Как понять, что получилось: рядом с папкой проекта появится папка blog со следующим содержимым:

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

Обратите внимание: файла urls.py здесь нет — Django его не создаёт, вы добавите его сами позже, если приложению понадобятся свои маршруты. Для этого разбора он не нужен.

Шаг 2. Подключаем приложение к проекту

Django не узнает о приложении, пока вы не пропишете его в настройках. Откройте myproject/settings.py и найдите список INSTALLED_APPS. Добавьте туда своё приложение:

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "blog",  # ваше приложение
]

Можно указать полный путь к классу конфигурации: "blog.apps.BlogConfig". Оба варианта рабочие; короткий "blog" Django сам развернёт до нужного класса. Класс BlogConfig лежит в файле apps.py, который создался автоматически.

Как понять, что получилось: выполните python manage.py check. Должна вывестись строка System check identified no issues (0 silenced). Если вместо этого вылезла ошибка — приложение подключено неправильно, разбор ниже.

Шаг 3. Описываем первую модель

Модель — это таблица в базе данных, описанная классом Python. Откройте blog/models.py и добавьте:

from django.db import models


class Post(models.Model):
    title = models.CharField(max_length=200)  # заголовок записи
    body = models.TextField()                  # текст записи
    created_at = models.DateTimeField(auto_now_add=True)  # дата создания

    def __str__(self):
        return self.title

Метод __str__ нужен, чтобы в админке запись отображалась заголовком, а не безликим Post object (1).

Шаг 4. Создаём и применяем миграции

Модель описана, но таблицы в базе ещё нет. Миграции^* — это способ Django превратить изменения в моделях в изменения структуры БД. Выполните две команды по очереди:

python manage.py makemigrations blog
python manage.py migrate

Как понять, что получилось: после первой команды в терминале появится строка вроде Migrations for 'blog': blog/migrations/0001_initial.py - Create model Post. После второй — список применённых миграций, среди которых будет blog.0001_initial... OK.

По умолчанию проект использует SQLite — отдельный файл db.sqlite3, который создастся автоматически. Ставить и настраивать базу вручную для старта не нужно.

^* Миграция — файл на Python, в котором Django хранит шаги изменения схемы базы: создать таблицу, добавить поле, переименовать. Каждое изменение модели рождает новую миграцию.

Шаг 5. Показываем модель в админке

Чтобы редактировать записи через веб-интерфейс, зарегистрируйте модель в админке. Откройте blog/admin.py:

from django.contrib import admin
from .models import Post

admin.site.register(Post)

Теперь создайте суперпользователя, если ещё не создавали:

python manage.py createsuperuser

Команда спросит логин, email (можно оставить пустым) и пароль. Запустите сервер:

python manage.py runserver

Как понять, что получилось: откройте в браузере http://127.0.0.1:8000/admin/, войдите под созданным пользователем. В списке разделов появится блок BLOG с моделью Posts. Нажмите «Add», создайте запись — она сохранится в базе.

Приложение считается рабочим не тогда, когда создалась папка, а тогда, когда его модель видна в админке и запись реально пишется в базу. Всё, что между этим, — просто файлы на диске.

Если не получилось

Пять ошибок, которые встречаются чаще всего у новичков.

• No module named 'blog' при check или migrate — вы запускаете команду не из папки с manage.py, либо опечатались в имени приложения в INSTALLED_APPS. Проверьте, что имя в списке совпадает с именем папки.
• Command 'startapp' not found / Unknown command: 'startapp' — вы вызываете django-admin startapp без указания проекта. Для существующего проекта используйте python manage.py startapp, а не django-admin.
• Миграции не создаются, пишет No changes detected — приложение не подключено в INSTALLED_APPS, либо вы забыли сохранить models.py. Сохраните файл и повторите makemigrations.
• В админке нет вашего приложения — забыли admin.site.register(Post) в admin.py или не перезапустили сервер после изменения. Django подхватывает не все изменения на лету — перезапустите runserver.
• That port is already in use при runserver — порт 8000 занят другим процессом. Запустите на другом: python manage.py runserver 8001.

Разница между версиями

Команды startapp, makemigrations, migrate одинаковы начиная с Django 1.7 и по 5.x. Заметная разница касается только настроек по умолчанию: в новых проектах поле первичного ключа по умолчанию — BigAutoField (параметр DEFAULT_AUTO_FIELD в settings.py). На старых проектах, мигрировавших с версий до 3.2, при первом makemigrations Django может предупредить об этом — предупреждение безопасно проигнорировать на старте.

Что делать дальше

Приложение создано и работает. Логичные следующие шаги:

• Добавить приложению собственный файл urls.py и подключить его в корневой urls.py проекта через include() — так вы получите первую страницу с реальным адресом.
• Написать первое представление (view) в views.py и шаблон к нему.
• Настроить отображение полей в админке через класс ModelAdmin вместо простого register — управление колонками и фильтрами отдельная тема, здесь мы её не разворачивали.

За точным описанием каждой команды держите под рукой официальную документацию — она версионируется, и это надёжнее любых пересказов.