«1. Обзор
Цель этого вводного руководства — изучить Play Framework и выяснить, как мы можем создать с его помощью веб-приложение.
Play — высокопроизводительная среда веб-приложений для языков программирования, код которых компилируется и запускается на JVM, в основном Java и Scala. Он объединяет компоненты и API, необходимые для разработки современных веб-приложений.
2. Настройка Play Framework
Давайте перейдем на официальную страницу Play Framework и загрузим последнюю версию дистрибутива. На момент написания этого руководства последней была версия 2.7.
Мы загрузим ZIP-папку учебника Play Java Hello World и разархивируем файл в удобное место. В корне этой папки мы найдем исполняемый файл sbt, который мы можем использовать для запуска приложения. Кроме того, мы можем установить sbt с их официальной страницы.
Чтобы использовать sbt из загруженной папки, давайте сделаем следующее:
cd /path/to/folder/
./sbt run
Обратите внимание, что мы запускаем скрипт в текущем каталоге, поэтому используется синтаксис ./.
Если мы установим sbt, то мы можем использовать его вместо этого:
cd /path/to/folder/
sbt run
После выполнения этой команды мы увидим утверждение, которое гласит: «(Сервер запущен, используйте Enter, чтобы остановить и вернуться к консоль…)». Это означает, что наше приложение готово, поэтому теперь мы можем перейти на http://localhost:9000, где нам будет представлена страница приветствия Play:
3. Анатомия приложений Play
В этом разделе, мы лучше поймем, как устроено приложение Play и для чего используется каждый файл и каталог в этой структуре.
Если вы хотите прямо сейчас проверить себя на простом примере, перейдите к следующему разделу.
Вот файлы и папки, которые мы находим в типичном приложении Play Framework:
├── app → Application sources
│ ├── assets → Compiled Asset sources
│ │ ├── javascripts → Typically Coffee Script sources
│ │ └── stylesheets → Typically LESS CSS sources
│ ├── controllers → Application controllers
│ ├── models → Application business layer
│ └── views → Templates
├── build.sbt → Application build script
├── conf → Configurations files and other non-compiled resources (on classpath)
│ ├── application.conf → Main configuration file
│ └── routes → Routes definition
├── dist → Arbitrary files to be included in your projects distribution
├── lib → Unmanaged libraries dependencies
├── logs → Logs folder
│ └── application.log → Default log file
├── project → sbt configuration files
│ ├── build.properties → Marker for sbt project
│ └── plugins.sbt → sbt plugins including the declaration for Play itself
├── public → Public assets
│ ├── images → Image files
│ ├── javascripts → Javascript files
│ └── stylesheets → CSS files
├── target → Generated files
│ ├── resolution-cache → Information about dependencies
│ ├── scala-2.11
│ │ ├── api → Generated API docs
│ │ ├── classes → Compiled class files
│ │ ├── routes → Sources generated from routes
│ │ └── twirl → Sources generated from templates
│ ├── universal → Application packaging
│ └── web → Compiled web assets
└── test → source folder for unit or functional tests
3.1. Каталог приложения
Этот каталог содержит исходный код Java, веб-шаблоны и исходники скомпилированных активов — в основном, все исходники и все исполняемые ресурсы.
Каталог app содержит несколько важных подкаталогов, каждый из которых упаковывает одну часть архитектурного шаблона MVC:
-
models — это бизнес-уровень приложения, файлы в этом пакете, вероятно, моделируют наши таблицы базы данных и позволяют нам получить доступ к представлениям уровня сохраняемости — все HTML-шаблоны, которые могут быть отображены в браузере, содержатся в этой папке. Контроллеры — подкаталог, в котором у нас есть наши контроллеры. Контроллеры — это исходные файлы Java, содержащие действия, которые должны выполняться для каждого вызова API. Действия — это общедоступные методы, которые обрабатывают HTTP-запросы и возвращают результаты, аналогичные активам HTTP-ответов — подкаталогу, содержащему скомпилированные активы, такие как CSS и javascript. Приведенные выше соглашения об именах являются гибкими, мы можем создавать наши пакеты, например. пакет приложения/утилиты. Мы также можем настроить имя пакета app/com/baeldung/controllers
Он также содержит необязательные файлы и каталоги, необходимые конкретному приложению.
3.2. Общедоступный каталог
Ресурсы, хранящиеся в общедоступном каталоге, являются статическими активами, которые обслуживаются непосредственно веб-сервером.
Этот каталог обычно имеет три подкаталога для файлов изображений, CSS и JavaScript. Мы рекомендуем организовывать файлы ресурсов таким образом, чтобы обеспечить единообразие во всех приложениях Play.
3.3. Каталог conf
Каталог conf содержит файлы конфигурации приложения. В application.conf мы поместим большинство свойств конфигурации для приложения Play. Мы определим конечные точки для приложения в маршрутах.
Если приложению нужны дополнительные файлы конфигурации, их следует поместить в этот каталог.
3.4. Каталог lib
Каталог lib является необязательным и содержит зависимости от неуправляемых библиотек. Если у нас есть jar-файлы, не указанные в системе сборки, мы помещаем их в этот каталог. Они будут автоматически добавлены в путь к классам приложения.
3.5. Файл build.sbt
«Файл build.sbt — это скрипт сборки приложения. Здесь мы перечисляем зависимости, необходимые для запуска приложения, такие как тестовые и сохраняемые библиотеки.
3.6. Каталог проекта
Все файлы, настраивающие процесс сборки на основе SBT, находятся в каталоге проекта.
3.7. Целевой каталог
Этот каталог содержит все файлы, сгенерированные системой сборки, например, все файлы .class.
Увидев и изучив структуру каталогов для примера Play Framework Hello World, который мы только что скачали, мы можем теперь пройтись по основам фреймворка на примере.
4. Простой пример
В этом разделе мы создадим очень простой пример веб-приложения. Мы будем использовать это приложение, чтобы ознакомиться с основами платформы Play.
Вместо того, чтобы загружать пример проекта и строить из него, давайте рассмотрим другой способ создания приложения Play Framework с помощью команды sbt new.
Давайте откроем командную строку, перейдем к выбранному местоположению и выполним следующую команду:
sbt new playframework/play-java-seed.g8
Для этого нам нужно уже установить sbt, как описано в Разделе 2.
Приведенная выше команда сначала предложит нам имя для проекта. Затем он запросит домен (наоборот, как в соглашении об именах пакетов в Java), который будет использоваться для пакетов. Мы нажимаем Enter, не вводя имя, если хотим сохранить значения по умолчанию, указанные в квадратных скобках.
Приложение, созданное с помощью этой команды, имеет ту же структуру, что и созданное ранее. Таким образом, мы можем приступить к запуску приложения, как делали это ранее:
cd /path/to/folder/
sbt run
Приведенная выше команда после завершения выполнения создаст сервер с номером порта 9000 для предоставления доступа к нашему API, к которому мы можем получить доступ через http: //локальный хост:9000. Мы должны увидеть сообщение «Добро пожаловать в игру» в браузере.
Наш новый API имеет две конечные точки, которые мы теперь можем по очереди опробовать в браузере. Первая, которую мы только что загрузили, — это корневая конечная точка, которая загружает индексную страницу с сообщением «Добро пожаловать в игру!».
Второй, по адресу http://localhost:9000/assets, предназначен для загрузки файлов с сервера путем добавления имени файла к пути. Мы можем протестировать эту конечную точку, получив файл favicon.png, загруженный вместе с приложением, по адресу http://localhost:9000/assets/images/favicon.png.
5. Действия и контроллеры
Метод Java внутри класса контроллера, который обрабатывает параметры запроса и создает результат для отправки клиенту, называется действием.
Контроллер — это класс Java, расширяющий play.mvc.Controller, который логически группирует действия, которые могут быть связаны с результатами, которые они производят для клиента.
Давайте теперь перейдем к app-parent-dir/app/controllers и обратим внимание на HomeController.java.
Действие индекса HomeController возвращает веб-страницу с простым приветственным сообщением:
public Result index() {
return ok(views.html.index.render());
}
Эта веб-страница является шаблоном индекса по умолчанию в пакете представлений:
@main("Welcome to Play") {
<h1>Welcome to Play!</h1>
}
Как показано выше, страница index вызывает основной шаблон. Затем основной шаблон обрабатывает отображение заголовка страницы и тегов тела. Он принимает два аргумента: строку для заголовка страницы и объект Html для вставки в тело страницы.
@(title: String)(content: Html)
<!DOCTYPE html>
<html lang="en">
<head>
@* Here's where we render the page title `String`. *@
<title>@title</title>
<link rel="stylesheet" media="screen" href="@routes.Assets.versioned("stylesheets/main.css")">
<link rel="shortcut icon" type="image/png" href="@routes.Assets.versioned("images/favicon.png")">
</head>
<body>
@* And here's where we render the `Html` object containing
* the page content. *@
@content
<script src="@routes.Assets.versioned("javascripts/main.js")" type="text/javascript"></script>
</body>
</html>
Давайте немного изменим текст в индексном файле:
@main("Welcome to Baeldung") {
<h1>Welcome to Play Framework Tutorial on Baeldung!</h1>
}
При перезагрузке браузера заголовок будет выделен жирным шрифтом:
Welcome to Play Framework Tutorial on Baeldung!
Мы можем полностью избавиться от шаблона, удалив render в методе index() HomeController, чтобы мы могли напрямую возвращать обычный текст или HTML-текст:
public Result index() {
return ok("REST API with Play by Baeldung");
}
После редактирования кода, как показано выше, в браузере будет только текст. Это будет просто текст без HTML или стилей:
REST API with Play by Baeldung
С таким же успехом мы могли бы вывести HTML, заключив текст в теги заголовка \u003ch1\u003e\u003c/h1\u003e, а затем передав текст HTML в Html. применить метод. Не стесняйтесь играть с ним.
Давайте добавим конечную точку /baeldung/html в маршруты:
GET /baeldung/html controllers.HomeController.applyHtml
«
public Result applyHtml() {
return ok(Html.apply("<h1>This text will appear as a heading 1</h1>"));
}
«Теперь давайте создадим контроллер, который обрабатывает запросы на этой конечной точке:
Когда мы посетим http://localhost:9000/baeldung/html, мы увидим приведенный выше текст в формате HTML.
Мы изменили наш ответ, настроив тип ответа. Мы рассмотрим эту функцию более подробно в следующем разделе.
Мы также рассмотрели две другие важные функции Play Framework.
Во-первых, перезагрузка браузера отражает самую последнюю версию нашего кода; это потому, что наши изменения кода компилируются на лету.
Во-вторых, Play предоставляет нам вспомогательные методы для стандартных ответов HTTP в классе play.mvc.Results. Примером может служить метод ok(), который возвращает ответ OK HTTP 200 вместе с телом ответа, которое мы передаем ему в качестве параметра. Мы уже использовали метод отображения текста в браузере.
В классе Results есть дополнительные вспомогательные методы, такие как notFound() и badRequest().
6. Манипулирование результатами
return ok("text to display");
Мы получили выгоду от функции согласования контента Play, даже не осознавая этого. Play автоматически определяет тип содержимого ответа из тела ответа. Вот почему мы смогли вернуть текст в методе ok:
И тогда Play автоматически установит для заголовка Content-Type значение text/plain. Хотя в большинстве случаев это работает, мы можем взять на себя управление и настроить заголовок типа контента.
public Result customContentType() {
return ok("This is some text content").as("text/html");
}
Давайте настроим ответ для действия HomeController.customContentType на text/html:
Этот шаблон подходит для всех типов контента. В зависимости от формата данных, которые мы передаем вспомогательному методу ok, мы можем заменить text/html на text/plain или application/json.
public Result setHeaders() {
return ok("This is some text content")
.as("text/html")
.withHeader("Header-Key", "Some value");
}
Мы можем сделать нечто подобное для set headers:
7. Заключение
В этой статье мы изучили основы Play Framework. Мы также смогли создать базовое веб-приложение Java с помощью Play.