CRUD на Clojure средствами Noir

Давно собирался рассказать немного о Noir – классном веб-фреймворке для Clojure. Наконец, у меня появилась возможность написать большой туториал по применению Noir, что я с удовольствием и сделаю :-)

Есть ли вообще необходимость в самоучителе по Noir? Не очень существенная, если честно. На сайте фреймворка (webnoir.org) более чем приличная документация: раздел для быстрого старта, несколько обучалок по использованию Noir и даже индекс API. Мой туториал, возможно, будет вам полезен, если вы, зная Clojure и разобравшись более-менее с Noir, все еще не очень представляете себе архитектуру своего будущего приложения.

А задуматься над архитектурой придется. Noir очень сильно отличается от всех известных мне фреймворков. При своем минимализме он оставляет выбор конкретных библиотек за пользователем – такая свобода может привести к неверному их использованию. Насколько этот выбор широк можете судить хотя бы по статье с обзором разных компонентов для каждого из уровней веб-стека на clojure.

Давайте посмотрим, на что похоже приложение Noir. Если вы проследовали инструкциям из Getting Started на сайте webnoir.org, то у вас уже установлен leiningen-плагин для Noir. Создадим новый проект командой lein noir new optimalist. У него очень простая структура.

resources – содержит каталог public со статическим контентом (css, javasript, images);

src – каталог с исходниками;

test – тесты;

project.clj – описание проекта и версий подключаемых библиотек.

Исходники содержаться в двух каталогах src/optimalist/views и src/optimalist/models. Никаких вопросов не вызывает? А как насчет src/optimalist/controllers? Такого каталога нету, т. к. самописных контроллеров здесь не предусмотрено. Это, конечно, у многих может вызвать разрыв шаблона: как вообще программировать MVC без C!

Автор Noir Крис Гранжер очень подробно обосновал свое представление архитектуры. Исторически сложилось, что бизнес-логику обычно помещали в контроллер. Но со временем её все больше и больше выносили в отдельные компоненты, контроллер стал совсем тоненьким и, откровенно говоря, ненужным. Функции маршрутизации берет на себя фреймворк, так что в Noir (да и в других современных веб-фреймворках) строгой необходимости в отдельных контроллерах попросту нету. Единственное, что всё еще делает контроллер – это указывает, какую страницу рендерить в ответ на запрос пользователя. Раз уж код контроллера такой маленький, то Крис Гранжер попросту решил перенести функции контроллера на уровень View.

Если сравнивать такой подход с другими фреймворками, то, пожалуй, Крис – один из первых, кто открыто решился заявить о ненужности контроллеров. Например, в практике программирования Ruby on Rails всё еще считается правильным всю бизнес логику вынести на уровень модели, а контроллеры сделать маленькими и легковесными. Это очень упрощает тестирование. Но это половинчатый подход: выбросили бы контроллеры да и дело с концом! Скажем, в JSF2.0 примерно так и обстоят дела. Вся бизнес-логика находится в Java-бинах, вызываются они с уровня View напрямую, минуя слой контроллера. Маршруты привязываются к страницам обычно централизованно в специальном файле конфигурации.

Поскольку каталог models пустой, давайте взглянем повнимательнее на содержимое каталога views.

В файле common.clj создается специальная функция layout. Она задает общий шаблон страницы, заголовки и структуру html-файла.

В файле welcome.clj при помощи defpage задается маршрут «/welcome» и функция, которая сгенерирует ответ на запрос пользователя по этому маршруту. Как видно из кода, функция вернет строку приветствия. Шаблон html-страницы создается при помощи библиотеки Hiccup. Она позволяет писать html-код прямо на языке clojure при помощи родных для clojure структур данных: векторов и мапов.

Hiccup очень удобен тем, что позволяет производить любые манипуляции с шаблоном прямо при помощи Clojure. Заметьте, такой подход вообще не встречается среди мейнстримных фреймворков. Что в ASP.NET, что в J2EE для разметки страницы применяется свой собственный DSL, построенный на базе XHTML. Как, например, сделать повторяющийся фрагмент страницы на JSF2.0, на которой еще есть экшены? Правильно, с применением ломика и какой-то матери. В ASP.NET с этим, вроде, несколько проще, но подход такой же: xml-теги. Ну и скажите мне, как программисту Java, почему я не могу использовать Java для изменения шаблона веб-страницы? Как ни крути, но даже Java... хотя нет, уж лучше этот долбаный XML, чем веб-страницы на Java...

Короче, в Noir используется hiccup, а hiccup позволяет писать html-страницы на clojure в декларативном стиле.

Вручную hiccup-код имеет смысл писать только для страниц очень небольшого размера. Если вам досталась от дизайнера монстрозная страница в десятки килобайт кода – конечно, такое поделие переписывать на hiccup не стоит. В этом вам поможет clj-tagsoup. Просто вызовите его функцию parse с указанием html-страницы и сохраните полученный hiccup-код.

Почти все руководства о веб-фреймворках в виде первого учебного приложения предлагают свой вариант блога. Давайте и мы сделаем свой простой блог при помощи Noir. Переименуем welcome.clj в article_pages.clj (а также namespace) и напишем код первой страницы блога – списка записей. Еще я немного изменил список импортируемых библиотек.

(ns optimalist.views.article_pages
  (:require [optimalist.views.common :as common]
            [noir.response :as resp])
  (:use [noir.core]
        [hiccup.core]))

(defpage articles "/articles" []
         (common/layout
           [:p "List of articles"]))

Обратите внимание, что маршрут «/articles» – именованный. В будущем я смогу получить его при помощи (url-for articles).

Запустите веб-приложение командой lein run и откройте его по ссылке localhost:8080/articles. Разумеется, вы увидите текст «List of articles». Но пока что еще не работает корневой маршрут: localhost:8080/. Давайте добавим для него определение маршрута.

(defpage "/" []
  (resp/redirect (url-for articles)))

Как видите, здесь объявляется неименованный маршрут «/», и вместо ответа на него сервер редиректит на страницу articles.

Следующая проблема: как вывести список каких-либо элементов? Поскольку код шаблона мы пишем на clojure, то воспользуемся функцией for:

(defpage articles "/articles" []
  (let [data [{:id 1, :title "First title", :body "First body"}
              {:id 2, :title "Second title", :body "Second body"}
              {:id 3, :title "Third title", :body "Third body"}]]
         (common/layout
          [:p "List of articles" [:br] [:br]
           (for [item data]
             [:div
              (:title item)
              [:br]
              (:body item)
              [:br][:br]])])))

Пока что все достаточно просто, не так ли? Страница articles покажет нам следующий текст:

List of articles

First title
First body

Second title
Second body

Third title
Third body

Теперь данные нужно перенести в отдельный файл. Создадим в каталоге models файл article_model.clj, добавим туда код:

(ns optimalist.models.article_model)

(def *data*
  (ref
   [{:id "1", :title "First article", :body "Lorem ipsum dolor sit amet."}
   {:id "2", :title "Second article", :body "Lorem ipsum dolor sit amet."}
   {:id "3", :title "Third article", :body "Lorem ipsum dolor sit amet. "}
   {:id "4", :title "Fourth article", :body "Lorem ipsum dolor sit amet."}]))

(defn fetch-list []
  @*data*)

Воспользуемся этой моделью. Чтобы импортировать модель, добавим в секцию require такую строку: [optimalist.models.article_model :as article-model]; а код функции articles перепишем таким образом:

(defpage articles "/articles" []
  (common/layout
   [:p "List of articles" [:br] [:br]
    (for [item (article-model/fetch-list)]
      [:div
       (:title item)
       [:br]
       (:body item)
       [:br][:br]])]))

Вообще такая организация кода всё еще не очень удобная. Что если будет несколько страниц с похожим функционалом? Нам придется выносить hiccup-код в отдельные модули чтобы сделать его reusable. Давайте сделаем это сразу. Создатим файл view/article_templates.clj и вынесем туда генерацию httml.

(ns optimalist.views.article_templates
  (:use [noir.core]
        [hiccup.core]))

(defn show-list [articles-list]
   [:p "List of articles" [:br] [:br]
    (for [item articles-list]
      [:div
       (:title item)
       [:br]
       (:body item)
       [:br][:br]])])

В модуле article_pages.clj необходимо добавить строку [optimalist.views.article_templates :as article-view] в секцию :require. А страница articles тогда будет выглядеть так:

(defpage articles "/articles" []
  (common/layout
   (article-view/show-list (article-model/fetch-list))))

Следующая наша задача – добавить к элементам списка ссылки на действия. Лично я – большой любитель технологии REST, о которой узнал из Ruby on Rails. Наши четыре действия над сущностью create, read, update, delete подразумевают наличие семи маршрутов:

Маршрут	Метод	Описание
/articles	GET	Список записей
/article/:id	GET	Просмотреть одну запись
/article/edit/:id	GET	Показать форму редактирования записи
/article/update/:id	POST	Изменить запись в соответствии с указанными данными
/article/delete/:id	POST	Удалить запись
/article/new	GET	Показать пустую форму для создания записи
/article/create	POST	Создать запись в соответствии с указанными данными

Вообще в REST должны использоваться методы не только GET и POST, а также PUT (для создания новой записи) и DELETE (для удаления). Но то ли браузеры не понимают этих методов, то ли веб сервера, но факт остается фактом: использовать мы можем только GET и POST. В Ruby on Rails для обхода этого ограничения создается скрытое поле. И если указывается метод PUT или DELETE, то на самом деле используется POST с пометкой в скрытом поле, что это все-таки PUT/DELETE.

Разные методы отправки запроса нужно использовать не только для красоты. По сети ползают роботы-индексаторы, которые пытаются перейти по ссылкам на другие страницы. Представьте, например, что на вашем сайте кнопка DELETE сделана при помощи обыкновенной ссылки (запрос методом GET), и робот решит по ней перейти. Робот ведь не знает, что эта ссылка приводит к какому-то разрушительному действию, правда? Вот для этого-то все запросы, как-нибудь изменяющие сущность, должны быть отправлены методом POST.

Итак, первая ссылка, которую я хотел бы добавить к списку сущностей – маршрут /article/:id для просмотра записи.

Вначале в article_pages добавим страницу:

(defpage view-article "/article/:id" {id :id}
  (common/layout
   "View article"))

Она пока ничего не делает, но зато её сразу же можно протестить в браузере по маршруту /article/1. Заметьте, что в определении страницы задан хеш параметров {id :id}. Это деструктуризаця параметров запроса, и делает она именно то, на что похоже: создает локальную переменную id, значение которой будет получено из части маршрута :id.

Теперь добавим ссылку на эту страницу в функции show-list

(defn show-list [articles-list]
   [:p "List of articles" [:br] [:br]
    (for [item articles-list]
      [:div  (:title item) [:br]
       (:body item) [:br]
       [:a {:href (url-for (str "/article/" (:id item)))} "View"]
       [:br][:br]])])

Функция url-for умеет создавать абсолютный URL по заданным параметрам. Параметром может быть как текстовая строка с маршрутом, так и сам именованный маршрут. И хотя предложенное выше решение – вполне работоспособное, но оно все-таки не оптимальное. Что если вы решите изменить URL в странице view-article? Тогда вам придется искать все места, где вы на него ссылаетесь, и править маршруты вручную. Лучше использовать именованый маршрут следующим образом:

(url-for optimalist.views.article_pages/view-article {:id (:id item)})

Здесь optimalist.views.article_pages/view-article – полное имя именованного маршрута. Необходимо писать его целиком, т. к. в файле article_templates.clj ничего не известно о aricle_pages.clj. И импортировать article_pages.clj мы тоже не можем, т. к. там уже есть импорт article_templates.clj, и мы получим циклическую зависимость. Поэтому, все-таки, придется писать целиком.

Второй параметр – хеш значений, которые будут переданы в генератор маршрута. Поскольку наш маршрут выглядит как «/article/:id», то ему нужно передать хеш {:id <значение>}.

Вообще, конечно же, такая запись жутко громоздкая и неудобная. Поэтому в начало файла article_templates.clj, после объявления неймспейса, добавим алиас:

(alias 'article 'optimalist.views.article_pages)

Теперь генерацию ссылки можно переписать таким образом:

(url-for article/view-article {:id (:id item)})

Это уже значительно лучше, но все еще пока не идеально. Элементов типа «ссылка» у нас будет достаточно много, особенно, если много разных сущностей. Но типов ссылок всего несколько: new, view, edit, delete, back. Мы могли бы сделать более абстрактный механизм генерации ссылок, который инкапсулирует в себе всю внутреннюю структуру вектора [:a …], в том числе и надпись на ссылке. Создадим файл views/helpers/widget.clj: 

(ns optimalist.views.helpers.widget
  (:require [noir.core]))

(defmacro view-link [page id]
  `(vec [:a
     {:href (noir.core/url-for ~page {:id ~id})} "View"]))

Теперь его можно подключить в article_templates.clj, добавив строку [optimalist.views.helpers.widget] в секцию :use. А вместо записи [:a {href … } «View»] вставим вызов макроса: (view-link article/view-article (:id item)).

Макрос здесь нужен из-за параметра page – символа, к которому привязан именованный маршрут. Конечно, его можно было бы передавать закавыченным, но это не очень-то красиво.

Сам макрос пока-что не слишком удачный. Что если нам понадобится добавить еще несколько похожих ссылок? Copy-paste – не наш метод, поэтому немного расширим наш язык для данного конкретного случая.

Это очень интересная технология, описанная Полом Грэмом в книге «On Lisp», и называется она «bottom-up programming». Идея заключается в том, что вы не только пишете свое приложение, используя Lisp, но и изменяете Lisp, чтобы легче было писать ваше предложение. Снизу, в язык вводятся новые конструкции, упрощающие реализацию приложения. Сверху, приложение описывается при помощи ваших новых конструкций, что делает код значительно короче. Отсюда и bottom-up programming.

Новые конструкции, которые мы вводим в язык, называются утилитами. Давайте добавим две таких:

(defmacro common-url [page id]
  `(noir.core/url-for ~page {:id ~id}))

(defmacro common-link [url text & params]
  `(vec [:a (merge {:href ~url} ~@params) ~text]))

Первый макрос просто инкапсулирует знание о том, как создавать URL. Теперь нам не надо заботиться о том, чтобы дописывать noir.core к url-for, а также создавать хеш для единственного занчения id.

Второй макрос создает html-ссылку с заданным текстом на указанный URL. Необязательный параметр params – это возможные параметры самой ссылки. Например, если нам потребуется задать обработчик onclick, то мы сможем сделать это через params.

Перепишем текст генерации ссылки с применением двух новых утилит:

(defmacro view-link [page id]
  `(common-link (common-url ~page ~id) "View"))
  
(defmacro edit-link [page id]
  `(common-link (common-url ~page ~id) "Edit"))

 Итак, на данный момент, у нас есть список записей и ссылка на просмотр каждой записи. Давайте теперь реализуем функцию view-article:

(defpage view-article "/article/:id" {id :id}
  (common/layout
   (article-view/show
    (article-model/fetch id))))

Чтобы она заработала, нужно в article_templates добавить функцию show:

(defn show [article]
  [:div
   [:h1 (:title article)]
   [:div (:body article)]
   [:br]
   [:a {:href (url-for article/articles)} "Back"]]) 

В article_model необходимо добавить функцию fetch:

(defn fetch [id]
  (first
   (filter #(= id (:id %)) @*data*)))

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

article_pages.clj

(ns optimalist.views.article_pages
  (:require [optimalist.views.common :as common]
            [noir.response :as resp]
            [optimalist.views.article_templates :as article-view]
            [optimalist.models.article_model :as article-model])
  (:use [noir.core]))

(defpage "/" []
  (resp/redirect (url-for articles)))

(defpage articles "/articles" []
  (common/layout
   (article-view/show-list (article-model/fetch-list))))

(defpage view-article "/article/:id" {id :id}
  (common/layout
   (article-view/show (article-model/fetch id))))

(defpage edit-article "/article/edit/:id" {id :id}
  (let [item (article-model/fetch id)]
    (common/layout
     (article-view/form (url-for update-article {:id id}) "Update" (:title item) (:body item)))))

(defpage update-article [:post "/article/update/:id"] {:keys [id title body]}
  (article-model/update id title body)
  (resp/redirect (url-for view-article {:id id})))

(defpage new-article "/article/new" []
  (common/layout
   (article-view/form (url-for create-article) "Create")))

(defpage create-article [:post "/article/create"] {:keys [title body]}
  (article-model/create title body)
  (resp/redirect (url-for articles)))

(defpage delete-article [:post "/delete/:id"] {id :id}
  (article-model/delete id)
  (resp/redirect (url-for articles)))

article_templates.clj

(ns optimalist.views.article_templates
  (:require [optimalist.views.helpers.widget :as widget])
  (:use [noir.core]
        [hiccup.core]))

(alias 'article 'optimalist.views.article_pages)

(defn show [article]
  [:div
   [:h1 (:title article)]
   [:div (:body article)]
   [:br]
   [:a {:href (url-for article/articles)} "Back"]])

(defn list-item [item]
  (let [id (:id item)]
    [:div [:div (:title item)]
     (:body item)
     [:form {:id (str "form-" id) :method "POST", :action (url-for article/delete-article {:id id})}
      [:div
       (widget/view-link article/view-article id) " | "
       (widget/edit-link article/edit-article id) " | "
       (widget/delete-link id)]]
     [:br][:br]]))

(defn show-list [articles-list]
  [:div
   (for [item articles-list] 
     (list-item item))
   [:a {:href (url-for article/new-article)} "New"]])

(defn form [url button-text & [title body & rest]]
  [:form {:method "POST", :action url}
   [:input {:name "title", :type "text", :value title}]
   [:br]
   [:textarea {:name "body"} body]
   [:br]
   [:input {:type "submit", :value button-text}]
   [:br]
   [:a {:href (url-for article/articles)} "Back"]])