Содержание
Каждый раз, когда вы разрабатываете веб-приложение, у вас всегда будет ряд статических ресурсов, которые вы хотите обслуживать до конечного пользователя. Эти статические файлы бывают разных форм — HTML, CSS, LESS, SCSS, Javascript, Plain Text, Markdown, Asciidoc и т. Д. — и имеют ряд проблем, которые лучше всего интегрировать в ваше веб-приложение для простоты процесса разработки. Цель этой статьи — показать несколько простых методов, использующих плагины Maven, для оптимизации разработки и включения этих статических ресурсов в ваше приложение.
Обслуживание статических ресурсов
Предполагается, что вы уже можете обслуживать статические ресурсы из своего веб-приложения. Как правило, какой бы фреймворк вы не использовали для создания своего приложения, есть стандартные способы поддержки этого — например, Spring — использует тег mvc:resources . Кроме того, предполагая, что вы используете контейнер сервлетов, такой как Tomcat, часто бывает так, что вы можете обслуживать все, что появляется в каталоге src/main/webapp без какой-либо дополнительной настройки вообще. Важно, чтобы вы знали, где в конечном файле WAR должны находиться ваши статические файлы, поскольку это будет неоднократно использоваться в примерах, приведенных в этой статье.
Простые, неуправляемые файлы
Абсолютно простейшая форма статических ресурсов, которые могут быть включены, это те, которые не требуют абсолютно никаких манипуляций. Это файлы, которые вы пишете и затем включаете в веб-приложение как есть. В том числе это действительно просто. Все, что вам нужно сделать, это поместить файлы в src/main/webapp или src/main/resources в зависимости от того, где вы хотите, чтобы они появлялись. Файлы, включенные в src/main/webapp будут скопированы в корень вашего WAR-файла, тогда как файлы, включенные в src/main/resources будут скопированы в target/classes , которые затем попадают в путь к классам вашего веб-приложения.
Шаблонные файлы
Иногда вы обнаруживаете, что хотите иметь несколько простых файлов, но включаете в них расширенные свойства, взятые из сборки Maven. Например, номер версии артефакта является общим, который может быть включен.
Это достижимо с помощью стандартных плагинов Maven, которые уже используются как часть вашей сборки — плагин Maven Resources и плагин Maven WAR — так что давайте посмотрим на них.
Плагин Maven Resources
Без какой-либо дополнительной настройки плагин Maven Resources уже используется для копирования каталога src/main/resources в результирующий файл JAR или WAR. (Обратите внимание, плагин Maven Resources также используется для каталога src/test/resources , и все, что здесь упоминается, в равной степени применимо к этому).
По умолчанию он не выполняет фильтрацию, поэтому для его поддержки требуется дополнительная настройка. Фильтрация — это процесс замены специальных заполнителей в ваших статических ресурсах правильными значениями во время копирования ресурсов в ваше веб-приложение.
Настройка фильтрации ваших ресурсов — это простой случай добавления следующей конфигурации в ваш файл pom.xml :
<build> <resources> <resource> <directory>src/main/filteredResources</directory> <filtering>true</filtering> </resource> </resources> </build>
Этот блок имеет два эффекта:
- Добавляет новый каталог, из которого будут копироваться ресурсы — в этом случае мы использовали
src/main/filteredResources - Включить фильтрацию для всех ресурсов в этом каталоге
Рекомендуется по возможности разделять отфильтрованные ресурсы, чтобы случайно не выполнить фильтрацию файлов, которые вы не собираетесь делать. Например, файлы Spring Context часто содержат свойства для расширения, которые используют точно такой же синтаксис, но вы не хотите расширять этот процесс.
Фильтрация достигается путем добавления специальных заполнителей в ваши файлы. Все эти заполнители начинаются с ${ и заканчиваются } . Между скобками указано имя свойства, которое вы хотите подставить в файл. Например, у вас есть файл src/main/filteredResources/details.txt который содержит следующее:
Group ID: ${project.groupId} Artifact ID: ${project.artifactId} Version: ${project.version}
Затем, после копирования в встроенное веб-приложение, оно будет автоматически расширено идентификатором группы, идентификатором артефакта и версией проекта, который в настоящее время создается.
Свойства, которые можно использовать здесь, доступны для реактора Maven. К ним относятся свойства Maven по умолчанию, дополнительные свойства, определенные в файле POM, и системные свойства, указанные в командной строке.
Плагин Maven WAR
Плагин Maven WAR немного менее интегрирован в процесс сборки, поэтому для его настройки необходимо использовать стандартный механизм настройки плагинов.
Опять же, по умолчанию это не будет делать никакой фильтрации. Как и раньше, вы, вероятно, хотите быть избирательными по отношению к файлам, которые выбраны для фильтрации, чтобы не слишком сильно мешать другим источникам. Если вы хотите использовать настройки, аналогичные предыдущим, где у вас есть один полный каталог для отфильтрованных ресурсов и один для нефильтрованных, то будет работать следующая конфигурация.
<build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-war-plugin</artifactId> <configuration> <webResources> <resource> <directory>src/main/filteredWebapp</directory> <filtering>true</filtering> </resource> <resource> <directory>src/main/webapp</directory> <filtering>false</filtering> </resource> </webResources> </configuration> </plugin> </plugins> </build>-<build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-war-plugin</artifactId> <configuration> <webResources> <resource> <directory>src/main/filteredWebapp</directory> <filtering>true</filtering> </resource> <resource> <directory>src/main/webapp</directory> <filtering>false</filtering> </resource> </webResources> </configuration> </plugin> </plugins> </build>
Как и раньше, теперь у нас есть две директории, из которых файлы будут включены в WAR-файл. Файлы в src/main/webapp будут включены как есть, в то время как файлы в src/main/filteredWebapp будут фильтроваться по мере их копирования.
В качестве альтернативы вы можете сохранить все файлы вместе и выборочно отфильтровать только небольшое их подмножество. Это может быть достигнуто следующим образом:
<build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-war-plugin</artifactId> <configuration> <webResources> <resource> <directory>src/main/webapp</directory> <filtering>true</filtering> <includes> <include>version.html</include> </includes> </resource> <resource> <directory>src/main/webapp</directory> <filtering>false</filtering> <excludes> <exclude>version.html</exclude> </excludes> </resource> </webResources> </configuration> </plugin> </plugins> </build>-<build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-war-plugin</artifactId> <configuration> <webResources> <resource> <directory>src/main/webapp</directory> <filtering>true</filtering> <includes> <include>version.html</include> </includes> </resource> <resource> <directory>src/main/webapp</directory> <filtering>false</filtering> <excludes> <exclude>version.html</exclude> </excludes> </resource> </webResources> </configuration> </plugin> </plugins> </build>в<build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-war-plugin</artifactId> <configuration> <webResources> <resource> <directory>src/main/webapp</directory> <filtering>true</filtering> <includes> <include>version.html</include> </includes> </resource> <resource> <directory>src/main/webapp</directory> <filtering>false</filtering> <excludes> <exclude>version.html</exclude> </excludes> </resource> </webResources> </configuration> </plugin> </plugins> </build>-<build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-war-plugin</artifactId> <configuration> <webResources> <resource> <directory>src/main/webapp</directory> <filtering>true</filtering> <includes> <include>version.html</include> </includes> </resource> <resource> <directory>src/main/webapp</directory> <filtering>false</filtering> <excludes> <exclude>version.html</exclude> </excludes> </resource> </webResources> </configuration> </plugin> </plugins> </build>
Эта версия хранит все файлы в src/main/webapp и выборочно фильтрует только указанные файлы — в данном случае version.html . Это облегчает отслеживание того, какие файлы используются, но недостатком является то, что список отфильтрованных файлов необходимо указывать дважды — один раз для включения в отфильтрованный набор файлов и один раз для исключения из нефильтрованного набора , Это является нежелательным побочным эффектом необходимости использовать различные теги resource для представления отфильтрованных и нефильтрованных ресурсов.
CSS файлы
Любое веб-приложение обязательно должно включать файлы Cascading Stylesheet (CSS) для описания стиля страницы. Эти CSS-файлы могут быть созданы различными способами, от ручной работы и включения в качестве простых ресурсов — как описано выше — до использования препроцессора CSS, такого как LESS или SASS .
МЕНЬШЕ
Файлы LESS могут поддерживаться с помощью плагина LESS Maven . LESS реализован как приложение Javascript, и плагин LESS Maven включает его в сборку, выполняя Javascript внутри JVM, выполняющей сборку. Этот плагин немного проще и легче, чем SASS, но LESS также является немного более простым препроцессором с меньшим количеством функций. Если вы никогда не использовали препроцессор CSS, прежде чем это хорошее место для начала.
Настройка сборки для автоматической сборки файлов LESS в файлы CSS может быть выполнена следующим образом:
<build> <plugins> <plugin> <groupId>org.lesscss</groupId> <artifactId>lesscss-maven-plugin</artifactId> <version>1.7.0.1.1</version> <configuration> <sourceDirectory> ${project.basedir}/src/main/less </sourceDirectory> <outputDirectory> ${project.build.directory}/${project.build.finalName}/css </outputDirectory> </configuration> <executions> <execution> <id>compile-less</id> <phase>generate-resources</phase> <goals> <goal>compile</goal> </goals> </execution> </executions> </plugin> </plugins> </build>
Эта конфигурация будет компилировать каждый файл *.less каталоге src/main/less и помещать полученные CSS-файлы в каталог css веб-приложения, точно так же, как если бы сами CSS-файлы были помещены в src/main/webapp/css Если вы хотите включить файлы в путь к классам — как если бы они были записаны в src/main/resources просто измените outputDirectory чтобы использовать classes вместо ${project.build.finalName} .
SCSS
Файлы SCSS могут поддерживаться с помощью плагина SASS Maven . SASS реализован как приложение Ruby, и плагин SASS Maven включает его в сборку, выполняя код Ruby с использованием привязок JRuby для Java. Это делает процесс немного более сложным, чем плагин LESS, но сложность в основном обрабатывается плагином Maven, и пользователь не должен о нем заботиться.
Настройка сборки для автоматической сборки файлов SCSS в файлы CSS может быть выполнена следующим образом:
<build> <plugins> <plugin> <groupId>nl.geodienstencentrum.maven</groupId> <artifactId>sass-maven-plugin</artifactId> <version>2.23</version> <executions> <execution> <id>lint</id> <phase>validate</phase> <goals> <goal>scss-lint</goal> </goals> </execution> <execution> <id>build</id> <phase>generate-resources</phase> <goals> <goal>update-stylesheets</goal> </goals> </execution> </executions> <configuration> <sassSourceDirectory> ${project.basedir}/src/main/scss </sassSourceDirectory> <destination> ${project.build.directory}/${project.build.finalName}/css </destination> </configuration> </plugin> </plugins> </build>
Эта конфигурация скомпилирует каждый файл *.scss каталоге src/main/scss и поместит полученные CSS-файлы в каталог css веб-приложения, точно так же, как если бы сами CSS-файлы были помещены в src/main/webapp/css Если вы хотите включить файлы в путь к классам — как если бы они были записаны в src/main/resources просто измените destination на использование classes вместо ${project.build.finalName} .
Обратите внимание, что одна особенность, которую плагин SASS предоставляет над плагином LESS, — это поддержка связывания таблиц стилей. Это настроено выше для выполнения на более ранней фазе и гарантирует, что файлы SCSS синтаксически допустимы. Это может быть очень полезно для гарантии того, что сборка будет действительна в начале жизненного цикла сборки.
Сгенерированные файлы HTML
Иногда вам может понадобиться сгенерировать HTML из файлов разметки, которые вы используете в своей сборке. Например, вы можете поддерживать API-документацию в формате Markdown или AsciiDoc и захотеть опубликовать ее HTML-версии как часть развернутого веб-приложения. (Можно даже сгенерировать их из вашего кода, а затем использовать этот плагин для преобразования этого в HTML. Это оставлено читателю в качестве упражнения.)
Файлы уценки
Файлы Markdown могут быть преобразованы в файлы HTML с помощью плагина Markdown Page Generator . Этот плагин будет автоматически генерировать HTML-файлы для всех обрабатываемых файлов Markdown. Он может быть настроен на полную настройку стиля сгенерированных файлов, но из коробки он по-прежнему генерирует идеально используемые файлы.
Настройка сборки для автоматической сборки файлов Markdown в файлы HTML может быть выполнена следующим образом:
<build> <plugins> <plugin> <groupId>com.ruleoftech</groupId> <artifactId>markdown-page-generator-plugin</artifactId> <version>1.0.0</version> <executions> <execution> <phase>process-sources</phase> <goals> <goal>generate</goal> </goals> </execution> </executions> <configuration> <inputDirectory> ${project.basedir}/src/main/markdown </inputDirectory> <outputDirectory> ${project.build.directory}/${project.build.finalName}/docs </outputDirectory> </configuration> </plugin> </plugins> </build>
Эта конфигурация будет обрабатывать каждый файл *.md в src/main/markdown и создавать HTML-файлы в каталоге docs веб-приложения, точно так же, как если бы сами HTML-файлы были помещены в src/main/webapp/docs .
Файлы AsciiDoc
Файлы AsciiDoc можно конвертировать в файлы HTML с помощью плагина Asciidoctor Maven . Этот плагин будет автоматически генерировать HTML-файлы для всех обрабатываемых файлов AsciiDoc. Он может быть настроен на полную настройку стиля сгенерированных файлов, но из коробки он по-прежнему генерирует идеально используемые файлы.
Настройка сборки для автоматической сборки файлов AsciiDoc в файлы HTML может быть выполнена следующим образом:
<build> <plugins> <plugin> <groupId>org.asciidoctor</groupId> <artifactId>asciidoctor-maven-plugin</artifactId> <version>1.5.5</version> <executions> <execution> <phase>process-resources</phase> <goals> <goal>process-asciidoc</goal> </goals> </execution> </executions> <configuration> <sourceDirectory> ${project.basedir}/src/main/asciidoc </sourceDirectory> <outputDirectory> ${project.build.directory}/${project.build.finalName}/docs </outputDirectory> <preserveDirectories>true</preserveDirectories> <backend>html5</backend> </configuration> </plugin> </plugins> </build>
Эта конфигурация будет обрабатывать каждый файл *.ad , *.adoc и *.asciidoc в src/main/asciidoc и создавать HTML-файлы в каталоге docs веб-приложения, точно так же, как если бы сами HTML-файлы были помещены в src/main/webapp/docs .
Резюме
Будь то фильтрация некоторых шаблонных файлов ресурсов для добавления информации о сборке, копирование файлов CSS, обработка файлов LESS или SCSS или преобразование Markdown Asciidoc в HTML, для всех существует плагин Maven. Каждый из них имеет гораздо большую глубину, чем может быть рассмотрено здесь, поэтому, если вы хотите сделать больше с ними, это возможно при некоторой работе по настройке. Тем не менее, приведенные выше примеры конфигурации можно использовать «из коробки», чтобы добавить поддержку этих технологий в качестве стандартной части сборки.
Надеемся, что это дало некоторые идеи о том, как упростить включение внешних ресурсов в ваше веб-приложение без необходимости сложных многоэтапных сборок.