«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.