Терминология

YDA

YDA (читается: «уай-ди-эй») — сокращённое от «Yamato Daiwa Automation» название утилиты, которой посвящена данная документация. Здесь «Yamato Daiwa» — название японского стартапа, на данный момент специализирующегося на кастомной веб-разработке, а также на разработке библиотек, фреймворков и утилит (в частности, YDA).

Вероятно, русскоязычные веб-разработчики придумают своё название этому инструменту, а пока эта аббревиатура YDA остаётся наиболее простой для запоминания и произношения.

Проект

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

Сборка проекта

Употребляется в значениях «процесс» и «набор файлов»:

• «Сборка проекта» как процесс — генерация выходных файлов на основе исходных файлов. Этот процесс — основное, для что делает YDA.
• «Сборка проекта» как набор файлов — совокупность всех выходных файлов проекта. Обычно они объединена общей директорией (директорией сборки), но YDA этого не требует.

Не все технологии предполагают сборку проекта. Например, если сайт или веб-приложение написаны на чистых HTML, CSS и PHP (последний является интерпретируемым языком программирования, что означает прямое выполнение файлов с исходным кодом без их компиляции в выходные исполняемые файлы), то в этом случае собирать нечего. YDA же рассчитан на работу с языками Pug, Stylus и TypeScript, каждый из которых предполагает преобразование в выходной код (HTML, CSS и JavaScript соответственно). Кроме того, файлы изображений в результате автоматической оптимизации тоже могут отличаться от исходных, а в случах, когда изменения содержимого файлов не требуется, можно настроить простое копирование, чтобы не смешивать исходные файлы с выходными.

Задача (Task)

В контексте сборки проектов, задача — конкретная работа для компьютера среди автоматизации сборки проектов. На данный момент можно выделить следующие основные задачи, на которых специализируется YDA:

• Обработка разметки с исходным кодом на препроцессорном языке Pug
• Обработка стилей с исходным кодом на препроцессорном языке Stylus
• Обработка ECMAScript-логики с исходным кодом на языке TypeScript. Хотя этот язык редко называют препроцессорным, де факто он будет являться таковым до тех пор, пока его интерпретаторы не наберут популярность). Возможно преобразование как в браузерный JavaScript, так и в Node.js.
• Обработка изображений
• Копирование шрифтов, видео, аудио и любых других файлов
• Автоматические открывание браузера при завершении начальной сборки проекта с автоматической перезагрузкой страницы браузера по мере обновления выходного кода
• Автоматический запуск Node.js-сервера при завершении начальной сборки проекта с автоматическим перезапуском этого сервера по мере обновления выходного кода

Сценарий (Scenario)

В контексте YDA, а также Gulp и аналогичных утилит для сборки проектов, сценарий — набор задач, расположенных в последовательности (серии) и параллели.

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

Поскольку YDA является более высокоуровневым инструментом, чем Gulp, то пользователям не нужно беспокоиться о правильном расположении задач в серии и параллели, а только лишь знать, какие сценарии доступны.

На данный момент YDA предлагает нижеследующие 2 сценария:

Инкрементальная сборка проекта (Incremental building of project)

Сначала выполняется полная сборка проекта, затем при внесении изменений в исходные файлы осуществляется выборочная пересборка. Таким образом, выполнение приложения будет осуществляться до тех пор, пока оно не будет вручную остановлено или не произойдёт критическая ошибка. При необходимости можно настроить автоматическое открытие браузера (если в проекте есть клиентская часть) и/или автоматический запуск локального сервера (если в проекте есть серверная часть на Node.js).

Продакшен-подобная сборка проекта (Production-like building of project)

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

Режим сборки проекта (Project building mode)

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

Инкрементальные (Incremental)

Актуальны для сценария инкрементальной сборки проекта. В соответствии с этим сценарием, сначала осуществляется полная сборка проекта, а затем по мере внесения изменений в исходный код автоматически запускается выборочная пересборка. Общим для инкрементальных режимов сборки требованием к сборщику проектов являются оптимизация пересборки проекта. Также, если речь идёт о разработке сайтов или приложений с графическим интерфейсом, то требуется автоматическая перезагрузка страницы браузера и прочие меры, обеспечивающие комфортную разработку программного продукта с качественной обратной связью включая ранее оповещение о разного рода проблемах, таких как нарушение валидности HTML-кода.

Статическое превью (Static preview)

Задуман как этап, на котором разработчик полностью сконцентрирован на вёрстке, а JavaScript-динамика и серверная часть — это задачи следующих этапов. Соответственно, данный режим сборки проекта актуален только для разработки сайтов и приложений с графическим интерфейсом. Важным требованием к сборщику проектов на этом этапе является обеспечение просмотра выходных файлов заказчиками или руководителями без технических знаний и специализированного программного обеспечения, такого как npm или Git, при этом изображения и другие мультимедийные файлы должны корректно отображаться в браузере. Проще говоря, должен соблюдаться принцип: «открыл скачанный HTML-файл в браузере — и всё корректно отображается».

Локальная разработка (Local development)

В случае с сайтами или приложениями с графическим интерфейсом, на этом этапе, в отличие от предыдущего, уже осуществляется полноценная реализация JavaScript-динамики клиентской части, а также серверной части. От сборщика проектов на данном этапе помимо общих требований для инкрементальных режимов может потребоваться некоторая дополнительная функциональность, например автоматический перезапуск локального сервера по мере обновления выходных файлов, если в проекте имеется серверная часть на Node.js.

Продакшен-подобные (Production-like)

Обычно перед тем, как публиковать сайт или веб-приложение, их запускают на тестовом сервере и настраивают ограниченный доступ, чтобы тестировщики могли выявить неполадки (баги), не обнаруженные на предыдущих этапах разработки. На этапах этой группы автоматической пересборки проекта, автоматической перезагрузки страницы браузера и автоматического перезапуска локального сервера по мере обновления файлов уже нет, поскольку собранные сайты или приложения подлежат запуску на удалённом сервере, а не локальном компьютере. Хотя такие сборки должны быть максимально блики к окончательной версии для публикации (или «продакшену», почему режимы этой группы и называется «продакшен-подобными»), какие-то особенности (например, уровень логирования или набор данных) часто отличаются в зависимости от конкретного режима.

Тестирование (Testing)

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

Стэйждинг (Staging)

В больших проектах часто помимо версии для тестирования имеется похожая версия, которую называют «инсценировкой» («стэйджингом»). Разница между ними, в принципе, небольшая: как правило это использование данных, приближённых к реальными, а не таких, которые удобны для тестирования. За счёт этого создаётся эффект, что руководство или заказчики работают с окончательной версией программного продукта. Кстати, по этой же причине заказчикам лучше презентовать именно эту сборку, а не тестовую.

Продакшен (Production)

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

Точки входа и дочерние файлы (Entry points / children files)

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

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

По типу файлов

Разметка

В случае разметки, точка входа соответствует завершённому HTML-документу.

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

Обычный HTML-файл не может быть разделён на несколько файлов, однако HTML-препроцессоры включая Pug позволяют это сделать на стадии исходного когда. В YDA, работающим с препроцессором Pug, термин «точка входа» применяется как по отношению к исходным Pug-файлам, так и к выходным HTML-файлам. Для того, чтобы включить дочерний файл в точку входа или другой дочерний файл, используется директива include. Директива extends тоже означает использование дочернего файла, потому что тот файл, от которого осуществляется наследование, не обязательно является завершенным HTML-документом.

Стили

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

Однако, при использовании CSS-препроцессоров, точка входа — файл с исходным кодом, с которого начинается процесс преобразования в выходной CSS-код. CSS-препроцессоры также позволяют организовать стили по дочерним файлам, которые сами по себе в отдельные CSS-файлы не преобразуются, но могут быть подключены в точки входа или другие дочерние файлы. В CSS-препроцессоре Stylus это возможно с помощью директив @require и @import.

Не существует никаких правил относительно того, сколько каждой HTML-странице должно соответствовать CSS-файлов, а значит точка входа стилей не обязательно должна содержать все стили исключительно для соответствующего HTML-документа. Однако, вопрос разбиения стилей на CSS-файлы является важным с точки зрения оптимизации, причём следует учитывать кэширование CSS-файлов браузером. Бывает, что все стили (общие, а также для каждой отдельной страницы) собирают в единый CSS-файл, но если стилей много, то пользователю, пришедшему посмотреть 1-2 страницы, будет впустую загружено большое количество лишних стилей, а кэширование в данном случае будет неэффективно. Более оптимизированным является такой подход:

• В отдельный CSS-файл (точку входа) собираются общие для всех страниц стили.
• Если на сайте или приложении есть админ-панель, то общие стили для её страниц следует вынести в отдельный от предыдущего CSS-файл.
• Если используется какой-либо CSS-фреймворк, то его стили тоже следует вынести в отдельный CSS-файл.
• У каждой страницы должен быть свой CSS-файл, где содрежатся стили, актуальные только для этой страницы.
• Также можно вынести в отдельный файл типографику, стили каких-либо крупных компонентов и так далее.

Наконец, в каждой странице нужно сослаться только на те CSS-файлы, которые нужны для корректного отображения этой страницы. Тогда загрузка неиспользуемых стилей будет минимизирована, а кэширование будет работать эффективно (для этого также потребуется генерировать имя файла, зависимое от содержимого — многие сборщики проекта это могут).

ECMAScript-логика

В случае ECMAScript-логики, понятие точки входа зависит от среды выполнения.

• В случае браузерного JavaScript-а, точкой входа обычно называют JavaScript-файл, содержащий логику конкретной HTML-страницы. Однако, такая организация кода является лишь рекомендацией, а в реальности с JavaScript-файлами ситуация почти такая же, как с CSS-файлами: логика страницы можно произвольным образом распределить между JavaScript-файлами, и до появления систем сборки проектов так часто и делали, чтобы в одном фале не скапливалось слишком много кода. Но всё-таки в современности рекомендуется придерживаться принципов, аналогичным приведённым выше рекомендациям для CSS-файлов, тем более что современные системы сборки проектов могут автоматически выносить в отдельные файлы повторяющиеся в нескольких точках входа фрагменты кода, а также динамически подгружать JavaScript-код по необходимости при просмотре страницы.
• В случае серверной среды, точкой входа является файл, с которого начинается выполнение серверного приложения. В случае серверного программирования «единая точка входа» является настоятельно рекомендуемой методологией, потому что наличие нескольких точек входа снижает уровень безопасности и усложняет поддерживаемость. Хотя YDA не может Вам запретить иметь несколько точек входа на серверной стороне, шаблон «единая точка входа» де факто является безальтернативным за исключением редких особых случаев.

Группа точек входа (Entry points group)

Группа точек входа — набор точек входа, обработка которых должна осуществляться согласно общим настройкам. Для лёгкости масштабирования, YDA работает с группами точек входа, даже если точка входа только одна.

• Группа одной точки входа не просто включает в себя одну точку входа, но при этом её путь явно указан в настройках.
• В случае группы произвольного числа точек входа указывается не  конкретные пути к точкам входа, а их общая директория, а далее при запуске YDA сама определит пути к соответствующим точкам входа.

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

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

Ассеты (Assets)

Обобщающий термин для следующих типов файлов:

• изображения
• шрифты
• аудио
• видео

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

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

Группы ассетов (Assets groups)

Группа ассетов — набор ассетов конкретного вида, обработка которых осуществляется согласно общим настройкам. Для лёгкости масштабирования, YDA работает с группами ассетов, даже если ассет только один.

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

Ресурсы (Resources)

В контексте YDA, ресурсы — обобщающий термин для стилей, скриптов и ассетов (в соответствии с приведённым выше определением).

Выборочное выполнение (Selective execution)

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

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

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

Важный для YDA общие термины

Публичный путь и укороченный абсолютный путь (Public path / Shortened absolute path)

Публичный путь — директория на сервере, относительно которой указываются пути к файлам, доступным в интернете без ограничений такие как аутентификация и авторизация. Если брать Linux-сервер, то обычно это что-то вроде /var/www/example.com/public.

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

С понятием публичного пути связано понятие укороченного абсолютного пути. Чтобы не затягивать раздел подробным рассмотрением структуры URI, ограничимся описательным упрощённым определением. Укороченный абсолютный путь в контексте HTML-кода и CSS-кода — способ указания пути к файлу, при котором путь начинается со знака косой черты, например /images/kittens/GrayKitten.jpg.

Не каждый укороченный абсолютный путь ссылается на публичный путь, однако если это путь изображению, файлу каскадных таблиц стилей, шрифтам и другим ассетам, то чаще всего это так. Хотя не зная кода серверной части нельзя однозначно сказать, ссылается ли /images/kittens/GrayKitten.jpg на файл ниже публичного пути, зачастую это именно так.