Ivan Grishaev's blog

25.04.2019
Беда с парком

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

Меня зовут Иван, я проживаю рядом с парком имени Дурова, что рядом с цирком. У меня двое детей, мы часто ходим гулять с ними в парк. К сожалению, с парком не все хорошо, и об одной из проблем я хочу рассказать.

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

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

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

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

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

Прикладываю набор фотографий. Обратите внимание на смену времен года. Фотографии охватывают осень, зиму и весну.
16.04.2019
Clojure.spec
Это вторая глава предполагаемой книги по Кложе на русском языке. См. первую главу про веб-разработку.

Содержание
В этой главе мы рассмотрим clojure.spec – библиотеку для проверки данных в Clojure. Это особенная библиотека, поэтому уделим пристальное внимание.

Spec это сокращение от specification, т.е. спецификация, описание. В общих словах, это набор функций и макросов, чтобы схематично описывать структуры данных. Например, из каких ключей состоит словарь и каких типов его значения. Такое описание называют спецификацией, или сокращенно спекой.

Особые функции принимают спеку, данные и проверяют, подходят ли данные под спеку. Если нет, то возвращают отчет: в каком узле данных произошла ошибка и почему.

Spec входит в стандартную поставку Clojure начиная с версии 1.9. Полное имя модуля clojure.spec.alpha. Пусть вас не смущает частичка alpha на конце имени. Она осталась по историческим причинам.

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

Технически spec основана на абстракциях, которые предлагает Clojure. Формально это обычная библиотека. Но абстракции spec оказались настолько мощны, что Clojure переиспользует их в работе. Начиная с 1.10, Clojure анализирует собственный код с помощью spec. Так проекты дополняют друг друга.

Мы начнем описание spec с валидации данных. Но прежде чем браться за техническую часть, разберемся с теорией. Как между собой связаны классы, типы и валидация.

Типы и классы

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

Рассмотрим абстракцию сетевого порта. Это целое число от 0 до 2^16-1. Поскольку целочисленные типы, как правило, представлены степенями двойки, наверняка найдется unsigned int, который охватывает именно этот диапазон. Но нулевой порт считается ошибочным, поэтому правильно отсчитывать порт с единицы. Вероятность, что язык реализует такой целочисленный тип, крайне мала.

Лучше всего проблема видна на диапазоне дат. Единичная дата может быть сколь угодно разумной, но диапазон накладывает ограничение: дата начала строго меньше даты конца. Со стороны бизнеса приходят новые требования: разница в датах не больше недели и в рамках текущего месяца.

В мире ООП знают об этой проблеме и решают ее классами. Типичный Java-программист пишет классы UnixPort и DateRange. Условный com.project.net.UnixPort – это класс с одним конструктором. Он принимает целое число и выполняет проверки на диапазон. Если число отрицательное или выходит за рамки 1 — 2^16, то конструктор выбрасывает исключение. Программист уверен, что создал новый тип. Это неверно – классы и типы не тождественны.

Конструктор такого класса это обычный валидатор, проверка во времени исполнения. Он неявно срабатывает, когда мы пишем new UnixPort(8080). Возникает иллюзия, что это тип, но на самом деле это проверка в рантайме. Ее удобство обусловлено синтаксисом.

В промышленных языках невозможно объявить класс так, чтобы выражение new UnixPort(-42) приводило к ошибке компиляции. Это возможно только сторонними утилитами или плагинами к IDE.

Проверки в конструкторах трудно переиспользовать. Предположим, два разработчика написали классы com.somecompany.util.UnixPort и org.community.net.MyPort. Класс UnixPort проверяет порт на диапазон и выбрасывает исключение. Нам выгодно пользоваться этим классом, поскольку он совмещен с валидацией. Однако сторонняя библиотека принимает порт как экземпляр MyPort, который только оборачивает целочисленный тип. Невозможно вызвать конструктор UnixPort для MyPort.

В примере выше мы вынуждены создать экземпляр UnixPort, чтобы проверить данные. Это стадия валидации. Потом извлечь из класса целое число порта. Это данные. Затем создать экземпляр MyPort и передать в библиотеку.

Из сказанного выше определим хорошие практики валидации. Это независимость от данных и компоновка. Независимость означает, что данные не привязаны намертво к валидации. Нет ничего плохого в том, что порт – это целое число. Пусть библиотека принимает integer, а разработчик сам решит, как проверять такое число. Так у него появится выбор, насколько строгой должна быть проверка.

Компоновка означает, что хорошо иметь несколько простых проверок, из которых легко составить сложные. Бывает, по отдельности реализованы проверки “это” и “то”, и теперь нужны их комбинации “это и то”, “это или то”. В идеале мы не должны тратить более одной-двух строк на столь тривиальные вещи.

Оба тезиса ложатся на функции. Вспомним, что функция это объект с операцией вызова. Договоримся, что для верного значения функция-валидатор вернет не ложное значение (отличное от false и nil), а для ошибочного — ложное. Поскольку функция это объект высшего порядка, другие функции принимают валидаторы как аргументы и возвращают их комбинированные версии.

Основы spec

С багажом этих рассуждений мы подошли к тому, как работает clojure.spec.

Импортируем главный модуль spec в текущее пространство:
```
(require '[clojure.spec.alpha :as s])
```
Синоним s нужен, чтобы избежать конфликтов имен с модулем clojure.core. Модуль spec несет определения s/and, s/or и другие, которые не имеют ничего общего со стандартными and и or. Считается плохой практикой, когда определения одного модуля заменяют другие. Это называется затенением имен, и мы рассмотрим проблему в отдельной главе. Пока что мы будем обращаться к spec через синоним s.

Базовая операция в spec – определить новую спецификацию:
```
(s/def ::string string?)
```
Макрос s/def принимает ключ и предикат. Он создал объект спеки из функции string?. Затем поместил спеку в глобальное хранилище под ключом ::string.

Важно понимать, что ::string – это не спека, а только ее псевдоним. Все макросы spec устроены так, что принимают не объект спеки, а ключ, и сами выводят по нему спеку. Это удобно, потому что ключи глобальны. В любом месте можно сослаться на ::string без нужды что-то импортировать.

Ключ спеки рассматривают как указатель или псевдоним. Легче передать псевдоним, чем реальный объект.

Вторым аргументом мы передали предикат string?. Предикат – это функция, которая возвращает истину или ложь.

Технически возможно получить объект спеки. Функция s/get-spec по ключу спеки возвращает ее Java-объект. Однако, на практике он мало чем полезен.
```
(s/get-spec ::string)

#object[clojure.spec.alpha$spec_impl$reify__2059 0x3e9dde1d ...]
```
Спеки хранятся в глобальном регистре под своими ключами. Макрос s/def не проверяет, была ли уже зарегистрирована такая спека. Если под этим ключом уже была спека, она будет потеряна.

Spec не разрешает использовать ключи без пространства, например, просто :error или :message. Это повышает риск конфликта ключей. Чтобы избавиться от конфликтов, используйте ключи с текущим пространством: ::error, ::message.

Самое простое, что можно сделать с новой спекой – проверить, подходит ли под нее значение. Функция s/valid? принимает ключ спеки, значение и возвращает true или false.
```
(s/valid? ::string 1)
false

(s/valid? ::string "test")
true
```
Заметим, пустая строка тоже будет валидной, однако чаще всего это не имеет смысла. Пустая строка в поле “имя пользователя” или “название проекта” означает ошибку. Объявим спеку, которая в дополнение к строке проверяет, что она не пустая.

Наивный способ сделать это – передать специальный предикат:
```
(s/def ::ne-string
  (fn [val]
    (and (string? val)
         (not (empty? val)))))
```
Быстрая проверка:
```
(s/valid? ::ne-string "test")
true

(s/valid? ::ne-string "")
false
```
Ключ ::ne-string это сокращение от ::non-empty-string. Эта спека встречается так часто, что логично сэкономить на ее упоминании.

Более изящный способ объявить ту же спеку – объединить предикаты через every-pred. Это функция, которая принимает предикаты и возвращает супер-предикат. Он вернет истину только если истинны все переданные предикаты.
```
(s/def ::ne-string
  (every-pred string? not-empty))

(s/valid? ::ne-string "test")
true

(s/valid? ::ne-string "")
false
```
Этот способ хорош, потому что декларативно собирает новую сущность из старых. Но еще лучше компоновать не предикаты, а спеки. Особый макрос s/and объединяет предикаты и объявленные ранее спеки в новую спеку:
```
(s/def ::ne-string
  (s/and ::string not-empty))
```
По такому принципу в Clojure строят сложные спеки. Объявляют примитивы и постепенно строят их усложненные версии.

Во время проверки Spec не перехватывает возможные исключения. Это остается на усмотрение разработчика. Рассмотрим пример – спеку для проверки строки на URL. Проще всего это сделать регулярным выражением:
```
(s/def ::url
  (partial re-matches #"(?i)^http(s?)://.*"))

(s/valid? ::url "test")
false

(s/valid? ::url "http://test.com")
true
```
Но не строковое значение вызовет ошибку:
```
(s/valid? ::url nil)
Execution error (NullPointerException) at java.util.regex.Matcher...
```
Это потому, что nil был передан в функцию re-matches. Функция трактует аргумент как строку, что приводит к NPE.

Считается хорошей практикой писать спеки, которые не выбрасывают исключения. В примере с ::url будет правильно сначала проверить, что значение строка, и только потом передавать ее в регулярное выражение.
```
(s/def ::url
  (s/and
   ::ne-string
   (partial re-matches #"(?i)^http(s?)://.*")))

(s/valid? ::url nil)
false
```
Теперь проверка nil не выбрасывает исключение.

По аналогии напишем проверку возраста пользователя. Это комбинация двух проверок: на число и диапазон.
```
(s/def ::age
  (s/and int? #(<= 0 % 150)))

(s/valid? ::age nil)
false

(s/valid? ::age -1)
false

(s/valid? ::age 42)
true
```
Спеки-коллекции

Выше мы проверяли примитивные типы или скаляры. Это удобно для демонстрации, но редко встречается в практике. Гораздо чаще проверяют не скаляры, а коллекции. Spec предлагает набор макросов, чтобы определить спеки-коллекции из примитивов.

Макрос s/coll-of принимает предикат или ключ и возвращает спеку-коллекцию. Она проверяет, что каждый элемент проходит валидацию. Вот так мы определим список адресов URL:
```
(s/def ::url-list (s/coll-of ::url))
```
Быстрая проверка:
```
(s/valid? ::url-list
          ["http://test.com" "http://ya.ru"])
true

(s/valid? ::url-list
          ["http://test.com" "dunno.com"])
false
```
Макрос s/map-of проверяет ключи и значения словаря. Вспомним поле запроса :params запроса из главы про веб-разработку. Его ключи кейворды, а значения строки.
```
(s/def ::params
  (s/map-of keyword? string?))

(s/valid? ::params {:foo "test"})
true

(s/valid? ::params {"foo" "test"})
false
```
Словари заслуживают отдельного упоминания. Проверка s/map-of достаточно слабая, чтобы покрыть все варианты. Факт того, что все значения строки не несет полезной информации. Гораздо важнее знать, что в словаре именно те ключи, что мы ожидаем. К тому же редко бывает так, что значения словаря одного типа. Наоборот, чаще всего словарь объединяет поля разных типов в рамках одной сущности. Например, имя, возраст и статус пользователя.

Для таких проверок используют макрос s/keys. Он выглядит как список спек. Ключи спек совпадают с ключами словаря. Значения таких ключей проверяются одноименными спеками.

Пусть объект страницы задан словарем с двумя полями. Это будут address, строка URL и description, текстовое описание. Объявим поля-примитивы:
```
(s/def :page/address ::url)
(s/def :page/description ::ne-string)
```
обратите внимание на пространство ключей :page. Адрес и описание относятся к сущности страницы, поэтому логично задать им особое пространство. Одноименные поля могут быть у пользователя или товара. Пространства гарантируют, что спеки :page/address и :user/address не затронут друг друга.

Составим спеку страницы.
```
(s/def ::page
  (s/keys :req-un [:page/address
                   :page/description]))
```
Параметр :req-un содержит вектор спек. Для каждой из них s/keys ищет ключ с таким же именем в словаре и проверяет значение. Рассмотрим, что именно означает :req-un и какие еще параметры принимает s/keys.

Ключ :req-un состоит из двух логических частей: req и un. Это признаки наличия ключа и его типа. Req означает, что перечисленные ключи обязаны быть в словаре. Если хотя бы один ключ отсутствует, спека не проходит проверку. Противоположный по смыслу параметр называется opt. В нем указаны ключи, которых может не быть. Валидация таких ключей случается только если они присутствуют в словаре.

Частичка un означает unqualified, то есть неполные ключи. При проверке un-ключей используются только их имена. Например, если спека :page/address указана в списке -un, то в словаре ищется ключ :address, а не :page/address.

Неполные (краткие) ключи — довольно частое явление в s/keys. В основном мы получаем данные из JSON-документов и баз данных. Такие системы не знают о пространствах имен, поэтому мы игнорируем их. Исключения бывают, когда весь технологический стек фирмы построен на Clojure.

Различают следующие комбинации req, opt и un:
- :req — необходимые полные ключи,
- :req-un — необходимые краткие ключи,
- :opt — опциональные полные ключи,
- :opt-un — опциональные краткие ключи.
В примере со спекой ::page все ключи обязательны и не учитывают пространство.

Приведем пример ошибочных данных. Это может быть невалидный URL, пустое описание, отсутствующее поле. Если каждый из этих словарей подставить в выражение (s/valid? ::params <data>), результат будет false.
```
{:address "clojure.org"
 :description "Clojure Language"}

{:address "https://clojure.org/"
 :description ""}

{:address "https://clojure.org/"}

{:page/address "https://clojure.org/"
 :page/description "Clojure Language"}
```
Обратите внимание на последний случай. Значения полей верны, но ключи содержат пространства. Это потому, что мы поместили спеки адреса и описания под ключом req-un, что значит отбрасывать пространства при поиске в словаре. Чтобы последний пример сработал, измените :req-un на :req в объявлении ::page.
```
(s/def ::page-fq
  (s/keys :req [:page/address
                :page/description]))

(s/valid? ::page-fq
          {:page/address "https://clojure.org/"
           :page/description "Clojure Language"})
```
Примечание: частичка -fq означает fully qualified, т.е. полный, разрешенный.

Комбинированный пример. Предположим, у объекта страницы может быть поле HTTP-статуса, который мы получили при последнем обращении к ней. Если к странице еще не обращались, в поле нечего записать. Вот как выглядит спека в таком случае:
```
(s/def :page/status int?)

(s/def ::page-status
  (s/keys :req-un [:page/address
                   :page/description]
          :opt-un [:page/status]))
```
Словари без статуса и с правильным статусом проходят валидацию:
```
(s/valid? ::page-status
          {:address "https://clojure.org/"
           :description "Clojure Language"})

(s/valid? ::page-status
          {:address "https://clojure.org/"
           :description "Clojure Language"
           :status 200})
```
Заметим, что s/keys различает nil и наличие ключа в словаре. Если статус nil, это значит, что он состоит в словаре. Срабатывает проверка nil на int?, что приводит к ошибке валидации.
```
(s/valid? ::page-status
          {:address "https://clojure.org/"
           :description "Clojure Language"
           :status nil})
false
```
Вывод значений

До сих пор мы рассматривали проверку данных с помощью s/valid?. Эта функция возвращает истину или ложь, что значит данные верны или нет. Но одной проверки недостаточно. Часто бывает так, что данные корректны, но требуется привести их к нужному типу.

Например, мы получили число в виде строки. Валидация показывает, что строка состоит только из цифр и не превышает допустимой длины. Но и после валидации значение остается строкой. Это склоняет нас к ручному парсингу, увеличивает код и вообще неудобно. Хотелось бы, чтобы вывод значений происходил автоматически.

Spec предлагает такие возможности. Это функции s/conformer и s/conform (от анг. conform – подчиняться, приспосабливаться).

S/conformer строит спеку особого типа из функции-конформера. Такая функция принимает исходное значение и возвращает либо новое значение, либо ключ :clojure.spec.alpha/invalid.

S/conform принимает ключ спеки-конформера и данные. Если вывод значений прошел без ошибок, результатом будет новое значение. Если с ошибками, то вернется все тот же ключ invalid.

Рассмотрим пример с выводом числа из строки. Чтобы различать спеку-конформер от валидатора, к ее имени добавляют стрелку, что означает вывод, приведение.
```
(s/def ::->int
  (s/conformer
   (fn [value]
   (try
     (Integer/parseInt value)
     (catch Exception e
       ::s/invalid)))))
```
Такую спеку передают в s/conform вместе с данными:
```
(s/conform ::->int "42")
42

(s/conform ::->int "dunno")
:clojure.spec.alpha/invalid
```
Как и s/valid?, s/conform не перехватывает исключения в процессе вывода. Java устроена так, что вывод данных часто выбрасывает исключения. Хорошей практикой будет перехватывать их на уровне функции-конформера и возвращать ::s/invalid, как в примере выше.

Оба типа спек — валидатор и конформер – можно объединить через s/and. Например, добавить предварительные проверки перед выводом значения. В нашем случае логично убедиться, что значение – строка, чтобы не передать в parseInt значение nil или что-то еще:
```
(s/def ::->int+
  (s/and ::ne-string
       ::->int))

(s/conform ::->int+ nil)
:clojure.spec.alpha/invalid
```
Рассмотрим случай с восстановлением дат из строк. С этой проблемой часто сталкиваются веб-разработчики, когда получают от браузера JSON-документ. Формат JSON не поддерживает даты, поэтому их передают строкой или числом секунд.

Нам понадобится функция разбора такой строки и минимальная обвязка, чтобы подружить ее со спекой. Функция read-instant-date из модуля clojure.instant читает строку в дату. Она очень лояльна к входным данным: например, датой может быть только год.
```
(require '[clojure.instant
         :refer [read-instant-date]])

(read-instant-date "2019")
#inst "2019-01-01T00:00:00.000-00:00"
```
Обернем функцию в спеку:
```
(s/def ::->date
  (s/and
   ::ne-string
   (s/conformer
  (fn [value]
    (try
      (read-instant-date value)
      (catch Exception e
        ::s/invalid))))))
```
Как и в случае с числом, перед разбором значения мы делаем минимальные проверки. Убеждаемся, что это непустая строка, чтобы отсечь nil и другие не имеющие смысла значения.

Строка даты:
```
(s/conform ::->date "2019-12-31")
#inst "2019-12-31T00:00:00.000-00:00"
```
Дата и время:
```
(s/conform ::->date "2019-12-31T23:59:59")
#inst "2019-12-31T23:59:59.000-00:00"
```
Спеки-перечисления

Интересен вариант, когда возможные значения известны заранее. Например, при вызове определенного API клиент передает архитектуру программы – 32 или 64 бита. Ради двух значений не обязательно парсить число. Достаточно оператора выбора или подбора по словарю.

Рассмотрим вариант с перебором. Оператор case пробегает по вариантам и возвращает аналогичные числовые значения. Если ничего не найдено, возвращаем ::s/invalid.
```
(s/def ::->bits
  (s/conformer
   (fn [value]
   (case value
     "32" 32
     "64" 64
     ::s/invalid))))

(s/conform ::->bits "32")
32

(s/conform ::->bits "42")
:clojure.spec.alpha/invalid
```
Вариант со словарем. По заранее определенному словарю ищем результат. Если ключ не найден, возвращаем тег invalid.
```
(def bits-map {"32" 32 "64" 64})

(s/def ::->bits
  (s/conformer
   (fn [value]
     (get bits-map value ::s/invalid))))
```
Вариант выше хорош еще тем, что его опорная точка – словарь соответствий – вынесен в отдельную переменную. При желании его легко дополнить новыми значениями без изменения логики. Или даже вынести в конфигурацию.

Подобным способом восстанавливают логические значения из строк. Нет единого соглашения о том, как передавать истину и ложь в тексте. Это может быть True, TRUE, 1, on, yes для истины и их противоположности: FALSE, no, off… При разборе таких значений важно приводить их к одному регистру. В Clojure FALSE и false – это разные строки, хотя отправитель имел в виду одно и то же.

Сценарий вывода выглядит так:
- убедиться, что значение это строка;
- привести ее к нижнему регистру;
- проверить значение словарем или перебором.
Конформер из реального проекта:
```
(s/def ::->bool
  (s/and
    ::ne-string
    (s/conformer clojure.string/lower-case)
    (s/conformer
      (fn [value]
        (case value
          ("true" "1" "on" "yes") true
          ("false" "0" "off" "no") false
          ::s/invalid)))))
```
Примеры его работы:
```
(s/conform ::->bool "True") ;; true
(s/conform ::->bool "yes")  ;; true
(s/conform ::->bool "off")  ;; false
```
Продвинутые техники

К этому времени мы написали достаточно кода, чтобы увидеть одинаковые участки – паттерны. Перечислим несколько техник, которые ускоряют работу со спекой.

Множества

Когда значения известны заранее, спекой может выступить множество. Вспомним, что множество ведет себя как функция одного аргумента. Если такой аргумент есть в множестве, функция просто вернет его. Если нет, результат будет nil. Предположим, статус сущности может быть "todo", "in_progress" и "done". Тогда спека будет множеством этих значений:
```
(s/def ::status #{"todo" "in_progres" "done"})

(s/valid? ::status "todo")
true
```
Перечисления

Множество не подходит в случаях, когда мы считаем false и nil верными значениями. S/valid? трактует их как неудачную проверку. Если nil или false входят в множество значений, проверять проверять следует функцией contains?.
```
(contains? #{1 :a nil} nil)
true
```
Чтобы свести повторы кода к минимуму, напишем функцию enum. Она принимает значения и возвращает другую функцию-предикат. Этот предикат принимает один аргумент и проверяет, есть ли такой среди исходных значений.
```
(defn enum [& args]
  (let [arg-set (set args)]
    (fn [value]
      (contains? arg-set value))))
```
Внутренняя функция замкнута на переменной arg-set. Это множество, полученное из списка аргументов. Мы создаем его один раз, чтобы не делать это постоянно в теле функции. Теперь регистрировать спеки-перечисления гораздо удобней:
```
(s/def ::status
  (enum "todo" "in_progres" "done"))
```
With-conformer

Спеки-конформеры требуют особого внимания. В них легко допустить ошибку: не перехватить исключение, забыть обернуть функцию в s/conformer. Чтобы свести код к минимуму, воспользуйтесь макросом with-conformer. Он принимает символ для переменной и произвольное тело. Результатом макроса будет спека-конформер.

Ее внутренняя функция принимает параметр, заданный символом. Функция исполняет тело в блоке try-catch. Если исключения не было, результатом будет последнее выражение тела. Если было, то вернется тег invalid.
```
(defmacro with-conformer
  [bind & body]
  `(s/conformer
     (fn [~bind]
       (try
         ~@body
         (catch Exception e#
           ::s/invalid)))))
```
Примеры из реального проекта. Вывод числа:
```
(s/def ::->int
  (s/and
   ::ne-string
   (with-conformer val
     (Integer/parseInt val))))
```
Вывод логического значения:
```
(s/def ::->bool
  (s/and
   ->lower
   (with-conformer val
     (case val
       ("true"  "1" "on"  "yes") true
       ("false" "0" "off" "no" ) false))))
```
, где ->lower это тоже обертка для приведения регистра:
```
(def ->lower
  (s/and
    string?
    (s/conformer clojure.string/lower-case)))
```
в примере выше не обязательно указывать invalid для значения по умолчанию. Вспомним, что case, если не нашел соответствия и не задан вариант по умолчанию, выбрасывает исключение. With-conformer перехватывает его и возвращает invalid.

Логические пути

Результат s/conform не всегда то, что мы ожидаем. Некоторые спеки оборачивают результат в вектор, где первый элемент – часть логического пути. Такой пусть возникает в тех местах, где проверка ветвится.

До сих пор мы объединяли спеки через s/and. Такая супер-спека последовательно проходит дочерние и выполняет проверки. Это удобно, но недостаточно. Бывает, требуется спека-развилка, которая работает по условию. Например, если значение число, то оставить его как есть, а если строка, то попытаться привести к числу. Такие спеки называют условными.

Макрос s/or — одна из условных спек. Он принимает набор других спек и тегов. Макрос применяет значение к спекам до первого положительного случая. Результатом становится пара из нового значения и тега той спеки, что дала положительный результат.

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

Если валидация не прошла, то логический путь получают из отладочной информации. Эту информацию возвращают функции семейства s/explain*. Мы рассмотрим эти функции ниже.

Вот как выглядит спека сетевого порта. Она принимает число или строку, которую пытается преобразовать в число.
```
(s/def ::smart-port
  (s/or :string ::->int :num int?))
```
Теперь s/conform вернет не просто выведенное значение, а пару тег-значение:
```
(s/conform ::smart-port 8080)
[:num 8080]

(s/conform ::smart-port "8080")
[:string 8080]
```
Важно помнить, что если в спеке был условный узел (s/or, s/alt), то структура s/conform отличается от входных данных. Например, на месте скалярного значения появится вектор.

Покажем это на более сложном примере. Пусть порт — одно из полей параметров подключения к базе данных.
```
(s/def :conn/port ::smart-port)

(s/def ::conn
  (s/keys :req-un [:conn/port]))
```
Топология выходного словаря отличается от входных данных:
```
(s/conform ::conn {:port "9090"})
{:port [:string 9090]}
```
Анализ ошибок

Мы уже выяснили, что в случае неудачи s/valid? и s/conform возвращают false и invalid. Этих данных недостаточно, чтобы понять причину ошибки. Представьте, что у вас спека пользователя системы. У пользователя набор адресов, в каждом адресе несколько строк… и проверка вернула false. Поиск ошибки вручную в таком дереве займет день.

Функции семейства s/explain* принимают спеку и данные. Если ошибок не было, результат будет пустым. Если были, мы получим информацию о том, что пошло не так. Разница между функциями в том, как они обрабатывают результат.
- s/explain печатает текст ошибки в стандартный поток (на экран);
- s/explain-str возвращает эту же информацию в виде строки;
- s/explain-data возвращает словарь с данными. Это самый полный отчет об ошибке.
Рассмотрим s/explain и s/explain-str. Результат их работы одинаковый, разница лишь в том, куда приходит текст — в консоль или переменную.

Подготовим простую спеку:
```
(s/def :sample/username ::ne-string)

(s/def ::sample
  (s/keys :req-un [:sample/username]))
```
На корректных данных explain никак не проявляет себя, разве что первый вариант печатает Success!:
```
(s/explain ::sample {:username "some user"})
Success!
nil

(s/explain-data ::sample {:username "some user"})
nil
```
Случай с ошибкой, вместо строки передано число:
```
(s/explain ::sample {:username 42})
```
```
42 - failed: string? in: [:username] at: [:username] spec: ::string
```
Отчет следует читать так: значение 42 не прошло проверку на предикате string?. Путь к значению внутри структуры [:username]. Ключ спеки, на которой произошла ошибка – ::string.

Отчет показывает самые вложенные спеки и предикаты. Вспомним, что ::ne-string это комбинация ::string и not-empty. Ошибка случилась на этапе ::string, что отчет и показывает.

Для пустой строки вывод будет другим. На этот раз проверка оборвется на этапе not-empty. Проверим это:
```
(s/explain ::sample {:username ""})
```
```
"" - failed: not-empty in: [:username] at: [:username] spec: ::ne-string
```
Сообщения такого рода допустимы для разработчиков, например, при проверке конфигурации на старте приложения. Но чем сложнее структура данных, тем менее понятен отчет explain. И уж точно такое сообщение нельзя показывать пользователям, если они ошиблись в данных. В следующем разделе мы рассмотрим эти проблемы.

Понятные сообщения об ошибках

Когда мы проверяем данные, важно не только зафиксировать факт ошибки. Еще важнее доступно объяснить клиенту, что именно неверно в его данных. Под клиентом не обязательно подразумевают человека. Даже если клиент это другая программа, будет правильно снабдить ответ понятным описанием. Скорее всего, клиент запишет результат в лог, и его прочитает человек.

Многие из нас сталкивались с сообщениями вроде “Ошибка 0x00ffff” без каких-либо деталей. Или красной надписью “проверьте данные” над формой в два экрана. Этих глупостей можно было избежать, умей программисты переводить системные сообщения в человеческие.

Очевидно, фраза "" - failed: not-empty in: [:username] не только ничего не скажет пользователю, но и отпугнет его машинной природой. Возникнет ощущение, что в интерфейсе образовалась брешь, и пользователь видит то, чего не должен. Это резко снижает доверие к системе в целом.

Чтобы сформировать понятное сообщение об ошибке, воспользуемся s/explain-data. Эта функция возвращает словарь со всей необходимой информацией. Вот как он выглядит:
```
(s/explain-data ::sample {:username ""})

#:clojure.spec.alpha
{:problems
 ({:path [:username]
   :pred clojure.core/not-empty
   :val ""
   :via [::sample ::ne-string]
   :in [:username]})
 :spec ::sample
 :value {:username ""}}
```
На первый взгляд непонятно, что делать с этой структурой. К сожалению, многие разработчики пасуют перед проблемой и говорят, что spec не подходит для ошибок. На самом деле, это отличная структура данных, нужно только правильно ее обработать.

Вопрос, который задают новички – почему бы не сделать понятные сообщения сразу на уровне библиотеки? Например, назначить спеке дополнительное поле с текстом “введите правильный адрес”? Почему не взять пример с многочисленных фреймворков для Python или JavaScript?

Ответ на этот вопрос не устраивает новичков. Вспомним тезис из начала главы. Spec – это фундаментальная библиотека. Она не предназначена для обработки ввода пользователя. Это набор абстракций и примитивов. То, что мы проверяем спекой поля HTML-формы – всего лишь частный случай. Ниже мы убедимся, что у спеки самые разные области применения. Поэтому структура ошибки тоже фундаментальна.

Во-вторых, трудно создать систему ошибок, которая устроит всех. В каждом проекте свои правила о том, как показывать ошибки. Рассмотрим поле возраста. Где-то пишут “укажите правильный возраст”. Это фиксированное сообщение, которое не меняется. Но в другом проекте ошибку выводят с текущим значением: “999 не подходит под критерии возраста”. Такое сообщение уже не фиксированный текст, а шаблон. Это значит, на одном из этапов срабатывает код, который извлекает ошибочное значение, шаблон, форматирует текст… А теперь добавим локализацию. В зависимости от локали браузера будем формировать сообщения на английском, русском, французском. Это очень, очень сложные сценарии.

Если бы разработчики Spec занялись выводом ошибок по принципу других фреймворков, их фокус был бы смещен с главной цели. И тогда вместо spec мы бы получили валидаторы по типу тех, что пишут десятками для JavaScript. Они скучны, не гибки и без концепции.

Словарь explain-data содержит ключи :spec, :value и :problems (с пространством clojure.spec.alpha). Первые два это спека и значение, которые принимали участие в проверке. Нас интересует поле problems. Это список словарей. Каждый словарь описывает конкретную ошибку валидации. Перечислим его поля и семантику.
- :path – Логический путь валидации. Вектор ключей, где спеки чередуются с тегами-развилками. Условные спеки типа s/or записывают в этот вектор метки дочерних спек.
- :pred – полный символ предиката, например clojure.core/string?.
- :val – конкретное значение, которое не прошло проверку на предикат. Например, один из элементов исходного словаря.
- :via – цепочка спек, по которым успело пройти значение от верхнего уровня к нижнему.
- :in – физический путь к значению. Вектор ключей и индексов, который передают в функцию get-in. Если выполнить (get-in <исходные-данные> <путь>), то получим значение, которое вызвало ошибку.
Видим, что отчет содержит все данные, чтобы собрать понятное сообщение. Из :val возьмем конкретное неверное значение. Спека, на которой прервалась валидация это последний элемента вектора :via.

Составим словарь сообщений, где ключ — спека, а значение — понятный текст или шаблон. Зная спеку, в которой произошла ошибка, получим из словаря текст. Так, последним элементом вектора :via была спека ::ne-string. Логичное сопоставить ей сообщение “Строка не должна быть пустой” или что-то похожее.
```
(def spec-errors
  {::ne-string "Строка не должна быть пустой"})
```
Напишем наивную функцию, которая принимает словарь ошибки (один из элементов ::s/problems) и возвращает понятное сообщение:
```
(defn get-message
  [problem]
  (let [{:keys [via]} problem
        spec (last via)]
    (get spec-errors spec)))

(get-message {:via [::sample ::ne-string]})
"Строка не должна быть пустой"
```
Рассмотрим, как это работает на других полях. Добавим спеку электронной почты и новое поле в ::sample.
```
(s/def ::email
  (s/and
   ::ne-string
   (partial re-matches #"(.+?)@(.+?)\.(.+?)")))

(s/def :sample/email ::email)

(s/def ::sample
  (s/keys :req-un [:sample/username
                   :sample/email]))
```
Спека ::email проверяет строку по наивному шаблону электронного адреса. Регулярное выражение из примера выше читают как <что-угодно>@<что-угодно>.<что-угодно>.

Если передать в email пустую строку, последним элементом via будет ::ne-string. Для экономии места слегка сократим вывод explain-data:
```
(s/explain-data ::sample {:username "test" :email ""})

{:path [:email]
 :pred clojure.core/not-empty
 :val ""
 :via [::sample ::email ::ne-string]
 :in [:email]}
```
Если передать эту ошибку в get-message, она вернет прежнее сообщение о пустой строке. Но если email был непустой строкой, которая не попала под шаблон регулярного выражения, то последним элементом :via будет :sample/email. Полный словарь ошибки выглядит так:
```
{:path [:email]
 :pred
 (clojure.core/partial
  clojure.core/re-matches
  #"(.+?)@(.+?)\.(.+?)")
 :val "test"
 :via [::sample ::email]
 :in [:email]}
```
Чтобы get-message вернул другое сообщение, добавим в словарь ошибок ключ ::email:
```
(def spec-errors
  {::ne-string "Строка не должна быть пустой"
   ::email "Введите правильный почтовый адрес"})
```
Остается наращивать словарь все новыми спеками и сообщениями, пока не закроем все возможные ошибки. Но это линейный подход. Существует несколько способов улучшить поиск сообщений.

Например, что случится, если нужного перевода не окажется в словаре? В этом случае вернем нейтральное “исправьте ошибки в поле”. Заодно зафиксируем факт того, что перевод не был найден. Проще всего это сделать записью в лог.

Нормально, что команды разработки и локализации иногда не согласованы. Команда локализаторов время от времени просматривает этот лог и добавляет переводы.

Рассмотрим, как упростить поиск поля в словаре. Поле email может встречаться в разных спеках: :account/email, :patient/email, :client/email. Линейный подход из примера выше требует, чтобы для каждого такого ключа было сообщение об ошибке. Это склоняет нас к повторам в коде.

Чтобы не засорять словарь переводов, пойдем на хитрость. Пусть функция поиска пытается найти сообщение по полному ключу, а в случае неудачи — по его имени. Тогда достаточно ключа :email, и все емейлы будут сходиться на этот перевод. Если для одного конкретного емейла нужен особый перевод, добавим его полную версию в словарь:
```
(def spec-errors
  {::ne-string "Строка не должна быть пустой"
   :email "Введите правильный почтовый адрес"
   :account/email "Особое сообщение для адреса отправителя"})
```
Объединим вышесказанное в одну функцию. Вот как выглядит поиск в словаре с учетом неполного ключа и ошибки по умолчанию.
```
(def default-message
  "Исправьте ошибки в поле")

(defn get-better-message
  [problem]
  (let [{:keys [via]} problem
        spec (last via)]
    (or
     (get spec-errors spec)
     (get spec-errors
          (-> spec name keyword))
     default-message)))
```
Система, которую мы построили, достаточно проста. Ее легко тестировать и изменять под нужды конкретного проекта. Автор использовал доработанные версии такой системы в реальных проектах. В одном из случаев формы полностью проверялись на стороне клиента до их отправки на сервер. Это возможно, поскольку код на Clojure компилируется в JavaScript. Мощь clojure.spec в полной мере доступна на клиенте.

До сих пор мы использовали фиксированные сообщения. Но легко сделать их шаблонами, куда подставляют текущее значение или имя поля. В этом случае исправления в коде минимальны.

Получим имя поля как последний отличный от цифры элемент вектора :in. Ключ :val хранит текущее ошибочное значение. В тексте сообщения расставим %s для имени поля и значения. Функция (format <шаблон> <поле> <значение>) вернет что-то вроде “Поле email содержит неверное значение test.com”.

За рамками главы остались несколько вопросов. Первый — что делать, если требуется локализация сообщения, то есть вывод на русском или английском в зависимости от состояния? Очевидно, наша структура станет словарем словарей, где на первом уровне будет код локали (ru, en), а на втором — переводы для спек.

Теперь на первом шаге мы получаем по локали словарь переводов, затем переводим как описано выше. С кодом локали тоже можно схитрить, чтобы облегчить поиск. Например, иногда требуется различные написания для локалей en_US и en_GB. Реализуем функцию поиска так, что сперва она ищет по младшей локали (en_US), а затем по старшей (en).

Вопрос откуда приходит локаль остается на усмотрение разработчика. Ее можно хранить в сессии, параметрах адресной строки, базе данных, глобальной переменной, словом — как это удобно в текущем проекте.

Второй вопрос — как связать вывод ошибок с интерфейсом пользователя. Это тоже зависит от конкретного проекта. Хорошей практикой считается отделение модели от ее представления. Это верно и для форм. Удобно, когда форма — это структура данных с набором функций. Тогда все операции над ней будут чистыми функциями, которые легко поддерживать.

Представим форму как дерево, в листьях которого структура виджета. Виджет знает тип поля, текущее значение и ошибку. Специальный react-компонент подписан на этот лист дерева. На каждое его изменения компонент рисует HTML-элемент, например, поле ввода с текущим текстом. Если поле ошибки не nil, то оно выводится над полем.

Функция валидации принимает дерево формы. Она строит дерево значений. Это структура с той же топологией, но вместо листьев-виджетов на их местах значения. С помощью спеки мы проверяем значения (s/valid?) или выводим правильные типы из текста. В случае ошибки мы получаем отчет (s/explain-data). Для каждого элемента из поле problems находим путь, спеку и сообщение об ошибке. Это сообщение добавляем в соответствующий виджет в поле :error. Компонент, который отрисовывает этот виджет, уведомит пользователя об ошибке.

Парсинг

До сих пор мы обсуждали проверку данных и вывод значений. Теперь рассмотрим операцию более высокого уровня — парсинг. Под парсингом понимают разбор данных на части, выделение структуры там, где прежде ее не было.

Читателю наверняка приходилось парсить текст регулярными выражениями. Это особые шаблоны, которые описывают структуру фрагмента. Специальные функции принимают исходный текст и регулярное выражение. Структура результата известна заранее. Например, это список фрагментов, которые совпали с шаблоном.

Простейший пример регулярного выражения — IP-адрес. Это четыре группы, разделенные точками. Каждая группа состоит из числа от 0 до 255.
```
\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}
```
В примере выше мы ставим косую черту перед точкой. В регулярных выражениях точка это служебный символ. Мы экранируем его, чтобы описать именно символ точки.

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

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

Регулярные выражения подводят нас к regex-спекам. Это особый тип спек для разбора данных по шаблону. Разница в том, что и шаблон, и исходные данные это структуры, а не текст.

Предположим, мы читаем из текстового файла список пользователей. Каждый пользователь это кортеж вида <номер, емейл, статус>. Все значения в виде текста. Для каждого пользователя требуется:
- убедиться, что в кортеже именно три элемента;
- привести номер к числу;
- проверить емейл на минимальные критерии;
- привести статус к системному перечислению (одной из констант).
В идеале получить словарь с верными значениями.

Мы уже знакомы с s/conformer. Мы могли бы написать функцию, которая принимает кортеж пользователя и выполняет описанные выше преобразования. Технически это несложно. Но такая функция будет монолитной со слишком большим скоупом. Это плохая практика при работе с clojure.spec.

Для разбиения коллекций подходит s/cat. Эта спека принимает последовательность тегов и спек. На вход s/cat подают коллекцию значений, например список или вектор. Спека накладывает элементы коллекции на спеки. Если они совпали, результатом будет словарь. Ключи этого словаря — теги спек, значения — результат применения спеки к соответствующему значению.

Составим спеку для разбора кортежа. У нас уже есть парсинг чисел и проверка мейла. Опишем вывод статуса и соберем композицию спек:
```
(s/def :user/status
  (s/and
   ->lower
   (with-conformer val
     (case val
       "active" :USER_ACTIVE
       "pending" :USER_PENDING))))

(s/def ::user
  (s/cat :id ::->int
         :email ::email
         :status :user/status))
```
Проверим положительный случай:
```
(s/conform ::user ["1" "test@test.com" "active"])
{:id 1
 :email "test@test.com"
 :status :USER_ACTIVE}
```
Варианты с плохим номером, почтой или не тем статусом не проходят преобразование. Примеры ниже вернут ::s/invalid:
```
(s/conform ::user ["" "test@test.com" "active"])
(s/conform ::user ["1" "@test.com" "active"])
(s/conform ::user ["1" "test@test.com" "unknown"])
```
В примере с пользователем число полей в кортеже фиксировано. На практике так бывает не всегда. Мы все еще сталкиваемся с устаревшими форматами данных. В таких форматах бывают условия вроде “если перед номером строка BLOCKED, то пользователь заблокирован.” Это осложняет задачу, ведь теперь в кортеж состоит или из трех, или четырех элементов. Кроме того, сдвигается семантика полей. Первый элемент теперь не только номер, но и флаг блокировки. Встречаются и более сложные условия.

В императивных языка типа Python и Java такие требования порождают каскад if/else с перезаписью переменных. В Clojure эту проблему решают декларативно. Объявим спеку для флага блокировки:
```
(s/def ::blocked
  (s/and
   ->lower
   (s/conformer
    #(= % "blocked"))))
```
Добавим ее в итоговую s/cat, но укажем, что она встречается ноль или один раз:
```
(s/def ::user
  (s/cat :blocked (s/? ::blocked)
         :id ::->int
         :email ::email
         :status :user/status))
```
Теперь оба типа кортежа попадают под действие спеки. Если пользователь заблокирован, в итоговом словаре будет поле :blocked:
```
(s/conform ::user ["1" "test@test.com" "active"])
{:id 1 :email "test@test.com" :status :USER_ACTIVE}

(s/conform ::user ["Blocked" "1" "test@test.com" "active"])
{:blocked true :id 1 :email "test@test.com" :status :USER_ACTIVE}
```
Представим теперь, что на входе коллекция кортежей. Чтобы не утруждать себя ручной итерацией, объявим спеку-коллекцию:
```
(s/def ::users
  (s/coll-of ::user))

(def user-data
  [["1" "test@test.com" "active"]
   ["Blocked" "2" "joe@doe.com" "pending"]])

[{:id 1 :email "test@test.com" :status :USER_ACTIVE}
 {:blocked true :id 2 :email "joe@doe.com" :status :USER_PENDING}]
```
Отсеять заблокированных пользователей можно функцией filter с предикатом (complement :blocked).

С помощью regex-спек можно парсить не только данные, но и текст. Рассмотрим, как распарсить INI-файл в словарь данных. Напомним, INI — это старый текстовый формат для конфигурации приложений. Он состоит из секций в квадратных скобках и пар поле=значение.
```
# config.ini

[database]
host=localhost
port=5432
user=test

[server]
host=127.0.0.1
port=8080
```
Хотелось бы получить из файла вложенный словарь вида:
```
{:database {:host "localhost"
            :port 5432}
 :server {:host "127.0.0.1"}}
```
Если отбросить пустые и закомментированные строки, то структура файла сводится к грамматике (секция, пара*)*, где звездочка означает сколько угодно раз, в т.ч. ничего.

Сперва прочитаем строки из файла обычной функцией. Эта функция не должна быть частью спеки. Спеки не должны иметь побочных эффектов, они только преобразовывают данные.
```
(require '[clojure.java.io :as io])

(defn get-ini-lines
  [path]
  (with-open [src (io/reader path)]
    (doall (line-seq src))))
```
Теперь составим спеку-парсер. Решим, что такая спека принимает список строк из ini-файла. Требуется выполнить следующие шаги:
- удалить пустые строки и комментарии;
- оставшиеся строки сгруппировать по заголовкам, распарсить пары поле=значение;
- реструктурировать данные во вложенный словарь;
- вывести типы и все проверить.
Выразим это в коде:
```
(s/def ::->ini-config
  (s/and
   (s/conformer clear-ini-lines)
   (s/* (s/cat :title :ini/title :fields (s/* :ini/field)))
   (s/conformer remap-ini-data)
   ::ini-config))
```
Убедитесь, что поняли смысл четвертой строки. Мы считаем, что INI-файл это ноль и более блоков. Каждый блок состоит из заголовка и ноль и более пар ключ-значение.

Реализуем недостающие элементы. Функция clear-ini-lines выбрасывает незначащие строки:
```
(require '[clojure.string :as str])

(defn comment?
  [line]
  (str/starts-with? line "#"))

(defn clear-ini-lines
  [lines]
  (->> lines
       (filter (complement str/blank?))
       (filter (complement comment?))))
```
Объявим спеку :ini/title. Она проверяет, заголовок ли текущая строка или нет. Заголовок определяют квадратные скобки на границах строки. Если условие выполняется, вернем текст заголовка без скобок:
```
(s/def :ini/title
  (s/and
   #(str/starts-with? % "[")
   #(str/ends-with? % "]")
   (with-conformer val
     (subs val 1 (dec (count val))))))
```
Спека :ini/field парсит поле и значение. Просто разбиваем строку по знаку равенства. Цифра 2 означает, что в итоговом списке должно быть не более двух элементов: ключ и значение. Это полезно, когда значение содержит знак равенства (например, base64 строка).
```
(s/def :ini/field
  (with-conformer val
    (let [[key val :as pair] (str/split val #"=" 2)]
      (if (and key val)
        pair
        ::s/invalid))))
```
В примере выше мы убеждаемся, что действительно получили ключ и значение. Так мы исключим строки, в которых нет знака равенства.

На текущий момент запустим черновую, урезанную версию спеки:
```
(s/def ::->ini-config
  (s/and
   (s/conformer clear-ini-lines)
   (s/* (s/cat :title :ini/title :fields (s/* :ini/field)))))

(defn parse
  [path]
  (let [lines (get-ini-lines path)]
    (s/conform ::->ini-config lines)))

(parse "config.ini")
```
Результат:
```
[{:title "database"
  :fields [["host" "localhost"]
           ["port" "5432"]
           ["user" "test"]]}
 {:title "server"
  :fields [["host" "127.0.0.1"]
           ["port" "8080"]]}]
```
Разбор файла прошел удачно. Читатель заметит, что структура словаря отличается от той, что мы предложили вначале. Это неважно. Главное, нам удалось привести набор строк к определенному формату. Не составит труда обработать словарь функцией remap-ini-data:
```
(defn remap-ini-data
  [data-old]
  (reduce
   (fn [data-new entry]
     (let [{:keys [title fields]} entry]
       (assoc data-new title (into {} fields))))
   {}
   data-old))
```
Если передать в эту функцию вектор из предыдущего шага, результат будет тем, что мы ожидали:
```
{"database" {"host" "localhost" "port" "5432" "user" "test"}
 "server" {"host" "127.0.0.1" "port" "8080"}}
```
Напишем спеку, чтобы проверить конфигурацию и вывести типы. Например, чтобы номера портов были числами:
```
(s/def :db/host ::ne-string)
(s/def :db/port ::->int)
(s/def :db/user ::ne-string)

(s/def ::database
  (s/keys :req-un [:db/host
                   :db/port
                   :db/user]))

(s/def :server/host ::ne-string)
(s/def :server/port ::->int)

(s/def ::server
  (s/keys :req-un [:server/host
                   :server/port]))

(s/def ::ini-config
  (s/keys :req-un [::database
                   ::server]))
```
Перед тем, как применять словарь к этой спеке, следует перевести его ключи из строк в кейворды. Вот как выглядит итоговая спека:
```
(require '[clojure.walk :as walk])

(s/def ::->ini-config
  (s/and
   (s/conformer clear-ini-lines)
   (s/* (s/cat :title :ini/title :fields (s/* :ini/field)))
   (s/conformer remap-ini-data)
   (s/conformer walk/keywordize-keys)
   ::ini-config))
```
И результат:
```
(parse "config.ini")

{:database {:host "localhost"
            :port 5432
            :user "test"}
 :server {:host "127.0.0.1"
          :port 8080}}
```
Упражнение: устраните мелкие недоработки в коде выше. Пусть пара "foo=" становится {:foo nil}, а не {:foo ""}. Удалите пустые символы, которые могли остаться по краям ключа и значения. Опробуйте парсинг на больших ini-файлах.

Разбор Clojure-кода (теория)

В завершении темы немного поговорим о том, как парсить код. Мы уже видели, что clojure.spec подходит для разбора структур данных — в основном последовательностей. Вспомним, что код на Clojure состоит из списков. Это приводит к неожиданному решению: оказывается, исходный код на Clojure можно проверить спекой и вернуть ошибку еще до того, как он запущен.

В начале главы мы упоминали, что Clojure и Spec неразрывно связаны. Объясним эту связь на примере макросов. Большинство форм в Clojure представлены макросами. Это особые функции, которые срабатывают на этапе компиляции кода. Макрос принимает код как список символов. Задача макроса, как правило, в том, чтобы перестроить этот список в другой и вернуть его. Компилятор заменяет макрос на список-результат и выполняет его.

Макросы это отдельная веха в изучении Clojure. Мы поговорим о них в другой главе. Пока что заострим внимание на том, как проверить тело макроса.

Каждый макрос это по сути мини-язык с соглашением о том, что и в каком порядке передавать. Иногда один и тот же макрос допускает разные формы записи. По аналогии с языком, требуется разобрать грамматику кода. В случае ошибки доступно объяснить программисту, где он ошибся.

Хорошим примером служит defn, макрос определения функции. Кроме обязательных параметров он принимает несколько второстепенных: строку документации, пре- и пост-проверки. Справедлива форма записи с несколькими телами:
```
(defn my-inc
  [x]
  (+ x 1))

(defn my-inc
  "Increase a number"
  [x]
  {:pre [(int? x)]
   :post [(int? %)]}
  (+ x 1))

(defn my-inc
  ([x]
   (my-inc x 1))
  ([x delta]
   (+ x delta)))
```
Все это одна и та же функция, записанная по-разному. Очевидно, ручной разбор всех вариантов трудоемок. До версии Clojure 1.10 каждый макрос разбирал код по собственным правилам. Это было неорганизованно и неконсистентно. Начиная с 1.10 большинство макросов используют спеку для проверки и вывода ошибок. Так образовался общий подход к проблеме, который легко контролировать.

Разберем устно, как бы мы построили спеку для разбора defn. Очевидно, это список, поэтому на верхнем уровне спеки поместим s/cat. Первый его элемент — символ defn. Второй — символ с именем. После имени следует опциональный параметр строки документации. Затем тело или список тел.

Тело начинается с вектор параметров. После него идет опциональный словарь пре- и пост- проверок. Затем произвольное количество форм, которые составляют тело функции.

Грубая версия:
```
(s/def ::defn
  (s/cat :tag (partial = 'defn)
         :name symbol?
         :docstring string?
         :body (s/+ :defn/body)))
```
, где тело функции это
```
(s/def :defn/body
  (s/cat :args :defn/args
         :prepost (s/? map?)
         :code :defn/code))
```
В свободное время напишите такую спеку. Передайте в нее замороженную версию defn:
```
(s/conform
 ::defn
 '(defn my-inc
    "Increase a number"
    [x]
    {:pre [(int? x)]
     :post [(int? %)]}
    (+ x 1)))
```
Результатом будет что-то отдаленно напоминающее:
```
{:name my-inc
  :docstring "Increase a number"
  :bodies
  [{:params [x]
    :declaration [(+ x 1)]
    ;; other fields}]}
```
Каждый следующий уровень можно расширить вглубь. Выше мы упомянули вектор параметров. Будет здорово разобрать их на обязательные и необязательные. Например, чтобы параметры [x y & other] предстали в виде словаря:
```
{:required [x y] :rest other}
```
Усложните спеку так, чтобы она различала параметры функции. По аналогии выполните разбор словаря пре- и пост- проверок.

Спецификация функций

В последнем разделе мы поговорим о том, как clojure.spec связана с функциями. Мы уже упоминали проблему с проверкой входных данных. Даже если параметры нужного типа, это не гарантирует, что значения верны. Вспомним функцию, которая принимает диапазон дат. Случай, когда ее вызвали с параметрами start=2010.01.01 и end=2009.01.01, не имеет смысла.

Логично описать параметры этой функции спекой:
```
(s/def ::date-range-args
  (s/and
   (s/cat :start inst? :end inst?)
   (fn [{:keys [start end]}]
     (<= (compare start end) 0))))
```
Вторая функция из s/and принимает результат первого s/cat, то есть словарь с ключами :start и :end. Для сравнения дат используют специальную функцию compare, которая возвращает -1, 0 и 1 для случаев меньше, равно и больше. Быстрая проверка:
```
(s/valid? ::date-range-args [#inst "2019" #inst "2020"]) ;; true
(s/valid? ::date-range-args [#inst "2020" #inst "2019"]) ;; false
```
Возникает идея написать декоратор, который принимает целевую функцию и спеку ее параметров. Перед тем, как запускать функцию, он проверит параметры и в случае ошибки выкинет исключение. То же самое можно проделать для результата функции.

Нам не придется писать декоратор, потому что его включили в поставку clojure.spec. Речь идет о функции clojure.spec.test.alpha/instrument. Глагол instrument дословно означает оснастить, оборудовать.

Функция принимает символ другой функции, которую мы хотим оснастить проверкой. Вместе с тем она ищет особую функциональную спеку, зарегистрированную под этим же символом. Когда обе сущности найдены, instrument подменяет функцию на такую же, но с проверками. Это своего рода monkey patch, когда один модуль изменяет поведение другого.

Функциональную спеку объявляют макросом s/fdef. Сначала передают символ функции, которую хотели бы оснастить. Затем отдельные спеки для проверки входящих параметров, результата и их композиции.

В качестве примера напишем функцию и спеку к ней. Пусть это будет функция, которая возвращает разницу между двумя датами в секундах. В отличие от примера выше, мы допускаем случай, когда первая дата болье второй. В этом случае разница в секундах будет отрицательной.
```
(import 'java.util.Date)

(defn date-range-sec
  "Return a difference between two dates in seconds."
  [^Date date1 ^Date date2]
  (quot (- (.getTime date2)
           (.getTime date1))
        1000))
```
Теги ^Date нужны, чтобы компилятор знал тип объектов date1 и date2. В противном случае компилятор выполнит рефлексию, чтобы узнать тип. Это съедает машинное время. Мы поговорим о типах в отдельной главе.

Посчитаем разницу в сутках:
```
(date-range-sec
 #inst "2019-01-01" #inst "2019-01-02")
86400
```
Если поменять даты местами, результат будет отрицательным.

Опишем функциональную спеку. Ее символ будет date-range-sec. Под ключом :args указывают спеку входящих параметров. Поскольку параметры это список, на верхнем уровне почти всегда s/cat. Его задача разбить список на словарь, чтобы спекам ниже было удобно работать с отдельными значениями.

Под :ret указана спека выходного значения. Чаще всего это проверка на число или строку. Например, int?, string? или их nilable-версии: (s/nilable int) и так далее.

Ключ :fn особый. Это спека, которая будет вызвана в контексте входных параметров и результата. Бывает, что результат зависит от входных параметров по определенным правилам. Например, если функция возвращает число из диапазона, то проверка результата на int? недостаточна. Следует убедиться, что результат действительно не выходит за границы аргументов.

Спеке :fn передают словарь с ключами :args и :ret. Значение :args содержит не исходный список параметров, а результат s/conform от :args. Задача спеки — проверить, удовлетворяет ли результат входным аргументам. Если нет, вернуть false для предиката или ::s/invalid для s/conformer.

Напомним, что в ключи :args, :ret, :fn можно передавать объявленные ранее спеки. Это хорошая практика по переиспользованию кода. Например, у вас может быть семейство функций для работы с диапазонами чисел. Будет правильно объявить спеку параметров отдельно и затем ссылаться на нее в каждой из s/fdef.

Опишем спеку для функции date-range-sec. Ограничимся проверкой входных параметров и результата:
```
(s/fdef date-range-sec
  :args (s/cat :start inst? :end inst?)
  :ret int?)
```
Объявление функциональной спеки еще не меняет целевую функцию. Это правильно, потому что спека только декларирует проверки, но не запускает их. Чтобы подменить целевую функцию на ее оснащенную версию, используют instrument из модуля clojure.spec.test.alpha:
```
(require '[clojure.spec.test.alpha
           :refer [instrument]])

(instrument `date-range-sec)
```
Важно, что символ функции должен быть полным, то есть с пространством. Чтобы подставить в символ текущее пространство, перед ним ставят обратную кавычку ```.

Теперь date-range-sec проверяет аргументы и результат. Попробуем передать nil вместо одной из дат. Получим исключение класса clojure.lang.ExceptionInfo.
```
(date-range-sec nil #inst "2019")
```
Его текстовое сообщение и тело уже вам знакомы. Поле message содержит текст, аналогичный s/explain-str:
```
Execution error - invalid arguments to date-range-sec
nil - failed: inst? at: [:start]
```
В поле data структура, аналогичная результату s/explain-data. Чтобы получить эти данные из пойманного сообщения, используют функцию (ex-data exception).

Обратите внимание, что instrument расположен в отдельном модуле с доменом “test”. Это потому, что instrument предназначен для тестирования функций, но не продакшена. Разработчики пишут спеки для наиболее важных функций в отдельном модуле. Во время тестов проект стартует с особыми параметрами, где указаны дополнительные модули, которые нужно загрузить. Один из таких тестовых модулей оснащает функции их спеками. Если при прогоне тестов функция вернула неверный результат, это сразу станет заметно.

Instrument не подходит для боевого режима, потому что значительно снижает быстродействие функции. Замерим десять тысяч прогонов оснащенной функции:
```
(time
 (dotimes [n 10000]
   (date-range-sec #inst "2019" #inst "2020")))
```
```
"Elapsed time: 116.984496 msecs"
```
Получили десятую долю секунды на 10К вызовов. Пока что трудно сказать, быстро это или нет. Посчитаем время для исходной функции. Поскольку date-range-sec уже оснащена, объявим функцию с таким же телом, но другим именем, например date-range-sec-orig. Посчитаем стоимость ее вызова:
```
(time
 (dotimes [n 10000]
   (date-range-sec-orig
     #inst "2019" #inst "2020")))
```
```
"Elapsed time: 1.783962 msecs"
```
Разница в сто раз, или два порядка! Очевидно, что проверка в рантайме существенно замедляет приложение. По этой причине instrument не претендует на то, чтобы его использовали в продакшене. Замедление кода в десятки раз — слишком дорогая цена за детальный вывод ошибок.

Наоборот, во время тестов быстродействие нас не интересует. Мы стремимся покрыть код как можно большим числом проверок, чтобы отловить необычные сценарии.

В примере выше мы проигнорировали ключ :fn. Напомним, это комплексная проверка, в которой одновременно доступны аргументы и результат. Для функции date-range-sec справедливо правило: если первая дата больше второй, то результат отрицательный. Напишите спеку :fn, которая проверяет это условие. Тем самым вы предотвратите случай, когда кто-то решит, что результат должен быть по модулю.

Наличие спеки для функции улучшает документацию у ней. Специальная функция doc из модуля clojure.repl выводит на экран справку о запрошенной функции. С появлением clojure.spec ее поведение изменилось. Теперь, кроме строки документации, она выводит спеку функции.

Вот как выглядит справка для date-range-sec:
```
(require '[clojure.repl :refer [doc]])
```
```
-------------------------
date-range-sec
([date1 date2])
  Return a difference between two dates in seconds.
Spec
  args: (cat :start inst? :end inst?)
  ret: int?
```
Функцию doc активно используют различные IDE и редакторы, чтобы показывать сигнатуру по мере написания кода. Даже если вы не пользуетесь instrument для тестирования, спека помогает поддерживать проект.

Переиспользование спек

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

Хорошим примером служит clojure.jdbc. Это легковесная Clojure-обертка над реляционными базами данных. Почти каждое веб-приложение использует БД для хранения данных. JDBC-подключение описано словарем с ключами :host, :port, :user и так далее.

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

Сlojure.jdbc несет на борту семейство спек для всех своих подсистем. Достаточно импортировать модуль clojure.java.jdbc.spec, чтобы описанные в нем спеки попали в глобальный реестр.

Предположим, ключ :db в конфигурации описывает подключение. Пусть это будет edn-файл:
```
{:db {:dbtype "mysql"
      :host "127.0.0.1"
      :port 3306
      :dbname "project"
      :user "user"
      :password "********"
      :useSSL true}}
```
Прочитаем файл комбинацией read-string и slurp:
```
(read-string (slurp "config.edn"))
```
Спека для этого файла выглядит так:
```
(require '[clojure.java.jdbc.spec :as jdbc])

(s/def ::db ::jdbc/db-spec)

(s/def ::config
  (s/keys :req-un [::db]))
```
Нормально, если спеку поставляют в отдельной библиотеке как дополнение. Так поступили разработчики alia — Clojure-клиента для Кассандры. Базовый пакет qbits.alia несет базовую функциональность, а сторонний cc.qbits/alia-spec содержит спеку кластера и основных функций.

Дополнения к spec (обзор)

Spec входит в поставку Clojure и потому не меняется так радикально, как предлагают некоторые разработчики. Дополнения к spec выпускают отдельными библиотеками. Среди прочих заслуживают внимания два проекта: expound и spec.tools. В этом разделе мы коротко опишем возможности каждого.

Библиотека expound улучшает сообщения об ошибках, делает их понятней для человека. Сигнатура функции expound аналогична s/explain. Она тоже принимает спеку и данные. Сообщение об ошибке выглядит примерно так:
```
(expound/expound string? 1)
```
```
-- Spec failed --------------------
  1
should satisfy
  string?
-------------------------
Detected 1 error
```
Такой отчет все еще выглядит машинным, и мы не можем показать его пользователю. Все же он лучше, чем сырой s/explain. Например, его могут прочитать коллеги из команды Ops, которые не знакомы с Clojure. Особенно хорошо expound подходит для проверки конфигурации на старте приложения. Иногда код приложения не меняется месяцами, но конфигурацию обновляют часто, поэтому отчет о проблемах на старте важен.

Разработчики Metosin собрали ряд улучшений к clojure.spec в проекте spec.tools. В сердце этой библиотеки особый объект Spec. Он оборачивает стандартную спеку и дополняет ее различными методами. С помощью spec.tools удобно формировать JSON-схему или описывать REST-проект по стандарту Swagger. Библиотеку используют в основном как промежуточный слой между REST-фреймворком и спекой.

Мы не будем останавливаться подробно на этих проектах. Они просты в техническом плане и требуют больше кода, чем объяснения. Читателю не составит труда разобраться с ними, когда на то возникнет потребность.

Будущее спеки

На сегодняшний день пакет clojure.spec все еще не избавился от частички “alpha” в названии. Авторы все еще экспериментируют со спекой, пытаются найти лучший способ валидировать данные. Это смущает некоторых разработчиков. Опасаясь, что по окончании эксперимента от spec избавятся, они предпочитают альтернативные библиотеки: schema, bouncer.

Отдельные группы пишут обертки над спекой, чтобы расширить ее возможности. Например, подружить ее с JSON-схемами и популярными инструментами вроде Swagger.

В недавнем докладе Maybe Not Рич Хикки анонсировал вторую версию спеки. Ожидается, что разработчики упростят проверку сложных типов данных. Например, когда значением может быть и строка, и число. Разработка ведется в открытом режиме, но еще рано говорить о конкретных результатах. Обсуждение новой спеки выходит за рамки этой главы.

Итог

Как мы выяснили, clojure.spec — это набор функций и макросов. Ими описывают правила, которым должны удовлетворять данные. Правила это предикаты, т.е. Функции, которые возвращают истину или ложь.

Предикаты гибче и мощнее типов. Если о значении известно, что оно верного типа, это еще не гарантирует его корректность. Значение -1 не может быть Unix-портом. Пользовательские классы вроде UnixPort в конструкторе это не типы, а валидация в рантайме. Она привязана к вызову класса синтаксическим сахаром.

В отличие от классов, предикаты компонуются друг с другом. Легко написать супер-предикат с логикой “все из”, “любой из” и так далее.

Мы рассмотрели основные возможности из пакета clojure.spec. Это далеко не все, о чем еще можно рассказать. В обсуждение не попали различные спеки-комбинаторы вроде s/alt, полезные для тонких проверок. Другая обширная тема по spec — генераторы из модуля clojure.spec.gen.alpha. Мы коснемся их в отдельной главе про тесты.

Код этой главы доступен в одном модуле на Гитхабе.
11.04.2019
Харассмент

У всех на уме сплошной харассмент. А задумывались ли вы, откуда взялся термин? В Википедии наваляли статьи на шести языках, а насчет происхождения — ни слова. Тем интересней узнать про термин подробнее, ведь пришел он из области, которая не имеет ничего общего с отношениями.

В корейском языке слово “харрас” означает раздражать, отвлекать, надоедать. Этот термин активно употребляли игроки в первый Старкрафт. На их жаргоне харрасом называют раннюю атаку на базу противника одним-двумя юнитами.

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

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

Любопытно, что ни в английском, ни в русском языке не нашлось подходящего синонима. Английские комментаторы банально переняли иностранное слово. Jaedong is going to harass his opponent with six lings. What a successful harassment it has been! Потом термин перекочевал в русский как что-то само собой разумеющееся.

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

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

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

Я читал одно время Твиттер Джо Армстронга, создателя Эрланга. Он мило подтрунивает над безумием современного веба, в частности Джаваскриптом. Конечно, нелегко ему, ветерану индустрии, начинавшему с перфокарт, писать на современном JS. Но Джо всегда делает это вежливо, с долей самоиронии. Даже с тридцатью годами опыта он не позволяет себе постов с жалобами.

Ничего подобного я не слышал от Гвидо ван Россума, Кармака, Торвальдса. У последнего случались хейтерские посты, но это совсем другой посыл и тональность.

Когда читаю текст с жалобами, у меня в голове один и тот же вопрос. Он возникает естественно, по-человечески. Если в индустрии все так плохо, зачем ты этим занимаешься?

Я знаю ребят, которые делают хороший фронтенд и при этом не жалуются. Конечно, у них порой горит от этих вебпаков и редуксов, но в целом они бодречком. Проектируют интерфейсы, решают бизнес-задачи, делают мир лучше. Кто-то вообще не ведет блог, только изредка пишет в чат. Спрашивается, чей подход несет пользу?

Порой мы сталкиваемся с проблемами, преодолеть которые трудно морально. Понимаешь, что на незначительный финт потратишь массу усилий. Разработчик не понимает, что именно в этот момент его проверяют на профессионализм. Он может быть крутым кодером, но безвольно согласится на кабальные условия труда. Будет писать по ночам, увеличит кодовую базу и в итоге проиграет по затратам сил. А потом плак-плак в твиттере.

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

Словом, влияет на проблемы, а не только пишет о них.

У типичного кложуриста кумир Рич Хикки. Имя уже набило оскомину, но давайте вспомним, чем знаменит этот человек.

Рич двадцать лет писал промышленный софт на C++ и Java. Не бухгалтерские приложения, а экзит-поллы, распознавание речи, системы массового обслуживания. Очевидно, он собрал столько граблей, сколько мало кому приходилось. В какой-то момент он устал и понял, что не может продолжать.

Если бы он был типичным современным программистом, то наверняка написал бы пост (а то и серию) про выгорание. Выступал бы на конференциях о том, как все плохо. Что софт кривой, а языки ужасны. Думаю, был бы популярен у широкой аудитории айтишников. Попробуй поспорь с таким мэтром — двадцать лет опыта в индустрии.

Вместо того, чтобы снискать дешевую популярность, Рич посвятил себя разработке нового языка. Все собранные грабли, все пережитые ошибки он переработал в простые и чистые идеи. Пусть ненамного, но он протолкнул прогресс вперед. Это необратимо: идеи Кложи плавно расходятся по другим языкам и технологиям. Когда я вынужденно переключаюсь с Кложи на Питон, у меня чувство, что вернулся в прошлое на десять лет назад.

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

Когда я говорю, что восхищаюсь Ричем, я имею в виду именно тот качественный переход, что он совершил в одиночку. А вовсе не за Simple Made Easy и другие нашумевшие доклады. К сожалению, эту мысль трудно передать в разговоре.

Интересный факт: в Википедии нет статьи о Риче Хикки. Поиск по имени перенаправляет на язык. Просто потому, что об этом человеке нечего сказать. Важен не человек, а его вклад. До создания языка Рич вообще не появлялся в медийном пространстве. У него не было прокаченного Гитхаба, громкого Твиттера, скандального ЖЖ. Это был программист-работяга. Он двадцать лет писал код, копил опыт, и, наконец, выстрелил им.

Этим я подвожу вас к следующей мысли. Если ты упорно трудился двадцать лет, прошелся по граблям и чувствуешь, что не можешь так жить дальше, это твой шанс. Настало время для качественного перехода вверх. Кумир как бы намекает.

Переходом может быть что угодно. Новый язык, стандарт. Комитет, организация. Книга, учение. Что-то такое, что зафикcирует опыт, переживет годы. Останется в мозгу людей, прежде чем это сдует с главной Хакер-Ньюз.

Жалобы возникают от завышенных ожиданий. Индустрия сыпет обещаниями со страниц соцсетей. Что скоро нейронная сеть сверстает сайт. Что будут летающие автомобили. Что браузеры подружатся с видеокартами и покажут 60 fps на офисном железе. Но это или не происходит, или не в той мере, что мы ожидали.

Это напоминает биткоины и мошенников всех мастей, что всколыхнулись с мутного дна во время хайпа. Люди так долго врали всем и каждому про крипто-анархию и независимость от государства, что поверили сами себе. Постили пачками заказные статьи, печатали книги, подкупали блоггеров. Продавали недвижимость и вступали в крипту на пике 18-20К. Потом плакали и писали километры текста.

Вы сами в это поверили, вы сами в этом виноваты. Веб-девелопер, ты сам вообразил, что на языке, созданном за 12 дней, свернешь горы и поставишь десктоп в очередь безработных. А теперь стенаешь и причитаешь. С пятнадцатью годами опыта должна же появиться какая-то критичность мышления?

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

Я предпочитаю веб-версию Ютуба нативчику на айпаде. Скорость интерфейса одинакова что в браузере, что в нативе. Все упирается в сеть. Но в браузере табы. Обычно у меня запинены пять ютубных вкладок, которым я возвращаюсь в течение дня. С помощью адблока я вырезаю целые куски интерфейса, которые считаю лишними. Например, похожее видео, комментарии и прочую чушь. Мне не нравится, что когда один раз посмотришь Уральских Пельменей, то правая колонка наполняется Пельменями. Возможно ли такое в нативе? Сомневаюсь.

Я люблю интерфейс Gmail. Каждый день читаю RSS через Feedly. В каждом из этих продуктов есть косяки, но они не завязаны конкретно на браузер. Чаще всего это общие проблемы дизайна. Непонимание того, что нужно пользователю, что он ожидает, по какому сценарию действует. С таким подходом не важно, десктоп это или веб.

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

Конечно, попадаются отчаянные персонажи, которые сортируют на клиенте массив из 100К строк и выводят их реакт-компонентами. Виной тому низкая квалификация программиста и среда компании в целом. Ошибка прошла тестировщиков, руководство и попала в прод. Это не веб такой кривой, это сама жизнь. Дурные решения просачиваются и в медицине, политике, отношениях.

Решение проблемы простое — голосовать вниманием. Достаточно уведомить фирму и не пользоваться их продуктом. Например, я из принципа не читаю Медиум. Зачем страдать, когда можно подписаться на RSS или отправить статью в Киндл. Не использую Слак. Открываю раз в квартал, чтобы задать вопрос в профильной группе и закрыть через пять минут. Не согласился бы работать там, где общение через Слак.

Просто не пользуйся тем, что работает плохо. Создай свое — лучше, удобней, надежней.

Отдельные блоггеры страдают, что веб не идеален: тормозит, глючит, зависит от географического положения пользователя. Я согласен с этим, и у меня встречный вопрос. Почему вы решили, что веб должен быть идеальным? Кто это сказал? У нас что, полно идеальных систем?

Наоборот, любой сервис живет под вниманием человека. Конечно, системы автоматизированы: не админ проверяет место на диске, а скрипт. Но ключевое решение — что именно удалить с диска — принимает человек. Может быть, вы не знали, но в крупных фирмах есть особая должность — LiveOps. Это человек, который тупо мониторит прод. Шарится по системе под обычными аккаунтами, подмечает лаги, необычное поведение. Это не потому что фирме некуда деньги девать, а потому что это нужно.

Без внимания человека ни одна система не проработает дольше недели. Веб не идеален, потому что работает на огромных расстояниях и в сложной топологии. На самых разных языках и железе. В таких системах ошибки нормальны, они часть системы.

Я полагаю, веб и дальше будет развиваться по пути Java-платформы. То есть за счет двух факторов: все больше умов и денег. Мозги и деньги, мозги и деньги на протяжении многих лет — и тогда все получится. Рано или поздно одна из инициативных групп придумает новый протокол, предложит стандарт, условный Гугл даст им денег, и заживем.

Будет как-то так, я считаю. А пока призываю оставить жалобы и поработать. Я искренне считаю жалобы вредными. Они несут негативную повестку без пользы. Если не удалось чего-то достичь, хотя очень хотелось, это все же не повод для расстройства. Надо пережить это и работать усерднее. И сконвертировать опыт во что-то, полезное для всех.
20.03.2019
Введение в веб-разработку на Clojure. Часть I
(This is my attempt to compose a book about Clojure. I decided to start with a web development section to see how far I could go. It’s in Russian because here Clojure isn’t popular and its popularity across developers is low. I hope I’ll translate this in English one day.)

Содержание
В этой главе мы рассмотрим азы разработки на Clojure под веб-платформу. Поговорим о том, как устроен протокол HTTP и как передавать по нему данные. Рассмотрим, какие абстракции использует Clojure над протоколом, чтобы сделать разработку быстрой и удобной.

Каждый год компания Cognitect опрашивает Clojure-разработчиков. Среди прочих вопросов встречается о том, в какой области вы работаете? В 2010 году веб-разработкой занимались 50% опрошенных, то есть каждый второй. К 2018 году эта цифра выросла до 82%. Это уже четыре человека из пяти.

Развитие веба не связано напрямую с Clojure. Похожую динамику показывают ежегодные опросы StackOverflow. Согласно им, все больше разработчиков переходит из смежных областей в веб.

Справедливо утверждать, что если вы найдете работу на Clojure, то скорее всего это будет веб-приложение. Речь необязательно идет о сайте компании. Иногда такие сайты даже бывают статичными, то есть состоят из набора HTML-файлов. Но веб-приложение — это не только текст с картинками. В общем значении это передача и обработка данных по протоколу HTTP.

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

Прежде чем перейти к Clojure, давайте освежим в памяти устройство протокола. Из каких частей он состоит и по каким правилам сервер его обрабатывает. Это важно, потому что языки и фреймворки меняются, а протокол нет.

Основы HTTP

HTTP это протокол, который работает поверх TCP/IP. Протокол в широком смысле — это соглашение о том, в каком порядке передавать данные. Протоколы обычно зафиксированы в официальных документах. Для HTTP такой документ называется RFC 2616. Разработчики браузеров и фреймворков должны сверяться с этим документом во время работы.

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

Различают HTTP-запрос и ответ. Оба состоят из трех частей: первая строка, заголовки и тело.

Первая (или стартовая) строка содержит самую важную информацию о запросе или ответе. Формат строки различается для запроса и ответа. Для запроса это метод, путь и версия, для ответа — статус, сообщение и версия.

Заголовки — это пары ключ-значение. В современных фреймворках они, как правило, выражены словарем. Заголовки содержат дополнительные сведения о запросе или ответе. Например, заголовок Content-Type сообщает, как следует трактовать тело запроса. Был ли это XML- или JSON-документ? Программа проверяет заголовок и читает содержимое должным образом.

После заголовков следует тело. Телом может быть что угодно — текст, данные в виде “поле=значение”, JSON-документ, картинка, фильм, электронное письмо. Стандарт предусматривает смешанный тип, т.н. multipart-encoding. Тело такого запроса раздроблено на ячейки, в каждом из которых живет свое содержимое. Например, текст, картинка, снова текст, двоичный файл.

Несколько примеров HTTP-запросов и ответов. Именно в таком виде они передаются по сети. Это запрос к главной странице Google, поисковой терм — сlojure:
```
GET /search?q=clojure HTTP/1.1
Host: google.com
Accept-Language: en-us
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)
(blank line)
```
Пример POST-запроса с передачей JSON-документа:
```
POST /api/users/ HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)

{
  "username": "John",
  "city": "NY"
}
```
Ответ на такой запрос:
```
HTTP/1.1 200 OK
Date: Tue, 19 Mar 2019 15:57:11 GMT
Server: Nginx
Connection: close
Content-Type: application/json

{
  "code": "CREATED",
  "message": "A user has been created successfully"
}
```
Легко увидеть, как изящно устроен протокол. Данные в нем располагаются по убыванию важности. Прочитав только первую строку запроса, клиент и сервер готовы принять решение о том, что делать дальше.

Рассмотрим сценарий: в запросе указаны метод и путь GET /about, но такой страницы не существует. Сервер может проверить это заранее, например, сверив путь с конфигурацией маршрутов. Когда маршрута нет, сервер вернет ответ со статусом 404. Не придется читать тело запроса, что существенно ускорит работу сервера.

Получив ответ, клиент прочитает статус 404 из первой строки. Такой ответ трактуется как ошибочный. Логика клиента может быть такова, что в случае ошибки читать тело ответа не нужно. Это облегчит работу клиента.

Чтение и разбор содержимого это дорогая операция. Современные фреймворки пытаются исключить случаи, когда чтение происходит зря. Например, по заголовку Content-Type мы определяем, стоит ли читать тело. Наше приложение работает только с JSON, поэтому для значения text/xml вернем ошибку. Аналогично с заголовком Content-Length, где содержится длина тела в байтах. Если значение больше заданного лимита, сервер отклонит запрос до чтения тела.

Центральные параметры запроса это метод и путь. Путь указывает на определенный ресурс на сервере. Иногда сервер трактует путь как файл относительно заданной директории. Например, /images/map.jpg означает вернуть такой файл из директории /var/www/static. Но чаще всего приложение обрабатывает путь согласно внутренней логике. Ответом приложения может быть не только файл, но и js-скрипт, HTML-разметка или JSON-документ.

Метод запроса означает действие, которые мы намерены выполнить над ресурсом. Основные методы это GET, POST, PUT и DELETE. Их семантика в том же порядке — прочитать, создать, обновить, удалить ресурс. Так, запрос POST /users/ означает создать пользователя, а GET /users/1 — чтение пользователя под номером 1.

Главный параметр ответа это статус — целое положительное число. Статусы группируют по старшему разряду. Значения с 200 до 299 (или 2хх) считаются положительными. Они означают, что сервер успешно обработал запрос.

Значения в группе 3хх связаны с перенаправлением на другую страницу. Как правило, в заголовке Location сервер сообщает путь, по которому следует обратиться. Современные браузеры и HTTP-клиенты достаточно умны, чтобы автоматически послать второй запрос по новому адресу. Так, при запросе страницы http://yandex.ru вы получите пустой документ с заголовком Location: https://yandex.ru (безопасное соединение). Но браузер переключит страницу сам.

Статусы из группы 4хх означают ошибку на стороне клиента. Чаще всего это 404 — страница не найдена. На ошибочные данные сервер отвечает 400 — Bad request. Когда нет прав на просмотр документа, клиент получит код 403.

Статусы из группы 5хх сигнализируют об ошибке на стороне сервера или полной его недоступности. Это деление на ноль, недоступность базы данных, недостаток места на диске.

Принято считать, что ответ со статусом вне диапазона 2хх означает ошибку. Большинство HTTP-клиентов запрограммированы на выброс исключения в таких случаях. Строго говоря, это верно только на высоком, абстрактном уровне. С точки зрения протокола ответ 404 Not Found такой же правильный, как и 200 OK.

Дополнительные операции над ресурсом используют другие, более редкие методы. Например, HEAD — получить только краткие сведения об объекте. Сервис Amazon S3 в ответ на HEAD-запрос отдает только статус и заголовки. В них указаны тип файла и размер, контрольная сумма, дата последнего изменения. В данном случае HEAD-запрос предпочтительней GET. Метаданные могут храниться в особом хранилище отдельно от файла. Доступ к такому хранилищу обычно быстрее, чем к файлу на диске.

Подход “метод-ресурс” со временем вырос в то, что сегодня называется REST. Последователи REST выделяют бизнес-сущности и CRUD-операции над ними (Create, Read, Update, Delete). Считается хорошим подход, когда сущность определяется через путь, например /users/1, а операция — методом. Если это создание или изменение сущности, данные читаются из тела, обычно JSON-документа. Мы не будем задерживаться на REST, потому что это всего лишь свод рекомендаций, не идеальный и не единственный.

Отметим, что HTTP не предусматривает строгое соблюдение этих рекомендаций. Разработчик вправе обрабатывать запросы и ответы так, как удобно в данном случае. Например, принимать только POST-запросы с данными в теле. Или только GET с параметрами из строки запроса. Верную стратегию определяют бизнес, инструменты или потребители сервиса.

Возвращаясь к Clojure

Современные фреймворки строят абстракции над HTTP-протоколом. Разработчику не требуется читать данные из сокета и выполнять разбор запроса, ровно как и писать в сокет байты ответа. Эту задачу берет на себя фреймворк и сервер.

Взамен разработчик получает набор классов, чтобы с их помощью выразить бизнес-логику приложения. Типичный веб-проект на Python или Java это комбинация нескольких классов. Как правило, это Application — главная сущность проекта. Класс Router определяет, на какой обработчик переключить входящий запрос — Request. Обработчик — это класс Handler с методами .onGet, .onPost и тд. Ожидается, что он вернет экземпляр класса Response.

По такому принципу устроены все промышленные веб-фреймворки: Django, Rails, Symfony. Названия классов и их композиция различаются, но суть остается прежней. Это приложение, маршрутизатор, обработчик, запрос и ответ. Проблема в том, что каждый фремворк моделирует собственные классы, которые несовместимы между собой в рамках языка.

Рассмотрим язык Python и фреймворки Django и Flask. Оба следуют той же структуре. Так, запрос в Django представлен классом django.http.HttpRequest, а во Flask — flask.Request. Даже беглого взгляда достаточно, чтобы увидеть, насколько они отличаются. У классов разные методы и поля. То, что есть в первом классе, отсутствует во втором. Использовать flask.Request в проекте на Django не представляется возможным.

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

В Clojure другой подход.

Разработчик Джеймс Ривз (James Reeves) известен своим вкладом в экосистему Clojure. Он разработал 60 библиотек для самых разных задач. Нет такого проекта на Clojure, который бы не использовал его наработки.

Заслуга Джеймса в том, что он стандартизировал веб-разработку для Clojure на заре этого языка. Вместо того, чтобы писать фремворк под сиюминутные нужды, он придумал, как сделать удобно всем.

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

Скептики могут заметить, что мысль не нова. Действительно, в том же Django обработчик запроса может быть не классом, а функцией. Разница в том, что отдельный обработчик — это еще не приложение. Ему не хватает маршрутизатора, middleware и других абстракций. Поэтому в мире Django или Flask выразить обработчик функцией — всего лишь приятная возможность фреймворка.

Но Clojure устроена так, что маршрутизатор — это тоже функция, которая принимает запрос, определяет нужный обработчик и возвращает ответ. Middleware это тоже функция, которая принимает функцию-обработчик и возвращают новый обработчик с дополненной логикой. Каждую тяжелую абстракцию (классы Application, Router, Handler) в мире Clojure принято заменять функцией. Это удобно, потому что в отличии от классов функции компонуются.

Вторая идея Джеймса в том, чтобы зафиксировать структуру запроса и ответа. Должны быть документы (не код, а именно документы), где описаны поля этих структур и их семантика. Это напоминает спецификацию протокола HTTP.

Спецификация упрощает разработку и переносимость кода. Два веб-проекта на Clojure обязаны принимать и отдавать одинаковые структуры данных. Разработчик очередного фреймворка должен учитывать спецификацию. Если фреймворк следует стандартам, проще привлечь на свою сторону сообщество.

Описанные выше идеи выражены в проекте Ring. Сегодня это стандарт веб-разработки в Clojure. Репозиторий содержит спецификацию запроса и ответа и базовый код для обработки этих структур. Плюс основные middleware, запуск Jetty-сервера и документация. Удивительно, как мало кода понадобилось проекту, чтобы попасть на компьютер каждому Clojure-разработчику.

Со временем появился термин “Ring-совместимость”. Его придерживаются все современные Clojure-фреймворки. Типичное Ring-приложение запускается на многих платформах: Jetty, Netty, Immutant и др. без изменений в коде.

Библиотека Ring разбита на отдельные части, чтобы установить только необходимое. Перечислим компоненты, что будем использовать ниже:
- ring-core — базовая функциональность: параметры, разбор тела, куки, сессии, и тд;
- ring-jetty-adapter — запуск полноценного веб-сервера из функции-приложения.
Свое первое веб-приложение вы напишете даже без библиотеки. Вот оно:
```
(defn app
  [request]
  (let [{:keys [uri request-method]} request]
    {:status 200
     :headers {"Content-Type" "text/plain"}
     :body (format "You requested %s %s"
                   (name request-method)
                   uri)}))
```
Приложение извлекает путь и метод из запроса и формирует ответ. Его статус положительный — 200. Мы выставили один заголовок с типом документа “простой текст”. Поле :body содержит строку, которую мы построили функцией format.

Поскольку app это функция, вызовем ее с различными запросами:
```
(app {:request-method :get :uri "/index.html"})
{:status 200,
 :headers {"Content-Type" "text/plain"},
 :body "You requested get /index.html"}

(app {:request-method :post :uri "/users"})
{:status 200,
 :headers {"Content-Type" "text/plain"},
 :body "You requested post /users"}
```
Работает. Но пока что это структуры данных, и не ясно, что будет в браузере. Запустим приложение как HTTP-сервер.

Сервер это отдельная сущность. Он связывает структуры данных с сетевым вводом-выводом. Сервер принимает приложение, некоторые дополнительные параметры и запускает в фоне сложный процесс. Он слушает указанный порт и считывает запросы клиента. Из бинарных данных сервер восстанавливает структуру запроса. Затем, в отдельном треде, вызывает функцию-проложение с этим запросом. Результатом будет структура ответа. Сервер преобразует ответ в байтовый поток и записывает в удаленный порт клиента. Этот цикл повторяется для каждого запроса.

Добавим в проект зависимости:
```
[ring/ring-core "1.7.1"]
[ring-jetty-adapter "1.7.1"]
```
Пример запуска сервера:
```
(require '[ring.adapter.jetty :refer [run-jetty]])
(run-jetty app {:port 8080 :join? true})
```
Здесь происходит следующее. Мы импортировали в текущее пространство функцию run-jetty. Она принимает два параметра — функцию-приложение и словарь параметров. Опция join? определяет, будет ли заблокирован текущий тред до конца работы сервера. Если передать false, сервер будет запущен в фоне. Чтобы остановить, нужно сохранить его в переменную и вызвать метод .stop:
```
(def server
  (run-jetty app {:port 8080
                  :join? false}))

;; after a while
(.stop server)
```
Если флаг был true, как в первом случае, то главный поток повиснет до конца работы сервера. Придется либо завершить программу, либо нажать Ctrl-C.

Во время работы сервера откройте браузер по адресу http://127.0.0.1:8080/. Вы увидите строку из примера выше. Укажите произвольный путь, например /hello, /path/to/file.txt. Ответ сервера изменится.

Подробней о запросах и ответах

В предыдущем примере мы написали приложение, которые печатает метод и путь запроса. Это важные, но не единственные его поля. Запрос содержит порт и адрес сервера, строку запроса, тип протокола, заголовки и тело. Уточним, что запрос это неизменяемый словарь, ключи которого keywords (кейворды или ключевые слова, в других языках — теги). Полная спецификация запроса и ответа лежит в репозитории на Гитхабе.

Обратим внимание на поля :headers и :body.

Заголовки это неизменяемый словарь, но его ключи не кейворды, а строки. Такой словарь не работает с destructuring assignment. В примере ниже host получит значение nil:
```
(defn some-handler
  [request]
  (let [{:keys [headers]} request
        {:keys [host]} headers]
    ...))
```
Чтобы извлечь заголовки правильно, используйте get со строкой:
```
(get headers "host")
127.0.0.1
```
Заметим, что имя заголовка всегда в нижнем регистре. С точки зрения HTTP, оба написания Content-Type и content-type верны. Сервер принудительно сводит заголовки к нижнему регистру, чтобы избежать неоднозначности.

Значения заголовков тоже строки. Даже если стандарт HTTP определяет типы некоторых заголовков, Ring не пытается вывести их. Например, заголовок Content-Length передает длину тела в байтах. Современные фреймворки приводят его к числу и помещают в отдельное поле запроса. По умолчанию Ring не делает чего-то подобного, но такой функционал легко добавить.

За ключами-строками стоит проблема. Clojure спроектирована так, что почти всегда ключи словаря это кейворды. Легко забыть о том, что у заголовков они строки. Так появляются ошибки, когда разработчик деструктурирует заголовки и получает nil.

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

Поле запроса :body опционально. Вспомним, что согласно HTTP тела может и не быть. При попытке считать body проверяйте его на nil.

Обратите внимание на тип body. Это не строка, а входящий поток — java.io.InputStream. Поток — это источник данных, который можно прочесть только раз. По умолчанию Ring не читает поток. Это остается на усмотрение разработчика.

Вспомним, что чтение и разбор тела это сложная и небезопасная операция. По заголовкам следует определить тип документа и его длину, прочитать нужное число байт и восстановить документ в структуру (JSON, XML, etc). Результат каждого шага следует проверять по разным критериям. Чтобы получить из Content-Length число, мы должны быть готовы к исключению во время разбора строки. Но результат -42 тоже неверный, потому что число байт в потоке не может быть отрицательным.

Технически возможно послать серверу JSON-документ, но указать Content-Type: text/xml. Тот, кто это сделал, не обязательно злоумышленник. Это может быть ошибка в коде на стороне клиента. Сервер должен быть готов к подобному сценарию.

Легче всего считать тело в строку функцией slurp:
```
(defn handler
  [request]
  (when-let [content
             (some-> request :body slurp)]
    (process-content content))
  {:status 200})
```
Но в современном вебе уже не работают с текстом. Мы работаем с данными — словарями и объектами. Позже рассмотрим, как Ring переводит байты в данные и наоборот.

Структура ответа

Ответ Ring устроен проще. Это неизменяемый словарь, в котором только три поля: :status, :headers и :body.
- :status — целое положительное число. От статуса зависит успех запроса. Мы рассмотрели семантику статуса в начале главы.
- :headers — заголовки ответа. В отличии от заголовков запроса, ключи и значения не обязательно строки. Вариант ниже корректен:
```
{:status 302
 :headers {:content-length 0
           :location "/new/page.html"}}
```
Поле :body, как и в запросе, опционально. В простом случае это строка, но может быть файлом, ресурсом или потоком. Позже мы рассмотрим интересные сценарии и техники, связанные с телом ответа.

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

Мы запустили приложение и наблюдали его из браузера. На любой запрос оно выдает текст с незначительными отличиями. Это проблема. Невозможно поддерживать приложение, в котором все запросы сходятся в одну точку. Правильно будет написать отдельный обработчик для каждой бизнес-задачи. Затем как-то распределить по ним входящие запросы. Это называется маршрутизатор или роутинг.

Вспомним, что в мире Clojure и Ring нет отдельной сущности-роутера. Это будет функция, которая принимает обработчики (хендлеры) и возвращает функцию-приложение. Такая функция принимает запрос и по методу и пути подбирает нужный обработчик. Затем вызывает его с запросом и возвращает ответ.

Сказанное означает, что на верхнем уровне у нас по-прежнему функция. Она принимает словарь запроса и возвращает словарь ответа. Одинаковый принцип на всех уровнях.

Рассмотрим тривиальный случай. Вообразим, что адресу “/” мы бы хотели видеть название сайта, а по “/hello” — приветствие. Все другие адреса возвращают 404 Page not found. Определим обработчики:
```
(defn page-index
  [request]
  {:status 200
   :headers {:content-type "text/plain"}
   :body "Learning Web for Clojure"})

(defn page-hello
  [request]
  {:status 200
   :headers {:content-type "text/plain"}
   :body "Hi there and keep trying!"})

(defn page-404
  [request]
  {:status 404
   :headers {:content-type "text/plain"}
   :body "No such a page."})
```
Готово. Каждый такой обработчик можно запустить как сервер и проверить в браузере. Осталось связать их в единое целое.

Наивный подход

Сделаем самое простое, что приходит в голову. Напишем обработчик, который вручную определяет нужный маршрут. Достаточно проверить путь:
```
(defn app
  [request]
  (let [{:keys [uri]} request]
    (case uri
      "/"      (page-index request)
      "/hello" (page-hello request)
      (page-404 request))))
```
Ответ такой функции зависит от запроса, а именно его пути. Запустите новое приложение в браузере и проверьте результат для разных адресов. Хоть это и наивный перебор, но работает.

Недостатки этой функции очевидны. Мы не учитываем метод запроса. “GET /users” и “POST /users” различны по смыслу. Наша реализация сравнивает пути в лоб без учета их параметров. С точки зрения правильного роутинга запросы “GET /users/1” и “GET /users/99” сходятся в один обработчик, но с разным параметром id.

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

Эти и другие проблемы решены в отдельных Clojure-библиотеках. Мы рассмотрим две из них: Compojure и Bidi. Каждая библиотека решает задачу роутинга по-своему, их подходы ортогональны.

Compojure

Библиотека Compojure предлагает макросы для описания маршрутов. Макросы устроены так, что их набор похож на таблицу правил. Добавим зависимость в проект:
```
[compojure "1.6.1"]
```
Вот как выглядит приложение на Compojure:
```
(require '[compojure.core
           :refer [GET defroutes]])

(defroutes app
  (GET "/"      request (page-index request))
  (GET "/hello" request (page-hello request))
  page-404)
```
Это гораздо лучше той каши, что мы написали вначале.

Разберемся, что получили на выходе. Переменная app — это функция, которая принимает запрос. Обратим внимание, что app объявлена не через def или defn, а особенным макросом. Мы поговорим о макросах в отдельной главе. Пока что скажем, что defroutes делает две вещи: создает функцию-роутер и связывает ее с переменной через defn. Это обвязка, чтобы писать меньше кода.

Макрос принимает набор правил. Правило это форма вида (метод, путь, запрос, выражение). Первые два правила созданы макросом GET. Читать их следует так: если метод запроса GET и путь “/”, то для запроса request верни (page-index request).

Правило компилируется в функцию, которая принимает запрос. В начале работы такая функция проверяет, действительно ли метод и путь запроса совпадают с заданными. Если да, то функция вычислит выражение и вернет его результат, в нашем случае (page-index request).

Если запрос не удовлетворяет критериям, то правило-функция вернет nil. Это значит, что следует попробовать следующее правило, и так далее. Макрос defroutes автоматизирует эти действия. Он оборачивает правила в особый цикл. На каждом шаге макрос берет очередное правило, применяет к нему запрос и оценивает результат. Первое отличное от nil значение станет ответом к текущему запросу.

Что будет, если не подошло ни одно правило? Такое вполне возможно. Тогда приложение вернет nil, и это вызовет ошибку на уровне сервера. Nil не может быть ответом на запрос, потому что не ясен его смысл.

Чтобы избежать nil, в конец правил добавляют еще одно, такое, что вернет правильный ответ независимо от запроса. В нашем случае это функция page-404. Ее результат всегда одинаков. Так мы гарантируем, что даже если запрос не подошел первым двум правилам, последнее сработает обязательно.

Так работает роутинг на Compojure. Мы пишем обработчики запросов в отдельных модулях. Затем импортируем их в модуль с роутингом. С помощью макросов GET, POST и т.д. мы оборачиваем их в правила. Правило возвращает функцию, которая проверяет, что запрос соответствует критериям. Если да, то результатом будет вызов обработчика с запросом.

Продвинутые возможности

Выше мы обозначили проблему: правила “GET /users/1” и “GET /users/99” это один и тот же обработчик, но с параметром. Вот как описать такой путь:
```
(GET "/users/:id" [id :as request] (page-user request))
```
Обратите внимание, в пути двоеточие перед id, а третий параметр заключен в квадратные скобки. Такой синтаксис означает, что часть с двоеточием следует трактовать как параметр. Compojure поместит его в поле запроса params. Обработчик page-user должен извлечь его следующим образом:
```
(defn page-user
  [request]
  (when-let [user-id (-> request :params :id)]
    (let [user (get-user-by-id user-id)
          {:keys [fname lname]} user]
      {:status 200
       :body (format "User %s is %s %s"
                     user-id fname lname)})))
```
В данном случае предположим, что функция get-user-by-id возвращает словарь пользователя по его номеру. Из словаря мы извлекаем имя и фамилию, формируем строку и возвращаем ответ.

Compojure решает проблему вложенных путей. Предположим, приложение показывает и редактирует товары. По адресу “/content/order/1/view” открывается карточка товара для просмотра. Страница “/content/order/1/edit” выводит форму редактирования этого товара. Чтобы сохранить товар, нужно отправить поля формы по тому же пути, но методом POST.

Очевидно, правила пересекаются. Чтобы избежать повторов, используем макрос context:
```
(context "/content/order/:id" [order-id]
  (GET  "/view" request (order-view request))
  (context "/edit" []
    (GET  "/" request (order-form request))
    (POST "/" request (order-save request))))
```
Каждое правило под макросом context наследует параметры запроса. Это значит, обработчики order-view, order-form и order-save получат параметр :order-id из :params.

До сих пор в качестве выражения в правилах мы указывали что-то вроде (some-handler request). Бывает, что ответ по данному пути заранее известен, поэтому нет смысла выносить его в отдельную функцию. Пусть выражение будет готовым ответом. Рассмотрим это на примере healthcheck-обработчика.

Современные приложения часто запускают в контейнерах и облачных сервисах. Чтобы узнать, работает приложение или нет, специальная служба периодически опрашивает его. Стандартный способ сделать это — послать приложению GET-запрос по адресу “/health” и проверить статус. Тело и заголовки ответа не играют роли.

Чтобы не создавать лишний обработчик (page-health request), поместим ответ в тело:
```
(ANY "/health" _ {:status 200 :body "ok"})
```
Однако, можно сделать еще проще. В Compojure предусмотрен случай, когда выражение это строка. Compojure трактует такую строку как тело положительного ответа:
```
(ANY "/health" _ "ok")
```
Роутинг с Bidi

Библиотека Bidi решает проблему роутинга иным способом. Compojure предлагает макросы, чтобы описать правила и сделать по ним перебор. Bidi опирается на данные — списки и словари. Сценарий роутинга в Bidi состоит из нескольких шагов.

На первом этапе объявить особое дерево маршрутов. Это дерево — комбинация векторов и словарей по определенным правилам. В листьях дерева поместить теги — уникальные метки для обозначения листа. Особая функция принимает это дерево и запрос. Функция пытается понять, на какую ветвь дерева ложиться запрос. Если таковая нашлась, результатом будет тег ветки и, возможно, параметры пути. Например, {:route :show-user, :route-params: {:id 1}}.

На втором этапе написать middleware — промежуточный обработчик запроса. Такой middleware принимает запрос, добавляет в него тег и передает дальше по цепочке.

На третьем этапе — объявить обработчик запроса. Но это будет не функция, а мультиметод. Его функция-диспачер возвращает тег. Метод :default возвращает ответ 404, :show-user — страницу пользователя, и так далее.

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

Перепишем на Bidi все то, что сделали на Compojure. Добавьте в проект зависимость:
```
[bidi "2.1.5"]
```
Начнем с дерева маршрутов. Вариант с page-index, page-hello и page-404 будет выглядеть так:
```
(def routes
  ["/" {""      :page-index
        "hello" :page-hello
        true    :not-found}])
```
Проверим, как работает матчинг пути по этому дереву. Функция match-route принимает маршруты и путь и возвращает словарь с тегом:
```
(require '[bidi.bidi :as bidi])

(bidi/match-route routes "/hello")
{:handler :page-hello}

(bidi/match-route routes "/test")
{:handler :not-found}
```
Ответ функции следует объединить со словарем запроса. Чтобы сделать это за один шаг, воспользуемся функцией match-route*. Это альтернативная версия match-route, которая принимает словарь-накопитель.
```
(let [request
      {:request-method :get
       :uri "/test"}]
  (bidi/match-route* routes (:uri request) request))

{:request-method :get
 :uri "/test"
 :handler :not-found}
```
Видим, что match-route* вернула переданный запрос, но добавила в него поле handler. Перенесем код выше в middleware. Это функция, которая принимает обработчик запроса и возвращает его альтернативную версию. Такой обработчик, получив запрос, сперва добавит к нему поле handler и вызовет исходный обработчик с новым запросом.
```
(defn wrap-handler
  [handler]
  (fn [request]
    (let [{:keys [uri]} request
          request* (bidi/match-route*
                    routes uri request)]
      (handler request*))))
```
Мы еще не касались техники middleware, но вынуждены применить ее на данном этапе. Ниже мы рассмотрим во деталях, как устроены middleware и почему так важны.

Проверим wrap-handler на скорую руку. Будем считать, что обработчик запроса это стандартная функция identity. Она всегда возвращает переданный в нее аргумент:
```
((wrap-handler identity)
 {:request-method :get
  :uri "/hello?foo=42"})

{:request-method :get,
 :uri "/hello?foo=42",
 :handler :page-hello}
```
Конечный обработчик запроса будет мультиметодом. Его функция-диспатчер просто :handler.
```
(defmulti multi-handler
  :handler)

(defmethod multi-handler :page-index
  [request]
  {:status 200
   :headers {:content-type "text/plain"}
   :body "Learning Web for Clojure"})

(defmethod multi-handler :page-hello
  [request]
  {:status 200
   :headers {:content-type "text/plain"}
   :body "Learning Web for Clojure"})

(defmethod multi-handler :not-found
  [request]
  {:status 404
   :headers {:content-type "text/plain"}
   :body "No such a page."})
```
Теперь обернем multi-handler в middleware. Это и будет финальное приложение.
```
(def app
  (wrap-handler multi-handler))
```
Запустите веб-сервер и проверьте результат в браузере.

Это был простой вариант роутинга на Bidi. Рассмотрим пример с заказами: просмотр, редактирование и сохранение.

Новое дерево выглядит так:
```
(def routes
  ["/" {["content/order/" :id]
        {"/view" {:get  :page-view}
         "/edit" {:get  :page-form
                  :post :page-save}}}])
```
В этой версии листья уже не теги, а словари. Ключ такого словаря — метод HTTP-запроса, а значение — тег. Запрос “GET /content/order/1/edit” разрешается в тег :page-form, а POST с таким же адресом — в :page-save. При прохождении через wrap-handler запрос получит поле route-params. Для нашего случая это будет словарь {:id "1"}.

Вот так бы мог выглядеть обработчик page-edit. Получаем словарь заказа по его id. Если заказ найден, рисуем HTML страницу с формой редактирования. Если нет, отдаем 404 и сообщение об ошибке.
```
(defmethod multi-handler :page-edit
  [request]
  (let [order-id (get-in request [:route-params :id])
        order (get-order-by-id order-id)]
    (if order
      {:status 200
       :headers {:content-type "text/html"}
       :body (render-order-form order)}
      {:status 404
       :headers {:content-type "text/html"}
       :body "<h1>Order not found</h1>"})))
```
Выбор между Compojure и Bidi

Автору приходилось работать с роутингом обоих типов. По субъективным ощущениям, с Compojure легче начать. У библиотеки достойная документация с примерами. Compojure написал тот же разработчик, что и Ring. Проекты близки и дополняют друг друга.

Дерево маршрутов Bidi сложно для понимания. Оно многословно и не интуитивно. Легко допустить ошибку, перепутать вектор и словарь. С другой стороны, логика на мультиметодах несет преимущества. Код становится линейным, более организованным, приложение легче наращивать.

Если вы начинающий Clojure-разработчик или проект небольшой, выбирайте Compojure. Когда проект сложный со множеством эндпоинтов, рассмотрите переезд на Bidi.

Middleware

Выше мы упоминали про middleware и даже кинули пробный шар — написали wrap-route. В этом разделе мы разберем все вопросы о middleware и лучших практиках по работе с ними. Автор считает этому тему самой важной в главе.

В переводе с английского Middleware значит промежуточный слой, середина. В программировании под middleware понимают код, который обрабатывает данные между посредниками. Обработка данных это приведение типов, добавление новых полей, проверка прав доступа.

Паттерн “декоратор” это частный случай middleware. Декоратор это функция А, которая принимает функцию B и возвращает функцию C. Говорят, что A декорирует B. Результат декорирования это C. В ходе исполнения функция C вызывает B, но с изменениями. Например, корректирует входные или выходные данные B.

Приведем примеры простых декораторов. with-echo добавляет к функции побочные эффекты: печатает аргументы и результат.
```
(defn with-echo
  [func]
  (fn [& args]
    (apply println "The args are" args)
    (let [result (apply func args)]
      (println "The result is" result)
      result)))
```
With-catch оборачивает целевую функцию в форму try/catch. Если во время работы выброшено исключение, результатом будет его объект.
```
(defn with-catch
  [func]
  (fn [& args]
    (try
      (apply func args)
      (catch Throwable e
        e))))
```
Мы уже рассматривали структуру Ring-запроса. Возможно, читатель заметил, что в нем нет полей, с которыми он работал в других языках. Например, классы django.http.HttpRequest и flask.Request в Python содержат поля .params или .values. Это словари, полученные из адресной строки или тела запроса.

Почему в стандарте Ring нет столь важных вещей? Потому что не каждое приложение в них нуждается. Фреймворк предоставляет только базовую информацию о запросе. Остальные данные могут быть получены из исходных.

Представим, что на каждый запрос Ring парсит строку параметров и тело. Это удобно разработчику, но резко снижает производительность сервера. Нет гарантии, что параметры строки пригодятся в запросе. Но сервер потратит время и память на их обработку. Еще хуже с обработкой тела. Вспомним, что это дорогая операция. Возможен сценарий, когда сервер прочитал огромный JSON-документ, но внутри обработчика выяснилось, что у пользователя нет прав на запись. Эту проверку следовало выполнить раньше!

Как мы помним, обработчик запроса в Ring это функция, которая принимает запрос и возвращает ответ. Техника middleware как нельзя лучше подходит, чтобы добавить промежуточную логику. Параметры запроса, сессии, куки, права доступа — все это функция, которая возвращает функцию.

Вам не придется писать все middleware с нуля. Ring уже содержит основные из них. Остается только применить их к приложению. Рассмотрим некоторые middleware и принципы их работы.

Параметры запроса

Стандарт HTTP разрешает передавать данные в адресной строке. Это пары вида “name=John&city=NY” после знака вопроса. Удобно, когда параметры доступны в виде словаря. В нашем случае это была бы структура {:name "John" :city "NY"}.

Аналогично с параметрами из тела запроса. Их передают в теле по разным причинам. В основном это ограничение на длину и проблемы безопасности. Длина адресной строки ограничена 2048 байтами, в то время как на тело запроса ограничений нет. Пароли и адреса почты небезопасно передавать в адресной строке, потому что они остаются в логах и истории браузера.

Функция wrap-params из модуля ring.middleware.params меняет функцию-обработчик следующим образом. Переданный в нее запрос дополняется тремя полями:
- :query-params — словарь параметров адресной строки;
- :form-params — словарь данных из тела запроса;
- :params — их комбинированная версия.
Пусть app — ваше веб-приложение. Чтобы получить его обернутую версию, достаточно вызвать wrap-params c app. Результат будет финальным приложением. На жаргоне разработчиков это называется “врапнуть” (анг. wrap — обернуть).
```
(require '[ring.middleware.params
           :refer [wrap-params]])

(def final-app
  (wrap-params app))
```
Чтобы не запутаться в именах, придерживайтесь правил. Не обернутое приложение называйте app-naked или app-raw (голое, сырое), а финальное просто app.

Доработайте веб-приложение из примера выше так, чтобы оно учитывало параметры строки. Например, чтобы имя того, кого приветствовать, можно было задать параметром who: /hello?who=John.

Подсказка: добраться до параметра who можно так:
```
(defn page-hello
  [request]
  (let [who (get-in request [:params "who"])]
    ...))
```
или так:
```
(defn page-hello
  [request]
  (let [who (-> request :params (get "who"))]
    ...))
```
Обратите внимание, что ключи :params это строки. Это нормально, но Clojure всячески поощряет нас, когда ключи словаря кейворды. Исправим это. В поставке Ring есть особое middleware, которое приводит поле :params к удобному виду. Это wrap-keyword-params из модуля ring.middleware.keyword-params:
```
(require '[ring.middleware.keyword-params
           :refer [wrap-keyword-params]])

(def app
  (wrap-keyword-params (wrap-params app-naked)))
```
Мы подошли к новой проблеме: когда врапперов много, от них возникает шум. Типичное приложение включает десять-пятнадцать middleware:
```
(def app
  (wrap-something-else
    (wrap-current-user
      (wrap-session
        (wrap-keyword-params
          (wrap-params app-naked))))))
```
Это кашу невозможно поддерживать. Представьте, что требуется добавить еще один враппер где-то в середине. Это каскадно сдвинет элементы ниже. Чтобы победить сложность, сделаем структуру линейной. Применим стрелочный оператор:
```
(def app
  (-> app-naked
      wrap-params
      wrap-keyword-params
      wrap-session
      wrap-current-user
      wrap-something-else))
```
Такая форма напоминает обычный список, поэтому ее легко поддерживать.

Запись в стрелочном виде имеет особенность. Не заглядывая в следующее предложение, догадайтесь, в каком порядке будут выполнены middleware? Правильный ответ: снизу вверх для запроса и сверху вниз для ответа. Это может показаться странным, но становится очевидным при мысленном разборе.

Сперва запрос зайдет в wrap-something-else. Код внутри него вызовет обработчик, который получен из wrap-current-user. Обработчик внутри него – результат wrap-session, и так далее. Вершиной подъема станет app-naked. Структура ответа начнет опускаться по стеку вниз. Сначала он пройдет через wrap-params и wrap-keyword-params. Эти два middleware не изменяют ответ и просто возвращают его. Wrap-session и wrap-current-user, возможно, допишут в него новые заголовки. Последним сработает wrap-something-else. Цикл запроса и ответа пройден.

Цепочку middleware следует рассматривать как восхождение в гору и спуск с нее. Другой аналогией может быть пузырек, который всплывает и опускается (не имеет отношения к сортировке пузырьком).

По тому же принципу устроены middleware в Django, промышленном Python-фреймворке. Хоть в Django их роль играют не функции, а классы, их порядок обхода такой же.

Порядок middleware порой критичен. Некоторые из них опираются на данные, которые подготовили предыдущие middleware. Рассмотрим уже знакомые wrap-params и wrap-keyword-params. Последний отыскивает в запросе поле params и меняет тип ключей. Подразумевается, что params был подготовлен wrap-keyword-params. Поэтому wrap-keyword-params ставят строго после wrap-params.

Посмотрим на форму (def app...) выше. В нее закралась ошибка. Запрос поднимается снизу вверх, поэтому wrap-keyword-params сработает раньше. Он попытается найти поле params в запросе, но безуспешно. Следом сработает wrap-params. Он заполнит это поле словарем из адресной строки. В результате params будет словарем с ключами-строками. В следует поменять wrap-params и wrap-keyword-params местами.

Неверный порядок middleware стоит часов отладки. Но есть трюк. Если два и более middleware идут в строгой последовательности, можно “схлопнуть” их в одно целое. Стандартная функция comp принимает произвольное число функций и возвращает супер-функцию, которая последовательно применяет их к аргументу. Определим умный враппер параметров:
```
(def wrap-params+
  (comp wrap-keyword-params wrap-params))
```
Плюс на конце означает, что это улучшенная версия обычного wrap-params. Теперь заменим в стеке wrap-params и wrap-keyword-params на wrap-params+. Цепочка middleware станет короче, а логика параметров соберется в отдельном месте.

Перечислим другие полезные middleware. Мы не будем останавливаться на детальном описании каждого. Это скорее индекс, к которому можно обратиться в случае надобности.

Cookie

В стандарте HTTP куки — это маленькие кусочки информации. Между сервером и браузером особое соглашение о том, как хранить и передавать их. Если сервер выставил куки, браузер запоминает их для этого сайта. В следующий раз браузер отправит куки на сервер автоматически. Так продолжается до тех пор, пока сервер не удалит куки или истечет их срок жизни.

Простейший случай, когда нужны куки — определить, был ли уже пользователь на сайте. При первом визите приложение ищет в запросе куки с именем visited. Если значение не установлено, сервер выставляет заголовок вроде:
```
Set-Cookie: visited=true;
```
В последующих запросах браузер отправит это значение на сервер самостоятельно. Приложение проверяет: если visited true, значит пользователь уже был на сайте. Такие проверки влияют на показ рекламы, всплывающие окна, попапы с обновлениями.

Технически куки — это один длинный заголовок, где значения и атрибуты разделены специальными точками с запятой. Middleware wrap-cookie значительно облегчает работу с куки. Во время запроса заголовок преображается в словарь в поле :cookies. Чтобы сообщить клиенту новые куки, добавьте поле :cookies в ответ. Из такого словаря образуется заголовок Set-Cookie.

Напишем простую страничку, которая определяет, видим ли мы ее в первый раз.
```
(require '[ring.middleware.cookies
           :refer [wrap-cookies]])

(defn page-seen
  [request]
  (let [seen-path [:seen :value]
        {:keys [cookies]} request
        seen? (get-in cookies seen-path)
        cookies (assoc-in cookies seen-path true)]
    {:status 200
     :cookies cookies
     :body (if seen?
             "Already seen"
             "The first time you see it") }))

(defn app
  (-> page-seen
      wrap-cookies))
```
Запустите приложение в браузере. После обновления страницы надпись изменится на “Already seen”. Обратите внимание, что даже после перезагрузки сервера ответ по-прежнему будет “Already seen”, потому что флаг хранится в браузере. Только очистив куки вы снова увидите “The first time you see it”. Для полноты эксперимента откройте приватную вкладку или другой браузер.

Куки тесно связаны с безопасностью. Даже если вам понятны технические детали, убедитесь, что куки защищены от кражи и не раскрывают секретные данные (пароли, ключи доступа). В этом разделе мы не обсуждаем тему веб-безопасности. Она слишком обширна для этой главы и заслуживает отдельной книги.

Сессии

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

Wrap-session это довольно сложное middleware. Оно дополняет запрос полем :session, в котором словарь. Его ключи — поля сессии. Чтобы обновить сессию, следует положить ее новую версию в ответ по аналогии с :cookie. Middleware различает nil и факт отсутствия сессии в ответе. Если поле :session nil, вся сессия удаляется. Если ключа нет, ничего не происходит.

Сессия это абстрактное понятие, поэтому различают бэкенды сессии. Это разные способы хранить значения физически. Сессия может храниться в памяти, на диске, в базе данных, Memcached/Redis или даже куках. При выборе бэкенда важно учитывать, способен ли он работать на нескольких машинах одновременно. Что получится, если каждый запрос на случайно выбранной из десяти машин?

Если сессия хранится в памяти приложения, то на каждой машине будет ее разная версия. Это чревато странным поведением и трудной отладкой. Аналогично с файлами — машины не делят их между собой. А вот база данных или Redis это общее хранилище. Оно гарантирует актуальность сессии для всех клиентов.

Интересно, что сессия на базе куки тоже работает на множестве машин. На каждый запрос браузер передает и получает полную сессию в HTTP-заголовках. В этом случае сессия хранится на клиенте. Но если пользователь очистит куки или запустит другой браузер, сессия будет утеряна.

В стандартной поставке Ring сессия хранится в памяти или куках. Хранилище определяется настройками wrap-session. Ring закладывает необходимые абстракции, чтобы хранить сессию в базе или key-value системах типа Redis.

Рассмотрим пример со счетчиком посещений. Будем считать, сколько раз пользователь зашел на наш сайт. Для простоты храним сессию в памяти.
```
(require '[ring.middleware.session
           :refer [wrap-session]])

(defn page-counter
  [request]
  (let [{:keys [session]} request
        session (update session :counter (fnil inc 0))]
    {:status 200
     :session session
     :body (format "Seen %s time(s)" (:counter session))}))

(defn app
  (-> page-counter
      wrap-session))
```
Запустите app в веб-сервере и откройте браузер. Обновляйте страницу, и счетчик в сообщении возрастет с каждым просмотром. Ради интереса проделайте то же самое в другом браузере. Это будет вторая сессия, которая не зависит от первой. Поскольку данные хранится в памяти, они будут утеряны при перезагрузке сервера.

Упражнение: в примере выше мы считаем просмотры для всего сайта. Сделайте так, чтобы счетчик работал в рамках страниц. Например, главная страница / просмотрена пять раз, а справка /help — три раза. Параметры командной строки не влияют на подсчет.

JSON

Формат JSON предназначен для передачи данных. Среду прочих его достоинств — типы, вложеность и совместимость с JavaScript.

JSON различает базовые типы данных — числа, строки, логический тип. Это выгодно отличает его от параметров адресной строки или XML, где все значения строки.

Формат предусматривает основные коллекции — массив и словарь — и их произвольную вложенность. В разное время были попытки передать вложенные данные в адресной строке. Общий подход был в том, чтобы ключ содержал путь внутри структуры. Например, если в данных несколько адресов, а у каждого адреса несколько строк (line 1, line 2, etc), то получается что-то вроде:
```
address[0].line[0].value=SomeStreet
```
Требовалось писать и поддерживать код для работы с такими парами. Каждый фреймворк нес на борту собственный модуль, чтобы упаковывать и восстанавливать коллекции. К счастью, сегодня с этим покончено. Сегодня только старые системы передают коллекции через командную строку.

JSON совместим с JavaScript. Если передать такой документ в функцию eval, она вернет данные — комбинацию списков и словарей.

Все это способствовало тому, чтобы JSON стал главным способом передать данные в интернете.

Ring предлагает набор middleware для JSON. Они вынесены в отдельный пакет для удобства разработки. Добавим в проект зависимость:
```
[ring/ring-json "0.4.0"]
```
wrap-json-response облегчает возврат JSON-данных. Это middleware проверяет поле ответа :body. Если это коллекция (вектор, словарь), то middleware заменяет его на кодированную строку и выставляет заголовок Content-Type: application/json.

Рассмотрим пример:
```
(require '[ring.middleware.json
           :refer [wrap-json-response]])


(defn page-data
  [request]
  {:status 200
   :body {:some {:json ["data"]}}})

(def app
  (-> page-data
      wrap-json-response))
```
Более сложный пример. Если пользователь нашелся, возвращаем его модель. Если нет, то структуру ошибки.
```
(defn page-data
  [request]
  (let [user-id (-> request :params :id)]
    (if-let [user (get-user-by-id user-id)]
      {:status 200
       :body user}
      {:status 404
       :body {:error_code "MISSING_USER"
              :error_message "No such a user"
              :error_data {:id user-id}}})))
```
Для входящего JSON-документа в библиотеке два middleware. Это wrap-json-body и wrap-json-params. На фазе запроса оба проверяют, что заголовок Content-Type содержит application/json. Если да, они парсят тело с учетом возможных исключений. При ошибке разбора ответ будет 400 “JSON body malformed”.

Разница между wrap-json-body и wrap-json-params в том, куда они складывают полученные данные.

Wrap-json-body заменяет поле :body запроса на полученную структуру данных. В примере ниже обработчик page-body извлекает имя и город пользователя из :body. Тело запроса уже не входящий поток, а структура данных, о чем заботится wrap-json-body. Обратите внимание, middleware принимает опциональные параметры. Флаг :keywords? true Означает, что ключи словарей должны быть приведены к кейвордам.
```
(require '[ring.middleware.json
           :refer [wrap-json-body]])

(defn page-body
  [request]
  (let [{:keys [body]} request
        {:keys [username city]} body]
    (create-user username city)
    {:status 200
     :body {:code "CREATED"
            :message "User created"}}))

(def app
  (-> page-body
      wrap-json-body {:keywords? true}))
```
Чтобы отправить JSON-запрос к серверу, понадобится специальная программа. Это может быть утилита cURL или графическое приложение Postman. Пример с cURL:
```
curl \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{"username":"John","city":"NY"}' \
  http://localhost:8080/
```
Вариант с wrap-json-params Отличается тем, где хранится структура данных. Это middleware заносит данные в поле :json-params. В дополнение, если данные были словарем, они вливаются в поле :params. Это поле, как мы помним, используются другими врапперами, например, wrap-params.

Таким образом, :params выступает универсальным аккумулятором параметров. Продвинутое API может быть устроено так, что клиент вправе передавать данные удобным ему способом. Например, GET-запросом с параметрами строки, если это данные для чтения. POST с переменными в теле, чтобы изменять сущности. Или POST с JSON-телом, если данные с глубокой вложенностью.

Вспомним, что params это словарь с ключам-строками. По этой причине wrap-json-params сохраняет строки в ключах, чтобы слияние прошло правильно. Чтобы исправить ключи :params на кейворды, используйте уже знакомое нам wrap-keyword-params. Оно должно быть ниже wrap-json-params по стеку.

Разработчики не случайно выделяют поле :json-params. Тело JSON-документа не обязательно словарь, это может быть массив. Такую структуру невозможно влить в :params. Документ помещают в :json-params, и если это словарь, объединяют с :params.

Продемонстрируем сказанное на примере. Передаем данные гибридно: username в теле JSON-документа и city в параметрах строки. Обратите внимание на стек middleware. Сперва мы парсим параметры строки, затем тело документа. Оба словаря накапливаются в :params. Затем, уже после их накопления, исправляем тип ключей.
```
(require '[ring.middleware.json
           :refer [wrap-json-params]])

(defn page-params
  [request]
  (let [{:keys [params]} request
        {:keys [username city]} params]
    (create-user username city)
    {:status 200
     :body {:code "CREATED"
            :message "User created"}}))

(def app
  (-> page-params
      wrap-keyword-params
      wrap-json-params
      wrap-params))
```
Пример обращения к серверу:
```
curl \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{"username":"John"}' \
  http://localhost:8080/?city=NY
```
Собственные middleware

До сих пор мы использовали сторонние врапперы. Это те, что идут в поставке Ring и смежных библиотек. Но рано или поздно вам потребуются собственные. Обычно их накапливают в модуле с именем <projectname>.middleware. Рассмотрим примеры из реальных проектов.

wrap-headers-kw

Этот простой враппер меняет ключи заголовков со строковых на кейворды. Полезно, когда приложение часто обращается к заголовкам.
```
(require
 '[clojure.walk :refer [keywordize-keys]])

(defn wrap-headers-kw
  [handler]
  (fn [request]
	(-> request
    	(update :headers keywordize-keys)
    	handler)))
```
wrap-request-id

В протоколе HTTP запрос и ответ не связаны друг с другом. Порой трудно понять, к какому запросу относится тот или иной ответ и наоборот. Важно, чтобы система могла их сопоставить. Например, была серия ответов с кодом 500, но какие именно запросы вызвали ошибку?

Для этого ввели заголовок X-Request-Id. Если клиент не передал идентификатор запроса, мы назначаем ему случайный. Тот же идентификатор возвращаем в ответе. Все записи в лог содержат этот идентификатор.

Обратите внимание, что мы обращаемся к заголовкам как к ключевым словам. Мы ожидаем, что wrap-headers-kw был выше по стеку.
```
(import 'java.util.UUID)

(defn wrap-request-id
  [handler]
  (fn [request]
	(let [uuid (or (get-in request [:headers :x-request-id])
               	(str (UUID/randomUUID)))]
      (-> request
          (assoc-in [:headers :x-request-id] uuid)
          (assoc :request-id uuid)
          handler
          (assoc-in [:headers :x-request-id] uuid)))))
```
Мы храним идентификатор не только в заголовках, но и на уровне запроса в поле :request-id. Для записи в лог мы будем часто обращаться к нему. Поэтому вынесем в отдельную переменную вместе с другими полями в начале функции:
```
(defn some-handler
  [request]
  (let [{:keys [params request-id]} request]
	(log/info "Request id: %s" request-id)))
```
wrap-current-user

Этот враппер определяет текущего пользователя системы. Стратегия в том, что в запросе содержится идентификатор пользователя. В данном случае мы ищем его в сессии. Если идентификатор найден, читаем модель пользователя и присоединяем к запросу. Ожидается, что функция get-user-by-id знает, как извлекать данные о пользователе. Чаще всего это запрос к базе данных.
```
(defn wrap-current-user
  [handler]
  (fn [request]
	(let [user-id (-> request :session :user-id)
      	user (when user-id
             	(get-user-by-id user-id))]
  	(-> request
      	(assoc :user user)
      	handler))))
```
Условно говоря, хранить user-id в сессии безопасно. Сессия подписана секретным ключом, поэтому только сервер может менять ее значения. Не допускайте, чтобы user-id передавался в параметрах командной строки.

Прерывание стека

Выше мы рассмотрели непрерывную цепочку middleware, где каждое звено передает управление следующему. Но логика middleware не всегда линейна. Бывает, цепочку необходимо разорвать. Например, еще на уровне middleware мы определили, что пользователь не имеет прав к данному ресурсу. Продолжать цепочку по обычному пути не имеет смысла. Наоборот, мы должны как можно скорее вывалиться из стека.

Стандартные врапперы из примеров выше работают на условиях. Так, wrap-json-params читает тело только в том случае, если заголовок Content-Type установлен в application/json. Если в нем что-то другое, он оставит поток нетронутым. При разборе JSON-документа ловится возможное исключение. Такое возможно, если документ сформирован с ошибками или поврежден при передачи. В таком случае wrap-json-params не продолжает цепочку. Он возвращает ответ с текстом “JSON body malformed”. Ни одно middleware ниже по стеку не сработает.

Рассмотрим частный случай с проверкой доступа. Предположим, приложение доступно только авторизованным пользователям. Мы уже определили текущего пользователя в wrap-current-user. То middleware только определяет пользователя, но не ограничивает доступ. Добавим ниже по стеку другое:
```
(defn wrap-auth-user-only
  [handler]
  (fn [request]
    (if (:user request)
      (handler request)
      {:status 403
       :headers {:content-type "text/plain"}
       :body "Please sign in to see that page."})))
```
Теперь все middleware ниже wrap-auth-user-only не сработает если пользователь не авторизован.

Вспомним, цепочку middleware можно представить как восхождение и спуск с горы. Если один из элементов терпит неудачу, мы как будто срезаем верхушку. Словно добрались до середины, столкнулись с проблемой и повернули обратно. Общее правило: чем раньше мы обнаружим проблему, тем меньше потратим сил. Поэтому более общие проверки мы ставим выше по стеку.

Еще один вариант middleware с развилкой это перехват ошибок. Это критически важный обработчик. Вы не найдете его в стандартных библиотеках, потому что логика работы с ошибками меняется от проекта к проекту. Мы просто копируем такой middleware из прошлого проекта с небольшими изменениями.

Что случится, если при обработке запроса выброшено исключение? Не существует четких правил на этот счет. Каждый сервер или фреймворк обрабатывает исключения.

Один сервер покажет в браузере стек-трейс. Другой сервер вернет HTML-страницу с отладочной информацией. Разработчики третьего посчитали, что выводить стек-трейс небезопасно. Исключение пишут в лог, а в ответе статус 500 и фраза “Internal Server Error”.

Хорошо, когда разработчик сам определяет, что делать с исключениями. Ниже простое middleware, которое перехватывает потенциальную ошибку, пишет ее в лог и возвращает ответ-заглушку:
```
(defn wrap-exception
  [handler]
  (fn [request]
    (try
      (handler request)
      (catch Throwable e
        (let [{:keys [uri
                      request-method]} request]
          (log/errorf e "Error, method %s, path %s"
                      request-method uri)
          {:status 500
           :headers {:content-type "text/plain"}
           :body "Sorry, please try later."})))))
```
В примере выше log/errorf это макрос для записи ошибок. Он принимает объект исключения, шаблон и параметры. Мы хотим знать, какие были метод и путь запроса, поэтому записываем их тоже. Это значительно облегчит анализ логов в будущем.

Чем выше wrap-exception расположено в стеке, тем меньше шансов возникнуть не пойманному исключению. В идеале оно стоит на вершине цепочки, чтобы гарантированно ловить все исключения.

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

Чтобы разделять бизнес- и технические проблемы, на границах стека middleware расставляют разные wrap-exception. Самое нижнее оборачивает непосредственно app-naked. Оно отлавливает исключения в бизнес-логике. Такую ошибку обрабатывают подробно, во всех деталях. На вершине стека другая, облегченная версия wrap-exception. Его задача — ловить мелкие ошибки, связанные с предварительной обработкой запроса. По большей части это для того, чтобы возвращать адекватный ответ пользователю.

Middleware вне стека

Интересен сценарий, когда middleware должно оказать эффект только на запросы по определенному пути. Вернемся к wrap-auth-user-only. В чем его недостаток? Если включить его в стек, анонимный пользователь не увидит ни одну страницу. Абсолютно любой запрос будет отклонен со статусом 403. Главная страница, контактные данные, форма входа — все страницы недоступны. В этом нет никакого смысла.

Очевидно, wrap-auth-user-only должен перекрывать только некоторое подмножество запросов. Например, тех, что начинаются с /account: /account/cart, /account/orders и т.д. Место wrap-auth-user-only не в общем стеке, а ниже — на уровне роутинга.

Дальнейшая реализация зависит от того, как мы строим маршруты. В Compojure есть особое middleware под названием wrap-routes. Оно принимает правило и другое middleware. Если правило накладывается на текущий запрос, то целевой обработчик оборачивается в переданное middleware. Столь сложная логика нужна, чтобы не вызывать middleware, пока запрос не совпадет с правилом.

Вынесем семейство маршрутов для аккаунта в отдельную ветку:
```
(defroutes account-routes
  (with-context "/account" []
    (GET "/profile" request (account-profile request))
    (GET "/orders" request (account-orders request))
    (GET "/cart" request (account-cart request))))
```
Обернем аккаунты в маршрутах верхнего уровня:
```
(defroutes app
  (GET "/" request (page-index request))
  (GET "/help" request (page-help request))
  (wrap-routes account-routes wrap-auth-user-only))
```
Теперь wrap-auth-user-only сработает только для обработчиков account-profile, account-orders и account-cart.

Все вместе

Middleware, которое принимает middleware — довольно крутая абстракция. Если вы действительно поняли, как это работает и почему именно так — примите поздравления. Это серьезный рубеж.

Пожалуй, это все, что можно сказать о middleware. Небольшое обобщение: все, что мы проделали выше работает на функциях. Типичное middleware это функция, которая принимает функцию и возвращает функцию. Middleware — универсальный строительный материал.

Цепочку middleware называют стеком. Во время запроса мы движемся по стеку снизу вверх, во время ответа — сверху вниз. Такой обход можно сравнить с восхождением в гору. Каждое middleware может прервать цепочку в зависимости от обстоятельств. Легче всего выразить стек с помощью стрелочного оператора. Это экономит скобки и делает структуру наглядней.
12.03.2019
Tagging programmers

На позапрошлом митапе рассказал, как оцениваю разработчиков. Если коротко, меньше смотрю на классический грейд джун-мидл-синьор, но больше на характер. Привел примеры основных типажей и попытался связать это с возрастом и развитием. Доклад недолгий, обсуждение с 18 минуты.
09.03.2019
Питон и ненависть
По работе пришлось снова вернуться в Питон. Один чудак состряпал сервис на Кложе, но не осилил тесты и написал их на Питоне. Пока исправлял за ним, хлебнул тонны ненависти.

Во-первых, компилятор не обращает внимания на несуществующие переменные. Если допустить опечатку, то скрипт все равно запуститься, чтобы упасть на середине с ошибкой name "foo" is not defiened.

Я в курсе, что в Питоне сто способов подсунуть переменную в рантайм минуя обычное присваивание. Скажем, через globals:
```
>>> globals()["foo"] = 42
>>> foo + 1
43
```
Но за это отрывают руки, поэтому так все равно не делают. А кроме того, компилятор мог бы и ворнинг кинуть. Друг, ты используешь переменную accounts, а откуда она взялась я хз. Не хуйню ли ты пишешь часом? Я бы такой — ок, поправил. Но нет.

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

Питон замусорен лишними символами. Двоеточия, запятые — все это гнать поганой метлой. Сравним словари:
```
{
  "name": "John",
  "age": 42
}
```
и
```
{:name "John"
 :age 42}
```
Зачем двоеточие после ключа? В нем никакого смысла, все равно словари записывают по принципу пара на строку. Зачем запятые? Уберите их, ничего не изменится. Зачем строки на месте ключей? Строки — это сложный тип. Достаточно кейвордов или токенов. Это сущности, которые выражаются сами в себя. То же самое для списков и кортежей. Зачем там запятые?

Казалось бы, лаконичный синтаксис и бла-бла, а на деле мусор. Все, что можно убрать из языка, нужно убрать.

Кстати, о запятых. В Питоне на раз простреливаешь ногу последней запятой в кортеже. Если кортеж из одного элемента, запятая обязательна. Иначе такая запись вырождается в обычное значение а скобки игнорируются. Например, (1,) это кортеж, а (1) становится просто единичкой.

Конечно, об этом узнаешь только по странному поведению программы. Конкретно в моем случае была итерация по кортежу пар, по умолчанию было две пары:
```
for user, email in (("ivan", "ivan@test.com"), ("john", "john@test.com")):
```
Вторая пара стала не нужна, я удалил ее вместе с запятой и долго пытался понять, что не так. Блядь, я не хочу писать на языке, где одна запятая стоит часа потерянного времени.

Самое смешное, что лет шесть назад я плотно кодил на Питоне и знал наизусть все эти грабли. Разбуди меня ночью, и я расскажу сто примеров, когда кажется одно, а выходит другое. Все это я держал в голове и ревностно спрашивал на собеседованиях. Проще говоря, подъебывал кандидатов и надрачивал ЧСВ. А теперь сам затерпел.

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

У коллеги банальная задача. Есть говносервис на Джаве с апишкой. Все параметры передаются через GET в строке запроса. Все ничего, но значения могут быть коллекциями, и нужно их схлопнуть в плоские ключи. Например, {:info {:user "Ivan"}} преобразовать в "info[0].user=Ivan".

Коллега родил код на полтора экрана. Три вложенных оператора, шестерной отступ от левого края. Одну и ту же переменную переписывает три раза. Как это говно поддерживать — без понятия. Сюда даже новое условие не добавишь, потому что переменные перетираются, и все перепроверять. А на неизменяемых коллекциях двадцать строчек и бесконечная расширяемость.

Все, о чем я говорил — ошибки в дизайне языка. Мы не должны тащить на себе всю эту ересь. Питон был замечательным для своего времени. Сегодня я не представляю, как можно на нем писать, имя в распоряжении языки с неизменяемыми типами. Если существует другой язык с лучшим дизайном, надо использовать его. Пол Грэм сказал — не писать на самом мощном языке без уважительной причины значит совершить ошибку. А на чем писал Пол, вы и сами знаете.
09.03.2019
Дети

Я согласен с Лебедевым, что детей нужно заводить раньше. Дети это самое важное. То, чем ты занимаешься — нет. Даже если ты второй Стив Джобс или спаситель человечества. Все равно нет.

Мы живем не в средневековье, и не бывает так, чтобы на целый город приходился один мудрец. Все проблемы человечество решает коллективно. В Гугле работают сто тысяч инженеров. Ученые трудятся в НИИ и огромных лабораториях. Гениям одиночкам ничего не светит.

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

Сюда же относится опен-сорс, консалтинг, сертификаты, конференции, вебинары, курсы роста, ссылки на Хакер-Ньюз и прочее говно. Все это не важно и отвалится через пару лет. Бизнес продадут, код перепишут. Божественную Кложу заменят на блевотный Яваскрипт. Дизайн сделают серым на белом.

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

Мы не раз видели фильмы с таким сюжетом. Родитель не может выстроить отношения с подростком. Ты не уделял мне внимания в детстве! Но я же работал! Обеспечивал семью! Мы хотели твоей заботы, а не денег! Я делал все что мог! Дочь выбегает из комнаты. Да что с ней не так! Папуля морщит лоб и судорожно соображает.

Типовой случай. А секрет в том, что ты бы мог сделать и то, и другое. И работать, и заботиться о детях. Одно другому не мешает.

Ребенок — это продолжение тебя, твой контриб в будущее. Но неполный — что-то возьмут, что-то выкинут. Точную копию передать невозможно, и это круто.

Бездетные пары банально пролетают мимо огромного пласта жизни. Он и не хороший и не плохой, он просто другой — со своими проблемами и ништяками. Умение общаться с ребенком и наставлять его это особый скилл. Получить его можно только на практике.
29.01.2019
Пять новых прочитанных книг

В разделе Книжная полка – пять новых книг. Политология, война, алгоритмы, выступления и детская повесть. Описания стали длиннее. Про одну из книг – политологию Шульман – потом напишу отдельно.
25.01.2019
Зачем и как писать

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

Блог и дневник это разные вещи, но и общее у них есть. Оба помогают структурировать идеи и очистить голову. Дневник — это больше внутреннее, в то время как блог — про внешнее. Но в обоих случаях мы пишем.

Я считаю, когда мы пишем, то стравливаем ментальное напряжение. Записывать мысли — это как приводить порядок, только на этот раз не дома или на рабочем месте, а в голове.

С незаписанной мыслью беда — она не держится в голове слишком долго. Человек не может держать одновременно в голове больше трех-пяти идей, так уж он устроен. Мы устанавливаем календари, туду-листы, будильники, напоминалки. Это прекрасно, но будет круто еще и записывать. Потому что со временем идеи либо теряются, либо перестают приходить, так как им некуда поместиться.

Если носить в голове одну и те же идею, начинает казаться, что она гениальна. И как следствие, ты сам гениален. Я вижу два недостатка: мысленный застой и высокомерие.

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

В обсуждениях и чатах можно много наговорить в поддержку этой идеи и никогда не закончить. Причина в том, что при наличии оппонента мы невольно отклоняемся от первоначальной темы. А уж если оппонент допустил неточность, то грех не переключиться на нее, чтобы втоптать поглубже в грязь. Победил, но никто помнит, что ты говорил вначале.

Высокомерие ведет к провалу. Как бы агрессивно ты не защищал слабую идею, есть риск нарваться на опасного оппонента. Он уже обдумал ее, опробовал и выкинул на помойку. Находить выброшенные идеи не страшно. Гораздо хуже делать это из принципа и терять лицо из-за упрямства.

Наоборот, при написании текста оппонента не существует. Если точнее, оппонент — ты сам. И внезапно понимаешь, что утверждение основано ни на чем. Чтобы составить убедительный текст, придется лезть в книги и интернет, а это проверки, время… Упс, за противоположную точку зрения приводят сильные аргументы… Лучше ничего не буду писать.

Изложение мысли на бумагу — лучшая ее проверка на прочность. В голове идея искажается. Мозг упивается ей, всячески лелеет и прячет недостатки. В письме они проступают во всей силе. Если идея слаба, то чувствуешь, что скатываешься ко лжи. Начинаешь преувеличивать факты, проводить аналогии…

Случалось, что я садился за редактор, а затем отправлял файл в корзину. В голове все было идеально, но текст получался слабым. Значит, плохая идея! Хорошо, что не стал высказывать ее вслух.

Много слов — потеря лица. Бесконечный словесный поток — признак не профессионализма. Продираться через чат или толпу – слабый подход. Мы пишем текст.

В долгосрочной перспективе текст сильнее слов. Сколько каждый день мы пишем в чатах? Каждое сообщение живет не дольше часа. Да, история работает, но кто ее смотрит? Промелькнуло, обсудили и забыли. А текст живет вечно. На него действует уникальная ссылка. Поисковики его индексируют. Текст можно дополнять, улучшать. Много разрозненного текста на одну тему можно оформить в книгу.

Написанный тобою текст — лучший показатель, становишься ли лучше или нет. Если находишь написанное год назад слабым — отлично, так держать. Особенно, если это английский текст. Значит, имеет место рост.

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

Вообще, откажитесь от чувства вины за написанное ранее. Думал эдак — а теперь вот так! Все течет, все меняется, и человек тоже.

Отсюда правило — когда читаете текст, смотрите на дату. Будет нехорошо предъявлять автору за несбывшиеся прогнозы. Вам хорошо, вы отвечаете из будущего на мысль из прошлого. Это бой в неравных условиях.

Как и все остальные, я порой не знаю, с чего начать. Уже придумал середину, но топчусь на первой стоке. Выход — писать с середины. Просто пишешь самую главную мысль, потом вторую, и так далее. Какая-то из мыслей будет мягче остальных. Ее-то и ставим во вступление.

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

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

Самое лучше действие на текст оказывает сокращение. Чем емче текст, тем он мощнее. Значит, остается больше потенциала, чтобы донести мысль.

Минимальные навыки письма необходимы каждому. Я не про знание орфографии и пунктуации, нет. Ошибки легко ликвидировать программными средствами. Я про способность излагать и строить мысли. Сегодня трудно встретить человека, который способен написать страницу связного текста на какую-то тему. Я проводил собеседования и был удивлен, что почти никто не может составить текст о себе. Что я умею, чем полезен и чего ожидаю. Только табличка в резюме и зарплатная вилка.

Пользу записи знают психологи. Знакомый рассказывал, что врач велел ему разбирать проблемы письменно. Записать чего я боюсь? Что буду делать, если это случится? Что скажут окружающие? Что я почувствую? И оказывается, паника в голове меркнет перед бумагой. Не убоюсь, справлюсь, выстою.