Подобно тому, что мы делали при создании нашего приложения CLI в Главе 4 «Изучение Crystal посредством написания интерфейса командной строки», мы собираемся использовать команду crystal init для формирования каркаса нашего приложения. Однако, в отличие от прошлого раза, когда мы создавали библиотеку, мы собираемся инициализировать приложение. Основная причина этого в том, что мы также получаем файл shard.lock, позволяющий воспроизводить установку, как мы узнали в предыдущей главе. Полная команда в конечном итоге будет выглядеть как блог приложения crystal init.

Теперь, когда наше приложение создано, мы можем добавить Athena в качестве зависимости, добавив в файл shard.yml следующее, обязательно после этого запустив shards install:

dependencies:

  athena:

    github: athena-framework/framework

    version: ~> 0.16.0

И это все, что нужно для установки Athena. Он спроектирован так, чтобы быть ненавязчивым, поскольку не требует каких-либо внешних зависимостей за пределами Shards, Crystal и их необходимых системных библиотек для установки и запуска. Также нет необходимости в структурах каталогов или файлах, которые в конечном итоге сокращают количество шаблонов до тех, которые необходимы в зависимости от ваших требований.

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

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

Сущность статьи

Следуя нашей организационной стратегии, давайте создадим новую папку и файл, скажем, src/entities/article.cr. Наша сущность статьи начнется как класс, определяющий свойства, которые мы хотим отслеживать. В следующем разделе мы рассмотрим, как повторно использовать сущность статьи для взаимодействия с базой данных. Это может выглядеть так:

class Blog::Entities::Article include JSON::Serializable

   def initialize(@title : String, @body : String); end

   getter! id : Int64

   property title : String

   property body : String

   getter! updated_at : Time

   getter! created_at : Time

   getter deleted_at : Time?

end

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

Мы используем версию макроса getter для обработки идентификатора и создания/обновления свойств. Этот макрос создает переменную экземпляра, допускающую значение nilable, и два метода, которыми в случае нашего свойства ID будут #id и #id?. Первый повышается, если значение равно nil. Это хорошо работает для столбцов, которые на практике будут иметь значения большую часть времени, но не будут иметь их, пока они не будут сохранены в базе данных.

Поскольку наше приложение будет в первую очередь служить API, мы также включаем JSON::Serializable для обработки (де)сериализации. Компонент сериализатора Athena имеет аналогичный модуль ASR::Serializable, который работает таким же образом, но с дополнительными функциями. На данный момент нам особо не нужны никакие дополнительные возможности. Мы всегда можем вернуться к нему, если возникнет необходимость. См. https://athenaframework.org/Serializer/ для получения дополнительной информации.

Возврат статьи

Теперь, когда у нас есть смоделированная сущность статьи, мы можем перейти к созданию конечной точки, которая будет обрабатывать ее создание на основе тела запроса. Как и в случае с типом статьи, давайте создадим наш контроллер в специальной папке, например src/controllers/article_controller.cr.

Athena — это платформа Model View Controller (MVC), в которой контроллер — это класс, который содержит один или несколько методов, которым сопоставлены маршруты. Например, добавьте следующий код в наш файл контроллера:

class Blog::Controllers::ArticleController < ATH::Controller

   @[ARTA::Post("/article")]

   def create_article : ATH::Response

      ATH::Response.new(

         Blog::Entities::Article.new("Title", "Body").to_json,

         headers: HTTP::Headers{"content-type" =>

         "application/ json"}

      )

   end

end

Здесь мы определяем наш класс контроллера, обязательно наследуя от ATH::Controller. При желании можно использовать пользовательские классы абстрактных контроллеров, чтобы обеспечить общую вспомогательную логику для всех экземпляров контроллера. Затем мы определили метод экземпляра #create_article, который возвращает ATH::Response. К этому методу применена аннотация ARTA::Post, которая указывает, что эта конечная точка является конечной точкой POST, а также путь, по которому должно обрабатываться это действие контроллера. Что касается тела метода, мы создаем экземпляр и преобразуем жестко закодированный экземпляр нашего объекта статьи в JSON, чтобы использовать его в качестве тела нашего ответа. Мы также устанавливаем заголовок типа контента ответа. Отсюда давайте подключим все и убедимся, что все работает как положено.

Возвращаясь к первоначально созданному файлу src/blog.cr, замените все его текущее содержимое следующим:

require "json"

require "athena"

require "./controllers/*"

require "./entities/*"

module Blog

   VERSION = "0.1.0"

   module Controllers; end

   module Entities; end

end

Здесь нам просто нужна Athena, модуль JSON Crystal, а также папки контроллера и сущностей. Мы также определили здесь пространства имен Controllers и Entities, чтобы в будущем к ним можно было добавлять документацию.

Далее давайте создадим еще один файл, который будет служить точкой входа в наш блог, скажем, src/server.cr со следующим содержимым:

require "./blog"

ATH.run

Такой подход гарантирует, что сервер не запустится автоматически, если мы просто хотим запросить исходный код где-то еще, например, в нашем коде спецификации. ATH.run по умолчанию запустит наш сервер Athena на порту 3000.

Теперь, когда сервер запущен, если бы мы выполнили следующий запрос, используя cURL, например, curl --request POST 'http://localhost:3000/article', мы получили бы следующий ответ, как ожидал:

{

   "title": "Title",

   "body": "Body"

}

Однако, поскольку мы хотим, чтобы наш API возвращал JSON, есть более простой способ сделать это. Мы можем обновить действие нашего контроллера, чтобы напрямую возвращать экземпляр нашего объекта статьи. Афина позаботится о его преобразовании