Это перевод недавней статьи Recommended Django Project Layout от Франка Вильса (Frank Wiles) от 21 ноября 2014г.
Какая оптимальная структура для ваших Django приложений, настроек и других ассоциированных директорий?
Когда вышла Django 1.4 она включала обновленую структуру проекта, которая прошла долгий путь, чтобы стать основной, но здесь, собраны некоторые улучшения, чтобы сделать структуру лучше.
Подобный вопрос нам задают постоянно, поэтому я хочу потратить немного времени и рассказать все наше отношение к этому, чтобы всех клиентов можно было отправлять к этому документу. Эта заметка написана для Django 1.7.1, но может быть легко применена для всех Django версий выше 1.4.
Почему данная структура лучше
Рекомендуемая нами структура проекта имеет несколько преимуществ, таких как:
- Позволяет вам держать, пересобирать и переисопльзовать индивидальные Django приложения для использования в других проектах. Ведь не всегда создаваемое приложение делается реиспользуемым, но в будущем, может вырасти в такое. Построение проекта описываемым способом, позволяет писать реиспользуемые приложения сразу же, а не только, когда потребуется.
- Поощряет разработку реиспользуемых приложений
- Индивидуальных настройки для каждого окружения. Никаких больше “if DEBUG==True” в едином монолитном файле настроек. Это позволяет легко видеть, какие настройки общие и что переопределяется на каждом окружении.
- Индивидульный список pip зависимостей для каждого окружения.
- Шаблоны проекта и статические файлы, если требуется, могут переопределять значения по умолчанию уровня приложений.
- Небольшие более детальные тестовые файлы, которые легче для чтения и понимания.
Предположим, у вас есть 2 приложения blog и users и 2 окружения dev и prod, значит, ваш проект должен иметь следующий вид:
myproject/
manage.py
myproject/
__init__.py
urls.py
wsgi.py
settings/
__init__.py
base.py
dev.py
prod.py
blog/
__init__.py
models.py
managers.py
views.py
urls.py
templates/
blog/
base.html
list.html
detail.html
static/
…
tests/
__init__.py
test_models.py
test_managers.py
test_views.py
users/
__init__.py
models.py
views.py
urls.py
templates/
users/
base.html
list.html
detail.html
static/
…
tests/
__init__.py
test_models.py
test_views.py
static/
css/
…
js/
…
templates/
base.html
index.html
requirements/
base.txt
dev.txt
test.txt
prod.txt
Продолжение этой статьи расскажет, как привести свой проект к такой структуре и почему она лучше.
Текущая структура по умолчанию
Мы начнем с создания нового проекта с именем foo, да, я знаю, что это очень креативное название. Мы предполагаем здесь, что дальше проект будет расположен на домене foo.com, но почему название проекта должно точно повторять домен, ведь проект всеравно будет жить и без всяких подобных требований.
Если вы запустите свой проект с помощью команды django-admin.py startproject foo, вы получите следующую структуру:
foo/
manage.py
foo/
__init__.py
settings.py
urls.py
wsgi.py
Эта схема очень хороша для старта. У нас есть корневая директория foo, которая содержит наш manage.py и директорию проекта foo/foo. Эту директорию можно добавить в свою систему контроля версия, например в git.
Вы можете подумать, что директория foo/foo начало проекта, где все кроме этого это Django приложения или вспомогательные файлы относящиеся к проекту.
Исправляем настройки
Наша первая миссия, это исправить ваш плохой файл настроек. Мы показали данную архитектуру нашим клиентам и были впечатлены, как мало людей знают, что такое можно реализовать. Я виню в этом тот факт, что каждый знает, что файл настроек это просто Python код, но они не думают о нем, как о Python коде.
И так, давайте исправим наши настройки. Для нашего проекта foo реализуем схему с 4 окружениями: dev, stage, jenkins, и production. Давайте дадим каждому окружения свой собственный файл. Процесс для этого следующий:
- В foo/foo создадим директорию settings и пустой файл __init__.py внутри нее.
- Перенесем foo/foo/settings.py в foo/foo/settings/base.py
- Создадим индивидуальные файлы dev.py, stage.py, jenkins.py, и production.py в foo/foo/settings/. Каждый из этих файлов должен содержать следующее
from base import *
Так, почему это важно? Для локальной разработки вам требуется DEBUG=True, но вы также, можете случайно выкатить это и в продакшен, поэтому просто откройте foo/foo/settings/production.py и после первой строки импорта вставьте DEBUG=False. Теперь, ваш продакшен сайт защищен от такой случайности.
Что еще вы можете настроить? Достаточно очевидно, что для каждого окружения вы захотите иметь различные базы данных, например на разных хостах. Для этого, просто внесите эти настройки в соответствубщие файлы настроек.
Использование этих настроек
Использование этих настроект очень легкое и не зависит от того, какой метод вы предпочитаете. Для использования настроек определенного окружения, вы должны всего лишь:
export DJANGO_SETTINGS_MODULE=“foo.settings.jenkins”
И бум, вы теперь используете jenkins настройки.
Или вы можете предпочесть передачу настроек через коммандную строку:
./manage.py migrate —settings=foo.settings.production
Или используя gunicorn:
gunicorn -w 4 -b 127.0.0.1:8001 —settings=foo.settings.dev
Что еще должно быть настроено?
Другая часто используемая уловка с Django настройками, это изменить тип некоторых настроек с tuple на list. Для примера, INSTALLED_APPS изменить с:
INSTALLED_APPS = (
…
)
на:
INSTALLED_APPS = [
…
]
В foo/settings/base.py мы теперь можем проще добавлять и удалять приложения основываясь на конкретном файле настроек для текущего окружения. Для примера, возможно вам требуется модуль django-debug-toolbar установленным только в dev окружении.
Этот трюк также часто используется с настройками TEMPLATE_DIRS и MIDDLEWARE_CLASSES.
Еще один часто используемый трюк, это разбить ваши приложения на 2 списка, первый это глобальные зависимости, второй - специфичные для данного проекта. Как, например, здесь:
PREREQ_APPS = [
‘django.contrib.auth’,
‘django.contrib.contenttypes’,
…
‘debug_toolbar’,
‘imagekit’,
‘haystack’,
]
PROJECT_APPS = [
‘homepage’,
‘users’,
‘blog’,
]
INSTALLED_APPS = PREREQ_APPS + PROJECT_APPS
Почему это часто используется? Во первых, это помогает лучше различать Django core компоненты, сторонние приложения и внутренние, специфичные для данного проекта. Тем не менее, PROJECT_APPS часто управляет списком специфичных пакетов, для вещей таких как: тестирование и покрытие кода тестами. Вы имеет список с вашими приложениями, поэтому можете легко и автоматизированно убедиться, что все тесты были запущены только для них, а не для каких-то посторонних модулей.
Исправляем зависимости
Большинство проектов содержат лишь один файл requirements.txt, который ставит зависимости примерно так:
pip install -r requirements.txt
Этого достаточно для маленьких проектов, но малоизвестная возможность requirements файлов это использование ключа -f для включения других файлов:
-r base.txt
pytest==2.5.2
coverage==3.7.1
Я признаю, что это не огромная выгода, но это позволяет разделить зависимости на каждое окружение. Но для успокоения совести скажу, что это позволяет увеличить скорость установки пакетов, ведь вам не требуется стаивть на продакшен инсталяции пакеты, которые не будут использоваться.
Тестовые файлы
Почему мы разделяем тесты так сильно? Главная причина, если вы пишете достаточное количество тестов в одном файле tests.py для каждого приложения, то в конце концов он станет огромным и не поддерживаемым. Это плохо для читабельности, но также это простой факт, что вы тратите много времени на пролистывание текста.
В итоге, вы уменьшите количество мердж конфликтов при работе в команде, что является положительной чертой. Маленькие файлы - ваши друзья.
Ссылки (URLs)
Для маленьких проектов заманчиво определять все ссылки в одном файле foo/urls.py для сохранения их в одном месте. Как бы то ни было, если ваша цель это ясность и реиспользование, вы должны определять ссылки в каждом приложении и загружать их в корневом файле. Вместо:
urlpatterns = patterns(‘’,
url(r’^$’, HomePageView.as_view(), name=‘home’),
url(r’^blog/$’, BlogList.as_view(), name=‘blog_list’),
url(r’^blog/(?P<pk>\d+)/$’, BlogDetail.as_view(), name=‘blog_detail’),
…
url(r’^user/list/$’, UserList.as_view(), name=‘user_list’),
url(r’^user/(?P<username>\w+)/$’, UserDetail.as_view(), name=‘user_detail’),
)
вы должны использовать:
urlpatterns = patterns(‘’,
url(r’^$’, HomePageView.as_view(), name=‘home’),
url(r’^blog/‘, include(‘blog.urls’)),
url(r’^user/‘, include(‘user.urls’)),
)
Шаблоны и статические файлы
Использование templates/ и static/ директорий на каждое приложение дает способность к реиспользованию этого приложения в другом проекте как есть, без изменений.
В этом случае, приложение предоставляет шаблоны по умолчанию, а также различные вспомогательные файлы, такие как специальные Javascript файлы и поставляется все это в одном пакете.
Также, это дает нам возможность переопределить шаблоны на каждый проект базируясь на директории foo/templates/. При добавлении шаблона templates/blog/detail.html мы перезаписываем или скрываем шаблон по умолчанию blog/templates/blog/detail.html.
Переиспользование Django приложений
Допустим, вы используете предлагаемую структуру проекта некоторое время, однажды, вы поймете, что ваш новый проект нуждается в блоге и один из ваших проектов прекрасно к этому подходит. Вы скопируете файлы в … НЕ ПРАВИЛЬНО! Теперь вы имеете две копии приложения. Исправления ошибок или новые функции в одном, будут вручную переноситься между проектами если предположить, что вы всегда помните про это.
Вместо этого, сделайте новый репозиторий для вашего блога и вставьте в него директорию foo/blog/. И настройте, чтобы ваш существующий проект foo и новый проект, для установки блога через pip.
Они смогут использовать различные версии приложения, если это важно, или использовать всегда последнюю версию для получения всех исправлений и новых функций, как и разработчик. Вы все еще можете переопределять шаблоны и статические файлы в каждом проекте отдельно.
Дополнительные ресурсы
Наши друзья Дэнни и Аудрей из CartWheel Web напомнили нам про Cookie Cutter и специальный cookiecutter-django от Дэнни, мощная утилита для создания начального проекта, быстро и повторяемо.
Кроме того, если вы ищете все про Django уловки и рекомендации, вы не можете пройти мимо книги Two Scoops of Django: Best Practices For Django 1.6 которую мы рекомендуем всем нашим клиентам.
Обратная связь
Мы надеемся, вы нашли данное улучшение архитектуры проекта полезным. Если вы нашли какой-то баг или имеет предложение иил просто хотите пообщаться, пишите нам. Спасибо за прочтение.