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

Первое, что нам нужно сделать, это инициализировать новый проект, который будет содержать код приложения. Crystal предлагает простой способ сделать это с помощью команды crystal init. Эта команда создаст новую папку, создаст базовый набор файлов и инициализирует пустой репозиторий Git. Команда поддерживает создание проектов типа app и lib, с той лишь разницей, что в проектах библиотеки файл shard.lock также игнорируется через .gitignore, по той причине, что зависимости будут заблокированы через приложение, использующее проект. Учитывая, что у нас не будет никаких внешних общих зависимостей и в конечном итоге мы захотим разрешить включение проекта в другие проекты Crystal, мы собираемся создать проект lib.

Начните с запуска crystal init lib transform в вашем терминале. Это инициализирует проект библиотеки под названием Transform со следующей структурой каталогов (файлы, связанные с Git, опущены для краткости):

Давайте подробнее рассмотрим, что представляют собой эти файлы/каталоги:

• .editorconfig — файл https://editorconfig.org, который позволяет некоторым IDE (если они настроены правильно) автоматически применять стиль кода Crystal к файлам *.cr.

• LICENSE — лицензия, которую использует проект. По умолчанию используется MIT, и нас это устраивает.

См. https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/licensing-a-repository для получения дополнительной информации.

• README.md — следует использовать для общей документации по приложению, такой как установка, использование и предоставление информации.

• shard.yml — содержит метаданные об этом осколке Crystal. Подробнее об этом в Главе 8 «Использование внешних библиотек».

• spec/ — папка, в которой хранятся все спецификации (тесты), относящиеся к приложению. Подробнее об этом в Главе 14 «Тестирование».

• src/ — папка, в которой находится исходный код приложения.

• src/transform.cr — основная точка входа в приложение.

Хотя эта структура проекта является хорошей отправной точкой, мы собираемся внести несколько изменений, создав еще один файл: src/transform_cli.cr. Также добавьте в файл shard.yml следующее:

targets:

   transform:

      main: src/transform_cli.cr

Это позволит нам запустить run shards build, а также собрать двоичный файл CLI и вывести его в каталог ./bin.

Разбивать код на несколько файлов — хорошая практика как по организационным причинам, так и для предоставления более специализированных точек входа в ваше приложение. Например, проект преобразования можно использовать как через командную строку, так и в другом приложении Crystal. По этой причине мы можем использовать src/transform.cr в качестве основной точки входа, тогда как src/transform_cli.cr требует src/transform.cr, но также включает некоторую логику, специфичную для CLI. Мы вернемся к этому файлу позже в этой главе.

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

Написание базовой реализации

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

1. Преобразуйте входные данные YAML в JSON.

2. Передайте преобразованные данные в jq.

3. Преобразуйте выходные данные JSON в YAML.

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

Имея это в виду, давайте перейдем к написанию первоначальной реализации, начав с чего-то простого и повторяя его, пока не получим полностью работающую реализацию. Начнем с самого простого случая: вызовите jq с жестко закодированными данными JSON, чтобы показать, как эта часть будет работать. К счастью для нас, стандартная библиотека Crystal включает тип https://crystal-lang.org/api/Process.html, который позволяет напрямую вызывать процесс jq, установленный в данный момент. Таким образом, мы можем использовать все его функции без необходимости переносить их в Crystal.

Откройте src/transform.cr в выбранной вами IDE и обновите его, чтобы он выглядел следующим образом: