Когда новичок приходит в Elixir и Phoenix, ему почти всегда первым делом показывают Ecto. Создаём схемы, пишем changeset’ы, выносим запросы в контексты. Подход гибкий, но с ростом проекта начинает проявляться серьёзная проблема 😟

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

Ash Framework создан именно для решения этой боли 💪

Важное уточнение: Ash — это не замена Phoenix и не новый веб-фреймворк. Это мощный декларативный слой, который организует бизнес-логику и данные поверх существующей экосистемы.

ㅤ

ㅤ

📖 Предисловие

Важно понимать, что цель этой статьи вовсе не состоит в том, чтобы уговорить вас использовать Ash повсеместно и постоянно!

Сам я люблю Ash именно из-за того, что он даёт возможность собрать всю необходимую логику в едином пространстве, где ей самое место. Этот инструмент значительно упрощает работу, уменьшая количество шаблонного кода и освобождая от утомительной реализации стандартных CRUD.

Если готовы ознакомиться с таким инструментом, но собираетесь прибегать к нему лишь тогда, когда это действительно оправдано — смело читайте дальше. Ash — это не универсальное лекарство от всех проблем, а всего лишь удобный набор полезных инструментов.

ㅤ

ㅤ

🚀 Что такое Ash?

Ash — это фреймворк для быстрой и эффективной разработки приложений на Elixir. Его цель заключается в облегчении запуска новых проектов и обеспечении удобства поддержки существующих решений, гарантируя отличную производительность и стабильность даже после длительного периода активной разработки.

Ключевая идея Ash звучит так:

Точно сформулируй структуру своей бизнес-логики, а всю остальную работу (миграция базы данных, создание API-интерфейсов, валидация данных, управление доступом, оформление форм) возьмет на себя Ash

Фреймворк прекрасно взаимодействует с такими популярными инструментами, как Phoenix, PostgreSQL, GraphQL и LiveView.

ㅤ

ㅤ

🔑 Ключевые абстракции Ash

Всё в Ash строится вокруг трёх основных понятий:

• Resource (Ресурс) — описание одной бизнес-сущности
• Action (Действие) — операция, которую можно выполнить над ресурсом
• Domain (Домен) — логическая группа ресурсов одной бизнес-области

Давайте разберём каждую концепцию подробно!

ㅤ

ㅤ

🧩 Что такое Ресурс?

Resource — это один модуль, в котором полностью описана одна бизнес-сущность вашего приложения (Пользователь, Урок, Заказ, Пост, Платёж и т.д.).

В нём в одном месте собрано всё, что касается этой сущности:

• Структура данных (поля)
• Связи с другими сущностями
• Операции, которые можно выполнять (CRUD + кастомные)
• Правила валидации
• Авторизация (кто и что может делать)
• Вычисляемые поля
• Индексы и ограничения
• Настройки хранения в базе

Resource в Ash объединяет в одном модуле то, что в классическом Elixir/Phoenix обычно разносится по нескольким частям: Ecto Schema, Changesets, Context-функции, а также логика авторизации и вычисляемые поля.

ㅤ

Resource — сердце Ash

Ash построен вокруг идеи Resource-Oriented Design. Ты описываешь что представляет собой сущность и что с ней можно делать — а Ash сам генерирует остальное: SQL-запросы, API, формы, миграции, валидацию и т.д.

ㅤ

Полный пример современного Resource

defmodule CourseHub.Courses.Lesson do
 use Ash.Resource,
 otp_app: :course_hub, # Привязка к приложению
 domain: CourseHub.Courses, # В каком домене живёт
 data_layer: AshPostgres.DataLayer # Где храним данные

 # ==================== ХРАНЕНИЕ ====================
 postgres do
 table "lessons"
 repo CourseHub.Repo
 end

 # ==================== ПОЛЯ (Attributes) ====================
 attributes do
 uuid_primary_key :id

 attribute :title, :string do
 public? true # видно в API и формах
 allow_nil? false
 constraints min_length: 3, max_length: 200
 end

 attribute :description, :string, public?: true
 attribute :content, :string, public?: true

 attribute :status, :atom do
 public? true
 default? :draft
 constraints one_of: [:draft, :published, :archived]
 end

 create_timestamp :inserted_at
 update_timestamp :updated_at
 end

 # ==================== СВЯЗИ (Relationships) ====================
 relationships do
 belongs_to :author, CourseHub.Accounts.User do
 public? true
 allow_nil? false
 end

 has_many :comments, CourseHub.Courses.Comment do
 public? true
 end

 many_to_many :tags, CourseHub.Courses.Tag do
 public? true
 through CourseHub.Courses.LessonTag
 source_attribute_on_join_resource :lesson_id
 destination_attribute_on_join_resource :tag_id
 end
 end

 # ==================== ДЕЙСТВИЯ (Actions) ====================
 actions do
 defaults [:create, :read, :update, :destroy]

 # Кастомное чтение
 read :published do
 filter expr(status == :published)
 pagination offset?: true, countable: true
 prepare build(sort: [inserted_at: :desc])
 end

 # Кастомное создание с логикой
 create :publish do
 argument :reason, :string
 change set_attribute(:status, :published)
 end

 # Полностью кастомное действие
 action :calculate_reading_time, :integer do
 argument :content, :string, allow_nil?: false
 run fn input, _context ->
 minutes = String.length(input.arguments.content) |> div(500) |> max(1)
 {:ok, minutes}
 end
 end
 end

 # ==================== ВЫЧИСЛЯЕМЫЕ ПОЛЯ ====================
 calculations do
 calculate :reading_time_minutes, :integer do
 calculation fn records, _context ->
 Enum.map(records, fn lesson ->
 (String.length(lesson.content || "") / 500) |> Float.ceil() |> trunc()
 end)
 end
 end
 end

 # ==================== ИНДЕКСЫ ====================
 identities do
 identity :unique_title_per_author, [:title, :author_id]
 end

 # ==================== АВТОРИЗАЦИЯ ====================
 policies do
 policy action_type(:read) do
 authorize_if always()
 end

 policy action(:update) do
 authorize_if expr(author_id == ^actor(:id))
 end
 end
end

ㅤ

Основные разделы Resource

ㅤ

Ключевые особенности Resource

1. Всё в одном файле — огромный плюс для понимания сущности.
2. Introspection — Ash может в runtime читать всю информацию о ресурсе (поля, действия, политики). Это используется для генерации API, форм, админок.
3. Декларативность — ты описываешь что должно быть, а не как это реализовать.
4. Расширяемость — можно добавлять свои changes, preparations, validations, notifiers.
5. Embedded Resources — можно создавать ресурсы, которые хранятся не в отдельной таблице, а как JSON/Map внутри другого ресурса.

ㅤ

Когда создавать новый Resource?

Практически всегда, когда появляется новая бизнес-сущность (таблица или даже сложный JSON-объект).

ㅤ

ㅤ

🛠️ Подробнее об Actions (Действиях)

Action (Действие) — это явно объявленная операция, которую можно выполнить над ресурсом.

Всё взаимодействие с данными в Ash идёт только через Actions. Нельзя просто взять запись и изменить её вручную — всегда вызываешь действие.

Это заменяет:

• Обычные функции в Context’ах Phoenix
• Changesets в Ecto
• Контроллеры и сервисные слои

ㅤ

Пять типов Actions

ㅤ

Полный пример всех типов Actions

defmodule CourseHub.Courses.Lesson do
 use Ash.Resource, ...

 actions do
 # 1. Стандартные CRUD (defaults)
 defaults [:create, :read, :update, :destroy]

 # 2. Кастомное Read
 read :published do
 filter expr(status == :published)
 pagination offset?: true, countable: true, default_limit: 20
 prepare build(sort: [inserted_at: :desc], load: [:author, :comment_count])
 end

 read :for_user do
 argument :user_id, :uuid, allow_nil?: false
 filter expr(author_id == ^arg(:user_id))
 end

 # 3. Кастомное Create
 create :publish do
 argument :reason, :string, allow_nil?: true

 # Изменения (changes)
 change set_attribute(:status, :published)
 change set_attribute(:published_at, &DateTime.utc_now/0)
 change {CourseHub.Changes.NotifySubscribers, topic: "new_lessons"}

 # Хуки
 after_action fn _changeset, lesson, _context ->
 # side-effect после успешного создания
 {:ok, lesson}
 end
 end

 # 4. Кастомное Update
 update :archive do
 accept [:archive_reason] # какие поля можно менять
 change set_attribute(:status, :archived)
 change set_attribute(:archived_at, &DateTime.utc_now/0)
 end

 # 5. Generic Action (полностью кастомное)
 action :calculate_reading_time, :integer do
 argument :content, :string, allow_nil?: false
 argument :words_per_minute, :integer, default?: 200

 run fn input, _context ->
 minutes = String.length(input.arguments.content) 
 |> div(input.arguments.words_per_minute) 
 |> max(1)
 {:ok, minutes}
 end
 end
 end
end

ㅤ

Как вызывать Actions

# Через домен (рекомендуемый способ)
CourseHub.Courses.publish!(lesson, %{reason: "Готово"})

CourseHub.Courses.read!(CourseHub.Courses.Lesson, :published)

# Или с Ash.Query / Ash.Changeset для сложных случаев
query = Ash.Query.for_read(Lesson, :published)
Ash.read!(query)

ㅤ

Основные возможности Actions

1. argument — входные параметры

Позволяет передавать данные в действие и валидировать их.

argument :title, :string, allow_nil?: false, constraints: [min_length: 5]

argument :published_at, :datetime, default?: &DateTime.utc_now/0

argument :user_id, :uuid, allow_nil?: false

2. accept — какие атрибуты можно менять

Ограничивает список полей, которые разрешено изменять при create или update. Очень полезно для безопасности.

create :register do
 accept [:email, :password, :name] # только эти поля можно передать
end

update :update_profile do
 accept [:name, :bio, :avatar_url]
end

3. change — трансформации данных

Самая мощная и часто используемая часть Actions. Здесь происходит основная бизнес-логика.

create :publish do
 argument :reason, :string

 # Встроенные изменения
 change set_attribute(:status, :published)
 change set_attribute(:published_at, &DateTime.utc_now/0)

 # Кастомный change-модуль
 change {CourseHub.Changes.NotifySubscribers, topic: "lessons"}

 # Анонимная функция
 change fn changeset, _context ->
 Ash.Changeset.change_attribute(changeset, :slug, generate_slug(changeset))
 end
end

4. prepare — подготовка запроса (в основном для read)

Позволяет заранее настроить запрос: сортировку, предзагрузку связей, дополнительные фильтры и т.д.

read :published do
 filter expr(status == :published)

 prepare build(
 sort: [inserted_at: :desc],
 load: [:author, :comments, :reading_time_minutes],
 limit: 20
 )
end

5. Хуки (before/after)

Позволяют выполнить код до или после выполнения действия.

create :publish do
 before_action fn changeset, _context ->
 # проверка перед выполнением
 validate_business_rules(changeset)
 end

 after_action fn _changeset, lesson, _context ->
 # side-effect после успешного создания
 LessonNotifier.publish_event(lesson)
 {:ok, lesson}
 end

 after_transaction fn 
 {:ok, lesson}, _context -> broadcast_new_lesson(lesson)
 {:error, _}, _ -> :ok 
 end
end

6. transaction? — управление транзакцией

Определяет, нужно ли оборачивать действие в базу данных транзакцию.

action :transfer_money, :boolean do
 argument :from_account_id, :uuid
 argument :to_account_id, :uuid
 argument :amount, :decimal

 transaction? true # будет выполнено в одной транзакции

 run fn input, _context ->
 # сложная операция с несколькими записями
 {:ok, true}
 end
end

7. pipe_through — переиспользование логики

Позволяет создавать общие пайплайны и подключать их к разным действиям (очень полезно для DRY).

# В Resource
pipelines do
 pipeline :ensure_admin do
 change ensure_actor_role(:admin)
 validate actor_role(:admin)
 end
end

create :create_admin_content do
 pipe_through :ensure_admin
 accept [:title, :content]
end

update :update_admin_content do
 pipe_through :ensure_admin
 accept [:title, :content]
end

ㅤ

Почему Actions — это круто?

• Полная типизация и introspection — Ash знает всё о действии в runtime (используется для GraphQL, форм, админок)
• Декларативность — код читается как документация бизнеса
• Повторное использование — одно действие можно использовать в LiveView, API, Background Job, Tests
• Безопасность — политики авторизации привязываются к конкретным действиям
• Тестируемость — легко тестировать отдельные действия

ㅤ

Сравнение с классическим Elixir/Phoenix

Actions — это то место, где живёт вся бизнес-логика твоего ресурса

ㅤ

ㅤ

🏢 Что такое Domain (Домены)?

Domain (Домен) — это логический контейнер, который объединяет группу связанных Resources (ресурсов).

Он похож на Phoenix Context, но гораздо мощнее. Если Resource — это описание одной сущности (как User, Lesson, Order), то Domain — это «модуль» или «bounded context» (в терминах DDD), который собирает вместе несколько сущностей одной бизнес-области.

Пример:

• Accounts — домен для пользователей, профилей, авторизации
• Courses — домен для курсов, уроков, тестов, enrollments
• Billing — домен для платежей, подписок, инвойсов
• Therapy — домен для терапии, разговоров, сообщений (из реальных примеров)

ㅤ

Три главные цели Domain

1. Группировка ресурсов
   
   Организация проекта. Вместо того чтобы все ресурсы были разбросаны, они явно лежат в логических группах.

2. Централизованный Code Interface
   
   Domain позволяет определять удобные функции-обёртки для вызова действий ресурсов.

3. Общие настройки и cross-cutting concerns
   
   Здесь можно задать поведение, которое применяется ко всем ресурсам домена (таймауты, пагинация по умолчанию, авторизация и т.д.).

ㅤ

Как выглядит Domain на практике

defmodule CourseHub.Courses do
 use Ash.Domain, otp_app: :course_hub

 # 1. Группировка ресурсов
 resources do
 resource CourseHub.Courses.Course
 resource CourseHub.Courses.Lesson
 resource CourseHub.Courses.Quiz
 resource CourseHub.Courses.Enrollment
 end

 # 2. Code Interface — удобные функции
 define :get_lesson, action: :read, args: [:id], get?: true
 define :list_published_courses, action: :published
 define :enroll_user, action: :create, resource: CourseHub.Courses.Enrollment

 # 3. Общие настройки
 execution do
 timeout :timer.seconds(30) # глобальный таймаут
 default_page_size 20
 end

 # Включение AshAdmin (админка)
 admin do
 show? true
 end
end

ㅤ

Зачем нужен Domain?

• Организация и границы. Чётко разделяет разные части приложения (как bounded contexts в DDD). Accounts не знает про Billing без явного отношения

• Удобный публичный API. Вместо Ash.read!(CourseHub.Courses.Lesson, ...) ты пишешь красиво:
  

 CourseHub.Courses.get_lesson!(lesson_id)
 CourseHub.Courses.list_published_courses!()

• Централизованное управление. Можно отключить авторизацию для всего домена в dev-режиме, задать общие политики, notifiers и т.д.

• Introspection и расширения. Многие расширения Ash (GraphQL, JsonApi, Phoenix и т.д.) работают на уровне домена

• Тестирование и изоляция. Легче тестировать одну бизнес-область целиком

ㅤ

Лучшие практики при работе с доменом

• Один ресурс — один домен. Ресурс не может принадлежать нескольким доменам одновременно.

• Сколько доменов делать?

  • Маленький проект → 1–3 домена.
  • Средний/большой → по одному на крупную бизнес-область (Accounts, Core, Billing, Notifications и т.д.). Это помогает в масштабировании и понимании архитектуры.

• Code Interface — очень мощная фича. Ты можешь определять не только простые обёртки, но и с предустановленными фильтрами, load'ами и т.д.

ㅤ

Сравнение: Domain vs Resource

ㅤ

Почему Domain особенно полезен?

• Проект растёт > 10–15 ресурсов
• Нужна сложная авторизация (policies)
• Делаешь GraphQL / JSON:API / Admin-панель
• Командная разработка — всем нужно понимать границы

ㅤ

ㅤ

⚔️ Ash + Phoenix vs Ecto + Phoenix

Что стоит выбрать в 2026 году?

Плюсы Ash 🔥

• Декларативность → «Опиши домен — остальное Ash выведет сам»
• Сокращение шаблонного кода (часто встречаются отзывы о Ash вроде: «я создаю программы, используя в 3–5 раз меньше строк»)
• Автоматическая генерация GraphQL, JSON:API, Admin-панели, аутентификации
• Политики авторизации и multi-tenancy из коробки
• Отличная поддерживаемость на длинной дистанции (именно то, о чём мечтают в продакшене)

Плюсы классического Phoenix + Ecto 😐

• Полный контроль над каждым байтом кода
• Проще для совсем маленьких проектов и пет-проектов
• Нет дополнительной абстракции (если ты любишь «голый» Elixir)
• Легче для новичков в Elixir

Когда выбирать что?

• Маленький пет-проект или эксперимент → бери чистый Phoenix + Ecto
• Средний/крупный проект, SaaS, долгоживущее приложение → Phoenix + Ash (экономия времени и нервов огромная)
• Хочешь и то, и другое → можно спокойно миксовать в одном проекте (Ash и обычный Ecto отлично уживаются)

ㅤ

😴 В заключение

Ash — это не просто библиотека, а изменение подхода к разработке на Elixir. Он особенно хорошо заходит в проектах среднего и крупного размера, где важны чистота архитектуры, скорость разработки и долгосрочная поддерживаемость.

Конечно, у него есть кривая обучения, и в совсем простых пет-проектах он может быть избыточен. Но если вы устали от расползающейся логики и хотите чёткой, декларативной структуры — Ash дарит очень приятное ощущение контроля над кодом.

ㅤ

ㅤ

🥴 От автора

Спасибо большое за интерес к этой статье! Надеюсь, она помогла разобраться, что представляет собой Ash и зачем он используется.

Если эта статья пришлась вам по душе и хочется ещё материалов такого плана, присоединяйтесь ко мне в моём телеграм-канале, где выкладываю обзоры книг, публикации по Elixir, переводы технической литературы и интересные новости!