clojurice

Aplikasi Starter yang Dipendek untuk Aplikasi Web Full-Stack di Clojure

Persyaratan

Anda perlu diinstal boot, serta Java 1.8+, dan PostgreSQL 9.6+. Docker juga direkomendasikan untuk pengembangan lokal.

Instruksi

Cara terbaik untuk memulai proyek baru adalah dengan cukup mengklik tombol "Gunakan templat ini" di bagian atas halaman GitHub. Bergantian, jika Anda tidak ingin menggunakan github untuk proyek Anda, Anda dapat mengunduh master .zip, mengekstraknya secara lokal, dan git init dari sana.

Untuk memulai lingkungan dev, lakukan:

 docker-compose up &
boot dev

Ini akan memulai kompilasi backend dan frontend, dengan situs yang di -host di LocalHost: 7000. Dokumentasi API juga dapat ditemukan di http: // localhost: 7000/API-DOCS

Untuk membangun proyek ke Uberjar Do:

 boot build <target-dir> 

Uberjar yang disebut "App- (Versi) -StandAlone.jar" akan ditemukan di direktori target. Nomor versi proyek dapat diatur dalam build.boot .

Konfigurasi

Konfigurasi ditangani melalui file EDN di bawah direktori resources/config . base.edn menyediakan konfigurasi dasar yang berlaku untuk semua lingkungan, sedangkan dua profil, dev.edn dan prod.edn dimuat di lingkungan masing -masing dan diutamakan daripada base.edn . Selain itu, pada waktu pemuatan, file konfigurasi diperiksa terhadap skema Config yang terletak di domain.cljc .

Konfigurasi frontend disediakan melalui API di GET /api/config , dan menyediakan subset konfigurasi sebagaimana didefinisikan dalam skema FrontendConfig di domain.cljc .

Catatan Pembangunan

Backend

API backend utama dapat ditemukan di api.clj dan ditulis dalam Compojure-API. Ada juga tutorial tentang bekerja dengan sintaks CompoJure-API.

Injeksi ketergantungan dan penanganan komponen sistem ditangani melalui sistem dan model Raamwerk. Inilah yang memungkinkan pemuatan ulang live dari backend, tetapi juga mengatur semua komponen aplikasi (server statis dan API, config, db, dll.). Konstruktor utama untuk ini ditemukan di app.systems . Ada fungsi base build-system yang mengambil nama profil konfigurasi dan menghasilkan peta sistem dasar untuk profil itu, dan kemudian berfungsi yang menghasilkan sistem prod dan dev.

Catatan yang paling penting adalah :site-endpoint , yang merupakan komponen yang menangani rute statis seperti indeks utama dan titik ke app.routes/site , dan :api-endpoint , yang merupakan komponen untuk API REST, dan poin ke app.api/api-routes . Masing -masing fungsi ini mengambil argumen tunggal (disebut sys by convention), yang merupakan subset dari peta sistem, yang berisi kunci yang tercantum sebagai dependensi dalam vektor yang diteruskan ke component/using . Jadi agar komponen tersedia untuk titik akhir, kuncinya perlu ditambahkan ke vektor ini.

Migrasi basis data ditangani dengan komponen ragtime, dikonfigurasi untuk dijalankan secara otomatis di server start atau muat ulang. Migrasi terletak di resources/db/migrations , yang berisi file .up.sql dan .down.sql untuk migrasi, dinamai sesuai dengan skema yang dijelaskan dalam dokumentasi ragtime. Peta konfigurasi ragtime tersedia dari peta sistem sebagai :migrations dan dengan demikian dapat diakses dari repl atau dari komponen apa pun yang mewarisi sebagai ketergantungan. Peta ini dapat diteruskan ke fungsi di ragtime.repl untuk menjalankan atau memutar kembali migrasi secara manual.

Untuk abstraksi SQL, honeysQL digunakan di atas clojure.java.jdbc. HoneysQL menyediakan cara menulis kueri SQL sebagai peta, yang dengan demikian dapat dibangun dan disusun sebagai peta clojure lainnya, dan kemudian diformat menjadi SQL untuk dihubungi dengan driver JDBC. Fungsi helper, app.query/make-query disediakan di query.sql untuk membungkus panggilan ke driver JDBC, jadi orang hanya perlu menyediakan peta sistem dan peta kueri SQL untuk mendapatkan hasil.

Frontend

Frontend dibangun dengan reagen, menggunakan kombinasi pengiriman multimethod untuk membuat setiap tampilan, dan perutean sisi klien dengan Bide. Dengan demikian, menambahkan sub-view baru membutuhkan beberapa langkah yang penting untuk diingat:

1. Buat tampilan Anda di bawah namespace app.views , yaitu. app.views.foo di cljs/app/views/foo.cljs
2. Membutuhkan app.views.dispatch/dispatch-view multimethod, dan membuat multimethod Anda sendiri untuk dikirim dari kunci yang sesuai, yaitu. :app.foo . Metode ini harus mengambil dua argumen, yang pertama adalah kunci itu sendiri, yang kedua adalah parameter dari URI.
3. Membutuhkan namespace baru di index.cljs .
4. Tambahkan rute ke rute di router.cljs .

Status Aplikasi Utama disimpan dalam atom reagen bersama di app.state/app-state . app.api Namespace juga disediakan untuk panggilan API umum.

Catatan penting tentang perutean: Saat menautkan ke komponen lain dalam aplikasi, yang terbaik adalah menggunakan fungsi app.router/app-link karena ini mengaitkan ke dalam sistem perutean. HREF normal akan berfungsi, tetapi memaksa pemisahan ulang halaman, yang akan lebih lambat dan juga mengatur ulang APP-State.

Ruang nama umum

Selain frontend dan backend, ada juga termasuk beberapa ruang nama umum melalui file .cljc di src/cljc/app , yang memungkinkan data dan fungsi utama dibagikan oleh depan dan belakang. Yang paling penting adalah app.domain di src/cljc/app/domain.cljc . Ini menyediakan skema data umum untuk aplikasi, termasuk skema untuk file konfigurasi.

Alat dev

Docker-compose.yml telah disediakan untuk memulai konfigurasi postgres dasar dengan pengaturan default yang dijelaskan di atas dengan docker-compose up yang sederhana.

Konfigurasi default akan membuka koneksi NREPL ke kedua frontend di port 6809, dan backend di port 6502.

Ada juga elemen reagen-dev-dev tambahan yang ditambahkan ke halaman dalam mode dev yang memberikan refleksi ke status aplikasi saat ini.

Tugas boot cljfmt disediakan yang akan menjalankan cljfmt pada semua file di direktori src. Tugas check dan fix dari boot-cljfmt juga tersedia secara langsung, dan dapat digunakan untuk menjalankan terhadap masing-masing file atau direktori sesuai kebutuhan.

Reload panas yang panas

Baik kode frontend dan backend telah dikonfigurasi untuk secara otomatis memuat ulang perubahan file. Bahkan ada isyarat audio yang bermanfaat untuk memberi tahu Anda setelah pembangunan kembali selesai.

Perhatikan bahwa sistem server backend penuh hanya akan dinyalakan kembali sepenuhnya ketika file tertentu berubah. Ini dikonfigurasi melalui tugas build.boot dev dengan parameter :files ke langkah system .

Pengujian

Beberapa tes integrasi dasar telah disediakan. Anda dapat menjalankan ini dengan boot test , atau dengan boot test-watch , yang akan memulai pengamat dan menjalankan semua tes pada perubahan file.

Tes termasuk pengujian browser melalui Etaoin, dan Anda juga perlu menginstal geckowebdriver berbasis Firefox. Informasi dan tautan tentang cara melakukan ini dapat ditemukan di sini. Di Mac dapat diinstal dengan brew install geckodriver , di ubuntu dengan firefox-geckowebdriver , atau pada windows dengan scoop install geckodriver . Anda juga tentu saja membutuhkan Chrome.

Kredit dan lisensi

Aplikasi ini awalnya didasarkan pada sistem-sistem dengan beberapa panduan lebih lanjut dari Tenzing.

Dikembangkan oleh Annaia Danvers (@jarcane). Pengembangan dimungkinkan oleh Futurice.

Hak Cipta (C) 2018 Annaia Danvers. Kode ini didistribusikan di bawah Lisensi Publik Eclipse v2.0 atau versi selanjutnya. Untuk informasi lebih lanjut, lihat LICENSE di direktori root.