clojurice

Приложение для самоуверенного стартера для веб-приложений полного стека в Clojure

Требования

Вам понадобится установленная загрузка, а также Java 1.8+ и PostgreSQL 9,6+. Docker также рекомендуется для местного развития.

Инструкции

Лучший способ начать новый проект - просто нажать кнопку «Использовать этот шаблон» в верхней части страницы Github. В качестве альтернативы, если вы не хотите использовать GitHub для своего проекта, вы можете скачать Master .zip, извлечь его локально и оттуда git init .

Чтобы начать среду разработки:

 docker-compose up &
boot dev

Это начнет как бэкэнд, так и подборка фронта, с сайтом, размещенным на Localhost: 7000. Документация API также можно найти по адресу http: // localhost: 7000/api-docs

Чтобы построить проект до Uberjar Do:

 boot build <target-dir> 

Uberjar под названием «App- (версия) -standalone.jar» будет найден в целевом каталоге. Номер версии проекта может быть установлен в build.boot .

Конфигурация

Конфигурация обрабатывается через файлы EDN в рамках каталога resources/config . base.edn обеспечивает базовую конфигурацию, которая применяется ко всем средам, в то время как два профиля, dev.edn и prod.edn загружаются в соответствующих средах и имеют приоритет над base.edn . Кроме того, во время загрузки файлы конфигурации проверяются на Config схеме, расположенной в domain.cljc .

Конфигурация Frontend предоставляется через API в GET /api/config и предоставляет подмножество конфигурации, как определено в схеме FrontendConfig в domain.cljc .

Примечания к разработке

Бэкэнд

Основной бэкэнд API можно найти в api.clj и написан в Compojure-API. Существует также учебник по работе с синтаксисом Compojure-API.

Инъекция зависимости и обработка компонентов системы обрабатывается через систему и модель RAAMWERK. Это то, что позволяет вживую перезагрузку бэкэнда, но также организует все компоненты приложения (статические и API -серверы, конфигурация, DB и т. Д.). Основные конструкторы для них встречаются в app.systems . Существует базовая функция build-system , которая принимает имя профиля конфигурации и создает базовую карту системы для этого профиля, а затем функции, которые производят системы Prod и Dev.

Наиболее важным примечанием является :site-endpoint , которая является компонентом, который обрабатывает статические маршруты, такие как основной индекс и указывает на app.routes/site , и :api-endpoint , который является компонентом для API REST, и указывает на app.api/api-routes . Каждая из этих функций принимает один аргумент (называемый sys по соглашению), который является подмножеством карты системы, содержащей ключи, перечисленные как зависимости в векторе, передаваемом component/using . Таким образом, чтобы компонент был доступен для конечной точки, его ключ должен быть добавлен в этот вектор.

Миграции базы данных обрабатываются с помощью компонента Ragtime, настраиваются для автоматического запуска при запуске или перезагрузке сервера. Миграции расположены в resources/db/migrations .down.sql которые .up.sql файлы. Карта конфигурации Ragtime доступна из системной карты как :migrations и, таким образом, можно получить доступ от Repl или от любого компонента, который наследует ее как зависимость. Эта карта может быть передана функциям в ragtime.repl для запуска или отката миграции вручную.

Для абстракции SQL HoneySQL используется поверх clojure.java.jdbc. HoneyySQL предоставляет способ написания запросов SQL в качестве карт, которые, таким образом, могут быть созданы и составлены как любая другая карта Clojure, а затем отформатированы в SQL, чтобы вызвать с драйвером JDBC. Полученная функция, app.query/make-query предоставляется в query.sql для обертки вызова драйверу JDBC, поэтому нужно предоставить только карту системы и карту запросов SQL, чтобы получить результат.

Внешний интерфейс

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

1. Создайте свое представление в app.views пространство имен, т.е. app.views.foo в cljs/app/views/foo.cljs
2. Требуется app.views.dispatch/dispatch-view . :app.foo . Метод должен взять два аргумента, первым является сам ключ, второй - любые параметры из URI.
3. Требовать нового пространства имен в index.cljs .
4. Добавьте маршрут к маршрутам в router.cljs .

Основное состояние приложения хранится в общем атоме реагента в app.state/app-state . Пространство имен app.api также предоставляется для общих вызовов API.

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

Общие пространства имен

В дополнение к фронта и бэкэнд, также включены некоторые общие пространства имен через файлы .cljc в src/cljc/app , которые позволяют обмену ключевыми данными и функциями, которые будут переданы спереди и сзади. Наиболее важным из них является app.domain в src/cljc/app/domain.cljc . Это предоставляет общие схемы данных для приложения, включая схему для файлов конфигурации.

Dev Tools

Docker-Compose.yml был предоставлен для запуска базовой конфигурации Postgres с настройками по умолчанию, описанным выше, с помощью простого docker-compose up .

Конфигурация по умолчанию откроет соединения NREPL на фронтацию в порту 6809 и бэкэнд в порту 6502.

Существует также дополнительный элемент реагента-дв, добавлен на страницу в режиме DEV, который дает отражение текущего состояния приложения.

Предназначена задача boot cljfmt , которая будет запускать CLJFMT во всех файлах в каталоге SRC. Задачи check и fix от Boot-CLJFMT также доступны напрямую и могут использоваться для работы против отдельных файлов или каталогов по мере необходимости.

Горячая перезагрузка

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

Обратите внимание, что система полного бэкэнд -сервера будет полностью перезапущена только при изменении определенных файлов. Это настроено через задачу build.boot dev с помощью параметра :files на шаг system .

Тестирование

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

Тесты включают в себя тестирование браузера через Etaoin, и вам также необходимо установить geckowebdriver на основе Firefox. Информацию и ссылки о том, как это сделать, можно найти здесь. На Mac он может быть установлен с помощью brew install geckodriver , на Ubuntu с firefox-geckowebdriver или в окнах с scoop install geckodriver . Вам также, конечно, понадобится хром.

Кредиты и лицензия

Это приложение первоначально основано на системном образе с некоторыми дальнейшими руководством от Tenzing.

Разработано Аннея Данверс (@Jarcane). Развитие стало возможным благодаря FutUrice.

Авторские права (C) 2018 Анна Данверс. Код распространяется в соответствии с публичной лицензией Eclipse V2.0 или в любой более поздней версии. Для получения дополнительной информации см. LICENSE в корневом каталоге.