Crystal Programming. Введение на основе проекта в создание эффективных, безопасных и читаемых веб-приложений и приложений CLI

Для этой главы вам потребуется следующее:

• Рабочая установка Crystal.

Инструкции по настройке Crystal можно найти в Главе 1 «Введение в Crystal».

Все примеры кода, использованные в этой главе, можно найти в папке Chapter 14 на GitHub по следующей ссылке: https://github.com/PacktPublishing/Crystal-Programming/tree/main/Chapter14

Зачем тестировать?

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

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

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

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

Существуют различные виды тестирования, каждый из которых преследует свою цель. Некоторые из них включают следующее:

• Модульное тестирование (Unit testing): изолированное тестирование конкретной функции/метода.

• Интеграционное тестирование (Integration testing): тестирование интеграции различных типов вместе, имитация внешних коммуникаций (база данных, внешние API и т. д.).

• Функциональное тестирование (Functional testing): аналогично интеграционному тестированию, но с меньшим количеством насмешек и более конкретными утверждениями, например, конкретное значение, возвращаемое из базы данных, а не просто подтверждение того, что запрос был выполнен.

• Сквозное тестирование (E2E) (End-to-end (E2E) testing): аналогично функциональному тестированию, но обычно включает пользовательский интерфейс (UI) и минимальное количество макетов.

• Тестирование безопасности (Security testing): проверка отсутствия известных недостатков безопасности в коде. Каждый из этих типов тестирования имеет свои плюсы, минусы и цели. Однако мы собираемся в первую очередь сосредоточиться на модульной и интеграционной/функциональной стороне вещей, начиная с модульного тестирования.

Модульное тестирование

Spec

def add(value1, value2)

  valuel + value2

end

require "spec"

require "./add"

describe "#add" do

 it "adds with positive values" do

  add(1, 2).should eq 3

 end

 it "adds with negative values" do

  add(-1, -2).should eq -3

 end

 it "adds with mixed signed values" do

  add(-1, 2).should eq 1

 end

end

Spec

#describe

#add

#it

_spec

--order=random

crystal spec

crystal init

Spec

eq

Spec

require "spec"

it do

 true.should be_true

 nil.should be_nil

 10.should be >= 5

 "foo bar baz".should contain "bar"

 10.should_not eq 5

 expect_raises Exception, "Err" do

  raise Exception.new "Err"

 end

end

#it

focus: true

#describe

#it

it "does something", focus: true do

  1.should eq 1

end

Spec

#pending

"check cat" { cat.alive? }

#pending!

#pending!

#fail

#describe

#it

tags

require "spec"

describe "tags" do

 it "tag a", tags: "a" do

 end

  it "tag b", tags: "b" do

 end

end

--tag

crystal spec

--tag 'a' --tag 'b'

b

--tag '~a' --tag '~b'

b

--tag 'a' --tag '~b'

b

crystal spec --tag 'a'

NotificationEmitter

#process

NotificationEmitter

Processor

module TransformerInterface

 abstract def transform(value : String) : String

end

struct ShoutTransformer

 include Transformerinterface

 def transform(value : String) : String

  value.upcase

 end

end

class Processor

 def initialize(@transformer : Transformerinterface =

  ShoutTransformer.new); end

 def process(value : String) : String

  @transformer.transform value

 end

end

puts Processor.new.process "foo"

Transformer

ShoutTransformer

Processor

Transformer

#process

FOO

Processor

class MockTransformer

 include Transformerinterface

 getter transform_arg_value : String? = nil

 def transform(value : String) : String

  @transform_arg_value = value

 end

end

Processor

MockTransformer

require "spec"

describe Processor do

 describe "#process" do

  it "processes" do

   transformer = MockTransformer.new

   Processor.new(transformer).process "bar"

   transformer.transform_arg_value.should eq "bar"

  end

 end

end

Spec

.before_suite

#before_each

#after_each

require "spec"

Spec.before_suite do

 ENV["GLOBAL_VAR"] = "foo"

end

describe "My tests" do

 it "parentl" do

  puts "parent test 1: #{ENV["GLOBAL_VAR"]?}

   - #{ENV["SUB_VAR"]?}"

 end

describe "sub tests" do

 before_each do

  ENV["SUB_VAR"] = "bar"

 end

 after_each do

  ENV.delete "SUB_VAR"

 end

 it "child1" do

  puts "child test: #{ENV["GLOBAL_VAR"]?}

   - #{ENV["SUB_VAR"]?}"

 end

end

 it "parent2" do

  puts "parent test 2: #{ENV["GLOBAL_VAR"]?}

   - #{ENV["SUB_VAR"]?}"

 end

end

.before_suite

#before_each

#after_each

#describe

parent test 1: foo -

child test: foo - bar

parent test 2: foo -

around_*

#describe

around_each do |example|

 ENV["SUB_VAR"] = "bar"

 example.run

 ENV.delete "SUB_VAR"

end

Spec::Example

#run

Интеграционное тестирование

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

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

Распространенной формой интеграционного тестирования является контекст веб-фреймворка. Вы делаете запрос к одной из ваших конечных точек и утверждаете, что получили ожидаемый ответ, либо проверяя тело ответа, либо просто утверждая, что вы получили ожидаемый код состояния. Давайте воспользуемся нашим блог-приложением из Главы 9 «Создание веб-приложения с помощью Athena» и напишем для него несколько интеграционных тестов.

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

Компонент Athena

Spec

Spec

Spec

Основная цель компонента

Spec

Calculator

#add

#subtract

struct Calculator

 def add(value1 : Number, value2 : Number) : Number

  value1 + value2

 end

 def substract(value1 : Number, value2 : Number) : Number

  value1 - value2

 end

end

Пример тестового файла с использованием компонента

Spec

Calculator

struct CalculatorSpec < ASPEC::TestCase

 @target : Calculator

 def initialize : Nil

  @target = Calculator.new

 end

 def test_add

  @target.add(1, 2).should eq 3

 end

 test "subtract" do

  @target.subtract(10, 5).should eq 5

 end

end

Каждый метод, начинающийся с

test_

#it

Spec

test

ATH::Spec::APITestCase

Возвращаясь к интеграционным тестам нашего блога, давайте начнем с тестирования контроллера статей, создав для их хранения новый файл: spec/controllers/article_controller_spec.cr. Затем добавьте в него следующий контент:

require "../spec_helper"

struct ArticleControllerTest < ATH::Spec::APITestCase

end

Мы также можем удалить файл spec/blog_spec.cr по умолчанию.

APITestCase

#get

#post

HTTP::Server

E2E

Начнем с тестирования конечной точки для получения конкретной статьи по идентификатору (ID), добавив следующий метод в

ArticleControllerTest

def test_get_article : Nil

 response = self.get "/article/10"

 pp response.status, response.body

end

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

Athena::Spec

require "spec"

require "../src/blog"

require "athena/spec"

ASPEC.run_all

Помимо модуля

Spec

Framework

ASPEC.run_all

Spec

development_dependencies:

 athena-spec:

  github: athena-framework/spec

   version: ~> 0.2.3

Запуск

crystal spec

500

10

200

Смешивание данных базы данных разработки с данными тестирования — не лучшая идея, поскольку это усложняет управление и приводит к менее надежным тестам. Чтобы облегчить эту проблему, мы воспользуемся тестовой схемой, созданной еще в Главе 9 «Создание веб-приложения с помощью Athena». Файл настройки языка структурированных запросов (SQL) устанавливает владельцем того же пользователя, что и наша база данных разработки, чтобы мы могли повторно использовать одного и того же пользователя. Поскольку мы также настроили использование переменной среды, нам не нужно менять какой-либо код для поддержки этого. Просто

export DATABASE_URL=postgres://blog_user:mYAw3s0meB\!log@ localhost:5432/postgres?currentSchema=test,

EntityManager

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

Spec

DATABASE = DB.open ENV["DATABASE_URL"]

Spec.before_suite do

 DATABASE.exec File.read "#{__DIR__}/../db/000_setup.sql"

 DATABASE.exec "ALTER DATABASE \"postgres\" SET

  SEARCH_PATH TO \"test\";"

 DATABASE.exec File.read "#{__DIR__}/../db/001_articles.sql"

end

Spec.after_suite do

 DATABASE.exec "ALTER DATABASE \"postgres\"

  SET SEARCH_PATH TO \"public\";"

 DATABASE.close

end

Spec._each do

end

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

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

Spec.before_each do

 DATABASE.exec "TRUNCATE TABLE \"articles\" RESTART IDENTITY;"

end

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

На этом этапе, если бы мы снова запустили спецификации, мы бы получили ответ об ошибке

404

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

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

10

GET

def test_get_article : Nil

 DATABASE.exec <<-SQL

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

   updated_at) OVERRIDING SYSTEM VALUE

  VALUES (10, 'TITLE', 'BODY', timezone('utc', now()),

   timezone('utc', now()));

 SQL

 response = self.get "/article/10"

 response.status.should eq HTTP::Status::OK

 article = JSON.parse response.body

 article["title"].as_s.should eq "TITLE"

 article["body"].as_s.should eq "BODY"

end

Поскольку в наших таблицах для

первичного ключа (PK)

GENERATED ALWAYS AS IDENTITY

OVERRIDING SYSTEM VALUE

INSERT

В нашем тесте статьи

GET

def test_get_article_html : Nil

 DATABASE.exec <<-SQL

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

   updated_at) OVERRIDING SYSTEM VALUE

  VALUES (10, 'TITLE', 'BODY', timezone('utc', now()),

   timezone('utc', now()));

 SQL

 response = self.get "/article/10", headers: HTTP::Headers

  {"accept" => "text/html"}

 response.status.should eq HTTP::Status::OK

 response.body.should contain "
BODY
"

end

Мы также могли бы легко протестировать создание статьи, например:

def test_post_article : Nil

 response = self.post "/article", body: %({"title":"TITLE",

  "body":"BODY"})

 article = JSON.parse response.body

 article["title"].as_s.should eq "TITLE"

 article["body"].as_s.should eq "BODY"

 article["created_at"].as_s?.should_not be_nil

 article["id"].raw.should be_a Int64

end

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

Резюме

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

В этой главе мы узнали, как использовать модуль

Spec

Athena::Spec

В следующей главе мы рассмотрим еще одну вещь, которая не менее важна, чем тесты, — как документировать ваш код/проект.

Независимо от того, насколько хорошо реализован shard, если пользователь не знает, как его использовать, он не сможет использовать его в полной мере или полностью откажется. Хорошо документированный код может быть так же важен, как и хорошо написанный или хорошо протестированный код. Как предлагает https://documentation.divio.com, правильная документация для программного продукта должна охватывать четыре отдельные области:

• Учебники

• Практические руководства

• Пояснения

• Использованная литература

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

В этой главе мы рассмотрим следующие темы:

• Документирование кода Crystal.

• Директивы документации

• Создание документации.

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

Технические требования

Для этой главы вам понадобится работающая установка Crystal.

Инструкции по настройке Crystal см. в Главе 1 «Введение в Crystal».

Все примеры кода для этой главы можно найти в папке Chapter 15 репозитория GitHub этой книги: https://github.com/PacktPublishing/Crystal-Programming/tree/main/Chapter15.

Документирование кода Crystal

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

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

#

# This comment is not associated with MyClass.

# A summary of what MyClass does.

class MyClass; end

В этом примере есть два комментария: один связан с

MyClass

# This is the summary

# this is still the summary

#

# This is not the summary.

def foo; end

# This is the summary.

# This is no longer the summary.

def bar; end

Здесь метод #foo имеет многострочное резюме, которое заканчивается пустой новой строкой. С другой стороны, метод

#bar

bar

foo

# def bar

# def foo

Рисунок 15.1 - Созданная документация метода

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

Привязка функции API

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

# Creates and returns a default instance of 'MyClass'.

def create : MyClass; end

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

• Мы можем использовать

#foo

• Мы можем использовать

.new

• Мы можем использовать

MyClass

Функции, определенные в других пространствах имен, должны использовать свои полные пути; то есть

MyOtherClass#foo

MyOtherClass.new

MyOtherClass::CONST

#increment(by)

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

Если вы хотите добавить дополнительную документацию к параметру метода, рекомендуется выделить имя параметра курсивом, например:

# Returns of sum of *value1* and *value2*.

def add(value1 : Int32, value : Int32); end

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

Форматирование

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

# ## Example

#

# '''

# value = 2 + 2 => 4

# value # : Int32

# '''

module MyModule; end

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

'''yaml

# => value

# : Type

Другая причина использования синтаксиса значения

# =>

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

# Runs the application.

#

# DEPRECATED: Use '#execute' instead.

def run; end

В предыдущем примере будет создана документация, которая выглядит следующим образом:

Рисунок 15.2 - Пример использования относительно

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

В предыдущем примере мы использовали предупреждение

DEPRECATED

В случаях, когда вы хотите полностью объявить устаревшим тип или метод, предлагается использовать устаревшую аннотацию (https://crystal-lang.org/api/Deprecated.html). Эта аннотация добавит для вас предупреждение

DEPRECATED

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

Директивы документации

:ditto:

# Returns the number of items within this collection.

def size; end

# :ditto:

def length; end

# :ditto:

#

# Some information specific to this method.

def count; end

#length

#size

#count

:nodoc:

# :nodoc:

#

# This is an internal method.

def internal_method; end

abstract class Vehicle

  # Returns the name of 'self'.

  abstract def name

end

class Car < Vehicle

  def name

   "car"

  end

end

Car#name

# def name

Vehicle

seif

«Описание, скопированное из...»

:inherit:

class Truck < Vehicle

  # Some documentation specific to *name*'s usage within 'Truck'.

  #

  # :inherit:

  def name : String

   "truck"

  end

end

:inherit:

Truck#name

# def name : String

Truck

seif

:inherit:

Создание документации

Подобно команде

crystal spec

crystal docs

crystal docs

crystal docs

Мы также можем передать этой команде явный список файлов; например,

crystal docs one.cr two.cr three.cr

crystal docs

crystal docs lib/project1/src/main.cr lib/project2/src/main.cr src/main.cr

project1

project2

Предоставление файлов для использования вручную требуется, если вы не используете команду в контексте сегмента, поскольку ни папка src/, ни файл shard.yml не существуют. Файл

shard.yml

--project-name

--project-version

-dev

Помимо создания HTML, эта команда также создает файл index.json, который представляет документацию в машиночитаемом формате. Это можно использовать для расширения/настройки способа отображения документации; например, https://mkdocstrings.github.io/crystal/index.html. Теперь, когда мы создали документацию, давайте потратим некоторое время на обсуждение того, что с ней делать, чтобы другие могли ее просмотреть. Мы также коснемся того, как управлять версиями документации по мере разработки вашего приложения.

Хостинг документации

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

Сгенерированная документация представляет собой полностью статический HTML, CSS и JavaScript, что позволяет размещать ее так же, как и любой веб-сайт, например, через Apache, Nginx и т. д. Однако для этих вариантов требуется сервер, к которому большинство людей, вероятно, не имеет доступа, исключительно для размещения HTML-документации. Распространенным альтернативным решением является использование https://pages. github.com/. Руководство о том, как это сделать, можно найти в справочном материале Crystal: https://crystal-lang.org/reference/guides/hosting/github.html#hosting-your-docs-on-github-pages.

Управление версиями документации

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

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

Например, файл версий JSON для стандартной библиотеки можно найти по адресу https://Crystal-lang.org/api/versions.json. Содержимое файла представляет собой простой объект JSON с одним массивом версий, где каждый объект в массиве содержит имя версии и путь, по которому можно найти созданную для этой версии документацию.

Используя тот же URL-адрес, что и у файла версий Crystal, команда для создания документации будет выглядеть следующим образом:

crystal docs –json-config-url=/api/versions.json

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

Резюме

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

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

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

В этой главе мы рассмотрим следующие темы:

• Управление версиями вашего сегмента

• Создание рабочих двоичных файлов

• Распространение вашего двоичного файла

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

Технические требования

Требования к этой главе следующие:

• Рабочая установка Crystal

Пожалуйста, обратитесь к Главе 1 "Введение в Crystal" для получения инструкций по настройке Crystal.

Все примеры кода для этой главы можно найти в папке Chapter16 в репозитории этой книги на GitHub: https://github.com/PacktPublishing/Crystal-Programming/tree/main/Chapter16.

Управление версиями вашего shard

Первое, что вам нужно сделать, прежде чем вы сможете развернуть проект, — это создать новый выпуск. Как вы узнали из Главы 8 «Использование внешних библиотек», настоятельно рекомендуется, чтобы все сегменты Crystal, особенно библиотеки, следовали семантическому управлению версиями (https://semver.org), чтобы сделать зависимости более удобными в обслуживании, обеспечивая воспроизводимые установки и ожидая стабильности.

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

Crystal предоставляет аннотацию https://crystal-lang.org/api/Deprecated.html, которую можно использовать для создания предупреждений об устаревании при применении к методам или типам. В некоторых случаях программе может потребоваться поддержка нескольких основных версий сегмента одновременно. Эту проблему можно решить, проверив версию сегмента во время компиляции, а также некоторую условную логику для генерации правильного кода на основе текущей версии.

Константа

VERSION

module MyShard

  VERSION = "1.5.17"

end

{% if compare_versions(MyShard::VERSION, "2.0.0")	>= 0 %}

  puts "greater than or equal to 2.0.0"

{% else %}

  puts "less than 2.0.0"

{% end %}

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

Релиз — это не что иное, как тег Git для конкретного коммита. Как создать релиз, зависит от того, какой хост вы используете. Инструкции о том, как это сделать для вашего конкретного хоста, см. по следующим ссылкам:

• https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release

• https://docs.gitlab.com/ee/user/project/releases/#create-a-release

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

VERSION

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

shards install

shards update

Создание производственных двоичных файлов

Хотя это было предсказано в Главе 6 «Параллелизм», в основном мы собирали двоичные файлы с помощью команды

crystal build file.cr

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

--release

--no-debug

strip

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

Статическое связывание так же просто, как добавление параметра

--static

libc

musl-libc

Для этого требуется, чтобы собственные зависимости приложения имели статические версии, доступные в базовом образе. Флаг

--static

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

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

Пример команды для этого будет выглядеть так:

docker run --rm -it -v $PWD:/workspace -w /workspace crystallang/crystal:latest-alpine crystal build app.cr --static --release --no-debug

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

Мы можем обеспечить статическую компоновку полученного двоичного файла с помощью команды

ldd

otool -L

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

Распространение вашего бинарного файла

FROM crystallang/crystal:latest-alpine as builder

WORKDIR /app

COPY ./shard.yml ./shard.lock ./

RUN shards install –production

COPY . ./

RUN shards build --static --no-debug --release –production

FROM alpine:latest

WORKDIR /

COPY --from=builder /app/bin/greeter .

ENTRYPOINT ["/greeter"]

builder

WORKDIR

WORKDIR

COPY

--from

builder

docker build -t greeter .

docker run --rm greeter --shout George

./greeter --shout George

--rm

docker ps -a

--rm

docker create greetinger

cp

docker cp abc123:/greeter ./

abc123

Резюме

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

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

Дальнейшее чтение

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

• https://crystal-lang.org/reference/guides/static_linking. html

• https://docs.docker.com/develop/develop-images/baseimages

• montreal.html

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

• Код форматирования.

• Линтинг-код

• Непрерывная интеграция с GitHub Actions.

Технические требования

Требования к этой главе следующие:

• Рабочая установка Crystal.

• Специальный репозиторий GitHub.

Вы можете обратиться к Главе 1 «Введение в Crystal» для получения инструкций по настройке Crystal, а также к https://docs.github.com/en/get-started/quickstart/create-a-repo для настройки вашего репозитория.

Все примеры кода, использованные в этой главе, можно найти в папке Chapter17 на GitHub: https://github.com/PacktPublishing/Crystal-Programming/tree/main/Chapter17.

Форматирование кода

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

Вот некоторые примеры того, что делает форматтер:

• Удаляет лишние пробелы в конце строк.

• Отменить экранирование символов, которые не нужно экранировать, например

F\oo

Foo

• При необходимости добавляет/удаляет отступы, включая замену

;

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

Этот стиль кода обеспечивается командой Crystal, очень похожей на команды

spec

run

build

run crystal tool format

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

--check

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

Линтинг-код

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

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

В Crystal доступен инструмент статического анализа https://github.com/crystal-ameba/ameba. Этот инструмент обычно устанавливается как зависимость разработки, добавляя его в файл shard.yml и затем запуская

shards install

development_dependencies:

  ameba:

   github: crystal-ameba/ameba

version: ~> 1.0

После установки Ameba создаст и выведет себя в папку bin/ вашего проекта, которую затем можно будет запустить через ./bin/ameba. При выполнении Ameba просмотрит все ваши файлы Crystal, проверяя на наличие проблем. Давайте создадим тестовый файл, чтобы продемонстрировать, как это работает:

1. Создайте новый каталог и новый файл shard.yml в нем. Самый простой способ сделать это —

run shards init

2. Затем добавьте Ameba в качестве зависимости разработки и

run shards install

3. Наконец, создайте в этой папке еще один файл со следующим содержимым:

[1, 2, 3].each_with_index do |idx, v|

  PP v

end

def foo

  return "foo"

end

4. Затем мы можем запустить Ameba и увидеть примерно следующий результат:

Inspecting 2 files

F.

test.cr:1:31

[W] Lint/UnusedArgument: Unused argument 'idx'. If it's necessary, use '_' as an argument name to indicate that it won't be used.

> [1, 2, 3].each_with_index do |idx, v|

                                               ^

test.cr:6:3

[C] Style/RedundantReturn: Redundant 'return' detected

> return "foo"

 ^----------^

Finished in 2.88 milliseconds

2 inspected, 2 failure

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

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

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

Непрерывная интеграция с GitHub Actions

.github

ci

ci.yml

name: CI

on:

 pull_request:

  branches:

   - 'master'

 schedule:

  - cron: '37 0 * * *' # Nightly at 00:37

jobs:

jobs:

 check_format:

  runs-on: ubuntu-latest

  steps:

   - uses: actions/checkout@v2

   - name: Install Crystal

   uses: crystal-lang/install-crystal@v1

   - name: Check Format

   run: crystal tool format --check

 coding_standards:

  runs-on: ubuntu-latest

  steps:

   - uses: actions/checkout@v2

   - name: Install Crystal

   uses: crystal-lang/install-crystal@v1

   - name: Install Dependencies

   run: shards install

   - name: Ameba

   run: ./bin/ameba

run crystal tool format --check

run shards install

test:

 strategy:

  fail-fast: false

  matrix:

   os:

    - ubuntu-latest

    - macos-latest

   crystal:

    - latest

    - nightly

  runs-on: ${{ matrix.os }}

  steps:

   - uses: actions/checkout@v2

   - name: Install Crystal

   uses: crystal-lang/install-crystal@v1

   with:

    crystal: ${{ matrix.crystal }}

   - name: Install Dependencies

   run: shards install

   - name: Specs

   run: crystal spec --order=random --error-on- warnings

false

shards install

name: Deployment

on:

 release:

  types:

   - created

jobs:

 deploy_docs:

  runs-on: ubuntu-latest

  steps:

   - uses: actions/checkout@v2

   - name: Install Crystal

   uses: crystal-lang/install-crystal@v1

   - name: Build

   run: crystal docs

   - name: Deploy

   uses: JamesIves/github-pages-deploy-action@4.1.5

   with:

    branch: gh-pages

    folder: docs

    single-commit: true

crystal docs

single-commit

true

Резюме

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

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