Shard зависимости от кода C

До сих пор предполагалось, что устанавливаемые Шарды представляют собой чистые реализации Crystal. Однако, как мы узнали ранее в Главе 7 «Взаимодействие C», Crystal может связываться с существующими библиотеками C и использовать их. Шарды не поддерживают установку библиотек C, необходимых для привязок Crystal. Пользователь, использующий Shard, может установить их, например, через менеджер пакетов своей системы.

Хотя Shards не обеспечивает их установку за вас, он поддерживает ключ информационных библиотек в shard.yml. Пример этого выглядит следующим образом:

libraries:

  libQt5Gui:

  libQt5Help: "~> 5.7" libQtBus: ">= 4.8"

Глядя на это, кто-то, пытающийся использовать Shard, может узнать, какие библиотеки необходимо установить, основываясь на библиотеках C, на которые ссылается Shard. Еще раз: это чисто информационный характер, но вам все равно рекомендуется включить его, если ваш шард привязан к каким-либо библиотекам C.

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

Обновление осколков

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

Всем шардам предлагается подписаться на https://semver.org. Следуя этому стандарту, мы позволяем оператору

~>

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

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

shards update

Проверка зависимостей

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

shards outdated

Команду

shards prune

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

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

path

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

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

Ниже приведены некоторые из наиболее популярных и полезных ресурсов для поиска осколков:

• Awesome Crystal: https://github.com/veelenga/awesome-crystal — это реализация https://github.com/sindresorhus/awesome/blob/main/awesome.md для Crystal. Это составленный вручную список осколков кристаллов и других связанных ресурсов в различных категориях. Это хороший ресурс, поскольку он включает в себя различные популярные шарды в экосистеме.

• Shardbox: https://shardbox.org/ — это база данных осколков, созданная вручную, которая немного более сложна, чем Awesome Crystal. Он включает в себя функции поиска и тегирования, информацию о зависимостях и метрики для всех осколков в его базе данных.

• Shards.info: в отличие от двух предыдущих ресурсов, https://shards.info/ — это автоматизированный ресурс, который периодически очищает репозитории из GitHub и GitLab, ориентируясь на репозитории, которые были активны в течение последнего года и чей язык это Кристалл. Это полезный ресурс для поиска новых осколков, но вы также можете столкнуться с некоторыми, которые еще не готовы к производству.

Если вы ищете что-то конкретное, вы сможете найти это, используя один из этих ресурсов. Однако, если вы не можете найти осколок, соответствующий вашим целям, другой вариант — обратиться к сообществу: https://crystal-lang.org/community/#chat. Спросить тех, кто знаком с языком, обычно является отличным источником информации.

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

Пример сценария

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

Вы начинаете просматривать список Awesome Crystal и замечаете, что в категории «Форматы данных» есть осколок toml.cr. Однако, прочитав файл readme, вы решаете, что он не будет работать, поскольку вам требуется поддержка TOML 1.0.0, а Shard предназначен для версии 0.4.0. Чтобы получить больший выбор осколков, вы решаете перейти на shard.info.

При поиске TOML вы находите toml.cr, который предоставляет привязки C к библиотеке синтаксического анализа TOML, совместимой с TOML 1.0.0, и решаете использовать эту. Просматривая выпуски на GitHub, вы замечаете, что Shard еще не имеет версии

1.0.0

0.2.0

~> 0.2.0

0.2.x

0.3.x

dependencies:

 ctoml-cr:

  github: syeopite/ctoml-cr

  version: ~> 0.2.0

Отсюда вы можете запустить

shards install

require “toml-cr"

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

Подобно тому, что мы делали при создании нашего приложения CLI в Главе 4 «Изучение Crystal посредством написания интерфейса командной строки», мы собираемся использовать команду

crystal init

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?

nil

Поскольку наше приложение будет в первую очередь служить API, мы также включаем

JSON::Serializable

ASR::Serializable

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

Теперь, когда у нас есть смоделированная сущность статьи, мы можем перейти к созданию конечной точки, которая будет обрабатывать ее создание на основе тела запроса. Как и в случае с типом статьи, давайте создадим наш контроллер в специальной папке, например 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

Возвращаясь к первоначально созданному файлу 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

3000

Теперь, когда сервер запущен, если бы мы выполнили следующий запрос, используя cURL, например,

curl --request POST 'http://localhost:3000/article'

{

  "title": "Title",

  "body": "Body"

}

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

def create_article : Blog::Entities::Article

  Blog::Entities::Article.new "Title", "Body"

end

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

ATH::Response

ATH::Response

Athena также предоставляет некоторые более специализированные подклассы

ATH::Response

ATH::RedirectResponse

ATH::StreamedResponse

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

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

def ATH::Config::CORS.conРисунок : ATH::Config::CORS?

  new(

   allow_credentials: true,

   allow_origin: ["*"],

  )

end

В идеале значение источника должно быть фактическим доменом вашего приложения, например https://app.myblog.com. Однако в этой главе мы просто позволим все что угодно. Athena также поддерживает концепцию параметров, которые можно использовать для настройки независимо от окружающей среды. Дополнительную информацию см. на https://athenaframework.org/Components/config/.

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

struct ATH::Config::CORS

 def self.conРисунок : ATH::Config::CORS?

  new(

   allow_credentials: true, allow_origin: ["*"],

  )

 end

end

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

Обработка тела запроса

Как мы видели ранее, поскольку мы включили

JSON::Serializable

def create_article(request : ATH::Request) :

 Blog::Entities::Article

 if !(body = request.body) || body.peek.try &.empty?

  raise ATH::Exceptions::BadRequest.new "Request does not have a body."

 end

 Blog::Entities::Article.from_json body

end

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

"/add/{val1}/{val2}"

def add(val1 : Int32, val2 : Int32) : Int32

ATH::Request

В этом примере мы используем типизированный параметр

ATH::Request

nil

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

ATH::Exceptions

Athena::Exceptions::HTTPException

400

{

 "code": 400,

 "message": "Request does not have a body."

}

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

Athena::Exceptions::HTTPException

500

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

Blog::Entities::Article.from_json

{

 "title": "My Title",

 "body": "My Body"

}

Соответствующая команда cURL будет выглядеть следующим образом:

curl --request POST 'http://localhost:3000/article' \

--header 'Content-Type: application/json' \

--data-raw '{

  "title": "My Title",

  "body": "My Body"

}'

Отлично! Но так же, как существовал лучший способ вернуть ответ, Athena предлагает довольно удобный способ упростить десериализацию тела ответа. У Athena есть уникальная концепция, называемая преобразователями параметров. Конвертеры параметров позволяют применять собственную логику для преобразования необработанных данных из запроса в более сложные типы. См. https://athenaframework. org/Framework/ParamConverter/ для получения дополнительной информации.

Примеры преобразователей параметров включают следующее:

• Преобразование строки даты и времени в экземпляр времени.

• Десериализация тела запроса в определенный тип.

• Преобразование параметра пути идентификатора пользователя в реальный экземпляр пользователя.

Athena предоставляет первые два в качестве встроенных преобразователей, но когда дело доходит до определения пользовательских конвертеров, нет предела. Давайте воспользуемся преобразователем параметров, чтобы упростить действие контроллера создания статьи. Обновите метод следующим образом:

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

@[ATHA::ParamConverter("article", converter:

  ATH::RequestBodyConverter)]

def create_article(article : Blog::Entities::Article) :

  Blog::Entities::Article

  article

end

Нам удалось сжать действие контроллера в одну строку! Основным нововведением здесь является аннотация

ATHA::ParamConverter

ATH::RequestBodyConverter

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

JSON::Serializable

ASR::Serializable

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

Проверка

Компонент Athena Validator — это надежная и гибкая среда для проверки как объектов, так и значений. Его основной API предполагает применение аннотаций, представляющих ограничения, которые вы хотите проверить. Экземпляр этого объекта затем может быть проверен с помощью экземпляра валидатора, который вернет, возможно, пустой список нарушений. У компонента слишком много функций, чтобы их можно было охватить в этой главе, поэтому мы сосредоточимся на том, что необходимо для проверки наших статей. См. https://athenaframework.org/Validator/ для получения дополнительной информации.

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

AVD::Validatable

Article

@[Assert::NotBlank]

@[Assert::NotBlank]

property title : String

@[Assert::NotBlank]

property body : String

Если вы попытаетесь использовать пустые значения

POST

422

{

 "code": 422,

 "message": "Validation failed",

 "errors": [

  {

   "property": "body",

   "message": "This value should not be blank.",

   "code": "0d0c3254-3642-4cb0-9882-46ee5918e6e3"

  }

 ]

}

Это работает «из коробки», поскольку

ATH::RequestBodyConverter

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

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

Настройка базы данных

Crystal предоставляет сегмент абстракции базы данных https://github.com/crystallang/crystal-db, который определяет высокоуровневый API для взаимодействия с базой данных. Каждая реализация базы данных использует это в качестве основы и реализует способ получения данных из базового хранилища. Это обеспечивает унифицированный API и общие функции, которые могут использовать все реализации баз данных. В нашем случае мы можем использовать https://github.com/will/crystal-pg для взаимодействия с нашей базой данных PG.

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

dependencies:

 athena:

  github: athena-framework/framework

  version: ~> 0.16.0

 pg:

  github: will/crystal-pg

  version: ~> 0.26.0

Обязательно запустите

shards install

require "pg"

Базовый сегмент абстракции предоставляет модуль

DB::Serializable

JSON::Serializable

Прежде чем мы приступим к настройке регистрации пользователей, нам необходимо настроить базу данных. Есть несколько способов сделать это, но самый простой, который я нашел, — это использовать docker-compose, который позволит нам развернуть сервер Postgres, которым будет легко управлять, и при необходимости его можно будет отключить. Файл compose, который я использую, выглядит следующим образом:

version: '3.8'

services:

 pg:

  image: postgres:14-alpine

  container_name: pg

  ports:

   - "5432:5432"

  environment:

   - POSTGRES_USER=blog_user

   - POSTGRES_PASSWORD=mYAw3s0meB!log

  volumes:

   - pg-data:/var/lib/postgresql/data

   - ./db:/migrations

volumes:

 pg-data:

Хотя я не буду вдаваться в подробности, суть в том, что мы определяем контейнер pg, который будет использовать Postgres 14, доступный через порт по умолчанию, используя переменные среды для настройки пользователя и базы данных. и, наконец, создание тома, который позволит данным сохраняться между его запуском и выключением. Мы также добавляем папку db/ в качестве тома. Это сделано для того, чтобы у нас был доступ к нашим файлам миграции внутри контейнера — подробнее об этом позже. Эту папку следует создать перед первым запуском сервера, что можно сделать через

mkdir db

docker-compose up

-d

Теперь, когда ваша база данных работает, нам нужно настроить параметры базы данных, а также создать схему для нашей таблицы статей. Существует несколько сегментов для управления миграциями, однако я собираюсь просто сохранить и запустить SQL вручную. Если в вашем проекте будет больше нескольких таблиц, использование инструмента миграции может быть очень полезным, особенно для проектов, которые вы планируете сохранить в течение некоторого времени. Давайте создадим новую папку db/ для хранения наших файлов миграции, создав db/000_setup.sql со следующим содержимым:

CREATE SCHEMA IF NOT EXISTS "test" AUTHORIZATION "blog_user";

Технически нам это пока не нужно, однако это понадобится позже, в Главе 14 «Тестирование». Далее давайте создадим db/001_users.sql со следующим содержимым:

CREATE TABLE IF NOT EXISTS "articles"

(

 "id" BIGINT GENERATED ALWAYS AS IDENTITY NOT NULL

PRIMARY KEY,

 "title" TEXT NOT NULL,

 "body" TEXT NOT NULL,

 "created_at" TIMESTAMP NOT NULL,

 "updated_at" TIMESTAMP NOT NULL,

 "deleted_at" TIMESTAMP NULL

);

Мы просто храним некоторые стандартные значения вместе с временными метками и целочисленным первичным ключом с автоинкрементом.

Поскольку наш сервер Postgres работает внутри контейнера Docker, нам нужно использовать команду docker для запуска файлов миграции из контейнера:

docker exec -it pg psql blog_user -d postgres -f /migrations/ 000_setup.sql

docker exec -it pg psql blog_user -d postgres -f /migrations /001_articles.sql

Сохраняющиеся статьи

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

Первое, что нам нужно сделать, это включить модуль

DB::Serializable

Article

DB::ResultSet

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

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

#before_save

protected def before_save : Nil

 if @id.nil?

  @created_at = Time.utc

 end

 @updated_at = Time.utc

end

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

update_at

В некоторых Crystal ORM, а также в Ruby

ActiveRecord

#save

DB::Serializable

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

Суть этого нового типа будет заключаться в предоставлении метода

#persist

DB::Serializable

#before_save

#save

require “./services/*"

@[ADI::Register]

class Blog::Services::EntityManager

 @@connection : DB::Database = DB.open ENV["DATABASE_URL"]

 def persist(entity : DB::Serializable) : Nil

  entity.before_save if entity.responds_to? :before_save

  entity.after_save self.save entity

 end

 private def save(entity : Blog::Entities::Article) : Int64

  @@database.scalar(

   %(INSERT INTO "articles" ("title", "body", "created_at",

   "updated_at", "deleted_at") VALUES ($1, $2, $3, $4, $5)

    RETURNING "id";),

   entity.title,

   entity.body,

   entity.created_at,

   entity.updated_at,

   entity.deleted_at,

   ).as Int64

 end

end

Чтобы упростить запуск нашего кода на разных машинах, мы собираемся использовать переменную среды для URL-адреса соединения. Назовем это DATABASE_URL. Мы можем экспортировать это с помощью следующего:

export DATABASE_URL=postgres://blog_user:mYAw3s0meB\

!log@localhost:5432/postgres?currentSchema=public

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

#save

#after_save

protected def after_save(@id : Int64) : Nil

end

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

DB::Serializable

Наконец, что наиболее важно, мы используем аннотацию

ADI::Register

DB::Database

Аннотация

ADI::Register

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

Теперь, когда у нас есть все необходимые условия, мы можем, наконец, настроить постоянство статей, причем первым шагом будет предоставление нашему менеджеру объектов доступа к

ArticleController

Blog::Services::EntityManager

@[ADI::Register(public: true)]

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

 def initialize(@entity_manager : Blog::Services::

  EntityManager);

 end

 # ...

end

По причинам реализации служба должна быть общедоступной, следовательно, поле

public: true

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

#create_article

def create_article(article : Blog::Entities::Article) :

 Blog::Entities::Article

 @entity_manager.persist article

 article

end

Хотя действие контроллера выглядит простым, под капотом происходит немалое:

• Преобразователь тела запроса будет обрабатывать десериализацию и выполнять проверки.

• Менеджер объектов сохраняет десериализованный объект.

• Сущность можно просто вернуть напрямую, поскольку для нее будет установлен идентификатор и сериализована в формате JSON, как и ожидалось.

Давайте повторим наш запрос cURL ранее:

curl --request POST 'http://localhost:3000/article' \

--header 'Content-Type: application/json' \

--data-raw '{

 "title": "Title",

 "body": "Body"

}'

Это приведет к ответу, подобному этому:

{

 "id": 1,

 "title": "Title",

 "body": "Body",

 "updated_at": "2022-04-09T04:47:09Z",

 "created_at": "2022-04-09T04:47:09Z"

}

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

Получение статей

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

Repository

class Blog::Entities::Article::Repository

 def initialize(@database: DB::Database); end

 def find?(id : Int64) : Blog::Entities::Article?

  @database.query_one?(%(SELECT * FROM "articles" WHERE "id"

    = $1 AND "deleted_at" IS NULL;), id, as:

      Blog::Entities::Article)

 end

 def find_all : Array(Blog::Entities::Article)

  @database.query_all %(SELECT * FROM "articles" WHERE

  "deleted_at" IS NULL;), as: Blog::Entities::Article

 end

end

Это довольно простой объект, который принимает

DB::Database

def repository(entity_class : Blog::Entities::Article.class) :

 Blog::Entities::Article::Repository

  @@article_repository ||=

   Blog::Entities::Article ::Repository.new

   @@database

end

Этот подход позволит добавить перегрузку

#repository

Теперь, когда у нас есть возможность получать все статьи, а также отдельные статьи по идентификатору, мы можем перейти к созданию конечных точек, добавив в контроллер статей следующие методы:

@[ARTA::Get("/article/{id}")]

def article(id : Int64) : Blog::Entities::Article

 article = @entity_manager.repository(Blog::Entities::Article)

  .find? Id

if article.nil?

 raise ATH::Exceptions::NotFound.new "An item with the provided ID could not be found."

end

 article

end

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

def articles : Array(Blog::Entities::Article)

 @entity_manager.repository(Blog::Entities::Article).find_all end

Первая конечная точка вызывает

#find?

404

Как и раньше, когда мы начали с конечной точки

#create_article

ATH::RequestBodyConverter

@[ADI::Register]

class Blog::Converters::Database < ATH::ParamConverter

 def initialize(@entity_manager : Blog::Services

  ::EntityManager);

 end

 # :inherit:

 def apply(request : ATH::Request, configuration :

  Configuration(T)) : Nil forall T

  id = request.attributes.get "id", Int64

   unless model = @entity_manager.repository(T).find? Id

   raise ATH::Exceptions::NotFound.new "An item with the provided ID could not be found."

 end

 request.attributes.set configuration.name, model, T

 end

end

Как и в случае с предыдущим прослушивателем, нам нужно сделать прослушиватель сервисом с помощью аннотации

ADI::Register

Если объект с предоставленным идентификатором не найден, мы возвращаем ответ об ошибке

404

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

В контексте нашего конвертера метод configuration.name представляет имя параметра действия, к которому относится конвертер, на основе значения, указанного в аннотации. Мы используем это, чтобы установить имя атрибута, например,

article

article

#article

@[ARTA::Get("/article/{id}")]

@[ATHA::ParamConverter("article", converter:

 Blog::Converters::Database)]

def article(article : Blog::Entities::Article) :

 Blog::Entities::Article

 article

end

Та-да! Простой способ предоставления объектов базы данных непосредственно в качестве аргументов действия через их идентификаторы. Хотя на данный момент у нас уже довольно много конечных точек, связанных со статьями, нам все еще не хватает способа обновить или удалить статью. Давайте сначала сосредоточимся на том, как обновить статью.

Обновление статьи

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

PUT

POST

Сериализатор Athena имеет концепцию конструкторов объектов, которые управляют тем, как сначала инициализируется десериализуемый объект. По умолчанию они создаются обычным способом с помощью метода

.new

Однако, поскольку это немного усложняет работу сериализатора Athena, а в нашей статье есть только два свойства, мы не собираемся это реализовывать. Если вам интересно, как это будет выглядеть, или вы хотите попробовать реализовать это самостоятельно, ознакомьтесь с рецептом кулинарной книги: https://athenaframework.org/cookbook/object_constructors/#db. Он использует Granite ORM, но переключить его на наш EntityManager должно быть довольно просто.

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

#persist

def persist(entity : DB::Serializable) : Nil

 entity.before_save if entity.responds_to? :before_save

 if entity.id?.nil?

  entity.after_save self.save entity

 else

  self.update entity

 end

Где метод

#update

private def update(entity : Blog::Entities::Article) : Nil

 @@connection.exec(

  %(UPDATE "articles" SET "title" = $1, "body" = $2,

  "updated_at" = $3, "deleted_at" = $4 WHERE "id" = $5;),

  entity.title,

  entity.body,

  entity.updated_at,

  entity.deleted_at,

  entity.id

 )

end

Отсюда мы можем обновить нашу конечную точку

#update_article

@[ARTA::Put("/article/{id}")] @[ATHA::ParamConverter("article_entity", converter:

 Blog::Converters::Database)]

@[ATHA::ParamConverter("article", converter:

 ATH::RequestBodyConverter)]

def update_article(article_entity : Blog::Entities::Article,

 article : Blog::Entities::Article) : Blog::Entities::Article

 article_entity.title = article.title

 article_entity.body = article.body

 @entity_manager.persist article_entity

 article_entity

end

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

#persist

curl --request PUT 'http://localhost:3000/article/1' \ --header 'Content-Type: application/json' \

--data-raw '{

 "title": "New Title",

 "body": "New Body",

 "updated_at": "2022-04-09T05:13:30Z",

 "created_at": "2022-04-09T04:47:09Z"

}'

Это приведет к такому ответу:

{

 "id": 1, "title": "New Title",

 "body": "New Body",

 "updated_at": "2022-04-09T05:22:44Z",

 "created_at": "2022-04-09T04:47:09Z"

}

Прекрасно!

title

body

updated_at

id

create_at

И последнее, но не менее важное: нам нужна возможность удалить статью.

Удаление статьи

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

#remove

#on_remove

delete_at

DELETE

#remove

Начните с добавления этого в менеджер сущностей:

def remove(entity : DB::Serializable) : Nil

 entity.on_remove if entity.responds_to? :on_remove

 self.update entity

end

А это к нашей статье:

protected def on_remove : Nil

 @deleted_at = Time.utc

end

Наконец, действие контроллера будет выглядеть так:

@[ARTA::Delete("/article/{id}")]

@[ATHA::ParamConverter("article", converter:

 Blog::Converters::Database)]

def delete_article(article : Blog::Entities::Article) : Nil

 @entity_manager.remove article

end

Затем мы могли бы сделать запрос, например,

curl --request DELETE 'http:// localhost:3000/article/1'

delete_at

#find?

404

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