YAWAS — Ещё одна структура веб-приложений

Еще одна структура веб приложений… Которая была выверена «потом и кровью» и имеет достаточный уровень распределения.

Введение

С каждым годом разработки веб-приложений появляется все больше требований по эргономике, безопасности, архитектуре и прочим моментам. Это связано с быстрыми изменениями в мире, что выражает в нагрузках на проекты и качестве реализаций. Большая часть исследований и внимания со стороны разработчиков и управленцев направлена на архитектуру приложений, их безопасность и прочие фундаментальные вещи, которые прямо проецируются на производительность и удобство веб-приложения как со стороны разработчика, так и со стороны клиента [1]. Но, большая часть разработчиков и управленцев совершенно игнорируют тему организации структуры приложения, которая выражается именно в файловой организации.

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

Правильная организация файловой структуры веб-приложения позволит не только повысить скорость разработки, но и снизить порог вхождения для новых специалистов. Помимо этих моментов, грамотная организация файловой структуры обеспечивает сокращение времени на поиск нужного файла, который выполняется рекурсивно по иерархии дерева [3]. Такая простая операция достаточно трудоемка и «дорогая» по времени, если нет четкого определения структуры файлов в проекте.

Анализ существующих современных файловых структур веб-приложений

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

В общей случае, файловую структуру можно разделить на 2 категории: «самописная» и экосреда библиотеки разработки. В случае «самописных» реализаций везде прослеживается несколько базовых принципов: структура MVC (model-view-controller) приложения и структура жесткой привязки к страницам.

Если рассматривать классическую структуру MVC приложения, то структура папок выглядит следующим образом (рис. 1):

Рисунок 1. Структура папок MVC приложения

1. Контроллеры. Здесь хранятся точки входа после запросов, которые выполняют логику приложения.
2. Модели. Здесь хранятся объекты таблиц базы данных (БД) в представлении, чаще всего, ActiveRecord.
3. Представления (виды). Здесь хранятся шаблоны и виды страниц.

Основная проблема данной структуры в том, что «из коробки» нет предусмотренного места (папки) для хранения бизнес логики веб-приложения [4]. Для решения этой проблемы прибегают к дополнительным структурам или формируются собственные подходы. Если рассматривать данную структуру с точки зрения взаимодействия (рис. 2) и слоев, то получается, что запросы идут на основной файл приема (единая точка входа), который вызывает (исполняет) нужный контроллер. Контроллер работает с моделями, чтобы работать с данными, а потом отдает сформированные данные в представление, которое записывает в буфер и отправляет ответ на запрос клиенту.

Рисунок 2. Взаимодействие слоев MVC структуры

Очевидно, что такая структура является хорошей только для простых и небольших приложений, так как в данной структуре присутствует потенциальная возможность «загрязнения» и отсутствие строгого регламента на все возможные случаи [6].

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

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

Все вышесказанные слова крайне различно находят свое отражение в структурах современных веб-приложений, поскольку являются крайне гибкими и незаконченными. Проведя анализ и сформировав вышеуказанные выводы предлагается рассмотреть универсальную структуру веб-приложений, которая способна работать как модульно, так и разрозненно [8].

Предложение и обоснование структуры веб-приложения

Предлагаемая структура имеет название YAWAS (Yet Another Web Application Structure) — еще одна структура веб приложений [5].

Файловая структура

Файловая структура предназначена для упорядоченного и логичного хранения файлов. Приведенная структура обязательна для соблюдения и корректной работы системы/приложения.

			/: корневой каталог
    - /bin: (binaries) бинарные/исполняемые файлы.
    - /configs: конфигурационные файлы
    - /dumps: файлы резервных копий
    - /resources: файлы пользовательских ресурсов (изображения, стили и прочие файлы)
    - /runtime: переменные/изменяемые файлы
        - /log: файлы логов
        - /cache: файлы кэша
    - /src: (source) исходные файлы приложения/системы
    - /tests: файлы тестирования
		

В каждой папке присутствует свой README файл, который вносит разъяснения по выбранной директории, а также может хранить дополнительную файловую структуру.

1. /bin — (binaries) бинарные/исполняемые файлы

Этот каталог содержит исполняемые файлы. Здесь расположены программы/скрипты/утилиты, которые можно использовать дополнительно для расширения функционирования системы. Например, здесь может находиться исполняемый файл console, который отвечает за работу с консолью для обеспечения вспомогательных функций, например, создание миграций. Файлы в этой папке вызываются через php FILE аргументы.

2. /configs — конфигурационные файлы

Этот каталог содержит конфигурационные файлы для приложения/системы. Файлы могут быть различных форматов и структур. Предназначение всех файлов в данном каталоге — настройка и конфигурация приложения/системы.

3. /dumps — файлы резервных копий

Этот каталог содержит файлы резервных копий приложения/системы. Файлы могут быть различных форматов и структур.

4. /resources — файлы пользовательских ресурсов (изображения, стили и прочие файлы)

Этот каталог содержит файлы пользовательских ресурсов: изображения, стили и прочие файлы. Вложенная структура может быть любой, но реализация основных папок обязательна (media, css и js).

Файловая структура

			/resources: файлы пользовательских ресурсов (изображения, стили и прочие файлы)
    - /media: файлы медиа контента (изображения, иконки, видео и другие)
    - /css: файлы каскадных таблиц стилей
    - /js: файлы пользовательских скриптов JavaScript
		

4.1. /resources/media — файлы медиа контента (изображения, иконки, видео и другие)

Этот каталог содержит файлы медиа контента: изображения, иконки, видео и прочие файлы. Вложенная структура может быть любой.

4.2. /resources/css — файлы каскадных таблиц стилей

Этот каталог содержит файлы каскадных таблиц стилей. Вложенная структура может быть любой.

4.3. /resources/js — файлы пользовательских скриптов JavaScript

Этот каталог содержит файлы пользовательских скриптов JavaScript. Вложенная структура может быть любой.

5. /runtime — переменные/изменяемые файлы

Этот каталог содержит часто изменяющиеся файлы с нефиксированным размером. Примерами таким файлов могут служить логи, кеши, базы данных и прочие.

Файловая структура

			/runtime: переменные/изменяемые файлы
    - /log: файлы логов
    - /cache: файлы кэша
		

5.1. /runtime/log — файлы логов

Этот каталог содержит файлы логов работы приложения/системы. Допускается любая вложенность папок, но только, если они отвечают за конкретный модуль/подсистему или иные элементы.

5.2. /runtime/cache — файлы кеша

Этот каталог содержит файлы кеша приложения/системы. Допускается любая вложенность папок, но только, если они отвечают за конкретный модуль/подсистему или иные элементы.

6. /src — (source) исходные файлы приложения/системы

Этот каталог содержит исходные файлы приложения/системы: контроллеры, модели, модули и прочие файлы, которые выполняют логику функционирования самого приложения.

Файловая структура

			/src: (source) исходные файлы приложения/системы
    - /application: слой сервис логики приложения
    - /domain: слой доменной логики (предметной области), чистой бизнес логики без привязки к фреймворку
    - /events: события приложения/системы
    - /infrastructure: слой реализации доменного слоя (репозитории, модели и прочие элементы)
    - /presentation: слой запросов и представления (контроллеры и виды)
		

6.1. /src/application — слой сервис логики приложения

Этот каталог содержит исходные файлы слоя реализации логики сервисов приложения. Сервисы должны быть привязаны к предметной области. Именование структуры директории сервисов должно совпадать с сущностями. Сервисы не должны иметь состояния. Структура сервисов может выглядеть следующим образом:

			/src/application - слой сервис логики приложения
    - /services: сервисы бизнес логики
        - /service-name
            - / traits
		

Папка service-name является самим сервисом и должна называться соответствующим образом с привязкой к предметной области. Для корректного оперирования действиями сервиса лучше выносить действия в отдельные структуры:

			/src/application/services/service-name: конкретный сервис
    - /create
        - ServiceNameCreate.php
        - ServiceNameCreateValidation.php
        - ServiceNameCreateException.php
    - /traits
		

Для передачи данных из сервиса в репозиторий или иные элементы следует использовать DTO. DTO (data transfer object) — объекты для передачи данных. Структура для DTO объектов в слое сервисной логики приложения может выглядеть следующим образом:

			/src/application/services/service-name: конкретный сервис
    - /create
        - ServiceNameCreate.php
        - ServiceNameCreateValidation.php
        - ServiceNameCreateException.php
        - /dto
    - /traits
		

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

6.2. /src/domain — слой доменной логики (предметной области), чистой бизнес логики без привязки к фреймворку

Этот каталог содержит исходные файлы слоя доменной логики (предметной области), чистой бизнес логики без привязки к фреймворку. В данном слое реализуются сущности, объекты-значения, агрегаты и прочие элементы предметной области. Каждая сущность должна быть вынесена в отдельную директорию, где располагаются все необходимые элементы для ее работы.

Файловая структура

			/src/domain:  слой доменной логики (предметной области), чистой бизнес логики без привязки к фреймворку
    - /entity: директория сущности
        - /value-objects: объекты-значения сущности
        - /enums: статичные данные (нумераторы/константы/перечисления) сущности
        - /events: события сущности
        - /exceptions: исключения сущности
		

Сущность (entity) — это объект из предметной области. Сущность обязательно должна иметь идентификатор.

Объект-значение (value object) — это строительный блок сущности. Объект-значение не имеет идентификатор и обладает стабильным содержимым на все время жизни.

Константы/перечисления/нумераторы (enums) — статичные данные сущности. Данные объекты предназначены для хранения постоянных данных, которыми будет оперировать сущность.

6.3. /src/events — файлы событий приложения/системы

Этот каталог содержит исходные файлы событий приложения/системы.

6.4. /src/infrastructure — слой реализации доменного слоя (репозитории, модели и прочие элементы)

Этот каталог содержит исходные файлы слоя реализации доменного слоя (репозитории, модели и прочие элементы). Структура репозиториев должна быть привязана к доменному слою. Примерная структура может выглядеть следующим образом:

			/src: (source) исходные файлы приложения/системы
    - /infrastructure: слой реализации доменного слоя (репозитории, модели и прочие элементы)
        - /repositories: репозитории (конкретная реализация доменного слоя)
		

Важный аспект методов репозитория — операции либо выполняются «как нужно», либо не выполняются вообще.

6.4.1. /src/infrastructure/repositories — репозитории (конкретная реализация доменного слоя)

Этот каталог содержит исходные файлы конкретной реализации доменного слоя. Примерная структура для сущности entity может выглядеть следующим образом:

			/src/infrastructure: слой реализации доменного слоя (репозитории, модели и прочие элементы)
    - /repositories: репозитории (конкретная реализация доменного слоя)
        - /entity
            - InMemoryEntityRepository.php
            - SqlEntityRepository.php
            - FileEntityRepository.php
		

Здесь реализованы 3 вида репозитория: в памяти, sql и файловый.

6.5. /src/presentation — слой запросов и представления (контроллеры и виды)

Этот каталог содержит исходные файлы слоя реализации запросов и представления (контроллеры и виды). Здесь располагаются точки приема запросов и отдачи ответов (контроллеры), а также виды (views), которые они могут генерировать.

7. /tests — файлы тестирования

Этот каталог содержит файлы тестирования функционала приложения/системы. Вложенная структура может быть любой в зависимости от используемых технологий.

Заключение

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

Предложенная файловая структура YAWAS при строгом ее соблюдении предусматривает большую часть возможного функционала. Особенно важно отметить, что в в папке src ((source) исходные файлы приложения/системы) представлена структура для одного приложения. Если в проекте предусматривается множество приложений, то упомянутая структура оборачивается в соответствующие каталоги. Также предусматривается и другой вариант, который с одной стороны более модульный, но с другой стороны он имеет уровень избыточности и дублирования. При таком положении каждый руководитель проекта должен решить, по какому пути его команде идти.

Как было сказано ранее, здесь может быть несколько вариантов:

1. Добавлять вложенные папки в структуру, чтобы получать примерно так: src/presentation/controllers/admin
2. Разбить все «подсистемы» на папки, чтобы в src была примерно такая структура: src/admin-application и src/client-application. В таком случае, каждая папка (*-application) должна повторить текущую структуру папки src. Это дополнительно позволит добавить «глобальный» класс управления «подсистемой»: src/admin-application/AdminBundle.php.

Таким образом, предлагаемая система учитывает большую часть вопросов по организации файлов и каталогов проекта с достаточным уровнем документирования.

Список источников

1. Организация структуры приложения | Node.js с примерами кода. Date Views 23.05.2022 nodejsdev.ru/.
2. БЭМ | Организация файловой структуры. Date Views 21.05.2022 github.com/bem-site/bem-method/blob/bem-info-data/method/filestructure/filestructure.ru.md.
3. Файловая структура проекта. Node Hero: Глава 7 | by Andrey Melikhov | devSchacht | Medium. Date Views 19.05.2022 medium.com/devschacht/node-hero-chapter-7-4078fa61ece6.
4. Файловая структура приложения — Мегаобучалка. Date Views 22.05.2022 megaobuchalka.ru/16/42070.html.
5. mepihindeveloper/yawas: YAWAS (yet another web application structure) — структура директорий веб приложения. Date Views 24.05.2022 github.com/mepihindeveloper/yawas.
6. Попков, И. В. БЭМ. Компонентный подход к веб-разработке / И. В. Попков, Л. В. Курзаева // Международный студенческий научный вестник. — 2018. — № 5. — С. 165. — EDN XZPCTJ.
7. Макаренко, С. И. Принципы построения и функционирования аппаратно-программных средств телекоммуникационных систем / С. И. Макаренко, А. А. Ковальский, С. А. Краснов. — Санкт-Петербург : Издательство «Наукоемкие технологии», 2020. — 357 с. — ISBN 978-5-6044429-8-2. — EDN DOWPGX.
8. Крюков, В. В. Типовые организационные и технологические решения для создания региональной информационной среды вуза и филиалов / В. В. Крюков, К. И. Шахгельдян // Открытое образование. — 2004. — № 5. — С. 38-52. — EDN UQIHMV.