Play! Lift! Srsly?

Сразу о производительности. В минимальной конфигурации xitrum запускается и работает с ограничением по памяти в 64Mb. Расходы по процессорному времени не значительны, т.е. сам фреймворк нагрузку на процессор не дает. Все остальное зависит от вас.

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

Итак, xitrum:

• Типо безопасный (typesafe) во всех отношениях где это возможно
• Полностью асинхронный. Необязательно слать ответ на запрос немедленно, можно запустить сложные вычисления и дать ответ, когда он будет готов. Очень легко реализуются такие штуки как Long polling, chunked response, WebSockets, SockJs, EventStream
• Очень производительный, отдача статики сравнима по производительности с Nginx
• Автоматическая сборка маршрутов (routes) приложения, нет нужды заводить какие-либо xml и прочее
• Простая обработка параметров запроса, сессии и куки
• Пре и пост фильтры
• Встроенная поддержка кэширования ответов (в стиле Rails), поддержка ETag
• Прекрасно подходит для разработки RESTful API, встроенная поддержка документирования на основе Swagger Doc
• I18N на основе GNU gettext с динамической перезагрузки файлов перевода в случае их изменения. Автоматический генератор pot файлов из исходников
• Модульность — xitrum автоматически объединяет маршруты из всех jar зависимостей
• Подключаемый по требованию типо безопасный шаблонизатор Scalate или любой другой по вашему желанию

Xitrum является controller-first фреймворком. Очень легко динамически менять представления контроллера во время выполнения, что является не тривиальным для некоторых Scala/Java фреймворков. На моей памяти это вообще единственный фреймворк из мира Java который позволил без каких либо костылей написать CMS с динамической шаблонизацией, so sad.

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

git clone https://github.com/ngocdaothanh/xitrum-new my-app cd my-app sbt/sbt run 

./script		# скрипты используемые при разворачивании в production ./config		# папка конфигурации (akka, logback, xitrum) ./public		# папка со статикой (css, js, прочее) ./project		# sbt ./src			# src ./src/main/scalate	# папка с шаблонами  ./src/main/scala	# scala код ./src/main/scala/quickstart/Boot.scala  # точка входа в приложение 

Простой контроллер

В xitrum каждый запрос может быть обработан только наследником от Action. Т. е. на каждый самостоятельный маршрут обрабатываемый нашим сервером мы должны объявить отдельный класс контроллер.

import xitrum.Action import xitrum.annotation.GET  @GET("url/to/HelloAction") class HelloAction extends Action {    def execute() {     respondHtml(       <xml:group>         <p>Hello world!</p>       </xml:group>     )   }  } 

Каждый новый запрос поступающий на сервер будет обрабатываться новым экземпляром класса, т. е. хранить состояние в этих классах не имеет смысла. Очень важно понять тот факт, что обработка запросов выполняется асинхронно. Пока вы не вызовете метод respond*(), соединение с клиентом не будет закрыто и клиент будет ждать вашего ответа, возможно вечность. Метод execute выполняется на Netty потоке, поэтому не следует помещать в него длительные операции, например:

@GET("url/to/HelloAction") class HelloAction extends Action {    def execute() {     Thread.sleep(1000)  // ОШИБКА: блокирующая операция в Netty потоке     respond()   }  } 

При такой реализации контроллера ваш сервер вряд ли сможет обслужить более 1 подключения в секунду. Что бы решить эту проблему нужно использовать либо FutureAction, либо ActorAction.

• Action — метод exectue будет выполнен непосредственно в потоке Netty
• FutureAction — метод execute будет выполнен в отдельном потоке (Akka system dispatcher)
• ActorAction — в роли контроллера выступает обычный актор

Маршрутизация

Xitrum поддерживает все виды HTTP запросов с помощью аннотаций GET, POST и прочих. Любой контроллер может обрабатывать не ограниченно количество маршрутов. Можно определить порядок контроллеров с помощью аннотаций First и Last. Контроллер по умолчанию определяется как METHOD(":*")

@GET("url1") @First class A extends Action { ... }  @GET("url1", "url2", "...") @POST("url1", ...) class B extends Action { ... }  @GET(":*") @Last class Default extends Action { ... } 

Для получения ссылки на контроллер в Action предусмотрен метод url, который генерирует GET ссылку с параметрами.

url[HelloAction]("name" -> "caiiiycuk")  // url/to/HelloAction?name=caiiiycuk 

Ссылку на статические ресурсы из директории public или classpath можно получить с помощью методов publicUrl и resourceUrl соответственно. Поддерживаются классические перенаправления вроде forwardTo и redirectTo.

Разбор параметров

Xitrum позволяет прозрачно работать с тремя видами параметров:

• uriParams — параметры после ‘?’ (например: example.com/blah?x=1&y=2)
• bodyParams — параметры переданные в теле POST запроса
• pathParams — параметры закодированные в url (например: example.com/article/:id)

Доступ к параметрам осуществляется очень просто:

param("X")	// считать параметр X как String, бросить исключение если параметра нет params("X")	// считать параметр X как List[String], бросить исключение если параметра нет paramo("X")	// считать параметр X как Option[String] paramso("X")	// считать параметр X как Option[List[String]]  param[Type]("X")	// считать параметр X как [Type], бросить исключение если параметра нет params[Type]("X")	// считать параметр X как List[[Type]], бросить исключение если параметра нет paramo[Type]("X")	// считать параметр X как Option[[Type]] paramso[Type]("X")	// считать параметр X как Option[List[[Type]]] 

pathParams задаются по аналогии с Rails с помощью символа ‘:’ (:id, :article, :etc), дополнительно значения параметров можно ограничить с помощью регулярных выражений заключенных в ‘<>’ (например, :id<[0-9]+>).

@GET("articles/:id<[0-9]+>", "articles/:id<[0-9]+>.:format") class ArticlesShow extends Action {   def execute() {     val id     = param[Int]("id")     val format = paramo("format").getOrElse("json")     ...   } } 

Иногда возникает необходимость считать бинарные данные тела POST запроса, делается это так:

val body = requestContentString		// результат String val bodyMap = requestContentJson[Type]	// считать Json, результат Type val raw = request.getContent		// результат ByteBuf 

Шаблонизация

Сам по себе xitrum не имеет встроенного механизма шаблонизации, без шаблонизатора возможно генерировать следующие типы ответа:

• respondText — ответить строкой «plain/text»
• respondHtml — ответить строкой «text/html»
• respondJson — преобразовать Scala объект в Json строку
• respondBinary — бинарные данные
• respondFile — отправить файл используя zero-copy (send-file)
• Менее важные — respondJs, respondJsonP, respondJsonText, respondJsonPText, respondEventSource

val generator = new MyCsvGenerator  setChunked()  respondText(header, "text/csv")  while (generator.hasNextLine) {   val line = generator.nextLine   respondText(line) }  respondLastChunk() 

Для шаблонизации вы можете использовать Scalate, он подключен в шаблонном проекте. Шаблонизатор поддерживает несколько разных синтаксисов: mustache, scaml, jade и ssp. Я предпочитаю использовать ssp потому что он наиболее близок к html. В шаблонном проекте настроен jade, что бы сменить тип синтаксиса нужно в конфигурации xitrum.conf заменить строчку defaultType = jade на defaultType = ssp.

При использовании Scalate для каждого контроллера можно определить свое представление, по правилам Scalate путь до шаблона должен соответствовать пакету контроллера.

src/main/scala/quickstart/action/SiteIndex.scala  # класс контроллера src/main/scalate/quickstart/action/SiteIndex.ssp  # шаблон контроллера src/main/scalate/quickstart/action/SiteIndex/    # папка для фрагментов  package quickstart.action  import xitrum.annotation.GET  @GET("") class SiteIndex extends DefaultLayout {   def execute() {     respondView()   } } 

Как видите, что бы отобразить шаблон SiteIndex.ssp, достаточно вызвать respondView(). Предусмотрено понятие фрагмента, с помощью него можно менять представление контроллера.

@GET("") class SiteIndex extends DefaultLayout {   def execute() {     respondHtml(renderFragment("some"))  # из папки фрагментов этого контроллера   } } 

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

def execute() {     at("login") = "caiiiycuk"     at("rating") = 5     respondView() } 

Hello ${at("login")} You rating is ${at("rating")} 

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

def random = Random.nextInt  def execute() {     respondView() } 

<%     val myAction = currentAction.asInstanceOf[MyAction]; import myAction._ %>  You random number is ${random} 

Некоторый интерес представляет метод atJson, — он выполняет автоматическое преобразование моделей в Json, это оказывается очень полезным при передаче данных непосредственно в JavaScript.

case class User(login: String, name: String)  ...  def execute() {   at("user") = User("admin", "Admin")   respondView() } 

<script type="text/javascript">   var user = ${atJson("user")};   alert(user.login);   alert(user.name); </script> 

Сессия и куки

Внутри контроллера для доступа к куки нужно использовать переменную requestCookies, а для установки новой куки соответственно responseCookies.

// Чтение requestCookies.get("myCookie") match {   case None         => ...   case Some(string) => ... }  // Установка responseCookies.append(new DefaultCookie("name", "value")) 

Xitrum автоматически обеспечивает сохранение, восстановление и шифрование сессии в куки. Работа с сессией осуществляется через переменную session.

session.clear  // очистить сессию session("userId") = 1  // установить значение session.isDefinedAt("userId")  // проверить существование session("userId")  // считать из сессии 

Фильтры

Обработкой запроса можно дополнительно управлять с помощью фильтров, всего их предусмотрено три: beforeFilter, afterFilter и aroundFilter. beforeFilter выполняется перед всякой обработкой запроса, если он возвращает false, то никакая дальнейшая обработка запроса данным контроллером выполнятся не будет. Напротив afterFilter выполняются последними.

before1 -true-> before2 -true-> +--------------------+ --> after1 --> after2                                 | around1 (1 of 2)   |                                 |   around2 (1 of 2) |                                 |     action         |                                 |   around2 (2 of 2) |                                 | around1 (2 of 2)   |                                 +--------------------+ 

Пример, определение языка интернационализации до обработки запроса.

beforeFilter {   val lango: Option[String] = yourMethodToGetUserPreferenceLanguageInSession()   lango match {     case None       => autosetLanguage("ru", "en")     case Some(lang) => setLanguage(lang)   }   true }  def execute() { ... } 

Кэширование

Итак, обработка запросов упрощенно выполняется следующим образом: (1) request -> (2) before фильтры -> (3) execute метод контроллера -> (4) after фильтры -> (5) response. Xitrum имеет встроенные возможности для кэширования всей цепочки обработки запроса (2 — 3 — 4 — 5) с помощью аннотации CachePageMinute и непосредственно метода execute (3), — аннотация CacheActionMinute. Время жизни кэша указывается в минутах. В кэш попадают только ответы со статусом 200 Ok.

import xitrum.Action import xitrum.annotation.{GET, CacheActionMinute, CachePageMinute}  @GET("articles") @CachePageMinute(1) class ArticlesIndex extends Action {   def execute() { ... } }  @GET("articles/:id") @CacheActionMinute(10) class ArticlesShow extends Action {   def execute() { ... } } 

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

Кроме аннотаций, xitrum предоставляет доступ к объекту Cache. Его можно использовать для кэширования своих данных.

import xitrum.Config.xitrum.cache  // Cache with a prefix val prefix = "articles/" + article.id cache.put(prefix + "/likes", likes) cache.put(prefix + "/comments", comments)  // Later, when something happens and you want to remove all cache related to the article cache.remove(prefix) 

Методы предоставляемые объектом Cache

• put(key, value) — бессрочно поместить пару «ключ, значение» в кэш
• putSecond, putMinute, putHour, putDay(key, value, interval) — значение будет удалено из кэша через указанный промежуток времени
• putIfAbsent, putIfAbsentSecond, putIfAbsentMinute, putIfAbsentHour, putIfAbsentDay — тоже самое только значение в кэше не будет обновленно, если оно уже в нем содержится

RESTful API

Благодаря понятной маршрутизации реализация RESTful API тривиальна. Из коробки поддерживается документирование API с помощью Swagger

import xitrum.{Action, SkipCsrfCheck} import xitrum.annotation.{GET, Swagger}  @Swagger(   Swagger.Note("Dimensions should not be bigger than 2000 x 2000")   Swagger.OptStringQuery("text", "Text to render on the image, default: Placeholder"),   Swagger.Response(200, "PNG image"),   Swagger.Response(400, "Width or height is invalid or too big") ) trait ImageApi extends Action with SkipCsrfCheck {   lazy val text = paramo("text").getOrElse("Placeholder") }  @GET("image/:width/:height") @Swagger(  // <-- Наследуется от ImageApi   Swagger.Summary("Generate rectangle image"),   Swagger.IntPath("width"),   Swagger.IntPath("height") ) class RectImageApi extends Api {   def execute {     val width  = param[Int]("width")     val height = param[Int]("height")     // ...   } }  @GET("image/:width") @Swagger(  // <-- Наследуется от ImageApi   Swagger.Summary("Generate square image"),   Swagger.IntPath("width") ) class SquareImageApi extends Api {   def execute {     val width  = param[Int]("width")     // ...   } } 

Во время выполнения xitrum сгенерирует swagger.json который может быть использован в Swagger UI для удобного просмотра документации.

Важно: для всех POST запросов предусмотрена защита от CSRF атак, поэтому вы должны передавать csrf-token с любым POST запросом, либо, явно отключить эту защиту с помощью наследования от трейта SkipCsrfCheck. Подробнее про использование csrf-token.

def execute() {   respondHtml(t("hello_world")) } 

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

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

• Интеграция с JRebel
• Использование ActorAction
• Postbacks
• WebScoket, SockJS, EventSource
• Deploy

Источники

• Документация
• Гугл группа
• Официальный сайт

git clone https://github.com/ngocdaothanh/xitrum-demos.git cd xitrum-demos sbt/sbt run