Требование: это руководство предполагает, что вы ознакомились с вводными руководствами и запустили приложение Phoenix и убедились, что оно работает.

При использовании mix phx.new для создания нового приложения Phoenix формируется структура каталогов верхнего уровня, которая выглядит так:

├── _build
├── assets
├── config
├── deps
├── lib
│   ├── hello
│   ├── hello.ex
│   ├── hello_web
│   └── hello_web.ex
├── priv
└── test

Рассмотрим эти каталоги по очереди:

• _build — каталог, в котором хранятся все артефакты компиляции, созданные инструментом командной строки mix (входящим в состав Elixir). Как мы уже видели в разделе «Запуск и работа», mix — основной интерфейс вашего приложения. С помощью Mix мы компилируем код, создаём базы данных, запускаем сервер и выполняем другие задачи. Этот каталог не следует добавлять в систему контроля версий; его можно удалить в любой момент. После удаления Mix будет заново собирать приложение с нуля.

• assets — каталог с исходным кодом ресурсов фронтенда, обычно JavaScript и CSS. Эти исходные файлы автоматически объединяются инструментом esbuild. Статические файлы, такие как изображения и шрифты, помещаются в priv/static.

• config — каталог с конфигурацией проекта. Файл config/config.exs — точка входа для конфигурации. В конце файла config/config.exs импортируется конфигурация для конкретного окружения, которую можно найти в config/dev.exs, config/test.exs и config/prod.exs. Наконец, выполняется config/runtime.exs — это лучшее место для чтения секретов и других динамических параметров конфигурации.

• deps — каталог со всеми зависимостями Mix. Все зависимости перечислены в файле mix.exs в определении функции defp deps do. Этот каталог не следует добавлять в систему контроля версий; его можно удалить в любой момент. После удаления Mix загрузит все зависимости заново.

• lib — каталог с исходным кодом приложения. Он разделён на два подкаталога: lib/hello и lib/hello_web. Каталог lib/hello отвечает за всю бизнес-логику и предметную область. Обычно он напрямую взаимодействует с базой данных — это «Model» в архитектуре Model-View-Controller (MVC). lib/hello_web отвечает за представление вашей предметной области внешнему миру, в данном случае — через веб-приложение. В нём находятся компоненты View и Controller из MVC. Содержимое этих каталогов мы подробнее рассмотрим в следующих разделах.

• priv — каталог со всеми ресурсами, необходимыми в рабочей среде, но не входящими непосредственно в исходный код. Обычно здесь хранят скрипты для работы с базой данных, файлы переводов, изображения и другие ресурсы. Сгенерированные файлы ресурсов, созданные из файлов каталога assets, по умолчанию помещаются в priv/static/assets.

• test — каталог со всеми тестами приложения. Его структура часто повторяет структуру каталога lib.

Каталог lib/hello

В каталоге lib/hello находится вся предметная область приложения. Поскольку в нашем проекте пока нет бизнес-логики, каталог почти пуст. В нём всего три файла:

lib/hello
├── application.ex
├── mailer.ex
└── repo.ex

Файл lib/hello/application.ex определяет приложение Elixir с именем Hello.Application. В конечном счёте приложения Phoenix — это просто приложения Elixir. Модуль Hello.Application определяет, какие службы входят в состав нашего приложения:

children = [
  HelloWeb.Telemetry,
  Hello.Repo,
  {Phoenix.PubSub, name: Hello.PubSub},
  HelloWeb.Endpoint
]

Если вы впервые работаете с Phoenix, пока не нужно вникать в подробности. Достаточно знать, что приложение запускает репозиторий базы данных, систему PubSub для обмена сообщениями между процессами и узлами, а также endpoint приложения, который обрабатывает HTTP-запросы. Эти службы запускаются в том порядке, в котором они определены, а при завершении работы приложения останавливаются в обратном порядке.

Подробнее о приложениях можно узнать в официальной документации Elixir по модулю Application.

В файле lib/hello/mailer.ex находится модуль Hello.Mailer, который определяет основной интерфейс для отправки электронных писем:

defmodule Hello.Mailer do
  use Swoosh.Mailer, otp_app: :hello
end

В том же каталоге lib/hello находится файл lib/hello/repo.ex. В нём определён модуль Hello.Repo — наш основной интерфейс для работы с базой данных. Если вы используете Postgres (базу данных по умолчанию), вы увидите примерно следующее:

defmodule Hello.Repo do
  use Ecto.Repo,
    otp_app: :hello,
    adapter: Ecto.Adapters.Postgres
end

На этом пока всё. По мере работы над проектом мы будем добавлять в этот каталог файлы и модули.

Каталог lib/hello_web

В каталоге lib/hello_web находятся веб-компоненты приложения. В развёрнутом виде он выглядит так:

lib/hello_web
├── controllers
│   ├── page_controller.ex
│   ├── page_html.ex
│   ├── error_html.ex
│   ├── error_json.ex
│   └── page_html
│       └── home.html.heex
├── components
│   ├── core_components.ex
│   ├── layouts.ex
│   └── layouts
│       └── root.html.heex
├── endpoint.ex
├── gettext.ex
├── router.ex
└── telemetry.ex

Все файлы, которые сейчас находятся в каталогах controllers и components, нужны для создания страницы «Добро пожаловать в Phoenix!», которую мы видели в руководстве «Запуск и работа».

По каталогам controller и components видно, что Phoenix из коробки предоставляет средства для работы с макетами, HTML и страницами ошибок.

Помимо упомянутых каталогов, в корне lib/hello_web находятся четыре файла. lib/hello_web/endpoint.ex — точка входа для HTTP-запросов. Когда браузер обращается к адресу http://localhost:4000, endpoint начинает обрабатывать данные, что в итоге приводит к маршрутизатору, определённому в lib/hello_web/router.ex. Маршрутизатор задаёт правила перенаправления запросов к «контроллерам», которые вызывают модуль представления для формирования HTML-страниц и отправки их клиентам. Подробно эти уровни рассматриваются в других руководствах, начиная со следующего — «Жизненный цикл запроса».

Благодаря Telemetry Phoenix может собирать метрики и отправлять события мониторинга вашего приложения. В файле lib/hello_web/telemetry.ex определён супервизор, который отвечает за управление процессами Telemetry. Подробнее об этом можно узнать в руководстве по Telemetry.

Наконец, файл lib/hello_web/gettext.ex обеспечивает интернационализацию с помощью Gettext. Если интернационализация вам не нужна, этот файл и его содержимое можно смело пропустить.

Каталог assets

В каталоге assets находятся исходные файлы ресурсов фронтенда, например JavaScript и CSS. Начиная с Phoenix v1.6 для компиляции ресурсов используется esbuild, интеграция с которым обеспечивается пакетом Elixir esbuild. Интеграция с esbuild уже включена в приложение. Соответствующие параметры конфигурации находятся в файле config/config.exs.

Другие статические ресурсы помещаются в каталог priv/static, где priv/static/assets предназначен для сгенерированных ресурсов. Всё содержимое priv/static отдаётся через plug Plug.Static, настроенный в lib/hello_web/endpoint.ex. В режиме разработки (MIX_ENV=dev) Phoenix отслеживает изменения в каталоге assets и обновляет фронтенд-приложение в браузере по мере вашей работы.

Обратите внимание: при создании приложения Phoenix с помощью mix phx.new можно указать параметры, которые повлияют на наличие и структуру каталога assets. Приложения Phoenix могут использовать собственные инструменты для фронтенда или вовсе обходиться без него (например, если вы пишете API). Дополнительную информацию можно получить, запустив mix help phx.new.

Если стандартная интеграция с esbuild вам не подходит, например, если вы хотите использовать другой инструмент сборки, можно перейти на сборку ресурсов с собственной конфигурацией.

Для CSS Phoenix включает фреймворк Tailwind CSS, предоставляющий базовую конфигурацию для проектов. Вы можете перейти на любой CSS-фреймворк по своему выбору. Дополнительную информацию можно найти в руководстве по управлению ресурсами.